ki-praxis/manuskript/kapitel-01-einfuehrung.md

1. Einführung

Coding-Agents lesen Repositories, schreiben Patches, führen Tests aus, öffnen Pull Requests und „reden“ so überzeugend, dass man leicht vergisst, womit man es zu tun hat: mit einem System aus Sprachmodell und Steuerungsschicht, das Token vorhersagt und Werkzeuge bedient — nicht mit einem Kollegen, der Verantwortung übernimmt.

Dieses Buch ist ein Leitfaden für den produktiven, zuverlässigen Einsatz — unabhängig vom konkreten Produkt (Claude Code, Cursor, Codex, Aider, Grok Build, eigene Harnesses und vergleichbare Agents). Bewusst anti-hype: weniger „10x overnight“, mehr „wie verhindere ich, dass der Agent im Kreis refactored, den Context zuschlammt und etwas liefert, das grün aussieht und falsch ist“. Der Hebel sitzt nicht in einer clevereren System-Message und nicht im Logo, sondern in Prozess, Schnitt und den Regeln, unter denen der Agent arbeiten darf.

1.1 Was sich wirklich geändert hat

Vor ein paar Jahren war „KI im Editor“ Autocomplete und Chat über Snippets. Heute navigiert der Agent das Repo, patcht Dateien, startet Tests und meldet „fertig“. Die Versuchung ist groß, das als Kollegen-Ersatz zu lesen. Was sich geändert hat, ist nüchterner — und deshalb steuerbar.

Drei Entwicklungen haben Chat-Spielereien zu Werkzeugen im Lieferprozess gemacht. Kontextfenster und Code-Modelle machen größere Repos und längere Sessions möglich — möglich heißt nicht sinnvoll: mehr Fensterfläche verführt dazu, sie zuzumüllen. Harnesses mit echten Aktionen — Dateien, Shell, Tests, Git, Browser, Issue-Tracker — lassen das LLM die Welt verändern, nicht nur Text erzeugen. Tool-Use ist trainiert: die Kollaboration aus „denken“ und „Tool aufrufen“ ist Teil des Trainings, nicht nur Prompt-Bastelarbeit.

These 1: Ein Coding-Agent ist LLM + Harness.
Das LLM generiert. Der Harness gibt dem LLM die Möglichkeit, Aktionen auszuführen, die die Welt verändern, oder den Kontext zu ergänzen. Die Zusammenarbeit wird im Training optimiert — und in der Praxis von euch orchestriert.

Wer nur „das Modell“ optimiert und Harness, Context und Aufgabe ignoriert, greift am falschen Hebel. Typisch: Modell-Wechsel-Theater — neues Modell, gleicher unklarer Task, gleicher Context-Müll, dieselbe Schleife.

1.2 Wo Agents glänzen — und wo sie teuer scheitern

Der Agent hat den dritten Fix-Versuch gemacht. Im Context stapeln sich alte Stacktraces, halb gelesene Dateien und eine Erklärung, warum Versuch zwei „eigentlich schon fast“ stimmte. Tests rot, Diff unübersichtlich — und niemand kann in zwei Minuten sagen, was „fertig“ bedeuten soll. So fühlt sich teures Scheitern an — und so unnötig ist es oft.

Wo Agents glänzen, ist der Scope eng und das Feedback hart: Boilerplate und Migrationen mit klarem Muster; lokale Refactors, die man im Diff noch im Kopf behält; Exploration unbekannter Codebasen, wenn man sie führt; Verify-Loops (ändern → testen → fixen); Übersetzung zwischen Spec und Konventionen in gut vertretenen Stacks. Kurz: Muster, Grenzen, messbare Fertigstellung.

Die teuren Fehler sind fast immer Prozess und Schnitt, keine mystische Modellschwäche: Context-Müll („Context Rot“); fehlende agent-prüfbare DoD (Endlosschleifen, Pseudo-Done); horizontale Monster-Tasks; Aufgaben zu restriktiv oder vage ohne Grenzen; widersprüchliche Regeln (alte AGENTS.md, tote Skills); blindes Vertrauen in grüne Tests oder überzeugenden Text. Context eng halten, DoD prüfbar machen, vertikal schneiden, Regeln aufräumen, Diffs lesen — das Betriebssystem hinter den späteren Kapiteln.

1.3 Die neun Thesen (roter Faden)

Alles Weitere baut auf den folgenden Aussagen auf. Sie wiederholen sich absichtlich — genau dann, wenn der Agent „fast fertig“ wirkt und der nächste große Happen lockt, statt zu schneiden, zu prüfen und neu zu starten.

#	These	Vertiefung
1	Agent = LLM + Harness	Kapitel 2
2	Context is King — Antworten nur so gut, wie der Kontext es ermöglicht	Kapitel 3
3	Context-Performance ist oft U-förmig (Heuristik); große Kontexte sind teuer und oft schlechter	Kapitel 3, 4, 5, 6
4	DoD muss vom Agent selbst ermittelbar und verifizierbar sein	Kapitel 10
5	Aufgaben nicht zu restriktiv: Ziel + Nebenbedingungen + Ausschlüsse	Kapitel 14
6	Komplexität minimieren; vertikale Slices	Kapitel 8
7	Sprachen/Frameworks wählen, bei denen Agents zuverlässig wartbaren Code liefern (Trainingsdaten-Präsenz als Proxy)	Kapitel 15, Anhang B
8	Karpathy-Skills erzwingen (Fokus)	Kapitel 13
9	Aufräumen und Konsistenz sind kritisch	Kapitel 12

Die Thesen greifen ineinander: enger Context (2, 3) nützt wenig ohne prüfbare DoD (4); DoD nützt wenig bei horizontalen Monster-Tasks (6) und widersprüchlichen Regeln (9). Volle Lehre in der Vertiefungsspalte. Operativ: Context und DoD härter steuern als den Prompt-Witz.

{width=90%}

1.4 Was dieses Buch bewusst nicht ist

Dieses Buch ist kein Prompt-Zauberbuch (keine magische System-Message heilt schlechte Slices), kein Modell-Ranking und kein Vendor-Handbuch — Rankings und UI altern in Wochen; Prinzipien nicht. Knöpfe (Plan-/Ask-Mode, Compact/Summarize, Skills-Pfade) heißen je Tool anders; die Jobs sind dieselben. Es ist kein Ersatz für Engineering: Review, Architektur, Security und Produktentscheidungen bleiben menschlich — oder werden explizit an Prozesse delegiert.

Ebenso wenig eine Peer-Review-Studie. Füllgrad-U und Dumb Zone sind Praxisheuristiken. Was gemessen ist (Länge, Position, Multi-Turn) und was nicht: Kap. 3.12.

1.5 Erfolgsdefinition: Was „gut mit Agents arbeiten“ heißt

Im Stand-up klingt es oft so: „Der Agent hat gestern 2 000 Zeilen geschrieben.“ Das ist Throughput, kein Erfolg. Erfolg heißt: ähnliche Tasks wiederholbar durchbekommen, Diffs in endlicher Zeit reviewen, Fertigstellung ohne Bauchgefühl prüfen, Kosten im Blick — und im Team nicht von Helden-Prompts abhängen.

Fünf Dimensionen: Zuverlässigkeit (ähnliche Tasks, ähnliche Ergebnisse — nicht einmal Genie, einmal Chaos). Reviewbarkeit (Diffs, die ein Mensch verantworten kann). Verifizierbarkeit (DoD ohne „sieht gut aus“ — ideal per Command). Kostenkontrolle (Tokens, Wartezeit, Nacharbeit; „grün nach fünf Context-Resets“ ist teurer, als es aussieht). Lernkurve im Team (gemeinsame Templates schlagen Prompt-Kunststücke). Messbar z. B. über Erst-Slice-Akzeptanz, Nacharbeits-Commits, Zeit bis zum ersten Verify, geplante Session-Resets statt Panik.

1.6 Wie du dieses Buch nutzen sollst

Du musst nicht linear alles lesen. Wähle den Pfad zu Rolle und Engpass.

• Praktiker (Schnellstart): Vorlagen vom Begleit-Service laden (Material → vorlagen.zip, optional checklisten.zip), nach Schnellstart Vorlagen ins Repo — dann Kap. 1, 3–4, 14 (Context-Ops + Tasks); optional am ersten Tag 5–6 skimmen. Ausführlich: README.md · Lesepfade.
• Tech-Leads: Kap. 5–7, 8, 9–11, 12, 14–15, 18 → Context-Engineering, Workflow, Slices, Monorepo, DoD, Alignment, Hygiene, Tasks, Setup, Security; bei chaotischen Repos 21.
• Manager: Kap. 1, 3, 10, 18, 19, 20 → Erwartungen, Context-Kosten, DoD/Orakel, Security-Baseline, Anti-Patterns, Reife; optional 7 (Workflow) und 21 (Low-Maturity). Agent Skills (16) erst nach dem Unterschied zu Fokus-Skills (13).
• Legacy / Low-Maturity: Kap. 8 · 10 · 12 · 21 (+ Templates aus Anhang A).
• Fester Stack Angular / Spring Boot / Quarkus: Prinzipien, Context und DoD bleiben in diesem Buch. Stack-Patterns liegen im Companion Agents mit Angular, Spring Boot & Quarkus.

Rollen sind ein Schnitt. Der andere ist der Engpass dieser Woche — nicht das Inhaltsverzeichnis von vorn. In 15 Minuten liest du das Buch nicht; die erste Session retten die vier Schritte am Kapitelende.

Situation	Zuerst
Agent wiederholt sich, Context läuft voll	3, 4, 10
Neues Feature / dünner Slice	7, 8, 14
Grün, aber falsch / Loop ohne Stopp	10, 11
Legacy- oder Chaos-Repo	8, 10, 12, 21
Secrets, Isolation, Supply-Chain	18
Mehrere Agents parallel	22 (nach 5.6/5.7 und solider DoD)

Die Fehler→Praxis-Zuordnung steht in Kap. 19.10; hier nur der Sprung.

Jedes Kapitel endet mit Key Takeaways und Praktischen nächsten Schritten. Lebende Templates und Checklisten: templates/ und checklists/ im Buch-Repo sowie im Begleit-Service (versionierte ZIPs, Stand, Errata); Kerne im Anhang A. Pflege die Vorlagen, sonst werden sie selbst zu Context-Gift (These 9).

1.7 Arbeitsweise, die wir empfehlen (und selbst nutzen)

Nicht als Dogma, sondern als Default gegen zwei Extreme. Sofort-Execute bei unklarem Ziel: mutig in die falsche Richtung, Nacharbeit und Context-Müll. Endlos-Plan ohne Verify: schöne Skizzen, kein grüner Slice.

Default: Explore → Plan → Execute → Verify → Commit — Verify vor Commit ist nicht verhandelbar. Vertikale Slices halten den Durchlauf klein genug für Context und DoD. Explore und Plan klären den Slice; Execute und Verify prüfen hart; Commit schließt nur ab, was reviewbar ist. Figur und Vertiefung: Kapitel 7.

1.8 Terminologie (kurz)

Kernbegriffe der ersten Kapitel — Vertiefung am genannten Ort:

Begriff	Bedeutung hier
LLM / Harness / Coding-Agent	Token-Generator · Steuerung (Tools, Loop, Permissions) · beides im Aktions-Loop (Kap. 2)
Context	Alles, was dem Modell in einem Schritt sichtbar ist
Dumb Zone	Leistungsabfall bei ungünstig gefülltem Context (auch einmal „Dump-Zone“) — Kap. 3
Context Rot	Session-Qualitätsverfall; der Chroma-Report (2025) nutzt dasselbe Wort für Input-Länge (Kap. 3.12)
Lost-in-the-Middle	Positionsprofil: Ränder oft stärker als die Mitte (Kap. 3)
Compact	History verdichten (verlustbehaftet); UI-Name je Harness (Kap. 4)
Handoff	Datei für die nächste Session — nicht Compact, nicht Agent-Routing (Kap. 4)
DoD / Orakel	Fertigstellung, die der Agent selbst prüfen kann — Command, Exit-Code, Contract (Kap. 10)
Leiter	Vier Bedeutungen: Verify-Leiter (DoD-Leiter, Verify-Schichten: Tight / Slice / Heavy, Kap. 9.7, 10.6) · Orakel-Leiter (Kap. 10.7, 21.2) · Reifegrad-Leiter (Kap. 20.2, 21.1) · Autonomie-Leiter (Kap. 10.12, 21.1)
Vertikaler Slice	Dünner End-to-End-Schnitt mit früher DoD (Kap. 8)
Explore → Plan → Execute → Verify → Commit	Default-Ablauf; Verify vor Commit (Kap. 7)
Karpathy-Skills	Fokus-Zwang: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution — keine Skill-Dateien (Kap. 13)
AGENTS.md	Weiches Projekt-Memory; Dateiname je Tool kosmetisch (Kap. 15)

Weitere Begriffe (Hand-back, Knowledge Layer, Model Routing, Agent Skills, MCP, Alignment) im jeweiligen Kapitel.

---

Key Takeaways

• Ein Coding-Agent ist LLM + Harness; der Hebel sitzt in Prozess und Schnitt, nicht im Modell-Logo.
• Context und DoD steuern Outcome härter als Prompt-Witze.
• Die neun Thesen sind ein System; volle Lehre jeweils am Vertiefungsort.
• Erfolg = zuverlässig, reviewbar, verifizierbar — nicht Zeilen oder Tokens.

Praktische nächste Schritte

1. ZIPs vom Begleit-Service laden (Material) und die ersten Dateien ins Repo kopieren.
2. Minimale AGENTS.md anlegen (Anhang A · templates/agents-md-beispiel.md).
3. Eine laufende Aufgabe mit Ziel + Ausschlüssen + prüfbarer DoD formulieren (Anhang A).
4. Session-Start-Checkliste (Anhang A) als Ritual; weiter: Kapitel 2.