‏ ‏ ‎ ‏ ‏ ‎

1. 2026-09-22

1.1. AI Best Practise

1.1.1. Tokens & "Thinking"

1.1.2. What "Thinking" Means

  • Next-Token Predictors: Predict the most likely following text via statistical pattern completion.

  • No Intrinsic Intent: No memory, beliefs or genuine understanding

  • "Thinking" Models: Utilize chain-of-thought scratchpads (e.g. o1, Claude thinking) where '*more tokens = more reasoning

  • Pattern Recognition: Matches against billions of learned patterns rather than understanding code semantics. → Konsequenz: Es wird in markdown "programmiert", da auch die Quellen mit denen verglichen wird, natürlichsprachig sind.

1.1.3. Tokens Explained

  • Token Units: LLM read tokens (~3/4 word), not raw characters

    • Example: kubectl apply -f deployment.yaml → 7 tokens

  • Token Limits: Hard combined limit across input prompt and output completion.

  • Trade-offs: More tokens increase cost and latency, but provide richer context.

1.2. Context & Window Management

  • Complete Scope: System prompt + conversation history + user input + output response

    • GPT-4o: 1M+ tokens (~2500 pages)

    • Gemini: 1M+ tokens (~2500 pages)

    • Claude: 1M+ tokens (~2500 pages)

  • "Lost in the Middle" Effect: Bigger ungleich better; attention and reasoning degrade as context fills.

1.3. Context Management Rules

  • Curate Relevance: Never dump entire repositories; provide only relevant snippets.

  • Structured Formatting: Clear headings, markdown and bullet points assist parsing.

  • Primacy & Recency: Place critical constraints at the beginning and end.

  • Reset Often: Start fresh conversation when switching topics to avoid stale context.

1.4. Prompt Engineering

1.4.1. Prompt Engineering: Basics

  • Vague Prompt: "Write me a Dockerfile" → unpredictable output.

  • Specific prompt: "Write a multi-stage Dockerfile for Go 1.24, non-root nuser, pinned digests, no hardcoded secrets"

  • Core Rule: The more contraints you specify, the better the output.

1.4.2. Prompt Engineering: Advanced

  • System Prompts: Explicitly define persona and role (e.g. "You are a K8s security auditor"). → ganz schlecht. Er ist kein Experte und würde nichts mahr nachsehen.

  • Few-Shot examples: Provide 1-2 examples of target input/output pairs.

  • Chain-ofThought: Use "Think step by step" to enforce reasoning before answers.

  • Iterative Refinement: Avoid one-shot expectations; generate, critique and improve.

1.5. Spec-Driven Development (SDD)

Architecting software with AI as the builder.

1.5.1. Spec-Driven Principles (SDD) - Architecting Software with AI as the Builder

  • Role Separation: You are the architect, AI is the builder.

  • Explicit Requirements: Define constraints, behaviors and edge cases up front.

  • Acceptance Criteria: Specify measurable tests and verification steps.

  • Objective Review: Review AI outputs strictly against the spec, not gut feeling.

1.5.2. The SDD Workflow

01 Spec 02 Generate 03 Review 04 Iterate

Define what to build

AI writes the code

Check against spec

Refine with feedback
The spec is your source of truth — not the AI, not your assumptions.

1.6. Key Takeaways

"AI doesn’t think. It predicts. Your job is to think for it."

  • Manage Context: Keep inputs minimal, structured and focused.

  • Write Specs: Direct implementation with strict constraints and criteria.

  • Prompt Precisely: Use roles, few-shot examples and chain-of-thought.

  • Review Everything: Verify thoroughly against the specification.

Superpowers mit Design Patterns

  • Test Driven development

    • Kein Produktivcode ohne roten Test vorab

    • Das Minimalste wird gemacht, damit der Test rot wird

    • Rule: Beim Schreiben von Test wird kein Produktivcode geändert

    • Rule: Beim Schreiben von Produktionscode wird kein Test geändert

Wissen

  • Context

Vgl Harness zu Context

  • Memory:

    • ist projektbezogen (eigenes Verzeichnis).

    • Memory ist klein

    • bei Verwendung von Worktrees verschwindet das Memory, da die Worktrees in ein anderes Verzeichnis ausgelagert werden.

    • Wenn das Memory zu groß wird, liest er nicht mehr das ganze Memory-File und er "vergisst" was.

    • Will man sub-agenta haben und worktrees, dann lässt man den AI-agent träumen.

  • Continuations

  • repo i.S.v. Commit-History

    • Die Commit-History ist eine wichtige Wissenbasis.

    • Voraussetzung: nicht manuell committen

  • Source-Code

    • eher nicht als Wissenquelle verwenden eher verwirrend für den agent

1.7. Procedurales

  • skills:

    • Besteht aus einem Prompt-Mapper (Reizworte) und Text und auch Dateien die er braucht zB shell-Files

    • Wenn die Reiszworte im Prompt vorkommen, dann wird der Text des Skills gelesen (Instruktionen)

  • Es gibt shared-skills und projektspezifische Skills

  • commands

    • Prozedurale Anweisungen

    • zB träumen, zum Reorganisieren des Memories und die Infos aus dem Memory sollen in die Projektrepos übernommen werden.

  • rules

  • tools/mcp

Alle skills and rules werden in einem git-submodule "agents-and-skills" gespeichert und den Projektrepos hinzugefügt