ki-praxis/templates/agents-md-monorepo-root.md

AGENTS.md (Monorepo Root — Beispiel)

Root-Regeln für ein agent-freundliches Monorepo.
Anpassen an dein Tooling (pnpm/npm/yarn, Nx/Turborepo, …).
Package-lokale Regeln liegen unter packages/*/AGENTS.md bzw. apps/*/AGENTS.md.

# Agent instructions — <monorepo-name> (root)

## Mission
Produziere kleine, reviewbare, package-bewusste Änderungen.
Qualität und Verifizierbarkeit vor Tempo. Kein monorepo-weiter Drive-by-Refactor.

## Karpathy-Skills (verbindlich)
1. Think Before Coding — Graph und bestehende Packages lesen, bevor du schreibst.
2. Simplicity First — keine neuen Packages/Libraries ohne Auftrag.
3. Surgical Changes — nur betroffene Packages; keine „nebenbei“-Aufräumaktionen.
4. Goal-Driven Execution — DoD = scoped Verify-Commands.

## Context is King (Monorepo)
- Arbeite mit **explizitem Package-Scope** (Task oder Handoff).
- Lies bei Arbeit unter `packages/X` oder `apps/X` zuerst die lokale `AGENTS.md` dort.
- Lade nicht „halb das Monorepo“ in den Context; suche gezielt.
- Trigger = Muster im Transkript: Wiederhol-Reads ohne Fortschritt, Log-Wände, Scope-Drift, User-Korrektur. Eine Hauptaktion, nicht alle drei: gleicher Task und Context noch scharf → Compact mit fertigem Hint; Stand muss überleben → Progress/Handoff; Themen-, Task- oder Rot-Grenze → Handoff und neue Session. Füllgrad nur, wenn das Tool ihn anzeigt. Nach Compact und vor dem nächsten großen Patch: Ziel, DoD und eine harte Invariante kurz wiederholen; bei Fail Hint nachlegen oder Handoff.
- Artefakte und Dependencies sind ignore’d — nicht manuell pasten.

## Module Boundaries
- `apps/*` dürfen `packages/*` nutzen gemäß Project Graph / Tags.
- `packages/core` (o. Ä.) hat keine Abhängigkeit auf `apps/*`.
- Keine zyklischen Imports. Bei Unsicherheit: `nx graph` / Turborepo-Graph / README Architecture.
- Ownership: siehe CODEOWNERS oder Package-AGENTS.

## Definition of Done (Defaults)
Done erst wenn:
1. Akzeptanzkriterien des Tasks erfüllt sind.
2. **Scoped** Checks grün sind (nicht unnötig full monorepo).
3. Diff bleibt im vereinbarten Scope (Packages/Pfade).

### Verify-Kommandos (Beispiele — anpassen)
- Turborepo: `pnpm turbo run lint test --filter=@your-org/billing...`
- Turborepo build: `pnpm turbo run build --filter=@your-org/billing`
- Nx affected: `pnpm nx affected -t lint,test --base=main`
- Nx package: `pnpm nx run billing:test` und `pnpm nx run billing:lint`

Full-repo `test`/`build` nur wenn der Task das **explizit** verlangt oder der Graph unklar ist.
Dieselben Filter-Commands wie CI (Mirror) — Tight-Loop scoped, Heavy nicht nach jedem Edit.

## Parallel Agents
- Schreib-Scopes müssen disjunkt sein (verschiedene Packages/Apps).
- Lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`) und Root-Configs:
  nur ein Agent bzw. serialisiert.
- Bevorzugt separate Git-Worktrees pro parallelem Agent.
- Integrationstests über Package-Grenzen: nach dem Zusammenführen der Teildiffs.

## Permissions (hart — Harness, nicht nur diese Datei)
- Default: lesen/suchen. Write nur im vereinbarten Package-Scope.
- Verify-Shell scoped erlaubt (`--filter` / `nx run`, kein unnötiges Full-Repo).
- Commit/Push laut Task. force-push / `reset --hard` / shared-branch-delete: HITL.
- Destruktiv / Prod / Deploy: deny bis HITL.
- Keine Secrets committen. Generierte Clients: eine Source of Truth.
- Root-`AGENTS.md` ist weich. Allow/Deny, Sandbox, Tool-Approval setzt der Harness.

## Stack
- Package-Manager: <pnpm@X / npm / yarn>
- Monorepo-Tool: <Nx | Turborepo | …>
- Node/Runtime: <…>
- Neue Dependencies: nur mit Auftrag; Workspace-Protokoll bevorzugen.

## Dateien mit Vorrang (Session-Start)
1. Diese Root-`AGENTS.md`
2. HANDOFF.md / Task-Prompt (Scope!)
3. Package-`AGENTS.md` im Arbeitsbereich
4. Architektur-Skizze: `docs/architecture.md` (falls vorhanden)

## Kommunikation
- Deutsch (oder: Englisch), knapp.
- Am Ende: geänderte Packages, Verify-Commands + Ergebnis, offene Risiken an Grenzen.

Pflege

• Root schlank halten; Details in Package-Rules. Weich ≠ Allow/Deny.
• Nach Umbenennungen von Packages Commands und Filter am selben Tag anpassen.
• Siehe Buchkapitel 9 (Projekt-Struktur) und 15 (Setup).