Damit KI nicht mehr abschweift: ein praxistaugliches Collaboration‑Playbook (mit Vorlagen)

• Du bittest KI, einen Bug zu fixen—und sie ändert gleich „hilfsbereit“ auch Unrelated‑Code. Am Ende revertierst du von Hand.
• Du schreibst endlose Prompts, aber die KI findet die richtigen Dateien nicht und „rät“.
• Mitten in einer langen Unterhaltung vergisst sie Constraints; die Qualität fällt abrupt ab.

• AGENTS.md: harte Repo‑Constraints (Red Lines, Defaults, Definition of Done)
• docs/ai-playbook/index.md: ein einseitiger High‑Signal‑Index
• docs/ai-playbook/code-map.md: Code‑Landkarte (wo ändern)
• docs/ai-playbook/flows.md: zentrale Flows (wie es läuft)
• docs/ai-playbook/collab-rules.md: Kollaborationsregeln + Change‑Plan‑Template (wie wir arbeiten)

Step 0: Grenzen und „done“ definieren (nicht mit Prompts starten)

1. Boundary: was niemals passieren darf (Privacy/Architektur‑Redlines, Protokoll‑Kompatibilität, Guardrails für kritische Parameter)
2. Scope: ein Ziel pro Änderung, keine „wenn ich schon dabei bin…“
3. Done: Build/Tests + manuelle Regression‑Checkliste müssen stehen

Ein Ziel, zuerst der Plan; Privacy/Architektur‑Redlines nie brechen; done heißt: Build grün + Regression‑Checklist.

Häufige Anti‑Patterns (bitte vermeiden)

1. „Ändere den Code“ ohne Plan
   • Folge: 10 Dateien später stellst du fest, dass die Richtung falsch war—Rollback wird teuer
   • Besser: zuerst Change‑Plan, Implementierung erst nach Approval
2. Alle Dokus in den Prompt kippen
   • Folge: Kontext‑Overload; die KI verliert das Wesentliche (findet nicht mal Entry Points)
   • Besser: High‑Signal‑Index + Code‑Map
3. „Nebenbei optimieren“ erlauben
   • Folge: ein PR mit mehreren Zielen; Review wird schwer, Bugs schwerer revertierbar
   • Besser: Single‑Scope, minimal, gut roll‑backbar

Step 1: AGENTS.md schreiben (harte Constraints, stabil wiederverwendet)

• Plan first: AGENTS.en.md:7
• One change, one purpose: AGENTS.en.md:8
• Privacy & architecture red line: AGENTS.en.md:9
• Docs must stay in sync: AGENTS.en.md:12
• Verification required: AGENTS.en.md:13

# AGENTS — Repo Rules

First Principles

- Plan-first: Propose a change plan and get approval before writing code
- Single-scope: One PR solves one goal; avoid “while I’m here” fixes
- Redlines: Never cross privacy/architecture/protocol/key-parameter guardrails
- Docs-sync: Keep the playbook docs in sync when entry points/flows/interfaces change
- Validation: Must include build/tests and key manual regression checklist

Mehrsprachigkeit

• AGENTS.en.md als kanonische Version
• Lokalisierte Varianten nach Bedarf (z. B. AGENTS.<locale>.md)
• Nach dem Clone lokal den passenden Symlink setzen:

# English users
ln -s AGENTS.en.md AGENTS.md

• AGENTS.md in .gitignore, um Symlink‑Konflikte zu vermeiden

Kern‑Insight
Zuverlässige KI‑Zusammenarbeit entsteht nicht durch „bessere Prompts“, sondern indem Constraints Teil des Repos werden. AGENTS.md macht Regeln wiederverwendbar, der AI Playbook macht Kontext langlebig.

Step 2: docs/ai-playbook/index.md schreiben (High‑Signal‑Einstieg)

• in 30 Sekunden lesbar sein (Snapshot + Link‑Index)
• per Klick zu code-map / flows / collab-rules führen

# AI Playbook — Index

## Project Snapshot

- Stack: Next.js / Node / ...
- Red lines: ...

## Document Index

- Code map: docs/ai-playbook/code-map.md
- Key flows: docs/ai-playbook/flows.md
- Collaboration rules: docs/ai-playbook/collab-rules.md

Step 3: code-map.md schreiben (wo ändern)

• nur Schlüsselverzeichnisse und Entry‑Files
• pro Entry‑File ein Satz: Verantwortlichkeit
• bei einer Anfrage: erst 3–8 Kandidaten aus der Code‑Map, dann Deep‑Dive

Common request routing

- New page / SEO: frontend/app/\*\*/page.tsx + metadata.ts
- i18n copy: frontend/constants/messages/\*
- Blog: frontend/content/blog/\* + frontend/lib/blog.ts

Step 4: flows.md schreiben (wie es läuft)

• Sequenz + Invarianten => weniger „Bauchgefühl‑Patches“
• Debug‑Pitfalls werden zur wiederverwendbaren Checklist

1. Key flow / sequence (Mermaid wenn sinnvoll)
2. Debug‑Checkliste
3. Micro‑Plan‑Template (Plan‑first erzwingen)

Step 5: „Plan first“ erzwingen (Plan = Mini‑Design‑Doc)

Title: <short, clear title>

Goals
- <what you want to achieve>

Scope / Files
- <list of files you’ll change/add + why>

Approach
- <implementation plan and key design points>

Risks & Mitigations
- <risk> → <mitigation>

Acceptance Criteria
- <verifiable acceptance items>

Rollback
- <how to revert quickly>

Docs to Update
- docs/ai-playbook/index.md / code-map.md / flows.md / collab-rules.md / others?

Validation
- Build: next build
- Manual: <key cases & regression points>

1. index + code-map + flows lesen (read‑only)
2. Zustand + Constraints in eigenen Worten restaten (einmal korrigieren)
3. Change‑Plan schreiben (erst dann implementieren)

Step 5.1: Context Endurance (Checkpoint → neuer Chat)

# Handoff

## Problem statement (3–5 sentences)

## Confirmed plan (bullets)

## Done / Not done

## Key files and entry points

## Red lines and invariants

## Acceptance & regression checklist

## Next-step checklist

Step 6: Den Loop schließen (Agent wie ein neues Teammitglied behandeln)

1. Anfrage → Constraints (AGENTS.md)
2. Navigation → Entry Points (index + code-map)
3. Alignment → Sequenzen (flows)
4. Plan → Mini‑Design‑Doc (collab-rules)
5. Umsetzung → klein & single‑scope
6. Verifikation → next build + manuelle Regression
7. Sync → Playbook‑Docs aktuell halten

Prompt‑Beispiele (copy‑ready)

Industry‑Referenz: OpenAI und Codex

Minimale Ordnerstruktur (kopierbar)

AGENTS.en.md             # Canonical rules (English)
AGENTS.<locale>.md       # Optional localized rules
AGENTS.md                # Symlink (created locally after git clone)
docs/
  ai-playbook/
    index.md             # High-signal entry point
    code-map.md
    flows.md
    collab-rules.md

Nächste Schritte

1. Jetzt starten: kopiere die Minimalstruktur in dein Repo und beginne mit AGENTS.md
2. Referenz-Implementierung: besuche PrivyDrop GitHub und schau dir das komplette AI Playbook an
3. Feedback: wenn das hilft (oder du in Fallen läufst), eröffne ein Issue oder hinterlasse einen Kommentar
4. Star: wenn es dir Mehrwert bringt, gib PrivyDrop einen Star 🌟

Schluss