0 Fork 0

Files

T

grok-bot 60f8019939 Add Copilot-CLI-Harness manuscript, materials, and companion links.

Full book sources (00–08), vorlagen/beispiele, PDF pipeline, and links to
books.maatini.space/projects/copilot-cli-harness for ZIPs, stand, and errata.

2026-07-30 13:27:26 +02:00

16 KiB

Raw Permalink Blame History

Auftrag: Praxisbuch „Der Copilot-CLI-Harness“ erstellen

Du bist Autor und Repo-Architekt für ein deutschsprachiges Praxisbuch über GitHub Copilot CLI. Ziel: ein vollständiges Buch-Repository analog zum strukturellen Vorbild eines bestehenden Harness-Praxisbuchs – aber inhaltlich vollständig eigenständig und ausschließlich auf GitHub Copilot CLI bezogen.

Ziel-Repo (Default): dieses Repository (ki-copilot), Root-Ebene.

Strukturelles Vorbild (nur Form): falls erreichbar ../ki-claude – Kapitelzahl, Callouts, Vorlagen-Idee, PDF-Pipeline-Idee. Inhalt, Terminologie und Beispiele neu und Copilot-native.

Stand der Fakten: Mitte/Ende 2026. Primärquelle: offizielle GitHub-Docs.

0. Absolute Verbote

Kein Vergleich mit Claude Code, Cursor, Codex, Grok Build oder anderen Agents im Manuskript (keine Kapitel, keine Tabellen, keine „anders als …“- Sätze, kein Pattern-Transfer-Anhang mit Fremdtools).
Keine erfundenen Slash-Commands, Flags, JSON-Felder, Pfade oder UI-Labels. Primärquelle: https://docs.github.com/en/copilot/ (CLI-Bereich). Bei Unsicherheit: Unsicherheit und Stand Mitte/Ende 2026 benennen; Doku schlägt Buch.
Keine Secrets in Beispielen – Platzhalter YOUR_TOKEN, your-org/your-repo.
Kein Marketing, keine leeren Versprechen, kein Hype.
Autoren-Harness (Root-AGENTS.md, Agent-Config) und Leser-Content (vorlagen/, beispiele/) strikt trennen.

1. Buch-Identität

Feld	Wert
Titel	Der Copilot-CLI-Harness – Instructions, Permissions, MCP und Workflows in der Praxis
Produkt	GitHub Copilot CLI (`copilot`)
Sprache	Deutsch (Du-Ansprache); Produktnamen/Pfade original
Ton	erfahrener Kollege: präzise, geduldig, praxisnah
Stand Fakten	Mitte/Ende 2026
Zielgruppe	Entwickler mit Terminal-Basics; Stufen Laien → Teams
Erfolg	Leser steuern den Agenten über Memory, Permissions, Plan und Diff – nicht nur über Chat

These des Buchs (durchgängig): Copilot CLI ist ein allgemeiner Coding-Agent im Terminal; das Buch lehrt den Harness um Modelle: Tools, Freigaben, Instructions, Sessions und GitHub-Workflows. Wer die Schleife kennt, steuert gezielter.

2. Strukturelles Vorbild (nur Form, nicht Inhalt)

Nutze als Form-Vorlage, falls im Workspace vorhanden (../ki-claude):

Kapiteldateien 00–08, Callout-Konventionen, vorlagen/, beispiele/todo-cli/
Build: just + assemble + pandoc/lualatex + QA

Inhalt, Terminologie, Pfade und Beispiele neu schreiben – Copilot-native. Wenn kein Vorbild-Repo greifbar ist: diese Spezifikation allein reicht.

3. Harness-Modell (im Buch lehren)

Vermittle diese Schichten – immer mit Copilot-Namen:

Modell – wählbar (/model, Auto, optional eigener Provider)
Harness – CLI führt Tools aus, prüft Permissions, lädt Instructions
Memory (weich) – Custom Instructions / AGENTS.md steuern Verhalten über Kontext
Policy (hart) – Trusted dirs, Tool allow/deny, Hooks, Sandbox – erzwingen
Loop – Explore → Plan → Code → Verify → Commit (+ Diff lesen)
Erweiterungen – MCP, Skills, Hooks, Custom Agents, Plugins
GitHub-Native – Issues, PRs, Cloud Agent (/delegate), eingebaute GitHub-MCP

Vier wiederkehrende Hebel (max. 2–3 Reprisen pro Kapitel, am Gelenk, mit Brücke):

Scope eng halten
Diff lesen vor Merge/Commit
Deny / enge Allowlist vor Session-YOLO (--allow-all / /yolo)
Weich (Instructions) vs. hart (Permissions, Hooks)

Terminologie (kanonisch)

Begriff	Verwendung
GitHub Copilot CLI	Produkt
Harness	Tools + Permissions + Memory + Loop ums Modell
Custom Instructions	weiches Memory (`.github/copilot-instructions.md` etc.)
Permissions / Tool-Approval	hart: freigeben/blocken
`settings.json`	Verhalten/Policy-Schalter (User/Repo/Local)
MCP	externe Tool-Server
Skills	on-demand Workflows (`SKILL.md`)
Hooks	erzwungene Lifecycle-Skripte
Custom Agents / Subagents	Spezialisierung + Kontext-Ventil
Plugins	gebündelte Customizations
Plan Mode / Autopilot / Fleet	Steuerungsmodi

4. Kapitelplan (kanonische Dateien)

Erzeuge und fülle:

00-einleitung.md
01-laien-einstieg.md
02-grundlagen-und-konfiguration.md
03-alltag-und-workflows.md
04-fortgeschrittene-konfiguration.md
05-mcp-skills-hooks-agents-plugins.md
06-teams-enterprise-ci.md
07-best-practices-troubleshooting.md
08-anhang-cheatsheets.md
README.md
AGENTS.md
abbildungen.md          # Katalog, Specs – Illustrationen können später folgen
vorlagen/               # kopierfertig für Leser
beispiele/todo-cli/     # Mitmach-Mini-Projekt
beispiele/configs/      # generische Settings / CI-Gerüst

Optional wenn PDF-Pipeline gewünscht (wie Schwesterprojekte; nachrangig zu Kapiteln):

justfile, scripts/assemble_book.py, scripts/check_pdf.py,
pdf/templates/, pdf/styles/, pdf/metadata.yaml

4.1 Kapitel-Inhalte (Pflichtthemen)

00 Einleitung

Warum Buch ≠ Doku (Lernpfad vs. Referenz)
Modell vs. Harness
Agent-Schleife: Prompt → Tool-Vorschlag → Permission → Ausführung → Ergebnis
Surfaces kurz: interaktiv, programmatic, Cloud, IDE – eine Engine
Zwei Lesepfade (Hands-on zuerst / Konzept zuerst)
Lesevertrag: Produkt-Drift; bei Abweichung Doku + Konzept behalten
Vorkenntnisse ehrlich (Terminal, Git, kein Non-Coder-Buch)
Kein Fremdtool-Vergleich

01 Tag-1-Einstieg

Installation (laut aktueller Doku: OS Linux/macOS/Windows+WSL)
copilot login / Token-Env für Headless
Start in Projektordner; Trusted directory-Dialog erklären (Session vs. merken)
Erste harmlose Aufgaben am todo-cli (erklären, kleinen Fix, Test laufen lassen)
Permission-Prompt: Yes / Session-Allow / No + Feedback
Esc stoppen; ? / /help
Sicherheits-Basics: kein Home-Dir als CWD; keine Secrets committen; Diff ansehen
Übung Jetzt selbst machen

02 Grundlagen und Konfiguration

Szene: leeres Repo → falscher Stack/Test-Command
Weich: Custom Instructions
- Repo: .github/copilot-instructions.md
- Path-scoped: .github/instructions/**/*.instructions.md mit applyTo
- AGENTS.md (Discovery)
- User: ~/.copilot/copilot-instructions.md, modular ~/.copilot/instructions/
- /instructions zum Ein-/Ausblenden; Reload-Verhalten (Session neu/--continue)
- copilot init wo sinnvoll
Hart: Permissions & Settings
- Tool-Approval und Session-Allow-Risiko (Beispiel rm)
- Flags: --allow-tool, --deny-tool, --allow-all-tools (Risiko klar)
- permissions-config.json (gespeicherte Approvals pro Location)
- Minimum: enge Allowlist für Test/Git-Status, Deny für destruktiv wo möglich
Faustregel: „sollte nicht“ → Instructions; „darf nicht“ → deny/Hook/Sandbox
Kurze, konkrete Instructions (Build/Test, 5–15 Zeilen Layout, 2–3 Immer/Nie)
Vorlagen verlinken

03 Alltag und Workflows

Explore → Plan → Code → Verify → Commit
Plan Mode (Shift+Tab / /plan), Plan reviewen, freigeben
Autopilot: wann ja/nein
@datei, #issue/pr, !shell, Bilder/PDF wo relevant
/diff, Steering, Queue während Thinking
Modelle: /model, wann starkes vs. günstiges Modell; Credits//usage
GitHub-Alltag: Issue bearbeiten, PR erstellen, Review anfordern – über CLI
/delegate vs. lokal arbeiten (Entscheidungsmatrix)
Mikrogeschichte: Feature von Issue bis PR

04 Fortgeschrittene Konfiguration

Settings-Hierarchie (Defaults → MDM → User → Repo → Local → Env → Flags)
Pfade: ~/.copilot/settings.json, .github/copilot/settings.json, .github/copilot/settings.local.json, COPILOT_HOME
Path-scoped Instructions vertiefen; Konflikte vermeiden (Docs: combine, no general precedence)
Trusted dirs, /add-dir, /cwd, multi-repo
URL allow/deny; Network-Risiken
Sandbox lokal vs. Cloud
Session-State grob (session-state/, resume) – Details in Kap. 7

05 MCP, Skills, Hooks, Agents, Plugins

Entscheidungsmatrix (Härtegrade):

Bedarf	Mittel
Immer gültige Normen	Custom Instructions
Wiederholbarer Task on-demand	Skill
Neue externe Fähigkeiten	MCP
Erzwingen / Guardrail	Hook (preToolUse etc.)
Spezial-Persona / Tool-Subset	Custom Agent
Bundle verteilen	Plugin

MCP: GitHub MCP built-in; weitere Server; mcp-config.json / /mcp; Angriffsfläche
Skills: SKILL.md, Orte (.github/skills, ~/.copilot/skills, …), /skills, allowed-tools Warnung
Hooks: Events (sessionStart/End, userPromptSubmitted, pre/postToolUse, …), .github/hooks/*.json version 1; bash+powershell
Built-in Agents (Explore, Task, General purpose, Code review, Research, Rubber duck)
- eigene Agent-Profiles (User/Repo/Org)
/fleet: Parallelisierung, Credits-Kosten, wann sinnvoll
Plugins/Marketplaces: installieren, reviewen vor Trust

06 Teams, Enterprise, CI

Team-Baseline: gemeinsame Instructions im Repo, Review-Pflicht, Conventions für Plan/Delegate
Org/Enterprise Custom Agents (.github-private /agents laut Doku)
MDM / managed settings wo dokumentiert; permissions.disableBypassPermissionsMode
Programmatic: copilot -p "…" --deny-tool=… --allow-tool=…
Auth für CI: unterstützte Token-Typen (fine-grained PAT mit Copilot Requests; keine classic ghp_ laut Doku Stand Mitte 2026) – exakt nach aktueller Doku formulieren
Cloud Agent + Branch Protection + menschlicher Merge
Kosten/Credits, Session-Limits
Compliance-Orientierung (Audit, Datenschutz, AI Act) – nüchtern, ohne Rechtsberatung
Kein Auto-Merge als Empfehlung

07 Best Practices & Troubleshooting

Context: /context, /compact, Auto-Compact; fokussierte Sessions (/clear)
Session hygiene: /resume, --continue, Checkpoints
Sandbox & YOLO-Risiken
Multi-repo Patterns
Modell- und Provider-Wahl; BYOK-Grenzen (tool calling + streaming Pflicht)
Symptom→Fix-Raster (Hooks feuern nicht, Instructions greifen nicht, Permission fragt immer, Context voll, Auth fehlschlägt, …)
Vorgehen bei Doku-Drift

08 Anhang Cheatsheets

Slash-Commands (Kernmenge + Hinweis /help ist Source of Truth)
CLI-Flags & copilot help Topics
Dateipfade (User/Repo)
Permission-Patterns (shell(git:*), write, MCP-Namen)
Vorlagen-Index
Glossar (Harness, Instructions, Hook, Skill, Fleet, …)
Ressourcen: nur GitHub-Docs + offizielle Blog/Skills – keine Fremd-Agent-Vergleiche

4.2 Kapitel-Konventionen (Form)

Jeder größere Block wo vorgesehen:

Einstieg mit > **Kern in einem Satz:** … oder > **Kern:** …
Szene/Leserproblem vor der ersten großen Lookup-Tabelle
Tabellen/Code mit 1–3 Sätzen einrahmen (Wie + Warum)
Bei großen Blöcken: Checkliste, häufige Fehler, „So baust du das nach“
Abschluss: Was du jetzt kannst / Nächste Schritte
Übungen: **Jetzt selbst machen**
> **Achtung:** nur für echte Risiken (sparsam)

Stil:

Aktive, konkrete Sätze; Floskeln streichen
Mindestens 2–3 konkrete Beispiele pro Kapitel (Terminal, Config, Vorher/Nachher)
Pro ###: mind. ein Wie und ein Warum
1–2 Frage-Überschriften pro Kapitel wo sinnvoll (z. B. „Warum greift meine Instruction nicht?“)

5. Vorlagen und Beispiele (Leser-Content)

5.1 `vorlagen/` (mindestens)

copilot-instructions.minimal.md → Zielpfad .github/copilot-instructions.md
copilot-instructions.team.md
path-instructions.example.md (mit applyTo Frontmatter)
settings.permissions-hints.md oder kommentiertes JSON-Beispiel für enge Allow/Deny-Flags (CLI) + Hinweise zu permissions-config.json
hooks/guard-pretool.example.json + optionales Script
hooks/format-posttool.example.json
skills/verify/SKILL.md (Test/Lint-Verify-Workflow)
agents/security-reviewer.agent.md (oder korrekte Dateiendung laut Doku)
PLAN.md.skeleton.md
mcp-config.beispiel.json (ein Server, Platzhalter)

5.2 `beispiele/todo-cli/`

Mini-Python-CLI (add/list/done) mit pytest – vollständig lauffähig, inkl.:

App-Code + Tests
.github/copilot-instructions.md (Build/Test, Layout, Immer/Nie)
optional path-scoped Instructions für tests/**
Beispiel-Hook (z. B. Format oder Guard)
Verify-Skill
README: „So startest du copilot hier“

Kein aufgeblasener App-Stack.

6. Repo-Meta und Autoren-Harness

README.md: Lesepfad-Tabelle, Verzeichnisstruktur, Vorlagen-Index, Quellen, Build
AGENTS.md: Regeln für Agents am Buch (Deutsch, Callouts, Doku-Fakten, chirurgische Edits, PDF nur auf Auftrag) – nicht als Leser-Kapitel
Optional .github/ für das Buch-Repo selbst (eigene Instructions), getrennt von vorlagen/

7. Fakten-Checkliste (vor dem Schreiben jedes Kapitels)

Gegen aktuelle GitHub-Docs verifizieren:

Installationswege und Auth
Trusted directories Verhalten
Instruction-Discovery und unterstützte Dateien
Settings-Hierarchie und Schlüssel nur wenn in Doku
Permission-Flags und Precedence (deny > allow)
Slash-Commands der behandelten Features
Hook-Events und Config-Orte
Skill-Pfade und Frontmatter
Custom Agent Orte (User/Repo/Org)
/fleet, Plan, Autopilot, /delegate
Programmatic mode und CI-Token-Regeln
Context/Compact-Verhalten

Wenn Doku und ältere Blogposts widersprechen: Docs gewinnen.

8. Qualitätskriterien (Definition of Done)

Alle Kapitel 00–08 existieren, in sich stimmig, Querverweise greifen.
Eigenständiges Narrativ: ein Leser ohne Kenntnis anderer CLI-Agents versteht alles.
Null Vergleichs-Rhetorik zu anderen Coding-Agents.
Vorlagen und todo-cli nachbaubar; Platzhalter statt Secrets.
Terminologie konsistent (Tabelle Abschnitt 3).
Callouts und Abschlüsse wie spezifiziert.
README erklärt Lesepfad und Build.
Keine erfundenen Features; Drift-Hinweis in 00 und 07.
Optional: just assemble / just pdf / just qa lauffähig, wenn Pipeline gebaut.

9. Arbeitsreihenfolge

Repo-Gerüst + README-Skelett + AGENTS.md
beispiele/todo-cli + Kern-vorlagen/
Kapitel 00 → 01 → 02 → 03 (Alltags-Pfad fertig)
Kapitel 04 → 05
Kapitel 06 → 07 → 08
Querverweise, Wiederholungs-Echo kürzen, Cheatsheets mit Manuskript abgleichen
Fakten-Pass gegen docs.github.com
Optional PDF-Pipeline und QA-Keywords (Copilot CLI, instructions, permissions, MCP, …)

10. Output-Format deiner Arbeit

Schreibe echte Dateien ins Ziel-Repo (nicht nur Outline im Chat).
Nach Meilensteinen: kurze Statusmeldung (was fertig, was als Nächstes).
Am Ende: Inhaltsverzeichnis mit Einzeiler-Zusammenfassung pro Kapitel + Liste der Vorlagen.

11. Primärquellen (start set)

Bei jedem Kapitel: relevante Unterseiten nachschlagen, nicht aus dem Gedächtnis raten.

12. Autoren-Hinweis (nicht ins Buch)

Interne Achsen-Übersicht und Abgrenzung zu anderen Agents: siehe research/copilot-cli-achsen.md. Diese Datei ist kein Manuskript-Inhalt und darf nicht als Kapitel übernommen werden.

16 KiB Raw Permalink Blame History Unescape Escape