ki-grok/07-agents-md-projektregeln.md

Kapitel 7

AGENTS.md und Projektregeln

Kern in einem Satz: AGENTS.md und Rules-Dateien sind der stabile Kompass deines Repos: einmal geschrieben, in jeder Session geladen – präzise genug zum Handeln, kurz genug zum Folgen.

---

7.1 Warum Dateien statt Prompt-Rituale

Alltagsschmerz: Jede Session beginnt mit „Bitte TypeScript, bitte npm test, bitte keine Secrets committen…“. Drei Leute, drei leicht abweichende Versionen. Der Agent hält sich an den lautesten Prompt – nicht an den Team-Standard.

Lösung: Handlungsanweisungen versionieren. Was in jeder Session gelten soll, gehört in Projektregeln. Was nur diese Story betrifft, bleibt im Prompt oder Ticket.

Schicht	Lebensdauer	Beispiel
Prompt	ein Turn / eine Story	„Nur payments/retry.ts anfassen“
AGENTS.md / Rules	Repo-Lebenszeit	„Tests: npm test. Conventional Commits.“
Skill	wiederholbarer Workflow	/commit, /verify (Kapitel 8)
Hook / Permission	erzwungen	rm -rf blocken (Kapitel 8, 13)

Merksatz: AGENTS.md ist weich (Anweisung). Permissions/Hooks sind hart (Durchsetzung). Beides brauchen gute Teams – ersetzt einander nicht.

{width=90%}

{width=90%}

---

7.2 Welche Dateien Grok lädt

Pro Verzeichnis prüft Grok u. a. (Reihenfolge der Namensliste laut User-Guide):

• Agents.md, Claude.md, CLAUDE.md, CLAUDE.local.md, AGENT.md, AGENTS.md

Mehrere Treffer im selben Ordner werden alle geladen. Auf case-insensitiven Dateisystemen dedupliziert Grok denselben Dateiinhalt (z. B. Agents.md ≡ AGENTS.md).

Claude-Kompatibilität (default an): zusätzlich Home ~/.claude/ und pro Level .claude/CLAUDE.md / .claude/CLAUDE.local.md.
Cursor-Kompatibilität: analog ~/.cursor/ und projektbezogene Cursor-Rules, wenn enabled.

Rules-Verzeichnisse

Zusätzlich zu den Named Files: alle *.md in:

Ort	Scope
<dir>/.grok/rules/	immer
<dir>/.claude/rules/	Claude-compat (konfigurierbar)
<dir>/.cursor/rules/	Cursor-compat (konfigurierbar)
~/.grok/rules/	global (alle Projekte)
~/.claude/rules/, ~/.cursor/rules/	global, vendor-gated

Empfehlung für Grok-first Teams: Root-AGENTS.md + bei Bedarf .grok/rules/*.md für thematische Scheiben (testing.md, security.md).

---

7.3 Discovery und Precedence

Reihenfolge:

1. Home-Rules ($GROK_HOME / ~/.grok/rules/, dann optionale Vendor-Homes)
2. Repo-Pfad vom Git-Root bis CWD (inklusive) – jedes Level Named Files + rules/
3. Kein Git-Repo: nur CWD

my-app/
  AGENTS.md                 # global im Repo
  src/
    AGENTS.md               # enger
    components/
      AGENTS.md             # am engsten

In src/components/ lädt Grok alle drei. Deeper wins: bei Konflikt gilt die Anweisung, die später im Kontext erscheint (tieferes Verzeichnis).

Auto-Loading: Root→CWD beim Session-Start. Arbeitet der Agent in Verzeichnissen außerhalb dieses Pfads, erkennt er dortige Instruction-Files und zieht sie bei Bedarf nach.

Gitignore: Von .gitignore ignorierte Instruction-Files werden bei der Discovery übersprungen. Persönliche Overrides z. B. als CLAUDE.local.md gitignoren – Custom-Namen wie AGENTS.local.md werden als Top-Level-Named-File nicht erkannt (in .grok/rules/ gilt jedes *.md).

{width=90%}

---

7.4 Was rein darf – und was nicht

Rein (actionable)

# AGENTS.md

## Stack
- TypeScript strict; keine neuen `any` ohne Begründung im PR

## Commands
- Test: `npm test`
- Lint: `npm run lint`
- Nie `npm install` ohne Nachfrage

## Do
- Vor Merge: Tests + Lint grün
- Diffs klein und reviewbar halten

## Don't
- Keine Secrets in Repo oder Prompt
- Kein Force-Push auf `main`
- Keine Edits an `dist/` generierten Artefakten

Commands an euren Stack anpassen (pytest/cargo/…); siehe auch beispiele/todo-cli/AGENTS.md und die Vorlagen unter vorlagen/.

Raus (oder nur verlinken)

• README-Kopie, Architektur-Roman, Marketing
• Secrets, Tokens, interne Hostnamen mit Credentials
• 20 Seiten Style-Guide – lieber Link + 5 harte Regeln

Dateigröße: Grok lädt Instruction-Files vollständig (kein Cap/Truncate). Trotzdem: kurz und spezifisch – Kontext ist endlich, und lange Wände werden schlechter befolgt.

---

7.5 Nested Rules und Monorepos

my-monorepo/
  AGENTS.md                      # Workspace: pnpm, Package-Grenzen
  packages/
    frontend/
      AGENTS.md                  # React, CSS modules
      .grok/rules/a11y.md
    backend/
      AGENTS.md                  # Express, REST, OpenAPI
    shared/
      AGENTS.md                  # kein Framework-Code

Pattern: Root = Build-Orchestrierung und Do/Don’t global. Package = Stack und Commands. .grok/rules/ = thematisch (Testing, Security), damit Root-AGENTS.md nicht explodiert.

{width=90%}

CWD-Trick: Starte grok im Package, das du bearbeitest (cd packages/backend && grok), damit die relevanten Nested Rules ohne Umweg greifen – und der Agent weniger Frontend-Kontext mitschleppt.

---

7.6 Session-Flags und Overrides

# Zusätzliche Regeln nur für diese Session (an System-Prompt angehängt)
grok --rules "Always use TypeScript. Prefer functional components."
# Alias: --append-system-prompt

# Kompletter System-Prompt-Ersatz (Default-Prompt + --rules entfallen)
grok --system-prompt-override "Du bist ein strenger Security-Reviewer. …"
# Alias: --system-prompt

Wann --rules: Experiment, Pairing, einmaliger Policy-Spike.
Wann Datei: Team-Standard.
Wann Override: Spezial-Agent (selten) – du verlierst den Default-Harness-Prompt, also bewusst einsetzen.

---

7.7 Inspizieren: was wurde wirklich geladen?

grok inspect
grok inspect --json

Zeigt Instruction-Files mit Pfad und grober Token-Last – plus Skills, MCP, etc. Erster Debug-Schritt, wenn „er hält sich nicht an unsere Regeln“: Liegt die Datei im Discovery-Pfad? Gitignored? Falsches CWD?

In der Session helfen /context und /session-info bei der Kontext-Bilanz (Kapitel 3, 12).

---

7.8 Kompatibilität mit Claude Code und Cursor

Viele Repos haben schon CLAUDE.md und .claude/rules/. Grok liest sie standardmäßig mit – du musst nicht sofort umbenennen.

Ziel	Praxis
Grok-first, grünes Feld	AGENTS.md + .grok/rules/
Claude-Team, Grok-Einstieg	CLAUDE.md behalten; optional AGENTS.md mit denselben Kernregeln
Dual-Agent	Beide Dateien kurz und konsistent – nicht zwei Wahrheiten
Vendor aus	[compat.claude] / [compat.cursor] Rules/Agents/Skills in Config (Kapitel 14)

Anti-Pattern: AGENTS.md sagt „pnpm“, CLAUDE.md sagt „npm“ – die später geladene Anweisung gewinnt (Precedence ist bestimmt). Im Alltag wirkt das wie Willkür, wenn beide Dateien divergieren. Eine Source of Truth, der Rest verlinkt oder ist identisch.

---

7.9 Best Practices (knapp und verbindlich)

1. Root zuerst – das Wichtigste project-weit.
2. Spezifisch – `cargo fmt` vor Commit schlägt „formatiere bitte“.
3. Kurz – eine Seite schlägt ein Essay.
4. Nested für Monorepos – nicht alles in Root pressen.
5. Versionieren – committe Team-Regeln; Persönliches nach ~/.grok/ oder *.local.md + gitignore.
6. Nicht duplizieren – README verlinken, nicht kopieren.
7. Periodisch reviewen – tote Commands sind schlimmer als keine.
8. Prüfbar – jede Do-Regel idealerweise mit Command oder „Definition of Done“.

Minimal-Vorlage: vorlagen/AGENTS.md.minimal.md.

---

7.10 Praxis-Sessions

Session 1 – Minimal-AGENTS.md anlegen

cd ~/projects/your-app
# Datei anlegen (oder vom Agenten schreiben lassen – dann Diff lesen)

Erstelle eine knappe Root-AGENTS.md mit: Stack in 3 Bullets,
Test- und Lint-Commands exakt, 3 Don'ts (Secrets, force-push, dist/).
Keine Romane. Zeig mir den Diff.

Danach:

grok inspect | head -80

Erfolg: Datei gelistet, Token-Count sichtbar.

Session 2 – Nested Rule greift

# packages/backend/AGENTS.md (oder lass den Agenten anlegen)
Nur im Backend: REST, keine React-Imports, Tests mit pytest.

cd packages/backend && grok

Welche Projektregeln gelten hier? Liste die geladenen Instruction-Pfade
und fasse die Backend-spezifischen Don'ts zusammen. Ändere nichts.

Erfolg: Nested Inhalt taucht auf; Root bleibt sichtbar.

Session 3 – Konflikt Deep vs. Root

Root: „Formatter: prettier“.
src/legacy/AGENTS.md: „Dieser Ordner: kein Auto-Format, manuell.“

Arbeite nur unter src/legacy/. Welcher Formatter-Hinweis gewinnt und warum?

Trainingsziel: Deeper precedence erklären können.

Session 4 – Session-Rules ohne Datei

grok --rules "Antworte auf Deutsch. Keine neuen Dependencies."

Schlage einen Fix für den flaky Test vor – halte dich an die Session-Rules.

Trainingsziel: --rules vs. committed AGENTS.md unterscheiden.

---

7.11 Das .grok/-Projektverzeichnis (Landkarte)

Pfad	Zweck
.grok/config.toml	u. a. MCP, Plugins, Permissions (projektskopiert)
.grok/skills/	Team-Skills (Kapitel 8)
.grok/plugins/	Projekt-Plugins
.grok/agents/	Custom Agents
.grok/hooks/	Lifecycle-Hooks (Kapitel 8)
.grok/rules/	Nested Markdown-Rules
.grok/lsp.json	LSP

Alles optional. AGENTS.md bleibt der Einstieg – der Rest skaliert das Harness.

---

7.12 Jetzt selbst machen: Rules-Parcours (20 Minuten)

Jetzt selbst machen

1. Root-AGENTS.md mit Commands + Don'ts anlegen oder schärfen.
2. grok inspect – Datei und Tokens notieren.
3. Eine .grok/rules/testing.md mit einem Satz „Neue Features: failing-first Test“.
4. Session starten und den Agenten die geladenen Rules nennen lassen.
5. Optional: absichtlich gitignorierte CLAUDE.local.md mit privatem Hinweis – prüfen, ob sie (nicht) erscheint.
6. Monorepo: CWD in ein Package legen und Nested-Verhalten spüren.

---

7.13 Häufige Fehler

Symptom	Ursache	Fix
Regeln greifen nicht	Falsches CWD / gitignore / Name	grok inspect, Pfade prüfen
Zwei widersprüchliche Dateien	AGENTS + CLAUDE divergieren	Eine Wahrheit
Agent ignoriert lange Bibel	Zu viel Text	Kürzen, Skills für Workflows
Secrets in AGENTS.md	Copy-Paste	Sofort rotieren; nur Token-Dummies in Beispielen
„Lokal nur bei mir“ committed	Personal in Root	~/.grok/ oder local+gitignore

---

7.14 Checkliste AGENTS.md

• Root-Datei mit Stack, Commands, Do/Don't
• Commands exakt und lauffähig
• Nested nur wo Konventionen abweichen
• grok inspect einmal verifiziert
• Team-Datei committed; Locals gitignored
• Keine Secrets
• Review-Rhythmus (Quartal / nach großen Stack-Wechseln)

---

Was du jetzt kannst

• Discovery, Precedence und Named-File-Kompatibilität erklären
• Eine knappe, prüfbare Root-AGENTS.md und Nested Rules bauen
• grok inspect und Session-Flags gezielt einsetzen
• Dual-Agent-Repos ohne widersprüchliche Kompasse fahren

Nächste Schritte

→ Kapitel 08 – Skills, Plugins, Hooks und Marketplaces: wiederholbare Workflows on-demand, erzwungene Gates und installierbare Bundles.