Tag 3 · ca. 75 Minuten
seminar-api agent-ready machen
Der Teilnehmer kann eine Codebase „agent-ready" machen — navigierbar, verifizierbar, mit sauberen Handoff-Artefakten.
Die Antwort steht wörtlich im Lernziel. Mehr braucht es nicht.
Ein Ort, an dem steht, was dieses Projekt ist und wo es anfängt.
Ordner, Module, Klassen, Tests. Der Agent sucht über Namen — wie ihr.
Nicht sieben Schritte aus dem Confluence-Artikel von 2023.
Und der auf einem frisch geklonten Rechner grün ist.
Ein 40-Minuten-Build ist für einen iterierenden Agenten unbrauchbar.
„Das machen wir hier immer so" steht nirgends — also gilt es nicht.
Beleg aus einem echten Projekt: cgsit-finance beginnt seine CLAUDE.md mit einer Quick-Reference-Tabelle — genau die Fragen der ersten Woche, in Befehlsform.
| What | Command |
|---|---|
| Compile backend | mvn clean compile |
| Backend unit tests | mvn test |
| Frontend unit tests | npx ng test --watch=false |
| Local dev DB up / seed / reset | ./scripts/dev-db.sh up | seed | reset |
| Prod version check | curl .../auth/version |
Dieselbe Tabelle versorgt Mensch und Agent.
Auskommentierte Code-Leichen und toter Code — der Agent liest sie als gültig.
Drei Konfigurationswege für dasselbe, zwei davon veraltet.
Generierte Artefakte im Repo, die bei jeder Suche mittreffen.
Ordnernamen wie utils2, new, tmp.
Eine Wahrheit pro Sache — ein Build, ein Testbefehl, ein Config-Ort.
Löschen statt aufheben. Git erinnert sich, der Agent nicht.
Konsistente Struktur: gleiche Schichtung in jedem Modul.
Ein .gitignore, das Generiertes wirklich draußen hält.
Das Modell ist stateless (Modul 1) — CLAUDE.md ist das repo-verankerte Gedächtnis, das automatisch in jeden Aufruf gerät: Was hier steht, muss niemand mehr in den Chat tippen.
Bauen, testen, starten, deployen — kopierfertig, nicht beschrieben.
Welche Module gibt es, wer darf wen aufrufen, wo liegt was.
Was verboten ist und warum — besonders die teuer gelernten.
In welcher Reihenfolge gearbeitet wird, wo die Gates sitzen.
Zeiger nach docs/ statt Volltext — der wichtigste Trick.
Nicht „wir testen viel", sondern „Tests liegen hier, so benannt".
„Schreibe guten, wartbaren Code" — steuert nichts, kostet Tokens.
docs/Zwei Wahrheiten driften auseinander. Verlinken statt kopieren.
Passwörter, Tokens, Prod-Zugänge. Die Datei ist im Repo — für alle.
Wie Spring/Quarkus funktioniert, weiß das Modell besser als euer Text.
Was 2022 mal war, gehört ins Changelog, nicht in den Systemkontext.
Session-Zustand und Privates gehören nicht in ein Team-Artefakt.
| Pitfall | Warum es weh tut | Gegenmittel |
|---|---|---|
| Zu lang | Niemand liest es — das Modell auch nicht wirklich. Bei voller Datei verlieren einzelne Regeln ihre Wirkung. | Kürzen, verlinken, auslagern |
| Selbstverständlichkeiten | Verwässert die echten Regeln, kostet in jeder Session Tokens | Streichen ohne Reue |
| Veraltete Angaben | Schlimmer als keine — der Agent befolgt sie zuverlässig und läuft in die falsche Richtung | Same-Commit-Mandate (gleich) |
Duplikate zu docs/ | Zwei Wahrheiten, eine driftet — und niemand merkt, welche | Verweis statt Volltext |
| Geheimnisse | Landet im Git-Verlauf, in Forks, in jedem Klon | Env-Vars, Secret-Store |
| Wunschdenken | Beschreibt, wie das Projekt sein sollte, nicht wie es ist | Ist-Zustand dokumentieren |
cgsit-finance/CLAUDE.md — gewachsen über ein Jahr Projektarbeit, 1246 Zeilen.
Was drinsteht:
| Abschnitt | Funktion |
|---|---|
| Quick Reference | Alle Befehle in einer Tabelle |
| Local Environment | Eine wiederkehrende Fehlannahme ein für alle Mal ausgeräumt |
| RFC Planning Discipline | Wann ein RFC entsteht, wie er zerlegt werden darf |
| Development Workflow | 15 nummerierte Schritte, jeder mit Pflichtlektüre verlinkt |
| Same-Commit Documentation Mandates | Trigger-Tabelle Code Doku |
| Project Documentation | Nur Verweise — ~30 Links nach docs/ |
| Auto-Loaded Rules / Skills | Was sich wann von selbst lädt, was man rufen muss |
docs/, die Datei ist der Wegweiser dorthin.CLAUDE.md pflegenDie Datei verrottet wie jede Doku.
Für die Pflege gibt es ein Plugin von Anthropic aus dem offiziellen Marktplatz — zwei Werkzeuge, zwei Zeitpunkte.
claude-md-improver findet alle CLAUDE.md im Repo, bewertet sie gegen eine Punkte-Rubrik, schreibt einen Bericht — und ändert erst nach eurer Freigabe.revise-claude-md geht die laufende Session nach Erkenntnissen durch (Befehle, Stolpersteine, Konventionen) und ergänzt sie.SKILL.md, lädt also erst bei Bedarf.docs/test-data-strategy.md an — weil er den Verweis auf docs/testing.md in der CLAUDE.md zwar sah, die Datei aber nie öffnete. Die vorhandene 600-Zeilen-testing.md enthielt das Kapitel bereits. Ergebnis: ein verschwendeter Commit, danach zusammenführen und löschen.
erst grep in docs/, dann das Inhaltsverzeichnis lesen — nicht nur den Dateinamen.
Eine Tabelle im Repo: „Änderst du X, aktualisierst du Doku Y im GLEICHEN Commit." Auszug aus cgsit-finance:
| Wenn du änderst… | MUSST du im selben Commit aktualisieren |
|---|---|
security*-Tabellenschema | docs/securities-domain-model.md |
portfolio*-Tabellenschema | docs/portfolio-domain-model.md |
Scheduler-Eintrag oder @Scheduled | docs/schedulers.md + Manifest-Builder |
| Neue Asset-Klasse | docs/asset-types.md + AssetTypeRegistry |
Neue/gedroppte CREATE TABLE-Migration | docs/data-model-index.md |
| Neue Backend-Env-Variable | drei Stellen: .env.example + docker-compose.yml + docs/deployment.md |
git diff --staged --name-only gegen die Trigger-Spalte halten.Ein RFC ist ein Markdown-Dokument im Repo — eine Datei pro Vorhaben, fortlaufend nummeriert, mit Index.
Pflichtfelder aus dem Template:
Feature | Refactor | Migration | Cleanup — entscheidet, ob in Phasen geliefert werden darf.
Nicht „Checkliste abgehakt", sondern „die versprochene Eigenschaft existiert in Prod" — plus der Beweis.
Welches Problem — nicht welche Lösung.
Was verworfen wurde und warum. Das ist der Teil, den man später sucht.
Ein Haken. Davor: null Zeilen Code.
Der Arbeitsstand — und damit ein natürliches Handoff-Artefakt.
Status-Modell: Draft Accepted In Progress Done — der Statuswechsel ist jeweils ein Gate.
| Situation | Artefakt(e) | Warum |
|---|---|---|
| Neues Feature, neues Modul, Architekturänderung | RFC + Ticket | Entscheidungen müssen dokumentiert und reviewbar sein |
| Mehrschrittige Umsetzung (> 1 Tag, mehrere PRs) | RFC + Sub-Tickets | Ein RFC, mehrere Arbeitseinheiten |
| Übergreifendes Refactoring | RFC + Ticket | Viele Dateien betroffen, die Begründung zählt |
| Neuer Endpoint mit nicht-trivialem Kontrakt | RFC + Ticket | Kontrakt vor dem Code festhalten |
| DB-Migration mit Datenformänderung | RFC + Ticket | Migrationsplan muss reviewbar sein |
| Bugfix, klarer Scope, < wenige Stunden | Nur Ticket | Titel + Beschreibung reichen |
| UI-Politur, Textänderung, kleiner CSS-Tweak | Nur Ticket | Kein Spec-Dokument wert |
| Reine Doku-Änderung | Kein Artefakt | Einfach committen |
| Hotfix im Incident | Nur Ticket | Tempo zuerst — RFC ggf. später nachziehen |
Der RFC hält fest, warum und wie; das Ticket hält fest, wer und wann.
Getrennt gehalten, weil das eine mitversioniert wird und das andere nicht.
docs/rfcs/README.md ist der Index: eine Zeile pro RFC mit Status, betroffenen Modulen und Ticket-Link — die Landkarte aller offenen Vorhaben, die der Agent lesen kann.Modul 1: stateless.
Modul 4: /compact und /clear sind Werkzeuge, keine Notbremsen — beides zusammen ergibt eine einfache Regel:
/compact oder /clear: extrahierenNicht alles aus einer Session ist Zwischenstand — manches ist dauerhaftes Wissen und gehört an einen festen Platz:
| Art der Erkenntnis | Zielort |
|---|---|
| Projektweite Regel, Workflow, Policy | CLAUDE.md |
| Konvention für einen bestimmten Pfad | .claude/rules/<thema>.md |
| Architekturentscheidung, Begründung | docs/<thema>.md |
| Spezifikation, Arbeitsplan | docs/rfcs/NNN-*.md |
| Stolperstein aus einer Debug-Session | tasks/lessons.md |
| Reiner Arbeitsstand | Handoff-Datei |
| Geheimnisse, Zugangsdaten | Nicht ins Repo — Secret-Store |
tasks/lessons.md ist das Langzeitgedächtnis für Fallstricke: ein datierter Abschnitt pro Erkenntnis — was passierte, was die verallgemeinerte Lehre ist, was konkret zu tun ist.Modul 1: „Der Compiler ist der beste Halluzinationsdetektor." Verallgemeinert gilt das für alles, was objektiv grün oder rot ist.
Erfundene Methoden und falsche Signaturen sterben sofort.
Das einzige Werkzeug, das fachliche Korrektheit prüft.
Konventionen, die man nicht mehr im Review erklären muss.
„Modul A darf B nicht aufrufen" — als roter Test statt als Satz in der Doku.
Die unabhängige Zweitmeinung: sauberer Rechner, echte Umgebung.
Der Endpoint antwortet — oder eben nicht.
Lokal zuerst. Der schnelle Lauf am eigenen Rechner ist die Iterationsschleife, die CI ist das Sicherheitsnetz am Ende.
Kompakte Ausgabe. Am Ende steht, was rot ist — nicht 800 Zeilen Log davor.
Ein Befehl pro Absicht. Bauen, testen, deployen — je einer.
Ergebnis abfragbar. Der Agent kann den Zustand des letzten Laufs selbst nachsehen.
Nur in der CI testbar. Jede Iteration kostet einen Push und zehn Minuten Wartezeit.
Riesige Logs im Kontext. Ein Testlauf frisst mehr Fenster als die eigentliche Aufgabe (Modul 1).
Handgeschriebene Deploy-Schritte. Sieben Kommandos in der richtigen Reihenfolge, dokumentiert im Kopf.
Flaky Tests. Ein Orakel, das würfelt, ist kein Orakel.
lessons.md tragen den Stand über jeden Reset hinweg.seminar-api agent-ready machenSchritt 0 — Messpunkt setzen: Stellt in einer frischen Session
eine konkrete Aufgabe an seminar-api, z. B.
„Füge dem Buchungs-Endpoint eine Stornierung hinzu, inklusive Test."
Notiert: Wie viele Rückfragen? Welche falschen Annahmen? Wie oft musstet ihr eingreifen?
Schritt 1: Schreibt eine CLAUDE.md — Befehle, Struktur,
Testkonventionen, die drei Regeln, die euch beim ersten Lauf gefehlt haben.
Maximal 60 Zeilen, keine Selbstverständlichkeiten.
Schritt 2: Lasst den Agenten am Ende eine Handoff-Datei schreiben (Ziel, Stand, nächster Schritt, offene Entscheidungen, Fallstricke) und prüft sie.
Schritt 3 — nachmessen: Dieselbe Aufgabe, wieder frische Session,
jetzt mit CLAUDE.md.
CLAUDE.md und Handoff-Datei liegen
im Repo — und ihr könnt die Wirkung konkret benennen:
welche Rückfrage entfiel, welche falsche Annahme trat nicht mehr auf,
welcher Eingriff war nicht mehr nötig.
Dauer ca. 30 Minuten · Zweiergruppen
Alle Rechte vorbehalten
Diese Schulungsunterlagen sind urheberrechtlich geschützt. Vervielfältigung, Weitergabe oder kommerzielle Nutzung — auch in Auszügen — nur mit ausdrücklicher schriftlicher Genehmigung der CGS IT Solutions GmbH.
cgsit-claude-training · Modul 7 · v0.11.5