ki-codex/09-anhang-a-kernvorlagen.md

Anhang A

Stabile Kernvorlagen

Kern: Diese Kernvorlagen sind bewusst minimal und stabil gehalten. Vollständige, aktuelle und erweiterte Versionen findest du im Begleit-Service unter Material (versionierte ZIPs) und im Repo unter vorlagen/. Bei Abweichungen gilt der Lesevertrag: Konzept behalten, Syntax der aktuellen Doku / codex --help folgen.

---

Wozu dieser Anhang – und was er nicht ist

Gedruckte Bücher und PDFs altern bei CLI-Flags, TOML-Keys und UI-Labels. Was nicht altert, ist der Harness-Kern: Scope eng, Diff lesen, enge Sandbox vor Full Access, weich (AGENTS.md) vs. hart (Sandbox, Approvals, Rules, Hooks).

Dieser Anhang liefert kopierfertige Minima, die in 12–18 Monaten noch sinnvoll bleiben sollen. Er ersetzt weder die Kapitel 0–7 noch die vollständigen Materialien online.

Solo vs. Team: A.1 hat eine Solo-Minimal- und eine **Team-**Variante derselben Root-AGENTS.md. Team heißt hier: strenger im Git (Never, Review, keine Force-Pushes) – nicht Managed requirements.toml (Org, Kap. 6). Für CI, Hooks und Plugins bleibt der Begleit-Service / vorlagen/ zuständig.

Begleit-Service (ZIPs mit MANIFEST und SHA256, Stand & Drift, Errata, Hilfe):

https://books.maatini.space/projects/codex-harness/

Dort unter Material: beispiele.zip und vorlagen.zip (sobald freigeschaltet).

Im Anhang A (dieses Buch)	Nur online / im Repo-ZIP
Minimale Repo- und User-AGENTS.md	Team-Erweiterungen, nested Overrides, lange Stack-Essays
Sandbox×Approvals-Kern (Auto-Preset)	Profiles, Rules-Starlark, Managed requirements.toml
MCP-Snippet (Pattern)	volle Server-Listen, OAuth-Flows
Ritual Explore → Plan → Code → Verify → Commit	Session-Rezepte, Cloud-Ownership-Playbooks
Approval-Faustregeln (Yes / Session / No)	exakte UI-Labels, Screenshots
todo-cli: venv + Start	Projektcode, Tests, verdrahtetes Harness
—	Hook-Scripts, Plugin-Marketplace, CI-Workflows im Detail

Achtung: Wenn Buch und aktuelle CLI-Hilfe widersprechen, gewinnt die Hilfe der installierten Version – nicht der Anhang. Konzept und Reihenfolge bleiben; Syntax passt du an.

---

A.1 Minimale Repo-AGENTS.md

Zielpfad: Repo-Root AGENTS.md
Rolle: weiches Memory für dieses Repo – kurz genug, dass es gelesen wird (Cap ernst nehmen).

Kopierfertig – stack-neutral; Verify-Command durch den echten Befehl des Repos ersetzen:

# Project compass

## Build & Test

- Install: `pip install -e ".[dev]"` (anpassen)
- Test: `pytest -q`
- Lint: (Projekt-Command)

## Do

- Enger Scope pro Auftrag
- Diff lesen vor Commit
- Tests nach Code-Änderungen

## Don't

- Secrets in Dateien oder Commits
- `rm -rf` / destruktive Git-Befehle ohne explizite Freigabe
- Production-Deploy aus der Agent-Session

## Verify

Nach Änderungen: den Test-Command oben ausführen und kurz berichten.

Team-Variante (Kern, etwas strenger):

# Team baseline — AGENTS.md

## Stack & conventions

- (Sprache, Package-Manager, Branch-Strategie)
- Public APIs dokumentieren, wenn Verhalten ändert

## Build & Test

- `…` install
- `…` test
- `…` lint

## Always

- Scope eng halten; Multi-File nur mit Plan
- Diff und Tests vor PR
- Secrets nie committen

## Never

- Force-push auf shared branches
- Production credentials im Workspace für den Agent
- Auto-merge ohne menschliche Review

## Code Review Rules

### Secrets and config

- Flag hardcoded credentials, API keys, and private URLs in diffs.
  Safe path: env vars / secret manager; document required keys in README without values.

Nach dem Kopieren: Install/Test/Lint ersetzen. Keine langen Stack-Essays – die gehören in die Doku des Repos, nicht in den immer geladenen Kompass. Generator /init ist Startpunkt, nicht Source of Truth – Ergebnis reviewen.

Vollständige und aktuelle Version: Begleit-Service → Material → vorlagen.zip bzw. Repo vorlagen/AGENTS.md.minimal.md, vorlagen/AGENTS.md.team.md.

---

A.2 User-AGENTS.md-Gerüst

Zielpfad: ~/.codex/AGENTS.md (bzw. unter $CODEX_HOME)
Rolle: persönliche Defaults über alle Repos – nicht committen, keine repo-spezifischen Build-Commands.

Kopierfertig:

# ~/.codex/AGENTS.md — persönliche Defaults

## Working agreements

- Prefer small, reviewable diffs
- Run the project test command after code changes when one exists
- Ask before adding new production dependencies

## Never (personal)

- Commit secrets or `.env` contents
- Broaden sandbox to full access without a reason

Faustregel: Was in jedem deiner Repos gelten soll → User-Datei. Was nur dieses Repo betrifft → Root-AGENTS.md (A.1). Doppelungen und Widersprüche vermeiden. Temporärer Global-Override: ~/.codex/AGENTS.override.md (siehe Doku).

Vollständige und aktuelle Version: Begleit-Service → Material → vorlagen.zip (user/…) bzw. vorlagen/user/.

---

A.3 Sandbox × Approvals – Auto-Baseline

Rolle: harter Hebel am Start – bevor Full Access / --yolo.
Zielpfade: ~/.codex/config.toml (User) und/oder trusted .codex/config.toml (Project).

Kopierfertig – stabilster Alltagskern:

# Enge Baseline für lokale Codex-Arbeit (User oder trusted Project).
# Primärdoku: sandboxing + config reference — Keys bei Drift prüfen.

# model = "gpt-5.6"   # je Kontingent/Org anpassen

# Low-friction default: im Workspace schreiben, bei Boundary fragen
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# Full access (NUR bewusst):
# sandbox_mode = "danger-full-access"
# approval_policy = "never"

# web_search = "cached"

CLI-Äquivalent:

codex --sandbox workspace-write --ask-for-approval on-request

Absicht	Einstellung
Nur lesen/erklären	sandbox_mode = "read-only" (+ on-request)
CI read-only	read-only + approval_policy = "never"
Extra-Ordner ohne Full Access	[sandbox_workspace_write] writable_roots = […]
Full Access	nur isoliert; nie Default auf dem Alltags-Laptop

Project-Config greift nur bei Project Trust. Untrusted = Projekt-.codex/ wird übersprungen.

Achtung: danger-full-access und approval_policy = "never" (bzw. --yolo) sind kein Alltag auf Laptops mit echten Credentials. Erst eng starten; erst erweitern, wenn du die Bremse kennst (Kapitel 1–2, 4, 6).

Vollständige und aktuelle Version: vorlagen/config.permissions.toml, beispiele/configs/config.repo.example.toml.

---

A.4 MCP-Snippet (Pattern)

Rolle: externe Tools andocken – ohne Secrets im Repo.
Ziel: User- oder trusted Project-config.toml unter [mcp_servers].

Kopierfertig – nur Pattern; Server und Tokens anpassen:

# MCP-Server-Beispiel — Tokens nur in Env, nie committen.
# CLI-Alternative: codex mcp add … (Doku)

# [mcp_servers.filesystem]
# command = "npx"
# args = ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/path"]

# [mcp_servers.github]
# command = "npx"
# args = ["-y", "@modelcontextprotocol/server-github"]
# env_vars = ["GITHUB_TOKEN"]

# Remote MCP (Beispiel-Pattern):
# [mcp_servers.example_remote]
# url = "https://example.com/mcp"
# bearer_token_env_var = "YOUR_TOKEN"

Stabil bleibt:

Idee	Praxis
STDIO	command + args
HTTP	url + Auth aus Env
Token	Env-Var-Name, nie Literal im TOML im Git
Tool-Fläche eng	enabled_tools / disabled_tools (Doku)
Approval	MCP mit Write = wie andere riskante Tools

codex mcp list
# In der Session: /mcp

MCP hebt Sandbox und Approvals nicht auf. Start mit read-only/docs-Servern, nicht mit Shell-Write-Servern.

Vollständige und aktuelle Version: vorlagen/config.mcp.toml, Kapitel 05, MCP-Doku.

---

A.5 Explore → Plan → Code → Verify → Commit – Kurzrezept

Einseitiges Ritual – sprachlich stabil, ohne driftende Slash-Label-Pflicht. Die Reihenfolge ist der Kanon; Slash-Commands sind optional und driftfähig. Spickzettel mit typischen Session-Commands: Kapitel 8.6; Alltag: Kapitel 3.

Kopierfertig – Checkliste pro Aufgabe:

1. Explore
   „Erkläre X. Ändere nichts.“
   Ziel: verstehen, bevor der Agent schreibt.

2. Plan
   Struktur und Dateiliste klären – noch kein Produktiv-Code.
   Plan lesen, anpassen, erst dann freigeben. (/plan)

3. Code
   „Setze den freigegebenen Plan um – nicht mehr.“
   Scope eng halten; bei Drift: stoppen, Plan nachziehen.

4. Verify
   Projekt-Verify (A.1) ausführen.
   Rot → erklären → fixen → erneut Verify.

5. Diff
   Menschlich lesen (/diff oder git diff).
   Unerwartete Dateien / Secrets / Scope-Verletzung → ablehnen oder zurück.

6. Commit
   Erst nach gelesenem Diff und grünem Verify.
   Merge / Push bleibt menschliche Entscheidung.

Plan-Datei (optional, gegen Compact-Verlust):

# Plan: <!-- kurzer Feature-Titel -->

**Status:** draft | approved | done

## Ziel

<!-- Ein Absatz: was soll am Ende wahr sein? -->

## Nicht-Ziele

- …

## Schritte

1. [ ] Explore: …
2. [ ] Tests/Contract: …
3. [ ] Implementierung: …
4. [ ] Verify: …
5. [ ] Diff + Commit-Message-Entwurf: …

## Done when

- [ ] Tests grün
- [ ] Keine Secrets im Diff
- [ ] Kurze Zusammenfassung für Reviewer

Warum die Reihenfolge: Fehler akkumulieren in Tool-Ketten. Explore und Plan sind billig; ungelesene Diffs und YOLO-Commits sind teuer.

Vollständige und aktuelle Version: vorlagen/PLAN.md.skeleton.md, Kapitel 03.

---

A.6 Approval-Prompt-Faustregeln

Sobald der Agent etwas Riskantes ausführen oder schreiben will, kommt ein Freigabe-Dialog. Wortlaut der Buttons driftet – die Entscheidung bleibt:

Entscheidung	Wirkung (Konzept)	Wann typisch
Yes (einmal)	dieses Mal erlauben; nächstes Mal wieder fragen	Lesen, Verify, einmaliges Write nach Diff-Blick
Session-Scope	Tool für den Rest der Session ohne erneute Nachfrage (oft inkl. anderer Argumente)	häufige, harmlose Tools (status, Tests) – bewusst
No + Feedback	abbrechen; anderen Weg verlangen	unklar, destruktiv, unerwarteter Scope

Achtung: Session-Scope freigibt das Tool, nicht den einen harmlosen Pfad. Erlaubt du destruktive Shell „für die Session“ wegen einer Temp-Datei, darf derselbe Agent später auch breitere Löschbefehle vorschlagen und ausführen, ohne dich erneut zu fragen. Für rm, Push und Installer: lieber Yes einmal nach Lesen – oder No.

Tag-1-Faustregeln:

• Unklar → No + ein Satz Feedback („nur im Projektordner lesen, nichts löschen“).
• Destruktiv / Netz-Installer / unbekannte Skripte → kein Session-Scope.
• Auto-Preset (A.3) reduziert Prompt-Lärm, ersetzt aber nicht das Lesen.
• Project Trust nur für Ordner, die du kennst.

Vollständige und aktuelle Version: Kapitel 01 und 02; Begleit-Service bei dokumentierter UI-Drift (Stand & Drift).

---

A.7 Schnellstart todo-cli (ohne Code)

Das Mini-Projekt beispiele/todo-cli ist das durchgängige Übungsrepo der Kapitel 1–7. Code, Tests und verdrahtetes Harness liegen nur im ZIP bzw. Buch-Repository – hier nur die Befehlsfolge.

Voraussetzung: ZIP aus dem Begleit-Service (Material → beispiele.zip) in einen bekannten Arbeitsordner entpacken – oder Buch-Repository klonen. Danach existiert der Pfad beispiele/todo-cli.

Kopierfertig:

# 1) Ins Mini-Projekt
cd beispiele/todo-cli

# 2) Isolierte Python-Umgebung
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -q                          # sollte grün sein

# 3) Codex im Projektordner starten (nicht aus $HOME)
codex

# Optional eng (siehe A.3):
# codex --sandbox workspace-write --ask-for-approval on-request
# oder read-only:
# codex --sandbox read-only --ask-for-approval on-request

Ohne venv und pip install scheitern Test-Aufgaben – das ist kein Codex-Bug. Erklären ohne Edits geht auch ohne venv; Verify-Übungen brauchen die Umgebung.

Project Trust nur für Ordner bestätigen, die du kennst. Erste Prompts: „Erkläre … Ändere nichts.“ – dann kleine Edits mit Diff (Kapitel 1). Optional: AGENTS.md im Mini-Projekt lesen; trusted .codex/config.toml aus beispiele/configs/ kopieren.

Vollständige und aktuelle Version: Begleit-Service → Material → beispiele.zip (beispiele/todo-cli/…) bzw. Repo beispiele/todo-cli/.

---

Was du jetzt kannst

• den Hybrid-Vertrag anwenden: Kern im Buch, Breite und Drift online
• eine minimale Repo- und User-AGENTS.md anlegen, ohne Stack-Romane
• eine Session mit Auto-Preset (Sandbox × Approvals) starten
• ein MCP-Pattern ohne Secrets im Git andocken
• Explore → Plan → Code → Verify → Commit ohne „ein Prompt für alles“ fahren
• Yes / Session-Scope / No am Risiko unterscheiden
• todo-cli aus dem ZIP starten und die erste Session im richtigen CWD öffnen

Nächste Schritte

1. Kernvorlagen aus A.1–A.3 in dein Übungs- oder Arbeitsrepo übernehmen.
2. Vollständige Vorlagen und Beispiele aus dem Begleit-Service (Material) entpacken – oder aus vorlagen/ / beispiele/ im Buch-Repo.
3. Kapitel 8 als Spickzettel für Flags/Slash-Commands nutzen – Syntax dort und in der Doku verifizieren.
4. Bei Abweichung: Lesevertrag (Einleitung) + Stand & Drift / Errata im Begleit-Service.
5. Zurück zu Kapitel 1, wenn du den Tag-1-Pfad noch einmal fahren willst.