ki-eit/04-zielbild-agent-freundliches-repo.md

4. Zielbild: agent-freundliches Repo

Kern: Ein agent-freundliches Angular/Java-Repo hat eine Wahrheit für Runtime, Build, Test und Lint, schlanke Instructions/Package-Rules, scoped Verify und Ignore-Grenzen gegen Index-Müll — nicht die längste Rules-Datei der Abteilung.

Kapitel 3 hat die Reibung benannt. Dieses Kapitel baut die Infrastruktur, die sie senkt — im Repo, nicht im Chat. Pattern-Tiefe zu Setup und Tooling steht im Theorie-Schwesterbuch (Coding Agents in der Praxis, Kap. 15 und 9); hier die Stack-Übersetzung für Angular/Java. Surfaces (Copilot, Claude Code, Codex, Grok Build u. a.): Anhang C. Optionale Copilot-Produktiefe: Der Copilot-CLI-Harness.

{width=90%}

Lesart K-04: eine Wahrheit = Runtime + kanonische Commands + Boundaries im Repo, nicht die längste Rules-Datei.

{width=90%}

Lesart K-22 (Landkarte Kap. 4–12): Agent und Team teilen Repo-Wahrheit, Stack-Idiome, Verify und Review — These 7 invers: mehr Alignment-Infrastruktur, nicht mehr Prompt-Autonomie.

Agent-freundlich heißt nicht „maximal autonom“ und nicht „maximal dokumentiert“. Es heißt: wenn der Agent liest, patcht und testet, trifft er dieselbe Runtime, dieselben Commands und dieselben Boundaries wie ein neuer Kollege am ersten Tag — ohne Wiki-Archäologie und ohne „bei mir geht’s“. Agent-freundlich kompensiert die Reibung aus Kap. 3 (Pin, Commands, Boundaries) — es maximiert nicht Autonomie.

4.1 Toolchain: Runtime, Env und Tasks

Commands in Instructions sind nur gültig, wenn die Shell dieselbe Runtime trägt. Szene: Agent startet npm test mit System-Node 18, Repo und CI pinnen Node 22 — „Verify grün“ wird Zufall, der Context füllt sich mit Diagnose-Noise. Dasselbe mit JDK 17 vs. 21 hinter ./mvnw. Du merkst es daran, dass der Agent „kaputte Dependencies“ erklärt, obwohl nur die Toolchain driftet.

Eine Wahrheit gilt auch für die Shell. Version, Env-Schema und Task-Namen gehören als Code ins Repo: reviewbar, agent-auffindbar — Autonomie-Infrastruktur wie Verify-Commands und Ignore-Grenzen. Das Pattern zählt, nicht das Tool (Mise, asdf-Stil, Devbox, Nix-Shell, Devcontainers, direnv, just/Make — Beispiele, gleichrangig). Generische Matrix und Minimum: Coding Agents in der Praxis, Kap. 15.8.

Schicht	Was sie festhält	Stack-Beispiel
Runtime-Pin	Node, JDK (ggf. pnpm/Tool-Versionen)	mise.toml / .tool-versions / Team-Pin + CI-Image
Wrapper / Lock	Build-Einstieg ohne Host-Install-Rätsel	mvnw / gradlew, package-lock / pnpm-lock
Tasks	Kanonische Namen für Tight-Loop / Slice-DoD / Heavy	npm-scripts, Maven/Gradle-Goals, optional just
Env	Nicht-geheime Defaults; Secrets nicht im Chat	direnv / mise [env], Spring-Profiles ohne Klartext-Secrets

Minimum (auch ohne ausgereiftes Platform-Team): eine Runtime-Pin pro Stack-Seite; drei kanonische Tasks (Tight-Loop, Slice-DoD, Heavy); non-interactive Exit-Codes; dieselben Einstiege in Root-Instructions/AGENTS.md, Package-Rules und CI. Surfaces mappen: Anhang C. Isolation (Devbox/Nix/Container) lohnt bei PATH-Drift und systemnahen Deps — nach Schmerz, nicht nach Trend.

In den Vorlagen steht deshalb Runtime / Einstieg vor den Verify-Commands. „Umgebung passt“ ist keine Agent-DoD — und ohne Pin ist jedes „grün“ im Chat nur eine lokale Anekdote.

Vorher / Nachher — eine Wahrheit sichtbar. Drei READMEs, drei Welten — der Agent erbt die lauteste und füllt den Context mit toten Befehlen:

# README (Frontend):  ng test && ng lint
# README (API):       mvn test
# Onboarding-Wiki:    „am besten ./gradlew check, Node aus nvm“

Ein kanonischer Block in Root-AGENTS.md (Package spiegelt denselben Einstieg):

## Runtime / Einstieg
- Node: mise / .tool-versions (CI-Image gleich)
- JDK: ./mvnw bzw. ./gradlew (Wrapper, kein Host-JDK-Rätsel)

## Verify
- Tight-Loop FE: `npm test -- --watch=false` · `npm run lint`
- Tight-Loop BE: `./mvnw -q -Dtest=…Test test`
- Slice-DoD: Tight grün + `npm run build` / `./mvnw -q -DskipTests package` + Diff = Auftrag
- Heavy: CI (`verify` / e2e) — nicht nach jedem Edit

4.2 Eine Wahrheit pro Check

Der Agent darf nicht raten, ob Tests mit ng test, npm test, nx test, mvn test oder ./gradlew test laufen — und schon gar nicht, welche davon „die echten“ sind. Raten kostet Observations, und Observations füllen den Context (Kap. 2.2). Die Commands setzen die Toolchain aus Abschnitt 4.1 voraus (oder benennen den Einstieg explizit, z. B. mise exec -- npm test …).

Die Tabelle ist ein Muster, kein Dogma. Ersetzt die Beispiele durch eure echten Einstiege — einmal, an allen Stellen, an denen Mensch und Agent lesen.

Check	Angular (Beispiel)	Spring Boot (Beispiel)	Quarkus (Beispiel)
Unit / schnell	npm test -- --watch=false / nx test app --watch=false	./mvnw -q -Dtest=FooTest test / ./gradlew test --tests FooTest	./mvnw -Dtest=FooTest test
Lint / Format	npm run lint / nx lint	Spotless/Checkstyle-Target	dasselbe im Modul
Build	npm run build / nx build	./mvnw -q -DskipTests package	./mvnw package -DskipTests
Integration	e2e-Script non-interactive	Failsafe / Testcontainers-Profil	@QuarkusTest scoped

Tragt die echten Befehle in Root-Instructions/AGENTS.md und Package-Rules ein (Surfaces: Anhang C). Platzhalter aus den Templates ersetzen — tote Befehle sind schlimmer als keine: Der Agent führt sie aus, scheitert, und der Thread füllt sich mit Fehlerpfaden, die nie euer DoD waren.

Was ihr gewinnt: Tight-Loop und DoD werden auffindbar. Was ihr verliert, wenn drei READMEs drei verschiedene „so testet man“-Varianten pflegen: Session-Rot und Review-Diskussionen über die Test-Methode statt über den Diff.

4.3 Layout-Optionen

Repo-Layout ist kein Geschmacksstreit für Agents — es entscheidet, wo Context endet und wo Ownership beginnt. Multi-Repo und Monorepo sind beide legitim; sie verlangen nur andere Disziplin.

{width=90%}

Multi-Repo (häufig im Konzern)

frontend-angular/     # AGENTS.md + Convention eures Agents (s. Anhang C)
backend-spring/       # dito, Maven/Gradle
platform-docs/        # ADRs, API-Contracts (optional)

Agent-Folgen: Context endet an der Repo-Grenze. Das ist ein Feature (weniger Müll) und ein Risiko (FE-Session kennt die API-Wahrheit nicht). Contracts (OpenAPI) und Handoff zwischen Front- und Backend-Sessions werden Pflicht — nicht „nice to have“. Siehe Kapitel 8.

Monorepo (Nx, multi-module Maven/Gradle, Hybrid)

/
  AGENTS.md                   # schlank: Mission, Runtime, Verify-Übersicht, Nie/Immer
  .github/                    # optional: product-specific Surfaces (z. B. copilot-instructions)
  CLAUDE.md / .grok/ …        # optional: weitere Surfaces (Anhang C)
  apps/web/                   # Angular + AGENTS.md
  services/api/               # Spring Boot + AGENTS.md
  services/edge/              # optional Quarkus
  packages/contracts/         # OpenAPI / shared types

Agent-Folgen: Alles ist erreichbar — deshalb muss nicht alles permanent im Context liegen. Root-Instructions/AGENTS.md kurz halten; Package-Rules und path-scoped Rules tragen Stack-Details. Ignore: node_modules, target, .angular, Dist-Artefakte, riesige Logs. Sonst indexiert der Agent den Müll, den ihr lokal schon längst ausblendet.

{width=90%}

Lesart K-06: Root = Mission + Verify-Übersicht; Stil und konkrete Commands leben am Package/Pfad — nicht als zweites Root-Essay. (Control Hierarchy weich/hart und Skills/MCP: Kap. 10, Abbildung K-27.)

Progressive Disclosure meint hier: Wissen flughöhengerecht und on-demand laden — Root gibt Mission und Einstiege, Package und Pfad geben Stil und Commands. Wer alles in die Root-Datei stopft, zahlt mit Context und mit Drift, sobald ein Service abweicht.

Vorlagen: templates/agents-md-monorepo-root.md; Surface-Beispiel Copilot: templates/copilot-instructions-monorepo.md.

4.4 Was in Instructions und Package-Rules muss (minimal)

Prinzip: Zwei Höhen, nicht zwei Essays mit denselben 400 Zeilen. Root steuert den Einstieg für den ganzen Workspace (Mission, Runtime, Verify-Übersicht, Immer/Nie). Package trägt die Wahrheit, die nur dort gilt (Stil, konkrete Commands, Golden Paths, Invariants). Progressive Disclosure schützt Context (Kap. 2.2, 10).

Surfaces (kurz)

Dateinamen und Soft-Surfaces der Kern-Agents: Kap. 2.2.1 und Anhang C — hier nicht erneut tabellieren. Inhaltlich zählen zwei Höhen:

Höhe	Job (agent-neutral)	Typische Surfaces
Root / Workspace	Mission, Runtime, Verify-Übersicht, Immer/Nie	Root-AGENTS.md; Copilot zusätzlich .github/copilot-instructions.md; Claude CLAUDE.md; …
Package / path	Stil, konkrete Commands, Golden Paths, Invariants	Package-AGENTS.md; path-scoped Rules (Copilot: applyTo)

Package-AGENTS.md (Inhalt der Jobs — agent-neutral):

1. Stack-Konventionen (Angular-Stil, Spring-Layer, …)
2. Runtime / Einstieg (Versionen, Wrapper, ggf. Task-Runner)
3. Konkrete Verify-Kommandos (Tight-Loop / Slice-DoD / Heavy)
4. Security-Invariants
5. Golden-Path-Dateien

path-scoped Rules (optional): nur wo Glob klar hilft (z. B. apps/web/**, **/src/test/java/**) — siehe templates/path-instructions-*.example.md (Copilot-applyTo als Muster). Path-scoped Rules sind der Hebel, wenn Root sonst explodiert.

Was hier nicht hingehört: Essay über Clean Architecture. Veraltete CLI von 2022. Root und Package als 400-Zeilen-Duplikat. Tool-Krieg (Mise vs. Devbox) in den Root-Instructions. Eine Wahrheit, ein Einstieg — der Rest ist Progressive Disclosure und Kap. 10.

Mapping: Dieselben Jobs (Root kurz · Package detailliert · optional path-scoped · Verify verlinkt) auf die Surfaces eures Agents legen — nicht Dateinamen 1:1 kopieren. Checkliste: Anhang C.

4.5 Weich vs. hart

Prinzip: Instructions sagen dem Agent, wie er arbeiten soll. Permissions und CI entscheiden, was er überhaupt darf. Wer beides vermischt, schreibt „niemals Secrets committen“ in die Rules und lässt YOLO in Shared Repos trotzdem zu — weiches Memory ohne harten Boden.

{width=90%}

Weich	Hart
Instructions, path-scoped Rules, Package-Rules, Skills	Permissions / Tool-Approval, Hooks, CI-Gates

Surfaces: weich = Instructions/AGENTS.md/path Rules/Skills (Dateinamen: Anhang C); hart = Tool-Approval, Sandbox, Hooks, CI. Copilot-Allow/Deny-Startmuster: templates/permissions-hints-enterprise.md (andere Agents: Policy analog mappen). Optionale Copilot-Produktiefe: Der Copilot-CLI-Harness. Kap. 12 zieht Governance und HITL nach — hier zählt nur: Zielbild ohne harte Grenze ist Wunschdenken.

4.6 Ignore und Such-Grenzen

Agents und Repo-Maps ersticken an node_modules/, target/, .git/, generierten Clients, Coverage-HTML und 50-MB-Logs. Das ist kein Randdetail: Index-Müll wird zu Context-Müll, sobald der Agent „zur Sicherheit“ noch eine Ebene tiefer liest.

Harness-Ignore und .gitignore pflegen — und in Instructions kurz sagen, was nicht gelesen werden soll, wenn euer Tool das unterstützt. Pattern-Idee aus dem Theorie-Schwesterbuch auf Java/Angular übersetzen: generierte OpenAPI-Clients, Build-Ausgaben und lokale IDE-Caches gehören nicht in den Sweet Spot der Session.

Do this	Avoid that
dist/, target/, .angular/, Coverage, große Logs ignorieren	Generierte Clients als „Dokumentation“ indexieren
Ignore mit CI-Artefakt-Pfaden abgleichen	Nur lokal ausblenden, Agent sieht alles

4.7 Do this / Avoid that

Die Tabelle verdichtet das Kapitel. Wenn ihr nur eine Seite ins Onboarding legt, dann diese — und die Templates daneben.

Do this	Avoid that
Runtime, Env-Schema und Verify-Tasks im Repo pinnen	Setup nur mündlich / im Wiki / „bei mir geht’s“
Kanonische Einstiege in Instructions, AGENTS.md und CI spiegeln	Mensch und Agent mit unterschiedlichen Entry-Points
Ein dokumentierter Happy Path pro App/Service	Drei widersprüchliche README-„so baut man“
Scoped Tests im Tight-Loop	Immer Full Suite nach jeder Zeile
Kurze Root-Instructions + Package-Details	400 Zeilen Root-Rules für alles
OpenAPI/Contract im Repo	„Schau ins Wiki / frag Team X“ als einzige Quelle
Non-interactive Flags überall	CLI, die auf y/N wartet; interaktive Installer im Loop
Enge Permissions in Shared Repos	/yolo als Team-Default

Wer das umsetzt, hat noch kein perfektes Framework-Kapitel gelesen — aber ein Repo, in dem Kap. 5–9 überhaupt greifen können. Ohne diese Basis optimiert ihr Prompts auf treibsand.

Key Takeaways

• Eine Wahrheit für Runtime und Build/Test/Lint pro Modul — in Instructions/AGENTS.md und Package-Rules auffindbar (Surfaces: Anhang C).
• Toolchain ist Autonomie-Infrastruktur: Pin + Tasks als Code; Pattern vor Tool-Namen.
• Multi-Repo braucht Contracts und Handoff; Monorepo braucht hierarchische Instructions und Ignore.
• Weich (Instructions) und hart (Permissions) sind zwei Jobs.
• Tote Verify-Befehle und tote Runtime-Annahmen sind Context-Gift. Surfaces mappen: Anhang C.

Praktische nächste Schritte

1. Runtime-Pin und drei Tasks (Tight-Loop / Slice-DoD / Heavy) festnageln; in Root-Instructions/AGENTS.md und Package-Rules denselben Einstieg eintragen (Templates: Abschnitt Runtime / Einstieg).
2. Root- und Package-AGENTS.md (plus Convention eures Agents) anlegen oder straffen — Mission, Runtime, Verify, Immer/Nie; keine Architektur-Essays. Surfaces: Anhang C.
3. path-scoped Rules nur für 1–2 klare Globs starten; Permissions-Startmuster im Team festhalten (kein YOLO ohne Policy).
4. Ignore-Grenzen gegen node_modules, target, generierte Clients und Logs prüfen.
5. Danach Framework-Tiefe (Kap. 5–7) oder DoD/Verify (Kap. 9) — je nachdem, wo eure Top-Reibung aus Kap. 3 sitzt.

Das Zielbild ist die Bühne. Die nächsten Kapitel füllen sie mit Angular-, Spring- und Quarkus-Idiomen — auf einer Wahrheit, die der Agent finden kann.