ki-copilot/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). Bei Abweichungen gilt der Lesevertrag: Konzept behalten, Syntax der aktuellen Doku / copilot help folgen.

---

Wozu dieser Anhang – und was er nicht ist

Gedruckte Bücher und PDFs altern bei CLI-Flags, JSON-Feldern und UI-Labels. Was nicht altert, ist der Harness-Kern: Scope eng, Diff lesen, Deny vor YOLO, weich (Instructions) vs. hart (Permissions/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 Repo-Instructions. Team heißt hier: strenger im Git (Never, Review, kein Force-Push, kein YOLO ohne Policy) – nicht Managed Settings / MDM (Org, Kap. 6). Für CI, Hooks, path-scoped Dateien 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/copilot-cli-harness/

Dort unter Material: beispiele.zip und vorlagen.zip.

Im Anhang A (dieses Buch)	Nur online (Begleit-Service → Material)
Minimale Repo- und User-Instructions (Solo + Team-Kern)	path-scoped Instructions, AGENTS.md, Plugin-Skeletons, lange Team-Playbooks
Enge Allow/Deny-Patterns als Startbefehl	Gespeicherte Approvals, vollständige Flag-Hints, CI-Rezepte
Settings-Kern (Bypass-Sperre, URL-Idee)	komplette Settings-JSONC, Local-Overrides, MDM-Details
Ritual Explore → Plan → Code → Verify → Commit	Rezepte mit Session-Commands, Fleet, programmatic CI
Permission-Faustregeln (Yes / Session-Allow / No)	exakte UI-Labels, Screenshots, Session-State
todo-cli: venv + Start	Projektcode, Tests, verdrahtetes Harness, Hooks/Skills/Agents
—	MCP-Configs, GHA-Workflows, Format-/Guard-Hooks

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-Instructions

Zielpfad: .github/copilot-instructions.md
Rolle: weiches Memory für dieses Repo – kurz genug, dass es gelesen wird.

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

# Projekt-Kompass

## Vier Hebel

1. Scope eng halten (kleine Tasks, klarer Arbeitsordner, keine Home-Sessions).
2. Diff lesen vor Commit und Merge.
3. Deny / enge Allowlist vor YOLO und breitem allow-all.
4. Weich (diese Instructions) vs. hart (Permissions, Hooks, Policy).

## Verify

- Vor Commit: VERIFY_COMMAND ausführen (hier den echten Test-/Lint-Befehl eintragen).
- Bei rot: erst erklären, dann fixen – nicht „grün erzwingen“ ohne Diff.

## Immer

- Diff in einem Satz: was und warum.
- Keine Secrets in Commits, Logs oder Chat.

## Nie

- Destruktive Shell auf Home, Root oder unbekannte Pfade ohne explizite Freigabe.
- Force-Push auf shared Default-Branches.
- YOLO / allow-all ohne Sandbox, enge CWD und bewusste Policy.

Nach dem Kopieren: VERIFY_COMMAND ersetzen (z. B. pytest -q, npm test, go test ./…). Keine langen Stack-Essays – die gehören in die Doku des Repos, nicht in den immer geladenen Kompass.

Team-Variante (strenger im Git)

Zielpfad: ebenfalls .github/copilot-instructions.md – wenn das Repo geteilt wird.
Rolle: dieselben Vier Hebel, plus Branching/PR und klare Team-Never-Liste.

# Team-Baseline: your-org/your-repo

## Stack & Commands

- Install / Test / Lint / Build: (echte Befehle eintragen)

## Branching & PR

- Feature-Branches von main; PR-Titel kurz und klar.
- Kein Auto-Merge; menschlicher Review vor Merge.
- Agent darf Branch + PR vorschlagen; Merge nur durch Menschen.

## Agent-Arbeitsweise

1. Explore: relevante Dateien lesen, bevor du schreibst.
2. Plan: bei multi-file Tasks zuerst Plan (Plan Mode), dann Code.
3. Verify: Tests/Lint aus „Stack & Commands“.
4. Diff: vor Commit kurz erklären.

## Immer

- Scope eng; Secrets und Token nicht lesen/loggen/committen.
- Breaking Changes im PR-Text nennen.

## Nie

- Production-Deploy aus der Session.
- git push --force auf geschützte Branches.
- Dependencies ohne Begründung upgraden.
- YOLO (--allow-all / /yolo) ohne Team-Policy und Isolation.

Ausführlicher: vorlagen/copilot-instructions.team.md und Begleit-Service → Material → vorlagen.zip.

---

A.2 User-Instructions-Gerüst

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

Kopierfertig:

# Persönliche Defaults

## Ton

- Knapp, konkret, ohne Marketing-Floskeln.
- Unsicherheit benennen; bei destruktiven Schritten nachfragen.

## Git-Hygiene

- Kleine Commits mit klarer Message.
- Kein Force-Push auf shared Default-Branches.
- Diff lesen, bevor du einen Commit vorschlägst.

## Nie (persönlich)

- Secrets in Chat-Logs, Gists oder geteilten Session-Exporten.
- YOLO / allow-all ohne Sandbox und enge CWD.
- Produktions-Credentials als „Übungsmaterial“ in Agent-Sessions.

Faustregel: Was in jedem deiner Repos gelten soll → User-Datei. Was nur dieses Repo betrifft → Repo-Instructions (A.1). Doppelungen und Widersprüche vermeiden.

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

---

A.3 Enge Permissions-Baseline (Flags)

Rolle: harter Hebel am Start – bevor Session-YOLO.
Precedence (Konzept): Deny schlägt Allow und schlägt breites Allow-all. Exakte Flag-Namen: copilot help permissions der installierten Version.

Kopierfertig – stabilste Patterns; Stack-Tools anpassen, Deny behalten:

# CWD = dein Projektordner (nicht $HOME)
copilot \
  --allow-tool='shell(pytest)' \
  --allow-tool='shell(git status)' \
  --allow-tool='shell(git diff)' \
  --allow-tool='shell(git log)' \
  --deny-tool='shell(rm)' \
  --deny-tool='shell(git push)'

Anpassen ohne den Kern zu verraten:

Statt / zusätzlich	Idee
shell(pytest)	dein Verify-Befehl (npm test, cargo test, …)
write	nur freigeben, wenn der Agent Dateien schreiben soll
weiteres --deny-tool=…	z. B. Force-Push-Varianten, wenn die Hilfe sie trennt

Achtung: --allow-all / YOLO und weites Session-Allow 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: Begleit-Service → Material → vorlagen.zip (Permissions-Hints) und beispiele.zip (Rezept enge Permissions).

---

A.4 Settings-Kern

Zielpfade (Konzept): User- und/oder Repo-settings.json unter dem Copilot-Config-Root bzw. .github/copilot/ – genaue Pfade: Config-Referenz der Doku und Kapitel 2/4.

Kopierfertig – nur der stabile Kern; keine vollständige Schema-Kopie:

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  },
  "allowedUrls": ["*.github.com", "docs.github.com"],
  "deniedUrls": ["*.evil.example"]
}

Was das bewirkt (Konzept):

Schlüssel	Idee
permissions.disableBypassPermissionsMode: "disable"	breite Bypass-Modi (allow-all / YOLO o. Ä.) unterdrücken – Team-/Enterprise-tauglich
allowedUrls / deniedUrls	Netz-Zugriff des Agenten eingrenzen; Deny schlägt Allow

Nur Keys setzen, die in der aktuellen Doku bzw. copilot help config vorkommen. Platzhalter-Domains (*.evil.example) durch eure echten Deny-Listen ersetzen; Allow-Listen eng halten.

Vollständige und aktuelle Version: Begleit-Service → Material → vorlagen.zip / beispiele.zip (Settings-Beispiele, Local-Overrides).

---

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

Einseitiges Ritual – sprachlich stabil, ohne driftende Slash-Label-Pflicht. Session-Werkzeuge für Plan, Diff und Review existieren; Namen und Tasten: ? / Hilfe der laufenden Version (Kapitel 3 und 8).

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.

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 (Terminal, IDE oder Session-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 (Deny für Push behalten, A.3).

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: Begleit-Service → Material → beispiele.zip (Rezepte Plan, Diff/Review) und Kapitel 3 im Buch.

---

A.6 Permission-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-Allow	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-Allow freigibt das Tool, nicht den einen harmlosen Pfad. Erlaubt du rm „für die Session“ wegen einer kleinen 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-Allow.
• Enge Start-Flags (A.3) reduzieren Prompt-Lärm, ersetzen aber nicht das Lesen.

Vollständige und aktuelle Version: Kapitel 1.6 und 2 im Buch; 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) Copilot CLI im Projektordner starten (nicht aus $HOME)
copilot

# Optional eng (siehe A.3):
# copilot --allow-tool='shell(pytest)' \
#   --allow-tool='shell(git status)' \
#   --deny-tool='shell(rm)' --deny-tool='shell(git push)'

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

Trusted Directory nur für Ordner bestätigen, die du kennst. Erste Prompts: „Erkläre … Ändere nichts.“ – dann kleine Edits mit Diff (Kapitel 1).

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

---

Was du jetzt kannst

• den Hybrid-Vertrag anwenden: Kern im Buch, Breite und Drift online

• Solo- und Team-Minima für Repo-Instructions unterscheiden und anlegen

• eine minimale User-Instruction anlegen, ohne Stack-Romane

• eine Session mit enger Allowlist und Deny starten

• den Settings-Kern Bypass-Sperre und URL-Idee setzen

• Explore → Plan → Code → Verify → Commit ohne „ein Prompt für alles“ fahren

• Yes / Session-Allow / No am rm-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.4 in dein Übungs- oder Arbeitsrepo übernehmen.
2. Vollständige Vorlagen und Rezepte aus dem Begleit-Service (Material) entpacken.
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.