Add hybrid Anhang A with stable core templates in the PDF.

Keep full materials online as versioned ZIPs; wire chapter cross-refs,
assembler order, and rebuild the book PDF.
This commit is contained in:
grok-bot committed 2026-07-30 16:44:37 +02:00
1 parent 60f8019939
commit 68739ecf53
14 files changed
+350 -35

No files matched your search

+3 -3
View File
@@ -8,7 +8,7 @@ Build-Regeln für die PDF-Pipeline dieses Buchs.
| Kommando | Wirkung | Wann |
|----------|---------|------|
| `just assemble` | `00–08-*.md` → `build/book.md` | Debug Assembler / Callouts |
| `just assemble` | `00–09-*.md` → `build/book.md` | Debug Assembler / Callouts |
| `just pdf` | assemble + pandoc/lualatex → `dist/copilot-cli-harness.pdf` | nach inhaltlichen Änderungen (wenn Build verlangt) |
| `just pdf-draft` | Draft-PDF mit Wasserzeichen | Review-Runden |
| `just pdf-plain` | ohne gestyltes Template | schneller Layout-Vergleich |
@@ -21,7 +21,7 @@ PDF nur bauen, wenn der Task es verlangt.
## Pipeline
```text
00-einleitung.md … 08-anhang-cheatsheets.md
00-einleitung.md … 09-anhang-a-kernvorlagen.md
│
▼ scripts/assemble_book.py
build/book.md (Callouts → guidekern / guideuebung / guideachtung)
@@ -54,7 +54,7 @@ Diese Marker im Manuskript nicht „verschönern“ oder in andere Markdown-Kons
| Pfad | Rolle | Bearbeiten? |
|------|-------|-------------|
| `00–08-*.md` | Quellkapitel | ✅ ja |
| `00–09-*.md` | Quellkapitel | ✅ ja |
| `scripts/assemble_book.py` | Concat + Callouts | ⚠️ nur mit Auftrag |
| `scripts/check_pdf.py` | QA | ⚠️ nur mit Auftrag |
| `pdf/templates/*`, `pdf/filters/*`, `pdf/styles/*` | Layout | ⚠️ nur mit Auftrag |
+9 -3
View File
@@ -260,7 +260,9 @@ Du brauchst **keine** Copilot-CLI-Vorkenntnisse. Du brauchst Terminal-Basics, Di
### Mitmach-Dateien {#mitmach-dateien}
Beispiele (`beispiele/`) und Vorlagen (`vorlagen/`) liegen **nicht** im PDF.
**Im PDF:** stabile Kernvorlagen und Rituale in [Anhang A](09-anhang-a-kernvorlagen.md). Die vollständigen und laufend aktualisierten Materialien liegen im **Begleit-Service** (versionierte ZIPs mit MANIFEST/SHA256).
Beispiele (`beispiele/`) und erweiterte Vorlagen (`vorlagen/`) erscheinen **nicht** vollständig im PDF – nur die drift-resistenten Kerne in Anhang A.
**Begleit-Service** (ZIPs, Stand, Errata, Hilfe):
@@ -270,12 +272,14 @@ Dort unter *Material* die aktuellen ZIPs (MANIFEST/SHA256). Zusätzlich: *Stand
| Quelle | Was du tust |
|--------|-------------|
| **Anhang A** (dieses Buch) | stabile Kernvorlagen kopieren (Instructions, Permissions-Baseline, Settings-Kern, Rituale) |
| Begleit-Service → *Material* | ZIP in einen **bekannten** Arbeitsordner entpacken (im Archiv u. a. `beispiele/todo-cli`) |
| Buch-Repository | dieselben Pfade als Quellen; dort auch `vorlagen/` |
| Keins von beidem | in Kapitel 1 einen eigenen kleinen Projektordner nutzen |
| Pfad | Rolle |
|------|--------|
| [Anhang A](09-anhang-a-kernvorlagen.md) | stabile Kernvorlagen im Buch (Hybrid-Minima) |
| [`beispiele/todo-cli/`](beispiele/todo-cli/) | Mini-Python-CLI für Kapitel 1–7 (erklären, testen, refaktorieren; Referenz-Harness) |
| [`vorlagen/`](vorlagen/) | kopierfertige Instructions, Hooks, Skills, Agents, Plugin-Skeleton, Settings-Hinweise |
| [`beispiele/configs/`](beispiele/configs/) | generische Settings-/CI-Gerüste |
@@ -315,7 +319,8 @@ Wenn du mit dem Buch arbeitest und ein Prompt-Dialog anders heißt als hier: die
**Kapitel 4–5:** Settings-Tiefe, Sandbox, MCP/Skills/Hooks/Agents/Plugins.
**Kapitel 6:** Teams, Enterprise, programmatisch/CI, Cloud.
**Kapitel 7:** Context, Sessions, Troubleshooting, Drift.
**Kapitel 8:** Cheatsheets und Glossar.
**Kapitel 8:** Cheatsheets und Glossar.
**Anhang A:** stabile Kernvorlagen im Buch; volle Materialien im Begleit-Service.
**Übungen** sind mit **Jetzt selbst machen** markiert. **Achtung**-Callouts sind sparsam und meinen echte Risiken – nicht Marketing-Warnung.
@@ -329,11 +334,12 @@ Wenn du mit dem Buch arbeitest und ein Prompt-Dialog anders heißt als hier: die
- die Surfaces (interaktiv, programmatisch, Cloud, IDE) als **eine Engine** einordnen
- die vier Hebel Scope, Diff, Deny-vor-YOLO, weich/hart nennen
- den Lesevertrag anwenden: Konzept behalten, Syntax der Doku – und bei Abweichung zu Docs/`?`/`copilot help`, Kap. 7.8 bzw. Begleit-Service (Stand/Errata) gehen
- Offline-Kerne in [Anhang A](09-anhang-a-kernvorlagen.md) und vollständige ZIPs im Begleit-Service zuordnen
### Nächste Schritte
1. Wähle Lesepfad A oder B.
2. Kapitel [1 – Laien-Einstieg](01-laien-einstieg.md): installieren, einloggen; Mitmach-Material aus dem [Begleit-Service](https://books.maatini.space/projects/copilot-cli-harness/) (*Material*) oder dem Repo in [`beispiele/todo-cli/`](beispiele/todo-cli/) starten.
2. Kapitel [1 – Laien-Einstieg](01-laien-einstieg.md): installieren, einloggen; Mitmach-Material aus dem [Begleit-Service](https://books.maatini.space/projects/copilot-cli-harness/) (*Material*) oder dem Repo in [`beispiele/todo-cli/`](beispiele/todo-cli/) starten. Stabile Kernvorlagen: [Anhang A](09-anhang-a-kernvorlagen.md).
3. Beim ersten Permission-Prompt: **Yes** üben, Session-Allow sparsam, bei Unsicherheit **No** + Feedback.
Wenn du die Schleife einmal live gesehen hast, liest sich der Rest des Buchs wie Bedienungsanleitung – nicht wie Magie.
+6 -4
View File
@@ -231,7 +231,7 @@ Unbekannte Ordner sind riskant: Ein Agent mit Shell kann Installer und Skripte a
**15–25 Minuten, die den Rest des Buchs tragen.**
Material: [`beispiele/todo-cli/`](beispiele/todo-cli/). **ZIP:** unter [https://books.maatini.space/projects/copilot-cli-harness/](https://books.maatini.space/projects/copilot-cli-harness/) (*Material*) in einen **bekannten** Arbeitsordner entpacken – oder Buch-Repository (siehe Einleitung). Im entpackten Paket bzw. Repo liegt der Pfad `beispiele/todo-cli`. Klein, bekannt, mit Tests. Nicht Produktion.
Material: [`beispiele/todo-cli/`](beispiele/todo-cli/). **ZIP:** unter [https://books.maatini.space/projects/copilot-cli-harness/](https://books.maatini.space/projects/copilot-cli-harness/) (*Material*) in einen **bekannten** Arbeitsordner entpacken – oder Buch-Repository (siehe Einleitung). Im entpackten Paket bzw. Repo liegt der Pfad `beispiele/todo-cli`. Klein, bekannt, mit Tests. Nicht Produktion. Stabile Kernvorlagen (Instructions, enge Flags, Permission-Faustregeln) und die reine Start-Befehlsfolge stehen zusätzlich in [Anhang A](09-anhang-a-kernvorlagen.md).
#### Setup vor dem ersten Prompt
@@ -315,7 +315,7 @@ copilot \
--deny-tool='shell(rm)'
```
**Deny schlägt Allow:** selbst mit `--allow-all-tools` blockiert ein `--deny-tool` das genannte Tool. Das ist der Harness-Hebel „hart“, bevor du YOLO anfasst.
**Deny schlägt Allow:** selbst mit `--allow-all-tools` blockiert ein `--deny-tool` das genannte Tool. Das ist der Harness-Hebel „hart“, bevor du YOLO anfasst. Kompakte Baseline inkl. `git push`-Deny: [Anhang A.3](09-anhang-a-kernvorlagen.md).
---
@@ -362,6 +362,8 @@ copilot --allow-all-tools \
Slash-Commands in der Session (z. B. `/allow-all`, `/yolo` – aktuelle Liste: `?`): erst, wenn du die Risiken von Session-Allow verstanden hast.
Kompakt zum Nachschlagen (ohne driftende Button-Labels): [Anhang A.6](09-anhang-a-kernvorlagen.md).
---
### 1.7 Session steuern: Esc, Hilfe, Context
@@ -415,7 +417,7 @@ Die vier Hebel aus der Einleitung greifen hier praktisch: Scope, Diff, Deny-vor-
| Falsche Dateien / leeres Projekt | `pwd` / CWD; Trusted Directory für den richtigen Ordner? |
| Agent schreibt trotz „nur erklären“ | Prompt enger; Esc; „Ändere noch nichts.“ |
| pytest „not found“ | venv aktiv? `pip install -e ".[dev]"`? |
| `beispiele/todo-cli` fehlt | Nur PDF? [ZIP (Begleit-Service · Material)](https://books.maatini.space/projects/copilot-cli-harness/) in bekannten Ordner entpacken, Repo, oder eigenen Übungsordner |
| `beispiele/todo-cli` fehlt | Nur PDF? [ZIP (Begleit-Service · Material)](https://books.maatini.space/projects/copilot-cli-harness/) in bekannten Ordner entpacken, Repo, oder eigenen Übungsordner; Start-Befehle: [Anhang A.7](09-anhang-a-kernvorlagen.md) |
| Immer wieder Permission-Prompts | normal bei **Yes**; Session-Allow nur bewusst; oder enge `--allow-tool` |
| Alles fühlt sich unsicher an | gut so – mit Deny und ohne YOLO starten |
@@ -427,7 +429,7 @@ Die vier Hebel aus der Einleitung greifen hier praktisch: Scope, Diff, Deny-vor-
1. Installiere Copilot CLI (ein Weg aus 1.2) und prüfe `copilot --version`.
2. `copilot login` (oder `/login` in der Session).
3. Richte [`beispiele/todo-cli/`](beispiele/todo-cli/) ein (`venv`, `pip install -e ".[dev]"`, `pytest -q`).
3. Richte [`beispiele/todo-cli/`](beispiele/todo-cli/) ein (`venv`, `pip install -e ".[dev]"`, `pytest -q` – Befehlsfolge auch [Anhang A.7](09-anhang-a-kernvorlagen.md)).
4. Starte `copilot` **in** `todo-cli`, bestätige Trusted Directory (Session oder merken).
5. Aufgabe A: `store.py` erklären lassen, **ohne** Änderungen.
6. Aufgabe B: eine **minimale** Docstring- oder Kommentar-Änderung, Diff lesen, `pytest -q`.
+5 -4
View File
@@ -106,10 +106,11 @@ Minimum – und oft genug:
Vorlagen:
- Stabile Kernfassung im Buch: [Anhang A.1](09-anhang-a-kernvorlagen.md)
- [`vorlagen/copilot-instructions.minimal.md`](vorlagen/copilot-instructions.minimal.md)
- [`vorlagen/copilot-instructions.team.md`](vorlagen/copilot-instructions.team.md)
Im Beispielprojekt: `beispiele/todo-cli/` (README beschreibt das Harness-Layout). Was die Session dort mitbringt, siehst du an den Dateien – nicht erst im Prompt:
Vollständig und aktuell: Begleit-Service → *Material* → `vorlagen.zip`. Im Beispielprojekt: `beispiele/todo-cli/` (README beschreibt das Harness-Layout). Was die Session dort mitbringt, siehst du an den Dateien – nicht erst im Prompt:
![Was die Session mitbringt: Instructions, Settings, AGENTS — im Repo sichtbar. (todo-cli; Stand Mitte/Ende 2026.)](assets/screenshots/SD-04-instructions-sources.png){width=90%}
@@ -277,7 +278,7 @@ Speichert **Approvals pro Location** (Git-Root bzw. CWD) – z. B. „nicht wi
CLI-Flags (`--allow-tool` / `--deny-tool`) gelten nur für die aktuelle Session und schreiben diese Datei **nicht**. Deny schlägt trotzdem gespeicherte Approvals.
Schema und Matching: [CLI configuration directory](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference) – und die kommentierte Startvorlage [`vorlagen/settings.permissions-hints.md`](vorlagen/settings.permissions-hints.md).
Schema und Matching: [CLI configuration directory](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference) – und die kommentierte Startvorlage [`vorlagen/settings.permissions-hints.md`](vorlagen/settings.permissions-hints.md). Stabile Kernfassung im Buch: [Anhang A.3](09-anhang-a-kernvorlagen.md).
Reset in der Session (Approvals zurücksetzen):
@@ -395,7 +396,7 @@ Beobachte: Wird `pytest` ohne Rückfrage ausgeführt? Wird Write/rm blockiert bz
- Kapitel 3: Alltag – Explore → Plan → Code → Verify → Commit, `/review`, `/pr`, Modelle
- Kapitel 4: Settings-Hierarchie, Trusted Dirs, Sandbox, multi-repo
- Vorlagen kopieren und im eigenen Repo anpassen – nicht ungelesen committen
- Enge Permissions als Session-Rezept: [`beispiele/rezepte/01-enge-permissions.md`](beispiele/rezepte/01-enge-permissions.md) · User-Vorlage: [`vorlagen/user/`](vorlagen/user/)
- Vorlagen kopieren und im eigenen Repo anpassen – nicht ungelesen committen (Kern: [Anhang A](09-anhang-a-kernvorlagen.md); voll: Begleit-Service → *Material*)
- Enge Permissions als Session-Rezept: [`beispiele/rezepte/01-enge-permissions.md`](beispiele/rezepte/01-enge-permissions.md) · User-Vorlage: [`vorlagen/user/`](vorlagen/user/) · Buch-Kern: [A.2 / A.3](09-anhang-a-kernvorlagen.md)
Primärquellen: [Custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions), [About Copilot Memory](https://docs.github.com/en/copilot/concepts/agents/copilot-memory), [Allowing and denying tool use](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools), `copilot help permissions`.
+2
View File
@@ -25,6 +25,8 @@ Der Zyklus ist keine Bürokratie. Er ist die **Fehlerbremse** gegen genau diesen
**Scope eng halten** ist hier der Alltagshebel: pro Prompt Dateien, Done-Kriterium und Stop-Regel nennen – nicht „mach das Feature irgendwie fertig“.
Kurzform zum Mitnehmen (ohne Slash-Pflicht): [Anhang A.5](09-anhang-a-kernvorlagen.md).
---
### 3.2 Explore – ohne Nebenwirkungen
+1 -1
View File
@@ -79,7 +79,7 @@ Wert `"disable"` unterdrückt diese Bypass-Flags und die zugehörigen Slash-Komm
Faustregel (Hebel aus Kap. [2](02-grundlagen-und-konfiguration.md), hier nur am Gelenk): **enge Deny/Allowlist vor Session-YOLO**. Wenn Bypass abgeschaltet ist, bleibst du bei gezielten `--allow-tool` / Interaktions-Approvals.
Siehe Vorlage: [`vorlagen/settings.permissions-hints.md`](vorlagen/settings.permissions-hints.md) · Beispiel: [`beispiele/configs/settings.repo.example.jsonc`](beispiele/configs/settings.repo.example.jsonc).
Siehe Vorlage: [`vorlagen/settings.permissions-hints.md`](vorlagen/settings.permissions-hints.md) · Beispiel: [`beispiele/configs/settings.repo.example.jsonc`](beispiele/configs/settings.repo.example.jsonc). Stabile Kernfassung im Buch: [Anhang A.4](09-anhang-a-kernvorlagen.md). Vollständig und aktuell: Begleit-Service → *Material*.
---
+1 -1
View File
@@ -424,7 +424,7 @@ In einem Demo-Repo (oder [`beispiele/todo-cli/`](beispiele/todo-cli/) als Sandbo
### Nächste Schritte
- Kapitel [07](07-best-practices-troubleshooting.md): Kontext, Sessions, Symptom→Fix, Doku-Drift
- Kapitel [08](08-anhang-cheatsheets.md): Flags, Pfade, Glossar, Vorlagen-Index
- Kapitel [08](08-anhang-cheatsheets.md): Flags, Pfade, Glossar, Vorlagen-Index · stabile Kerne: [Anhang A](09-anhang-a-kernvorlagen.md)
- Vorlagen unter [`vorlagen/`](vorlagen/) und CI-Gerüst unter [`beispiele/configs/`](beispiele/configs/) ins echte Repo übernehmen
- Programmatic/CI als Rezept: [`beispiele/rezepte/04-programmatic-ci.md`](beispiele/rezepte/04-programmatic-ci.md)
- Primärdoku: [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli)
+3 -2
View File
@@ -496,7 +496,8 @@ Fehlt Tool Calling oder Streaming, bricht die CLI mit Fehler ab.
| 3 | Primär: [docs.github.com/en/copilot](https://docs.github.com/en/copilot/) (CLI-How-tos + Reference) |
| 4 | Konzept aus dem Buch anwenden (weich vs. hart, Scope, Diff, Deny vor YOLO) |
| 5 | Optional: [Begleit-Service](https://books.maatini.space/projects/copilot-cli-harness/) – *Stand & Drift* (dokumentierte Produkt-Abweichungen) und *Errata* (Buchfehler); *Schnelle Hilfe* bei typischen Symptomen |
| 6 | Interne Notiz/PR: was sich geändert hat – Team informieren |
| 6 | Offline-Kerne (Rituale, Minima): [Anhang A](09-anhang-a-kernvorlagen.md); Aktualität der vollen Vorlagen: Begleit-Service → *Material* |
| 7 | Interne Notiz/PR: was sich geändert hat – Team informieren |
Was **stabil** bleiben soll (Konzept):
@@ -551,7 +552,7 @@ Was **driften** darf (Syntax): exakte Flag-Namen, Slash-Command-Liste, Default-M
### Nächste Schritte
- Kapitel [08](08-anhang-cheatsheets.md): Slash-Commands, Flags, Pfade, Glossar
- Kapitel [08](08-anhang-cheatsheets.md): Slash-Commands, Flags, Pfade, Glossar · [Anhang A](09-anhang-a-kernvorlagen.md): stabile Kernvorlagen
- Team-Runbook aus 7.7 ableiten
- Offene Config-Lücken aus Kapitel [02](02-grundlagen-und-konfiguration.md)–[06](06-teams-enterprise-ci.md) schließen
+28 -9
View File
@@ -5,6 +5,8 @@
**So nutzt du den Anhang:** Beim Arbeiten offen halten. Slash-Command oder Pfad nachschlagen → bei Unklarheit ins Kapitel springen. **`/help` und `copilot help` sind Source of Truth** – dieser Anhang ist eine Kernmenge (Stand **Mitte/Ende 2026**).
**Hybrid:** Syntax und Slash-Commands hier können driften. **Stabile Kernvorlagen** (kopierfertige Minima, Rituale, Permission-Faustregeln) stehen in [Anhang A](09-anhang-a-kernvorlagen.md). Vollständige und laufend aktualisierte Materialien: Begleit-Service → *Material*.
---
### 8.1 Install & Auth (Spickzettel)
@@ -233,12 +235,14 @@ Yes · Session-Allow · No + Feedback · `/reset-allowed-tools`
}
```
Hinweise: [`vorlagen/settings.permissions-hints.md`](vorlagen/settings.permissions-hints.md), Kapitel [02](02-grundlagen-und-konfiguration.md), [04](04-fortgeschrittene-konfiguration.md), [06](06-teams-enterprise-ci.md).
Hinweise: [`vorlagen/settings.permissions-hints.md`](vorlagen/settings.permissions-hints.md), Kapitel [02](02-grundlagen-und-konfiguration.md), [04](04-fortgeschrittene-konfiguration.md), [06](06-teams-enterprise-ci.md). Minimale kopierfertige Baseline: [Anhang A.3–A.4](09-anhang-a-kernvorlagen.md).
---
### 8.6 Explore → Plan → Code → Verify → Commit
Ritual **ohne** Slash-Pflicht (drift-resistenter): [Anhang A.5](09-anhang-a-kernvorlagen.md). Unten die erweiterte Spickzettel-Form inkl. typischer Session-Commands (Namen: `?` / `/help`).
```text
1. Explore: „Erkläre X. Ändere nichts.“
2. Plan: Shift+Tab / /plan – noch kein Code
@@ -289,10 +293,23 @@ Kapitel [05](05-mcp-skills-hooks-agents-plugins.md).
### 8.8 Vorlagen- und Beispiel-Index
**Begleit-Service** (PDF-Leser): [https://books.maatini.space/projects/copilot-cli-harness/](https://books.maatini.space/projects/copilot-cli-harness/) – unter *Material* ZIPs entpacken, dann `beispiele/…` bzw. `vorlagen/…`. Dort auch Stand & Drift, Errata und schnelle Hilfe.
**Zuerst im Buch:** [Anhang A – Stabile Kernvorlagen](09-anhang-a-kernvorlagen.md) (A.1–A.7, kopierfertig, drift-resistent).
| Vorlage / Beispiel | Ziel im echten Projekt |
|--------------------|-------------------------|
**Vollständig und aktuell:** Begleit-Service → *Material* (`vorlagen.zip`, `beispiele.zip`, MANIFEST/SHA256): [https://books.maatini.space/projects/copilot-cli-harness/](https://books.maatini.space/projects/copilot-cli-harness/). Dort auch Stand & Drift, Errata und schnelle Hilfe. ZIP entpacken, dann `beispiele/…` bzw. `vorlagen/…`.
| Bedarf | Im Buch | Online (ZIP / Repo) |
|--------|---------|---------------------|
| Minimale Repo-Instructions | [A.1](09-anhang-a-kernvorlagen.md) | `vorlagen/copilot-instructions.minimal.md` (+ Team, path-scoped) |
| User-Instructions | [A.2](09-anhang-a-kernvorlagen.md) | `vorlagen/user/` |
| Enge Permissions | [A.3](09-anhang-a-kernvorlagen.md) | `settings.permissions-hints.md`, Rezept 01 |
| Settings-Kern | [A.4](09-anhang-a-kernvorlagen.md) | `beispiele/configs/`, `settings.local…` |
| Ritual Plan/Verify | [A.5](09-anhang-a-kernvorlagen.md) | Rezepte 02–03 |
| Permission-Faustregeln | [A.6](09-anhang-a-kernvorlagen.md) | Kap. 1 + *Stand & Drift* |
| todo-cli Start | [A.7](09-anhang-a-kernvorlagen.md) | `beispiele/todo-cli/` (Code) |
| Skills / Hooks / Agents / MCP / Plugin / CI | — | jeweilige Pfade in `vorlagen/`, `beispiele/` |
| Vorlage / Beispiel (online) | Ziel im echten Projekt |
|-----------------------------|-------------------------|
| [`vorlagen/copilot-instructions.minimal.md`](vorlagen/copilot-instructions.minimal.md) | `.github/copilot-instructions.md` (solo/minimal) |
| [`vorlagen/copilot-instructions.team.md`](vorlagen/copilot-instructions.team.md) | `.github/copilot-instructions.md` (Team-Baseline) |
| [`vorlagen/path-instructions.example.md`](vorlagen/path-instructions.example.md) | `.github/instructions/….instructions.md` |
@@ -414,12 +431,13 @@ Keine Fremd-Agent-Vergleiche in diesem Buch – bewusst.
| 6 | Team-Baseline, CI, Managed Policy | [06](06-teams-enterprise-ci.md) |
| 7 | Kontext-Hygiene, Troubleshooting-Runbook | [07](07-best-practices-troubleshooting.md) |
| 8 | Diesen Anhang als Spickzettel pinnen | 08 |
| 9 | Stabile Kernvorlagen pinnen (Hybrid) | [Anhang A](09-anhang-a-kernvorlagen.md) |
**Minimal-Team-Setup in einer Stunde:**
1. `vorlagen/copilot-instructions.team.md` → `.github/copilot-instructions.md`
2. Deny/Allow-Muster aus `settings.permissions-hints.md`
3. Verify-Skill kopieren
1. Kern aus [Anhang A.1 / A.3 / A.4](09-anhang-a-kernvorlagen.md) oder `vorlagen/copilot-instructions.team.md` → `.github/copilot-instructions.md`
2. Deny/Allow-Muster aus Anhang A.3 bzw. `settings.permissions-hints.md`
3. Verify-Skill aus `vorlagen.zip` kopieren
4. Optional CI-Gerüst ohne Auto-Merge
5. `/help` einmal komplett überfliegen
@@ -429,13 +447,14 @@ Keine Fremd-Agent-Vergleiche in diesem Buch – bewusst.
- Kern-Slash-Commands und Flags nachschlagen, ohne die Kapitel zu durchwühlen
- User- vs. Repo-Pfade und Permission-Patterns korrekt zuordnen
- Vorlagen und Beispiele gezielt ins eigene Repo übernehmen
- **stabile Kerne** aus [Anhang A](09-anhang-a-kernvorlagen.md) und **volle** Vorlagen/Beispiele aus dem Begleit-Service gezielt ins eigene Repo übernehmen
- Begriffe des Harness-Modells einheitlich verwenden
- Offizielle Docs als Source of Truth nutzen
### Nächste Schritte
- Buch schließen und **im echten Repo** eine Baseline committen
- Buch schließen und **im echten Repo** eine Baseline committen (Start: Anhang A)
- Internes Runbook aus Kapitel [07](07-best-practices-troubleshooting.md) ableiten
- Vierteljährlich: `copilot --version`, `/help`, Docs-Changelog gegen eure Configs halten
- Lesevertrag aus Kapitel [00](00-einleitung.md) im Team teilen: Konzept behalten, Syntax verifizieren
- ZIPs im [Begleit-Service](https://books.maatini.space/projects/copilot-cli-harness/) (*Material*) aktuell halten
+279
View File
@@ -0,0 +1,279 @@
# 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.
**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 | Team-/path-scoped Instructions, `AGENTS.md`, Plugin-Skeletons |
| 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:
```markdown
# 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.
*Vollständige und aktuelle Version: Begleit-Service → Material → `vorlagen.zip` (u. a. minimal, Team, path-scoped).*
---
### 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:**
```markdown
# 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:
```bash
# 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:
```json
{
"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:
```text
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:**
```bash
# 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
- eine minimale Repo- und 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](https://books.maatini.space/projects/copilot-cli-harness/) (*Material*) entpacken.
3. Kapitel [8](08-anhang-cheatsheets.md) 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 -4
View File
@@ -57,9 +57,10 @@ Projekt-Regeln für Coding-Agents. Karpathy-Prinzipien, adaptiert auf ein deutsc
| Pfad | Rolle | Agent-Hinweis |
|------|--------|---------------|
| `00-einleitung.md` … `08-anhang-cheatsheets.md` | Kapitel-Quellen (kanonisch) | nach Lesen editieren; Callouts nicht zerstören |
| `vorlagen/` | Fertige Instructions/Hooks/Skills für Leser | Nur bei Vorlagen-Tasks ändern |
| `beispiele/` | Mini-Projekte und Beispiel-Configs | todo-cli hat eigenes `.github/` |
| `00-einleitung.md` … `09-anhang-a-kernvorlagen.md` | Kapitel-Quellen (kanonisch) | nach Lesen editieren; Callouts nicht zerstören |
| `09-anhang-a-kernvorlagen.md` | Stabile Kernvorlagen im PDF (Hybrid) | nur drift-resistente Minima; kein Ersatz für `vorlagen/` |
| `vorlagen/` | Fertige Instructions/Hooks/Skills für Leser (ZIP-Quelle) | Nur bei Vorlagen-Tasks ändern |
| `beispiele/` | Mini-Projekte und Beispiel-Configs (ZIP-Quelle) | todo-cli hat eigenes `.github/` |
| `README.md` | Lesepfad und Übersicht | Kurz halten |
| `abbildungen.md` | Abbildungskatalog / Bild-Specs | Referenz, nicht still umbauen |
| `pdf/`, `scripts/`, `justfile` | Build-Pipeline (optional) | **nur bei explizitem Auftrag** |
@@ -68,7 +69,7 @@ Projekt-Regeln für Coding-Agents. Karpathy-Prinzipien, adaptiert auf ein deutsc
### Build-Befehle (wenn Pipeline vorhanden)
```bash
just assemble # 00–08 → build/book.md
just assemble # 00–09 → build/book.md
just pdf # assemble + pandoc/lualatex → dist/
just qa # scripts/check_pdf.py
just clean
+6 -3
View File
@@ -16,7 +16,7 @@ Stil: klar, unaufgeregt, praxisnah. Kein Marketing, keine leeren Versprechen. Ko
| Einsteiger | [02](02-grundlagen-und-konfiguration.md), [03](03-alltag-und-workflows.md) | Instructions, Permissions, Explore–Plan–Code–Verify–Commit |
| Fortgeschrittene | [04](04-fortgeschrittene-konfiguration.md), [05](05-mcp-skills-hooks-agents-plugins.md) | Settings-Hierarchie, MCP, Skills, Hooks, Agents, Fleet, Plugins |
| Experten & Teams | [06](06-teams-enterprise-ci.md), [07](07-best-practices-troubleshooting.md) | CI, Enterprise, Context/Sessions, Troubleshooting |
| Nachschlagewerk | [08](08-anhang-cheatsheets.md) | Cheatsheets, Vorlagen-Index, Glossar |
| Nachschlagewerk | [08](08-anhang-cheatsheets.md), [09](09-anhang-a-kernvorlagen.md) | Cheatsheets, Glossar; stabile Kernvorlagen (Anhang A) |
Einstieg für alle: [00-einleitung.md](00-einleitung.md). Kapitel 1–3 reichen für den produktiven Alltag; 4–6 bei konkretem Schmerz.
@@ -34,7 +34,7 @@ Einstieg für alle: [00-einleitung.md](00-einleitung.md). Kapitel 1–3 reichen
6. **Erweiterungen** – MCP / Skills / Hooks / Agents / Plugins / Fleet
7. **Teams & CI** – Baseline, programmatic mode, Cloud Agent, Compliance-Orientierung
8. **Best Practices** – Context, Sessions, Symptom→Fix
9. **Anhang** – Cheatsheets
9. **Anhang** – Cheatsheets (Kap. 8) und stabile Kernvorlagen (Anhang A / Kap. 9)
---
@@ -51,6 +51,7 @@ Einstieg für alle: [00-einleitung.md](00-einleitung.md). Kapitel 1–3 reichen
| [06-teams-enterprise-ci.md](06-teams-enterprise-ci.md) | Team-Baseline, CI, Cloud Agent, Credits, Compliance |
| [07-best-practices-troubleshooting.md](07-best-practices-troubleshooting.md) | Context, Sessions, BYOK, Symptom→Fix, Doku-Drift |
| [08-anhang-cheatsheets.md](08-anhang-cheatsheets.md) | Flags, Pfade, Patterns, Vorlagen-Index, Glossar |
| [09-anhang-a-kernvorlagen.md](09-anhang-a-kernvorlagen.md) | Stabile Kernvorlagen im PDF (Hybrid: Buch-Minima + Online-ZIPs) |
---
@@ -61,7 +62,7 @@ ki-copilot/
├── README.md
├── AGENTS.md # Regeln für Agents am Buch (Autoren-Harness)
├── .grok/ # Grok: rules, skills, slash-commands
├── 00-einleitung.md … 08-anhang-cheatsheets.md
├── 00-einleitung.md … 09-anhang-a-kernvorlagen.md
├── abbildungen.md # Bildkatalog (Konzept + SCREEN)
├── assets/illustrations/ # Konzept-Figuren für PDF
├── assets/screenshots/ # Terminal-Screendumps (SD-01…08)
@@ -81,6 +82,8 @@ ki-copilot/
## Vorlagen und Beispiele
**Hybrid:** Im PDF liefert [Anhang A](09-anhang-a-kernvorlagen.md) die stabilen Kernvorlagen. Vollständige und laufend aktualisierte Materialien liegen im Begleit-Service (versionierte ZIPs).
**Begleit-Service:** [https://books.maatini.space/projects/copilot-cli-harness/](https://books.maatini.space/projects/copilot-cli-harness/) — *Stand & Drift*, *Errata*, *Material* (ZIPs mit MANIFEST/SHA256 für `beispiele/` und `vorlagen/`), *Schnelle Hilfe*, *Feedback*.
| Pfad | Inhalt |
BIN
View File
Binary file not shown.
+2 -1
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env python3
"""Assemble Copilot-CLI book chapters for the PDF pipeline.
Concatenates root chapter files ``00-*.md`` … ``08-*.md`` into
Concatenates root chapter files ``00-*.md`` … ``09-*.md`` into
``build/book.md``. Strips per-chapter markdown-only noise that would
duplicate PDF frontmatter. Heading levels stay as written (``#`` =
chapter, ``##`` = section) for KOMA ``scrbook``.
@@ -34,6 +34,7 @@ CHAPTER_ORDER = [
"06-teams-enterprise-ci.md",
"07-best-practices-troubleshooting.md",
"08-anhang-cheatsheets.md",
"09-anhang-a-kernvorlagen.md",
]
# Drop markdown-only TOC blocks if present.