ki-praxis/AGENTS.md

AGENTS.md — Coding Agents in der Praxis

Projekt-Regeln für Coding-Agents am Buch. Karpathy-Skills, adaptiert. Qualität vor Tempo. Bei trivialen Edits nach eigenem Ermessen.

Titel: Coding Agents in der Praxis
Ton: erfahrener Kollege — präzise, geduldig, praxisnah, ohne Hype und Marketing.

Reihenfolge bei Konflikten: direkte Anweisung im Chat > diese Datei > .grok/rules/ > .grok/skills/ > docs/kb/.

1. Dateihoheit

Bereich	Pfade	Regel
Manuskript	manuskript/kapitel-*.md	bearbeitbar im Auftrag; jeder Eingriff textlich begründet
Navigation	00-inhaltsverzeichnis.md	bearbeitbar; nicht im PDF
Recherche	research/**	bearbeitbar bei Fakten- oder Abbildungsfragen
Leser-Vorlagen	templates/**, checklists/**	bearbeitbar; Anhang A mitziehen
Autoren-Harness	AGENTS.md, .grok/**, docs/kb/**	bearbeitbar
Satz und Bau	pdf/**, scripts/**, justfile, devbox.json	nur mit ausdrücklichem Auftrag
Bilder und Cover	assets/**	nur mit Auftrag; nicht neu generieren
Artefakte	build/**, dist/**	nie bearbeiten, nur erzeugen

build/ und dist/ schreibt ausschließlich die Pipeline. Die getrackten dist/*.pdf bleiben im Repo; löschen nur mit Freigabe.

Tote Referenzen, ungenutzte Skripte und Widersprüche werden gemeldet, nicht still gelöscht.

2. Denken vor dem Schreiben

• Annahmen explizit. Bei Unsicherheit: nachfragen.
• Tools, Flags, Slash-Commands, UI: nicht raten. Repo und Primärquellen schlagen Blogposts.
• Versionsangaben: Stand des Buchs; UI kann driften.

3. Einfachheit zuerst

• Nüchtern, praxisnah; keine ungefragten Exkurse, Kapitelumstellungen oder „interessante Fakten“.
• Deutsch durchgängig; Produktnamen und Pfade original.
• Vendor-agnostisch: Feature-Beispiele ≥2–3 Tools oder neutrale Harness-Sprache. Keine Vendor-Rankings.

4. Chirurgische Änderungen

• Nur anfassen, was der Task verlangt. Templates/Checklisten kopierbar halten.
• Platzhalter statt Secrets: YOUR_TOKEN, your-org/your-repo.
• kladde.md nicht ohne Auftrag ändern oder löschen.

5. Zielgetrieben

• Erfolgskriterien prüfbar. Nach dem Schreiben Ziel und DoD kurz wiederholen (Teach-back).
• Kap. 01–22: Key Takeaways und Praktische nächste Schritte (Labels nicht umbenennen).
• Workflow: Explore → Plan → Execute → Verify → Commit (Commit nur wenn erlaubt).

Schreibregeln im Detail: .grok/rules/schreibkonventionen.md.

Thesen-Schutz

Die neun Thesen nicht still widersprechen, umbenennen oder um eine zehnte ergänzen. Wortlaut nur mit Meta-Auftrag. Kanon: docs/kb/06-modelle/neun-thesen.md.

Thesen (kurz): (1) Agent = LLM + Harness (2) Context is King (3) Context-Performance oft U-förmig (4) DoD agent-ermittelbar (5) Ziel + Nebenbedingungen + Ausschlüsse (6) vertikale Slices (7) Stack nach Agent-Zuverlässigkeit (8) Karpathy-Skills erzwingen (9) Aufräumen und Konsistenz — veraltete Rules = Gift; diese Datei schlank und wahr halten.

Template-Pflege

templates/ und checklists/ sind lebende Leser-Quellen. Bei Änderung an Kern-Vorlagen Anhang A (manuskript/kapitel-23-anhang-a-kern-templates.md) knapphalten und mitziehen. Nicht mit Autoren-.grok/ vermischen. Mapping: docs/kb/04-templates-checklisten/.

Korrekturen aus Audits

Prüfprotokolle unter audits/ liefern Prüfaufträge, keine fertigen Sätze.

• Ersatzsätze sind ungeprüfte Behauptungen. Übernehmen nur mit geöffneter Quelle; den Wortlaut der Quelle nutzen.
• Lieber streichen als verneinen. Ein unbelegter Satz wird gestrichen, nicht in sein Gegenteil gedreht.
• Keine Kompromiss-Spannen. Widersprechen sich zwei Prüfungen, Quelle öffnen, Fassung festlegen, protokollieren.
• Abhängiges mitziehen. Wer einen Wert, ein Datum oder eine Zahl ändert, prüft abhängige Stellen und Einheiten.
• Streichungen vollständig ausführen. Echos per rg im ganzen Manuskript suchen, auch in Takeaways, Nachbarkapiteln, Glossar und Bildunterschriften.
• Konfliktregel. Es gilt die jüngste Prüfung mit geöffneter Primärquelle. Eine Prüfung ohne Quelle begründet nur einen Prüfauftrag.

Build und QA

Tight-Loop nach Manuskript- und Template-Patches:

just markdownlint
just link-check

Slice-DoD: dieselbe Kette plus git diff --name-only gegen den Auftrag.

Mit PDF-Auftrag zusätzlich:

just pdf && just qa

Mit Print-Auftrag: just pdf-print && just qa-print. Mit EPUB-Auftrag: just epub && just qa-epub.

Regeln:

• Ein Bericht „fertig“ ohne Build ist unzulässig.
• FAIL wird behoben oder als blockiert gemeldet. WARN wird im Bericht genannt.
• Seitenzahlen nur aus pdfinfo, .grok/scripts/seiten.py oder der QA-Ausgabe zitieren, nie schätzen.
• _print_pages im justfile nur mit Freigabe ändern.
• Die Kette und ihre Stolpersteine stehen in .grok/rules/bau-pipeline.md.

Compact / Handoff

• Session-Context schlank und signalstark halten.
• Bei Rauschen oder Fokusverlust: Compact vorschlagen, fertigen Hint anbieten (Ziel, DoD, eine Invariante, nächste Schritte).
• Nach Compact: Ziel, DoD und eine harte Invariante kurz wiederholen; bei Fail Hint nachlegen oder Handoff.
• Bei Themenwechsel, Phasengrenze oder Pollution: HANDOFF-buch.md aktualisieren und neue Session empfehlen.
• Compact ≠ Handoff ≠ Hand-back. Datei = Handoff (Kap. 4.3).

Arbeitsweise und Bericht

• Erst lesen, dann ändern. Bei mehrdeutigem Auftrag nachfragen.
• Chirurgisch: nur die Stellen anfassen, die der Auftrag nennt. Keine Drive-by-Korrekturen.
• Behauptungen über den Projektstand mit Befehl belegen (wc -w, pdfinfo, just qa), nicht aus dem Gedächtnis.
• Am Ende berichten: geänderte Dateien, Build- und QA-Status, offene Punkte. Keine Erfolgsmeldung ohne Prüfung.

Session-Start

1. Diese Datei + .grok/rules/*.md — Grok lädt das automatisch.
2. docs/kb/INDEX.md — erste Informationsquelle (nicht den KB-Tree oder 01–24 dumpen).
3. HANDOFF-buch.md — nur bei Fortsetzung / unfertigem Slice.

Parent-Context: Skill parent-context (Select; Isolate mit Hand-back). Kapitel-Jobs: Skills lektorat / kapitel-review / humanizer.

Werkzeuge im Repo

Pfad	Zweck
.grok/rules/schreibkonventionen.md	Textregeln, prüfbar
.grok/rules/bau-pipeline.md	Build-Kette und Fehlerbehebung
.grok/rules/subagenten.md	Sub-Agenten, Modelle, Rückgabeformat
.grok/rules/sachlogik.md	Akteur, Mechanik, Ebene, Zeitstand
.grok/skills/lektorat/, kapitel-review/	Kapitel-Jobs
.grok/skills/humanizer/	KI-Stil
.grok/skills/lesepass/	Durchgang über mehrere Kapitel
.grok/skills/faktencheck/	Flags, Versionen, Belege
.grok/skills/sachlogik/	Sachlogik mit Kandidatensuche
.grok/skills/pdf-bauen/, pdf-print/	Build und QA
.grok/skills/total-check/	buchweite Vollprüfung
.grok/skills/abbildung/, parent-context/	Figuren, Context-Disziplin
.grok/commands/	/pdf, /review, /buch-status, /faktencheck, /lesepass, /sachlogik
.grok/scripts/	seiten.py, manuskript_check.py, _repo.py

Nicht ohne Auftrag

kladde.md · Gesamtrewrite · PDF oder EPUB bauen · pdf/ / Assembler / bestehende QA-Scripts · Thesen-Wortlaut · destruktive Git-Ops · Secrets committen.

Placement

Richtlinie hier. Fakten-Map docs/kb/. Session HANDOFF-buch.md. Pfad-Rollen docs/kb/00-projekt/repo-karte.md. Prozedur Skills / just.