ki-copilot/07-best-practices-troubleshooting.md

Kapitel 7

Best Practices und Troubleshooting

Kern in einem Satz: Die meisten „Copilot spinnt“-Tickets sind Kontext-, Permission-, Trust- oder Erwartungsprobleme – und die löst man mit Systematik, nicht mit lauteren Prompts.

Du brauchst dieses Kapitel, wenn Sessions teuer und unscharf werden, /compact „irgendwas“ löscht, Freigaben nicht greifen oder das Ticket wörtlich „Copilot macht Unsinn“ heißt. Lautere Prompts helfen selten – oft ist das Fenster voll, die falsche Schicht geladen oder Wissen nur im Chat.

Schnell: 7.7 Symptom → Fix · Kontext: 7.2–7.3 · Sessions & Remote: 7.3–7.3b · Persistenz: 7.4 · Sandbox/YOLO: 7.5 · Multi-Repo & Modelle: 7.6 · Drift: 7.8

Lesevertrag: Kapitel 00 – Produkt driftet; Konzept behalten, Syntax mit /help und docs.github.com verifizieren.

---

7.1 Best Practices – kompakt

Kurz genug zum Abhaken; die Mechanik steckt in den folgenden Abschnitten.

Prompts

1. Ziel + Nicht-Ziel + Verify – sonst steuerst du nur Hoffnung
2. Dateipfade nennen (@datei), wenn bekannt
3. „Ändere nichts“ bei Explore – Default ist Handeln, nicht nur Lesen
4. Bei Fehlern: komplette Fehlermeldung, nicht „geht nicht“

Repo

1. Instructions kurz und konkret (Build/Test, 5–15 Zeilen Layout, 2–3 Immer/Nie)
2. Deny / enge Allowlist von Tag 1 – Incident teurer als ein Flag-Snippet
3. Skills für Prozeduren, Instructions für Normen, Hooks für Zwang
4. Kleine PRs – auch wenn der Agent 30 Dateien anbietet

Sessions

1. Ein Thema pro Session
2. /context lesen, bevor du „lauter“ promptest
3. /plan vor multi-file
4. /compact mit Fokus-Hinweis, nicht blind am Limit
5. Entscheidungen in Dateien persistieren (PLAN.md, Instructions)
6. Vor Merge: Diff lesen; frische Review-Session oder menschlicher Reviewer

Sicherheit

1. Kein --allow-all / /yolo auf Alltagsrechnern mit Prod-Zugang
2. MCP wie Dependencies reviewen – Code + Credentials
3. Force-push und destruktive Shell standardmäßig deny
4. CI least privilege – Runner-Tokens sind attraktive Ziele

Die vier Hebel aus dem Buch (Kapitel 00): Scope eng · Diff lesen · Deny vor YOLO · weich vs. hart.

---

7.2 Kontext-Management als Kernkompetenz

Kern: Das Kontextfenster ist die Primärressource der Session – was im Fenster liegt, steuert Qualität und Kosten, nicht die Eloquenz im Prompt.

Donnerstag, 16:40. Dieselbe Session seit dem Morgen: Auth-Fix, dann „kurz CSS“, dann CI. Copilot erfindet einen Plan, den du um 11 verworfen hast, fragt nach dem Test-Command aus den Instructions und schlägt denselben kaputten Fix zum dritten Mal vor. Du tippst lauter. Das Fenster ist voll – nicht das Modell dumm. Ein /context, ein Compact mit Fokus oder /clear hätte früher geholfen als der vierte Korrektur-Prompt.

Warum Kontext alles dominiert

Jede Session speichert u. a.: System-/Harness-Kontext, Custom Instructions, Skill-Katalog, MCP-Tool-Namen, deine Nachrichten, gelesene Dateien, Tool-Outputs, Agent-Antworten. Das Fenster ist endlich. Wenn es voll und verrauscht wird, steigt die Fehlerquote: frühere Anweisungen verblassen, alte Fehlversuche werden wiederverwendet, Instruction-Zeilen gehen im Rauschen unter.

{width=90%}

Wie du das spürst: Antworten werden unscharf, der Agent „erinnert“ verworfene Pläne, oder fragt Dinge, die in .github/copilot-instructions.md stehen. Mehr Text im vollen Fenster verdrängt oft genau die Regel, die du durchsetzen wolltest.

Diagnose: /context

/context

Zeigt eine Visualisierung der Token-Nutzung (System/Tools, History, freier Raum – Labels je Version).

Wann schauen:

• vor einem großen Feature (Baseline)
• wenn Antworten driftieren oder Instructions „ignoriert“ wirken
• wenn Kosten/Latenz überraschen
• nach dem Laden neuer MCP-Server oder langer Explore-Phasen

Jetzt selbst machen (todo-cli):

cd beispiele/todo-cli
copilot

/context

Notiere den groben Füllstand. Dann: „Erkläre nur todo/store.py, keine anderen Dateien“ – und erneut /context. Du siehst, wie ein Read den Balken bewegt.

/compact und Auto-Compact

/compact
/compact Fokus Auth-Flow und freigegebener Plan; verwirf CSS-Experimente und gescheiterte Fixes

Mechanik	Was du wissen musst
Manuelles /compact [FOKUS]	Zusammenfassung steuern – Hint/Fokus ist der Hebel
Auto-Compact	laut Docs bei ca. 95 % des Token-Limits im Hintergrund, ohne Workflow zu unterbrechen
Verlustbehaftet	Nuancen und verworfene Alternativen können verschwinden

Achtung: Compact fasst zusammen und vergisst Nuancen. Was überleben muss, gehört in Dateien (PLAN.md, Instructions) – nicht nur in den Chat.

{width=90%}

Fokussierte Sessions: /clear, /new, /reset

/clear
/new
/reset

Zwischen unverwandten Tasks Kontext zurücksetzen. „Infinite sessions“ heißen nicht „eine Session für die ganze Woche Kitchen-Sink“. Fokussierte Sessions liefern bessere Ergebnisse – wie ein frisches Gespräch mit einer Kollegin.

Degradationssignale

Signal	Wahrscheinliche Ursache	Erste Reaktion
Widersprüchliche Annahmen im selben Turn	alter Plan + neuer Scope	/clear oder Compact mit Fokus
„Erfindet“ verworfene Alternativen	Compact ohne Fokus / Kitchen-Sink	Datei-Persistenz, dann Compact-Hint
Fragt Dinge aus den Instructions	nicht geladen, zu lang/vage, oder ertrunken	/context, /instructions, kürzen
Loop: gleicher Fix, gleiches Fail	vergifteter Kontext	Stop; nach 2 Korrekturen /clear + besserer Prompt
Teuer und langsam ohne Nutzen	zu viele Reads/MCP	Scope enger, Subagent/Explore, MCP reduzieren

Hebel-Matrix

Hebel	Wann	Effekt
Enger Prompt, @datei, Pfade	immer	gezieltere Reads
„Ändere nichts“ / Plan Mode	Explore	kein Edit-Ballast
Built-in Explore / Research-Agent	breite Codebase-Suche	Roh-Leseberg außerhalb der Main-Session
/compact mit Fokus	gleiches Thema, Fenster voll	gesteuert verlustbehaftet
/clear / /new	Themenwechsel	frischer Faden
Neue / Review-Session	Bias, großer Scope-Schnitt	Isolation von Annahmen
Entscheidungen in Dateien	alles, was überleben muss	Compact- und Session-fest

---

7.3 Session-Hygiene: Resume, Continue, Chronicle

Kern: Sessions sind wiederaufnehmbar und auswertbar – aber nur, wenn du weißt, was lokal liegt, was zu GitHub synct und was du bewusst neu startest.

Weiterarbeiten

Befehl / Flag	Zweck
copilot --continue	schnellste letzte lokale Session fortsetzen
copilot --resume / /resume	Session-Picker (lokal/synced, Sortierung)
/resume SESSION-ID	direkt in eine bekannte Session
/rename NEUER_NAME	Session im Picker benennen (ohne Anführungszeichen nötig)
/session	Infos zur laufenden Session (ID, Log-Pfad, …)
/session checkpoints	Compaction-Checkpoints ansehen
/session plan	aktueller Plan der Session
/session files	temporäre Session-Artefakte

Session teilen: /share (Alias /export)

Befehl	Ergebnis
/share	sharebarer Link auf GitHub.com (Session sichtbar machen)
/share off	Teilen beenden
/share gist	privates Gist (Enterprise Managed User / Data Residency: oft nicht verfügbar)
/share file [PFAD]	Markdown-Export der Conversation
/share html [PFAD]	interaktives HTML

Programmatisch: Flags wie --share=PATH / --share-gist (Command Reference). Gists und Links können Prompts und Tool-Outputs enthalten – keine Secrets, keine Kunden-PII.

/chronicle – Einsichten aus der Session-Historie

Standardmäßig speichert die CLI Sessions lokal und synct sie mit deinem GitHub-Konto (Details und Opt-out: Chronicle-Konzeptdoku). Darüber hinaus:

Subcommand	Nutzen
/chronicle standup	Standup-Report aus kürzlicher Arbeit (Default oft 24 h; Zeitraum im Prompt erweiterbar)
/chronicle tips	personalisierte Nutzungstipps aus deinen Mustern
/chronicle cost tips	wo Tokens/Credits hingehen
/chronicle search …	Volltextsuche in Session-Inhalten
/chronicle improve	Vorschläge für .github/copilot-instructions.md (Scope: aktuelles Repo)
/chronicle reindex	lokalen Session-Store neu aufbauen / Sync anstoßen

/chronicle standup for the last 3 days
/chronicle improve

Freiform geht oft auch: „Wann war ich zuletzt an Auth?“ – die CLI nutzt den Session-Store, wenn die Frage nach CLI-Nutzung klingt. improve schreibt erst nach deiner Auswahl in die Instruction-Datei – Review wie bei copilot init.

Session-State (Orientierung)

Unter ~/.copilot/session-state/{session-id}/ (bzw. $COPILOT_HOME) liegen u. a.:

events.jsonl      # History
workspace.yaml    # Metadaten
plan.md           # Plan, falls erzeugt
checkpoints/      # Compaction-Historie
files/            # persistente Artefakte
research/         # /research-Reports (falls genutzt)

Löschen von session-state/ entfernt lokale History – synced Daten auf GitHub können separat existieren. Nicht während laufender Session wild löschen.

Praxis:

• Sessions mit /rename wiederfindbar machen
• Nach Compaction: Checkpoints lesen, wenn der Agent „plötzlich anders“ denkt
• Wichtige Pläne zusätzlich ins Repo (PLAN.md) – Session-State ist kein Team-Wiki
• Sync/Chronicle: Compliance und „was landet auf github.com?“ im Team klären

Vorlage: vorlagen/PLAN.md.skeleton.md.

---

7.3a Rollback: /undo, /rewind, Esc×2

Kern: Rewind rettet schlechte Agent-Runden – ist aber final und kann mehr zurücksetzen als nur den letzten Diff.

Auslösen (Session idle, Eingabe leer):

• /undo oder /rewind
• oder Esc zweimal kurz hintereinander

Picker: frühere Prompts der Session (neueste zuerst). Nach der Wahl landet der Prompt oft wieder im Input – editieren und erneut senden möglich.

Variante	Erkennung	Wirkung
Git-based Rewind	Picker zeigt Snapshots; Auswahl rollt sofort zurück	Workspace auf Stand vor dem gewählten Prompt – inkl. manueller Edits und Shell-Effekte danach; neue Dateien nach dem Snapshot können weg sein
Tools-based Rewind	nach Prompt-Wahl Menü Conversation only vs. Conversation + files	History allein oder History + von Copilot geänderte Dateien; Dateien, die du danach manuell geändert hast, oft unangetastet

Tools-based Rewind kann experimentell sein (/experimental / --experimental). Voraussetzung Git-based: Git-Repo mit mind. einem Commit. Kein Rewind vor dem ersten Prompt der Session.

Achtung: Rewind lässt sich nicht rückgängig machen. Spätere Session-History ist weg. Bei Git-based: gesamter Workspace, nicht nur Agent-Hände. Nach dem Rollback prüfen:

! git status
! git log --oneline -1
! git diff

Tag-1-Kurzfassung: Kapitel 1.

---

7.3b Remote Control vs. Session-Sync

Kern: Sync macht Sessions sichtbar; Remote Control macht laufende Sessions steuerbar von GitHub.com / Mobile.

	Session-Sync (Default oft an)	Remote Control
Zweck	History speichern, Resume, Chronicle	live steuern: Output, Permissions, weiterarbeiten
Gerät	nur ansehen auf github.com/Mobile	Session von unterwegs steuern
Voraussetzung	Account-Sync-Policy	laufende Session, Maschine online, GitHub-Repo als CWD

Remote einschalten:

/remote on
/remote          # Status / Links erneut anzeigen
/remote off

copilot --remote
copilot --no-remote   # diese Session nicht remote

Dauerhaft (User-Settings, Key laut Doku):

{
  "remoteSessions": true
}

Zugriff: Link aus der CLI, oder GitHub.com → Copilot → Recent agent sessions (Filter CLI), oder Repo Agents-Tab; Mobile analog. QR-Code oft über Anzeige-Toggle (Doku: z. B. Ctrl+E bei leerem Input – driftfähig).

Maschine wach halten:

/keep-alive on
/keep-alive busy
/keep-alive 2h
/keep-alive off

Ohne wache Session bricht Remote ab – Cloud Agent (/delegate) ist die Alternative, wenn der Laptop zu darf.

Achtung: Remote Control = jemand mit deinem Account und dem Session-Link steuert denselben Agenten inkl. Permission-Prompts. Default oft aus; in geteilten Shell-Umgebungen und bei sensiblen CWDs bewusst aus lassen. Nur eigene Sessions sind steuerbar – nicht die der Kollegen.

---

7.4 Persistenz: was im Chat stirbt, was in Dateien lebt

Inhalt	Wohin	Warum
Team-Normen, Build/Test	.github/copilot-instructions.md	jede Session, reviewbar
Path-Regeln	.github/instructions/*.instructions.md	Relevanz
Freigegebener Implementierungsplan	PLAN.md oder Session-plan.md + Repo-Kopie	Compact-fest
Einmalige Explore-Erkenntnis	optional kurze Notiz	sonst weg nach /clear
Agent-abgeleitete Facts (Produkt)	Copilot Memory (Kap. 2)	kein Ersatz für reviewbare Instructions
Secrets	Secret Store / CI Secrets	nie Instructions, nie Chat-Logs, nie /share

Ritual vor Compact oder Session-Ende:

1. Entscheidungen in PLAN.md / Instructions schreiben
2. Offene TODOs als Checkliste
3. Erst dann /compact oder /clear

---

7.5 Sandbox und YOLO-Risiken

Sandbox

Variante	Idee
Lokal (/sandbox enable)	Tools/Commands des Agenten eingeschränkt (FS/Netz/System) – die CLI selbst läuft lokal
Cloud (copilot --cloud)	gesamte Session in isolierter Remote-Umgebung

Sandbox begrenzt wie weit ein Befehl greift; Deny begrenzt was überhaupt freigegeben wird. Eine Linie reicht selten. Details: copilot help sandbox und die Sandbox-Konzeptdoku.

YOLO / Allow-all

copilot --allow-all
copilot --yolo

/allow-all on
/yolo on

Gleiche Rechte wie du – ohne Einzel-Approval für Tools, oft inkl. Paths/URLs je Flag-Set.

Achtung: --allow-all / /yolo sind breite Bypass-Modi für isolierte Umgebungen und bewusste Experimente – nicht der Alltag auf Laptops mit Prod-Credentials, und nicht der CI-Default. Enterprise kann Bypass per permissions.disableBypassPermissionsMode: "disable" sperren (Kapitel 06).

Checkliste vor YOLO:

1. CWD eng und trusted?
2. Keine Prod-Secrets in der Umgebung?
3. Sandbox an, wenn möglich?
4. Team-Policy erlaubt es?
5. Diff danach wirklich lesen?

---

7.6 Multi-Repo, Modelle und BYOK

Multi-Repo-Patterns

Pattern	Wie	Wann
Parent-Directory	cd ~/projects && copilot	mehrere Sibling-Repos/Repos sichtbar
/add-dir /abs/pfad	Zugriff erweitern	gezielte Extra-Repos
/list-dirs	erlaubte Dirs anzeigen	Transparenz
/cwd / /cd	Working Directory wechseln	Fokus ohne neue Session

/add-dir /Users/YOU/src/backend-service
/add-dir /Users/YOU/src/shared-libs
/list-dirs

Warum: API-Contracts, Microservices, Docs+Code. Risiko: zu breiter Scope → mehr Reads, mehr Schaden bei YOLO. Trusted directories und Path-Gates bleiben aktiv – jedes neue Dir ist eine Trust-Entscheidung (Kapitel 01, 04).

Modellwahl

/model

Orientierung	Typische Nutzung
Auto	weniger Rate-Limit-Friction, dynamische Wahl
Stärkeres Modell	Architektur, harte Bugs, nuancierte Refactors
Schnelleres/günstigeres Modell	Alltag, enge Edits
Review-taugliches Modell	zweite Meinung auf Diffs (/review, zweite Session)
Extended Context (wo angeboten)	sehr große Codebases / lange Docs – teurer
Höheres Reasoning (wo angeboten)	harte Analyse – teurer; nicht Alltags-Default

Modelle und Default-Labels driften – /model und die aktuelle Doku sind Source of Truth. Mid-Session wechseln ist erlaubt und sinnvoll, wenn die Task-Klasse wechselt. Extended Context und Reasoning-Level nur bewusst (Kap. 3).

Session-Limit für AI Credits

/limits set max-ai-credits 50
/limits unset

copilot -p "…" --max-ai-credits 40

Soft-Cap pro Session (Preview): Agent stoppt am Limit; interaktiv Reset möglich, programmatisch endet der Lauf. Doku empfiehlt oft Werte > 30, weil einzelne Model-Calls teurer sein können. /usage zeigt den Verbrauch.

BYOK – eigener Provider

Env-Variablen (vor Start setzen; Details: copilot help providers und BYOK-How-to):

Variable	Pflicht	Bedeutung
COPILOT_PROVIDER_BASE_URL	ja	API-Base-URL
COPILOT_PROVIDER_TYPE	nein	openai (Default), azure, anthropic
COPILOT_PROVIDER_API_KEY	nein*	API-Key (*lokal z. B. Ollama oft ohne)
COPILOT_MODEL	ja	Modell-ID (oder --model)

export COPILOT_PROVIDER_BASE_URL=https://api.openai.com/v1
export COPILOT_PROVIDER_API_KEY=YOUR_KEY
export COPILOT_MODEL=YOUR-MODEL-NAME
copilot

Anforderungen an das Modell:

• Tool calling (Function Calling) – Pflicht
• Streaming – Pflicht
• Context Window mind. ~128k empfohlen

Fehlt Tool Calling oder Streaming, bricht die CLI mit Fehler ab.

Grenzen (laut Best-Practice-Doku):

• Built-in Subagents erben die Provider-Config
• Credit-Kostenschätzungen können ausgeblendet sein; Token-Zähler bleiben
• /delegate braucht zusätzlich GitHub-Login und läuft serverseitig bei GitHub – nicht über deinen BYOK-Endpoint
• Offline-Modus (COPILOT_OFFLINE=true): nur dann wirklich isoliert, wenn der Provider lokal/on-prem ist

---

7.7 Typische Symptome und Fixes

Symptom	Erst prüfen	Fix
Instructions greifen nicht	/instructions, /context, Pfad .github/copilot-instructions.md	Datei committen/korrekt benennen; Session neu oder --continue nach Edit; Konflikte entschärfen (Docs: Discovery kombiniert, keine generelle Precedence)
Path-Instructions wirken nicht	Frontmatter applyTo, Datei unter .github/instructions/	Glob prüfen; an betroffene Datei andocken
Hook feuert nicht	Datei unter .github/hooks/*.json, version, Event-Name	Schema gegen Hook-Doku; disableAllHooks?; executable Scripts; Session neu
Fragt immer nach Permission	kein Session-Allow, keine Flags, leere Approvals	enge --allow-tool; oder interaktiv Session-Allow; permissions-config.json pro Location (kein Deny dort)
Deny greift nicht	Flag-Syntax, Precedence	--deny-tool schlägt allow/all; copilot help permissions
Context „voll“ / unscharf	/context	Compact mit Fokus; oder /clear; Entscheidungen in Dateien
Auth schlägt fehl	Token-Typ, Env-Name, Org-Policy	fine-grained PAT + Copilot Requests; Env COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN; kein classic ghp_; copilot login interaktiv
YOLO / --allow-all blockiert	Managed Policy	erwartet bei permissions.disableBypassPermissionsMode: "disable" – Admin, nicht Workaround
MCP-Tool fehlt / startet nicht	/mcp, mcp-config.json, disabledMcpServers	Config, Auth, Name exakt; copilot plugins list --kind mcp
Skill wird nicht angeboten	Pfad SKILL.md, Name, disabledSkills	Orte prüfen (.github/skills, ~/.copilot/skills, …); /skills
Custom Agent fehlt	Pfad User/Repo/Org	.github/agents/ vs. ~/.copilot/agents/ vs. Org .github-private/agents/; /agent
Trusted-directory-Ärger	CWD, Parent vs. Repo-Root	bewusst trusten; nicht Home als CWD; /add-dir nur gezielt
Programmatic hängt / fragt	interaktive Defaults	--no-ask-user, enge allows, -s
Modell-Fehler bei BYOK	Capabilities	Tool calling + streaming; URL/Key/Model; copilot help providers
Session nicht resumebar	gelöschter State, anderer COPILOT_HOME	session-state/ und COPILOT_HOME prüfen
„Ignoriert“ Plan	Plan Mode verlassen / nicht freigegeben	Plan reviewen, freigeben, dann umsetzen; Plan in Datei
Rewind hat „zu viel“ gelöscht	Git-based Rewind	erwartet bei Workspace-Snapshot; git reflog/Backup; künftig tools-based oder engere Commits vor Agent-Lauf
Remote Control geht nicht	kein GitHub-Repo, Session tot, Sleep	CWD = GitHub-Repo; /keep-alive; /remote on; Maschine online
/chronicle leer / veraltet	Sync, Index	/chronicle reindex; Sync-Policy; genug Historie
Credits-Cap zu früh	Soft-Limit, teures Modell	/limits set erhöhen; Extended/Reasoning prüfen; /usage

Debugging-Baum (kurz)

1. Reproduzieren mit kleinem Prompt
2. /context  →  Fenster-Problem?
3. /instructions  →  Custom Instructions geladen?
4. Permission-Prompt / Flags  →  Policy-Problem?
5. Logs: /session → Log-Pfad unter ~/.copilot/logs/
6. copilot --version / copilot help <topic>
7. Frische Session vs. Resume trennen

Qualitäts-Ritual vor dem Merge

1. /diff (oder git diff) lesen
2. Verify: Test/Lint aus den Instructions
3. Optional /review (Bugs/Security)
4. Secrets und Debug-Noise scannen
5. /pr create oder bewusster Push – PR-Body: Intent + Risiko
6. Merge bleibt menschlich; bei Schrott: /undo bevor gepusht wurde

---

7.8 Wenn Doku und Buch abweichen

Kern: Bei Drift Konzept behalten, Syntax verifizieren – nicht raten und nicht das Buch als Spezifikation missbrauchen.

Lesevertrag (Kapitel 00): Stand des Buchs ist Mitte/Ende 2026. UI-Labels, Default-Modelle und einzelne Flags können sich ändern.

Schritt	Aktion
1	In der Session ? oder /help
2	Terminal: copilot help, copilot help config, copilot help permissions, copilot help environment, copilot help providers
3	Primär: 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 – Stand & Drift (dokumentierte Produkt-Abweichungen) und Errata (Buchfehler); Schnelle Hilfe bei typischen Symptomen
6	Offline-Kerne (Rituale, Minima): Anhang A; Aktualität der vollen Vorlagen: Begleit-Service → Material
7	Interne Notiz/PR: was sich geändert hat – Team informieren

Was stabil bleiben soll (Konzept):

• Custom Instructions = weiches, reviewbares Memory (Dateien)
• Permissions/Hooks/Sandbox = harte Grenzen
• Plan vor großem Code
• Diff lesen; Mensch merged
• Copilot Memory (Produkt) ≠ Instruction-Dateien (Kap. 2)

Was driften darf (Syntax): exakte Flag-Namen, Slash-Command-Liste, Default-Modelle, JSON-Keys.

---

7.9 Grenzen, Trade-offs und kritische Einordnung

Kern in einem Satz: Ein guter Harness macht Copilot CLI steuerbar – er macht das Modell weder unfehlbar noch kostenlos noch anbieterunabhängig.

Bis hierher war das Buch konstruktiv: Scope, Diff, Deny vor YOLO, Instructions, Sessions, CI. Das bleibt gültig. Es ersetzt aber keine ehrliche Einordnung: Was systematisch schwer bleibt, welche Trade-offs du kaufst, wann der Agent nicht laufen sollte – und warum dieses Buch bei Copilot CLI bleibt, ohne die Landschaft zu leugnen.

Was trotz guter Steuerung schiefgehen kann

Konfiguration und Disziplin senken die Fehlerquote. Sie heben die harte Decke nicht auf.

Kontextfenster. Wie in 7.2: Das Modell sieht nur, was im Fenster liegt. Lange History, fette Tool-Outputs und zu viele Instructions verdrängen das Ticket. /compact schafft Platz und verliert Nuancen. Gute Instructions sind kein unendliches Arbeitsgedächtnis.

Halluzinationen trotz Verify. Ein grüner Test beweist die geprüften Pfade, nicht die ungeschriebenen. Falsche Stack-Befehle und „plausible“ APIs treten auch mit Verify-Command auf – seltener, nicht nie. Verify ist ein Filter, kein Freibrief.

Lange Tool-Ketten. Je mehr Schritte (suchen → editieren → testen → nachbessern), desto fester setzt sich ein früher Fehlschluss. Der Harness führt aus, was erlaubt ist; er korrigiert keine falsche Problemdeutung im dritten Turn.

Kosten und Multiplikation. Hoher Reasoning-Aufwand, breite Exploration, Fleet und /delegate multiplizieren Tokens, Credits und Wartezeit. Parallelität ersetzt weder Plan noch Diff – bei unklarem Scope macht sie beides teurer (Kap. 5 und 6.6).

Enge Permissions als Bremse. Deny-Listen und enge Allowlists sind der richtige Default in fremden oder sensiblen Trees. Im vertrauten Repo spürst du die Reibung: Shell wartet, Fetch fragt. Das ist der Preis von Kontrolle – kein Policy-Bug. Wer aus Frust auf YOLO / --allow-all wechselt, tauscht Reibung gegen Review-Last und Vorfallrisiko.

Vendor-Abhängigkeit und Produkt-Drift. Auth, Credits, Modellnamen, Labels und Managed Settings liegen beim Anbieter und deiner Org. Was lokal greift, greift in Cloud Agent oder CI nicht automatisch mit (Kap. 3 und 6). Lesevertrag (Einleitung, 7.8): Konzept behalten, Syntax der Doku. Du baust Rituale um ein Produkt, das sich bewegen darf.

Wann du Copilot CLI besser nicht oder nur eng einsetzt

• Produktionshotfix mit unklarem Blast Radius ohne reproduzierbare Verify-Schleife
• Security-/Compliance-kritische Änderungen, bei denen menschliche Review und Vier-Augen Pflicht sind – nicht „auch noch vom Agenten“
• Unbekannte Repos / Supply-Chain-Verdacht: erst lesen und eng freigeben – oder gar kein Agent
• Rein politische Architekturentscheidungen ohne messbares Done-Kriterium
• Wenn du Diffs nicht mehr liest, weil „der Agent das schon macht“ – Ownership ist dann abgegeben

Trade-offs, die du nicht wegrationalisieren kannst

Jeder Hebel kauft etwas und verkauft etwas anderes. Sicherheit und Geschwindigkeit sind oft Gegenpole derselben Entscheidung – unten als getrennte Zeilen, weil du sie im Alltag separat spürst.

Achse	Mehr davon …	kostet typischerweise …
Sicherheit ↔ Geschwindigkeit	enge Deny/Allow oder YOLO in Isolation	Tempo und Klicks oder Review-Last, größere Diffs, teure Fehlversuche
Autonomie (Cloud Agent, Fleet, lange Sessions)	parallele/async Arbeit	Kontext- und Kostenrisiko, weniger Live-Steuerung
Kontrolle (Plan Mode, enger Scope, Diff vor Merge)	nachvollziehbare Schritte	mehr menschliche Minuten pro Ticket
Weiches Memory (Instructions)	bessere Defaults	kein Zwang – „Nie“ wird gebeten, nicht erzwungen
Harte Boundaries (Permissions, Hooks, Sandbox, Managed)	echte Verbote	Pflege, False Positives, Onboarding-Reibung

Lokal CLI vs. Cloud Agent vs. IDE ist dieselbe Produktfamilie mit anderen Oberflächen und Isolationsgraden – kein Ranking „Cloud ist sicherer“. Lokal: Live-Steering und /diff. Cloud//delegate: async, environment-eigene Policy. IDE: niedrigere Einstiegshürde, dieselben Trust- und Ownership-Fragen. Surface-Wahl ist Workflow, nicht Moral.

Kern: Weich steuert Verhalten; hart begrenzt Schaden. Wer nur Instructions pflegt und Permissions aufweicht, hat Dokumentation – keine Boundary.

Orientierende Einordnung: Coding-Agents und übertragbare Prinzipien

Kern in einem Satz: Ein Vergleich kann Mehrwert liefern – aber nur als orientierende, prinzipienbasierte Einordnung, nicht als detaillierter Produktvergleich.

Feature-Listen und Punkt-für-Punkt-Produktvergleiche altern in Monaten. Labels, Preisstufen, Default-Policies und Integrationsflächen verschieben sich; was gestern „einzigartig“ wirkte, ist morgen Standard oder verschwunden. Eine prinzipienbasierte Einordnung hält länger: Sie fragt nach Einstieg, Steuerungsphilosophie und Workflow-Passung – nicht nach dem aktuellen Menüpunkt in der UI.

Dieses Buch bleibt bei GitHub Copilot CLI, weil Praxis Tiefe braucht: eine durchgängige Terminologie (Instructions, Permissions, Trusted Directory, Sessions, CI), nachbaubare Configs und einen Lernpfad von Trust bis Merge. Andere Ansätze abzuwerten wäre unsachlich; drei Produkte halb zu erklären erzeugt nur Schein-Übersicht. Die Landschaft unten dient der Orientierung – nicht der Kaufberatung und nicht dem Ranking.

Landschaftsskizze (Stand Mitte/Ende 2026)

Coding-Agents teilen oft dieselbe Grundschleife (planen, editieren, Shell, iterieren), unterscheiden sich aber im Schwerpunkt des Einstiegs:

Kategorie	Schwerpunkt / typischer Einstieg	Beispiele (nicht abschließend)
Terminal-zentriert	Repo und Shell als Arbeitsfläche; Steuerung über CLI, Instructions und Permission-Grenzen	Copilot CLI; vergleichbare Terminal-Agenten
IDE-zentriert	Editor, Diff-Ansicht und Projektsicht eng verwoben; niedrige Hürde im Alltagscode	IDE-Agenten und vergleichbare Editor-Integrationen
Diff-/Git-zentriert, leichtgewichtig	Kleine, nachvollziehbare Änderungen; Git-Disziplin und geringer Overhead	Leichte terminalnahe Tools mit starkem Diff-Fokus
Cloud-/asynchron	Auftrag wegschicken, später Diff/Ergebnis prüfen; Isolation und Environment-Policy statt Live-Steering	Cloud Agent / /delegate und vergleichbare async/remote Agenten

Die Zeilen beschreiben Einstiege, keine Feature-Vollständigkeit. Ein Produkt kann mehrere Kategorien berühren (Copilot etwa lokal und in der Cloud) – die Frage bleibt: Wo steuerst du primär, und welche Boundary spürst du zuerst?

Wann eignet sich welcher Ansatz eher?

Die Matrix bezieht sich auf Workflow und Steuerungsphilosophie, nicht auf Modellqualität oder Feature-Score:

Dein Schwerpunkt …	Passt eher zu …	Typische Passung
Starke Terminal-Kontrolle und harte Boundaries (Deny, Allowlist, Policy vor Tempo)	Terminal-zentrierte Agenten	Du willst Shell, Repo und Grenzen explizit steuern; Reibung ist akzeptierter Preis
Tiefer Editor-Bezug und visuelle Integration (Inline, UI-Diff, Projektsicht)	IDE-zentrierte Agenten	Der Alltag lebt im Editor; der Agent soll dort „mitlaufen“, nicht erst im Terminal starten
Maximale Diff- und Git-Disziplin bei geringem Overhead	Diff-/Git-zentrierte, leichte Tools	Kleine, reviewbare Schritte; wenig Setup, viel Commit-Hygiene
Asynchrone oder isolierte Cloud-Arbeit (Auftrag, warten, Diff prüfen)	Cloud-/async Agenten	Parallelität und Isolation; weniger Live-Steering, mehr Environment- und Apply-Disziplin

Keine Zeile bedeutet „Produkt A schlägt B“. Sie bedeutet: passender Einstieg und ehrlicher Scope. Wer fast nur Inline-Chat im Editor braucht, lernt CLI-Harness-Tiefe nicht als Erstes. Wer Permissions und Instructions systematisch trainieren will, findet im Kernpfad dieses Buchs den roten Faden – unabhängig davon, welche Tools du zusätzlich im Stack hast.

Übertragbare Prinzipien

Produktfeatures kommen und gehen. Die folgenden Regeln gelten in jedem seriösen Coding-Agent-Setup – unter anderen Dateinamen und UI-Labels, aber mit derselben Logik:

1. Scope eng halten. Dateien, Done-Kriterium, Nicht-Ziele, Stop-Regel. Breite Aufträge multiplizieren Diff, Kosten und Fehldeutungen.
2. Diff lesen vor Merge und vor „fertig“. Tests und grüne Häkchen ersetzen keine menschliche Sicht auf was sich geändert hat – lokal, in der Cloud und vor dem Apply.
3. Weich vs. hart trennen. Bitten (Instructions, Conventions, „bitte nie …“) steuern Verhalten. Erzwingen (Permissions, Hooks, Sandbox, Managed Policy) begrenzt Schaden. Wer nur bittet und Boundaries aufweicht, hat Dokumentation, keine Grenze.
4. Menschliche Ownership an Merge, Secrets und Produktion. Der Agent schlägt vor und ändert im erlaubten Rahmen. Freigabe in den Mainline-Branch, Umgang mit Geheimnissen und produktive Eingriffe bleiben beim Menschen bzw. bei klaren Team-Prozessen.
5. Verify und Phasen vor blinder Autonomie. Explore → Plan → Code → Verify → Commit (oder das Äquivalent deines Tools) ist billiger als eine ungebremste Tool-Kette. Autonomie ohne Checkpoints spart Klicks und kauft Review-Last.

Kern: Diese Prinzipien sind langlebiger als jedes Feature-Release. Wer sie beherrscht, wechselt den Harness mit Lernkurve – wer nur Hotkeys und Default-Prompts kennt, startet bei jedem Produkt bei null und ohne Bremse.

Warum das wichtiger ist als einzelne Produktfeatures: Features erklären wie ein Tool etwas anbietet. Prinzipien erklären welche Fehlerklasse du vermeidest – Scope-Creep, ungeprüfte Diffs, weiche „Verbote“, abgegebene Ownership, blinde Autonomie. Genau diese Klassen bleiben, wenn die UI morgen anders heißt.

Trade-off – jeder Ansatz kauft etwas

Jeder Einstieg kauft etwas und verkauft etwas anderes. Terminal-Kontrolle und harte Boundaries kosten oft Klicks und Geduld. IDE-Nähe senkt die Einstiegshürde und kann Live-Review erleichtern – die Boundary-Frage verschwindet dadurch nicht. Diff- und Git-Disziplin mit wenig Overhead belohnt kleine Schritte, skaliert aber anders bei großen, multi-repo Refactors. Cloud und Asynchronität kaufen Parallelität und Isolation und verkaufen Live-Steering: Du steuerst über Auftrag, Policy und späteren Diff, nicht über jeden Zwischenschritt am Prompt. Wer beides maximal will – maximale Autonomie und maximale Kontrolle ohne Review – will zwei gegenläufige Achsen gleichzeitig. Das löst kein Produkt; das löst nur ehrliche Priorisierung.

Was du mitnehmen kannst

• Feature-Listen und Tiefenvergleiche veralten schnell; Einstieg + Steuerungsphilosophie halten länger.
• Vier grobe Kategorien reichen zur Orientierung: Terminal, IDE, Diff/Git-leicht, Cloud/async.
• Die Entscheidungsfrage lautet „welcher Workflow?“, nicht „welches Produkt gewinnt?“.
• Fünf Prinzipien (Scope, Diff, weich/hart, Ownership, Verify/Phasen) sind harness-übergreifend mitnehmbar.
• Dieses Buch vertieft GitHub Copilot CLI – nicht, weil die Landschaft leer wäre, sondern weil Tiefe einen Fokus braucht.

Typische Fehlerbilder – auch bei korrekter Config

Diese Fehlerbilder treten auf, obwohl Trust sitzt, Instructions sinnvoll sind und YOLO nicht der Default ist.

1. Grüne Tests, falsche Semantik. Die Suite ist grün, die Produktabsicht verfehlt (Edge Case, UX, stille Invariante).
   Tun: Akzeptanzkriterien und Nicht-Ziele in PLAN.md; kritischen Pfad manuell prüfen; Diff auf „was fehlt?“ lesen.

2. Approval-Müdigkeit. Nach dem zwanzigsten Dialog wird „Session-Allow“ aus Gewohnheit geklickt.
   Tun: Scope/Allowlist enger, nicht die Policy weiter; Session neu mit enger Baseline; destruktive Muster nie session-weit.

3. Tool-Schleife. Flaky Test oder unklare Meldung → Edit-Test-Schleife, Kontext voll Noise.
   Tun: stoppen; Fehler selbst reproduzieren; neuer Scope mit Stop-Regel; ggf. neue Session.

4. Fleet-/Reasoning-Spirale. Parallele Agents und hohe Reasoning-Stufen multiplizieren Kosten, ohne schärferes Ticket.
   Tun: Credits/Limits im Blick; ein Explore-Pass mit klarer Frage; Plan in Datei; Code-Phase ohne parallele Explore-Sessions.

5. Kontext-Matsch nach Themenwechsel. Dieselbe Session, drittes Ticket – Antworten vermischen Repos.
   Tun: neue Session; CWD/Trust prüfen; Compact nur mit Datei-Anker (7.2–7.3).

6. Lokal eng, remote weit. Lokal eng (Deny), Cloud/CI mit anderen Rechten – der Diff fühlt sich fertig an.
   Tun: Environment- und Job-Policy lesen; Merge nie blind; least privilege pro Surface (Kap. 6).

Wann das Harness-Modell besonders stark ist – und wo es aneckt

Stark, wenn:

• das Problem abgrenzbar ist (Dateien, Done, Verify)
• du Diff und Tests als Eigentümer behandelst
• weiche Guidance und harte Boundaries zusammen sitzen
• Surfaces bewusst gewählt sind (lokal iterieren, remote nur mit Policy)

An Grenzen, wenn:

• das Ziel vage ist („mach es besser“) und niemand Ownership übernimmt
• Sicherheit und Tempo gleichzeitig maximal sein sollen
• niemand Version//help pflegt
• Kosten steigen, ohne dass Scope und Verify mitwachsen

Der Harness ist ein Steuerungssystem, kein Ersatz für Urteilsvermögen. Wer das akzeptiert, holt aus Copilot CLI mehr heraus – und schaltet ihn ab, wenn die Situation es verlangt.

---

Checkliste – Troubleshooting-Session

• Symptom in einem Satz
• /context und grober Füllstand
• Instructions geladen? (/instructions)
• Permission: Flag, Session-Allow oder Managed?
• Auth: welcher Token/Env?
• Repro in frischer Session?
• Fix dokumentiert (Team-Instructions oder Runbook)?

Häufige Fehler beim Debuggen selbst

1. Sofort YOLO statt engem Repro
2. Drei Themen in einer Debug-Session mischen
3. Compact ohne Fokus und dann wundern
4. permissions-config.json während laufender Session editieren
5. Classic PAT erwarten, obwohl die Doku fine-grained verlangt

So baust du ein internes Runbook nach

1. Die Tabelle aus 7.7 ins Team-Wiki kopieren
2. Eure Stack-Commands (pytest/npm/…) eintragen
3. Kontakte: wer managed Settings / Tokens rotiert
4. Link zur aktuellen Copilot-CLI-Doku
5. Vierteljährlich gegen /help und Release Notes prüfen

---

Was du jetzt kannst

• Kontext mit /context, /compact und fokussierten Sessions steuern
• Resume/Continue, /rename, /share und /chronicle nutzen
• Remote Control von Session-Sync trennen und bewusst schalten
• Schlechte Agent-Runden mit /undo / Esc×2 einordnen und absichern
• Sandbox und YOLO als Risiko-Entscheidung behandeln
• Multi-Repo, Modelle (inkl. Extended/Reasoning), Session-Limits und BYOK einsetzen
• Symptom→Fix systematisch abarbeiten
• Doku-Drift über den Lesevertrag (Kap. 00) handhaben
• Grenzen, Trade-offs und typische Fehlerbilder des Harness-Ansatzes benennen
• entscheiden, wann Copilot CLI eng bleibt, pausiert oder ein anderer Einstieg näherliegt

Nächste Schritte

• Kapitel 08: Slash-Commands, Flags, Pfade, Glossar · Anhang A: stabile Kernvorlagen
• Team-Runbook aus 7.7 ableiten
• Offene Config-Lücken aus Kapitel 02–06 schließen

Primärquellen (Auswahl): Session data / Chronicle, Roll back changes, Remote control, Session credit limit.