ki-grok/AGENTS.md

AGENTS.md — Grok Build Praxisleitfaden (Buch-Repo)

Projekt-Regeln für Coding-Agents. Karpathy-Prinzipien, adaptiert auf ein deutschsprachiges Praxisbuch.

Tradeoff: Vorsicht vor Geschwindigkeit. Bei trivialen Edits nach eigenem Ermessen handeln.

---

1. Denken vor dem Schreiben

• Annahmen explizit machen. Bei Unsicherheit: nachfragen.
• Fakten zu Grok Build: User-Guide (~/.grok/docs/user-guide/), CLI und dieses Repo – nicht raten.
• Bei Versionsangaben: Stand des Buchs (Juli–Aug 2026, CLI 0.2.x) nennen; UI-Details können driftieren.

2. Einfachheit zuerst

• Nüchtern, praxisnah, ohne Marketing und ohne leere Versprechen.
• Keine ungefragten Exkurse, Kapitelumstellungen oder „interessante Fakten“.
• Deutsch durchgängig; Produktnamen und Pfade in Originalschreibweise (AGENTS.md, config.toml, grok).

3. Chirurgische Änderungen

• Nur anfassen, was der Task verlangt.
• Bestehenden Ton treffen: erfahrener Kollege, präzise, geduldig.
• Beispiel-Configs und Terminal-Sessions lauffähig und kommentiert halten.
• Platzhalter statt Secrets: YOUR_TOKEN, your-project, xai-….

4. Zielgetrieben

• Erfolgskriterien prüfbar formulieren.
• Kapitel-Konvention: Abschnitte mit „Was du jetzt kannst“ und „Nächste Schritte“ schließen, wo im Buch vorgesehen.
• Mehrschrittig: Plan mit Checkpoints nennen, dann umsetzen und verifizieren.

---

Projekt-Kontext

Titel: Grok Build – Der umfassende Praxisleitfaden. Der Coding-Agent von xAI richtig einsetzen

Ziel: Praxisbuch für professionelle Entwickler, Tech-Leads und Power-User – 70–75 % praktische Verwendung, realistische Sessions, kopierbare Configs.

Ton: erfahrener Kollege – präzise, geduldig, ohne Hype. Wenn etwas riskant ist, steht das da.

Schwesterprojekte: ../ki-claude (Claude Code), ../ki-codex (Codex-Harness). Stil und Pipeline konsistent halten; Produktlogik nicht vermischen. Siehe ADAPTIONEN.md.

Autoren-Harness vs. Leser-Vorlagen: Root-AGENTS.md / CLAUDE.md / .grok/ steuern Agenten, die am Buch arbeiten. vorlagen/ und beispiele/ sind Content für Leser – nicht mit dem Autoren-Harness vermischen.

Autoren-Skills (.grok/skills/): pdf-bauen, pdf-print, lektorat, kapitel-review, humanizer, update-pics. Slash-Commands: .grok/commands/ (/pdf, /pdf-print, /lektorat, /review, /status, /update-pics). Schreib- und Build-Details: .grok/rules/.

Intern (nicht Manuskript): prompts/ ist Autoren-Material.

Source of Truth (editieren)

Pfad	Rolle	Agent-Hinweis
00-vorwort.md … 18-anhang-schnellreferenz.md	Kapitel-Quellen (kanonisch)	search_replace nach Lesen; Callouts nicht zerstören
vorlagen/	Fertige AGENTS.md- und config-Vorlagen für Leser	Nur bei Vorlagen-Tasks ändern
beispiele/	Mini-Projekte und Beispiel-Configs	Demo-Harness unter .grok/ wenn vorhanden
README.md	Lesepfad und Übersicht	Kurz halten
ADAPTIONEN.md	Übernahmen aus dem Schwesterprojekt	Bei Strukturänderungen aktualisieren
assets/	Cover + Illustrationen (JPG) für PDF	Pfade in Kapiteln beachten
pdf/	LaTeX-Template, Filter, Styles, Metadaten	nur bei explizitem Auftrag
scripts/	Assembler + PDF-QA	Ausführen ja; Umbau nur mit Auftrag
justfile	Build-Orchestrierung	just pdf, just qa, …
build/, dist/	Generierte Artefakte	Nicht manuell „reparieren“; neu bauen

Operativer Kurzkompass (Build, Do/Don’t): Root-CLAUDE.md. Details: .grok/rules/.

Build-Befehle

just assemble   # 00–18 → build/book.md
just pdf        # assemble + pandoc/lualatex → dist/grok-build-praxisleitfaden.pdf (A4 eBook)
just pdf-draft  # Draft-PDF mit Wasserzeichen
just pdf-plain  # ohne gestyltes Template
just pdf-print  # KDP Interior 6×9 Grayscale → dist/…-print.pdf
just qa         # scripts/check_pdf.py (eBook)
just qa-print   # scripts/check_pdf.py --mode print
just all        # pdf + qa
just all-print  # pdf-print + qa-print
just clean      # build/ und dist-PDF-Artefakte

PDF nur bauen, wenn der Task es verlangt (nach inhaltlichen Änderungen oder explizit). Nach just pdf / just pdf-print bei Bedarf just qa bzw. just qa-print. eBook und Print sind parallele Outputs.

Voraussetzungen: pandoc, just, TeX Live (LuaLaTeX, KOMA scrbook), Fonts Charter + DejaVu.

---

Spezielle Konventionen

Callouts (Assembler → PDF-Boxen)

Markdown-Form	PDF-Box	Bedeutung
> **Kern in einem Satz:** … / > **Kern:** …	navy (guidekern)	Abschnittsthese
> **Achtung:** …	burgundy (guideachtung)	echtes Risiko – sparsam
**Jetzt selbst machen** / Abschnitte damit	teal (guideuebung)	Übung zum Nachmachen

• Callout-Labels und Blockquote-Struktur nicht umformatieren.
• Warum-/Wie-Absätze, Checklisten und „So baust du das nach“ bleiben normaler Fließtext (keine extra Callout-Flut).
• Keine erfundenen Callout-Typen („Pro-Tipp“ o. Ä.) – der Assembler mappt sie nicht.

Kapitel-Struktur (wo im Buch vorgesehen)

1. Einstieg mit Kern in einem Satz (Blockquote)
2. Hauptabschnitte mit Szenen/Problemen vor großen Tabellen
3. Bei größeren Blöcken: Checkliste, häufige Fehler, Nachbau-Schritte
4. Abschluss: Was du jetzt kannst / Nächste Schritte

Terminologie (kurz, einheitlich)

Begriff	Verwendung
Grok Build	Produktname; CLI-Befehl grok
Harness	Software-Schicht ums Modell (Tools, Permissions, Memory, Loop)
AGENTS.md	Projektregeln / Kompass (weich); Nested Rules unter .grok/rules/
config.toml	Hauptkonfiguration (~/.grok/config.toml und projektspezifisch)
Plan Mode	Read-only Planung → Plan-Datei → Freigabe
Subagents	isolierte Kind-Sessions (general-purpose, explore, plan, …)
Worktrees	git-isolierte Arbeitskopien für parallele Agent-Arbeit
MCP	Model Context Protocol – externe Tools
Skills	on-demand Workflows (SKILL.md)
Hooks	erzwungene Pre/Post-Tool-Schritte
Headless	grok -p / nicht-interaktive Läufe
ACP	Agent Client Protocol – IDE/Server-Modus (grok agent)

Vier Hebel (max. 2–3 Reprisen pro Kapitel, am Gelenk)

1. Scope eng halten
2. Diff lesen vor Merge/Commit
3. Enge Permissions / Deny vor Always-approve
4. Weich (AGENTS.md) vs. hart ([permission], Hooks, Sandbox)

Nicht ohne Auftrag anfassen

• pdf/templates/*, pdf/filters/*, pdf/styles/*, pdf/print/* (Layout-Pipeline)
• Generierte build/-Inhalte (kommen aus dem Assembler)
• Große Binaries unter dist/, assets/ ohne konkreten Bild-/Build-Task
• beispiele/* nur ändern, wenn das Beispiel selbst Thema ist

Fakten und Aktualität

• Primärquelle: ~/.grok/docs/user-guide/ und aktuelle CLI-Hilfe
• Keine erfundenen Slash-Commands, TOML-Keys oder CLI-Flags
• Bei Unsicherheit: Unsicherheit benennen und Stand des Buchs (Juli–Aug 2026) angeben
• Keine Secrets in Beispielen; Platzhalter YOUR_TOKEN, your-project, xai-…

---

Ton und Qualitätsregeln (Buch)

• Jeder Satz Nutzen stiften. Floskeln streichen.
• Mindestens 2–3 konkrete Beispiele pro Kapitel (Terminal, Configs, Vorher/Nachher) – in Feature-Kapiteln 2–4 Sessions.
• Jetzt selbst machen: für Übungen klar markieren.
• Checkliste + häufige Fehler + „So baust du das nach“ an größeren Abschnitten.
• 70–75 % Praxis – Architektur nur, wo sie Nutzung erklärt.
• Keine Secrets in Beispielen; Platzhalter wie YOUR_TOKEN.

Erklärungsdichte (Wie & Warum)

• Tabellen, Listen und Code-Blöcke eingerahmt erklären: 1–3 Sätze davor und/oder danach.
• Pro Hauptabschnitt (###) mindestens ein klarer Wie-Gedanke (Mechanik) und ein Warum-Gedanke (Risiko, Kosten, Fehlerklasse).
• Keine bloßen Stichwort-Wände: der Leser soll nach dem Abschnitt in einem Satz wiedergeben können, warum die Empfehlung gilt.
• Anhang (Kapitel 18) bleibt knapp; Glossar und Cheatsheets dürfen Mini-Erklärungen tragen.

Lesbarkeit (Mensch zuerst)

• Pro ###: Szene oder Problem des Lesers vor der ersten größeren Tabelle (Vergleich/Lookup).
• Tabelle nur für Vergleich oder Nachschlagen; sonst Fließtext oder Vorher/Nachher.
• Nach Tabelle: 1–2 Sätze Transfer („was du heute änderst“ / „was du mitnimmst“).
• Max. eine Lookup-Tabelle pro Unterabschnitt, wo machbar.
• Pro Kapitel eine kurze Mikrogeschichte (Alltagsschmerz → was du tust) an der dichsten Stelle.
• 1–2 Frage-Überschriften pro Kapitel, wo der Leser sucht.
• Kapitel 18 (Schnellreferenz) und Symptom→Fix-Raster ausgenommen – dort sind Tabellen Feature.