Zum Hauptinhalt springen

Tiefenstudie zum Claude-Code-Quellcode

1. Untersuchungsumfang und Kernaussage​

1.1 Was genau untersucht wurde​

Die Untersuchung bestand nicht nur aus dem Lesen einer einzelnen Prompt-Datei oder einem schnellen Blick auf die Ordnerstruktur. Stattdessen wurde der Quellcode aus sourcesContent in cli.js.map rekonstruiert und entlang des tatsächlichen Runtime-Flusses analysiert.

Im Fokus standen:

  • die Gesamtstruktur von Claude Code
  • der dynamische Aufbau des Haupt-Systemprompts
  • die modellseitigen Protokolle von AgentTool und SkillTool
  • die Aufgabenteilung der built-in agents
  • die Agent-Orchestrierungskette
  • die Einbindung von plugins, skills, hooks und MCP
  • das Zusammenspiel von permissions, tool execution und hook decisions
  • die Frage, warum Claude Code deutlich stärker wirkt als ein gewöhnlicher „LLM + Tool Caller“

1.2 Bestätigte Fakten​

Es ließen sich mindestens folgende Fakten bestätigen:

  1. cli.js.map im npm-Paket enthält vollständige sourcesContent
  2. Aus der Map konnten mindestens 4756 Quelldateien rekonstruiert werden
  3. Die zentrale Datei des Haupt-Systemprompts ist src/constants/prompts.ts
  4. Der Agent-Tool-Prompt liegt in src/tools/AgentTool/prompt.ts
  5. Der Skill-Tool-Prompt liegt in src/tools/SkillTool/prompt.ts
  6. Zum Kern der Agent-Orchestrierung gehören src/tools/AgentTool/AgentTool.tsx und src/tools/AgentTool/runAgent.ts
  7. Die Tool-Execution-Kette stützt sich wesentlich auf src/services/tools/toolExecution.ts und src/services/tools/toolHooks.ts

1.3 Die wichtigste Schlussfolgerung vorab​

Claude Code ist nicht wegen eines magischen Systemprompts stark, sondern wegen eines vollständigen Systems.

Seine Stärke entsteht aus der Kombination von:

  • modularer Prompt-Assembly
  • kontrollierter Tool-Ausführung
  • Permission-Modell
  • spezialisierten Agents
  • Workflow-Paketierung über Skills
  • Plugin-Metadaten und Runtime-Constraints
  • Hooks als Policy-Layer
  • MCP als Injektionsschicht für Fähigkeiten und Verhaltenshinweise
  • cache-bewusstem Prompt-Aufbau
  • Lifecycle-Management für asynchrone und Hintergrundarbeit

Kurz gesagt:

Claude Code ist kein Prompt, sondern ein Agent Operating System, das Prompts, Tools, Permissions, Agents, Skills, Plugins, Hooks, MCP, Cache-Verhalten und produktionsreife Runtime vereint.

2. Quellcode-Architektur: Warum es wie ein Agent Operating System wirkt​

2.1 Die Top-Level-Struktur zeigt bereits Systemkomplexität​

Im rekonstruierten src/ sind unter anderem folgende Module sichtbar:

  • src/entrypoints/
  • src/constants/
  • src/tools/
  • src/services/
  • src/utils/
  • src/commands/
  • src/components/
  • src/coordinator/
  • src/memdir/
  • src/plugins/
  • src/hooks/
  • src/bootstrap/
  • src/tasks/

Das ist keine dünne CLI-Hülle, sondern eine Runtime-Plattform.

2.2 Die Entry-Layer zeigen Plattformdenken​

Sichtbare Entry-Points sind:

  • src/entrypoints/cli.tsx
  • src/entrypoints/init.ts
  • src/entrypoints/mcp.ts
  • src/entrypoints/sdk/

Damit wird klar: dieselbe Agent-Runtime soll CLI, Initialisierung, MCP-Modus und SDK-Consumer bedienen.

2.3 Das Command-System ist Teil der Control Plane​

Die Commands umfassen unter anderem:

  • /mcp
  • /memory
  • /permissions
  • /hooks
  • /plugin
  • /reload-plugins
  • /skills
  • /tasks
  • /plan
  • /review
  • /status
  • /model
  • /output-style
  • /agents
  • /sandbox-toggle

Außerdem werden nicht nur built-in commands, sondern auch plugin commands, skill commands, bundled skills und dynamic skills integriert. Das Command-System ist also selbst ein Ökosystem-Einstiegspunkt.

2.4 Die Tool-Schicht macht aus dem Modell einen Akteur​

Wichtige Tools sind:

  • FileRead
  • FileEdit
  • FileWrite
  • Bash
  • Glob
  • Grep
  • TodoWrite
  • TaskCreate
  • AskUserQuestion
  • Skill
  • Agent
  • MCPTool
  • Sleep

Diese Schicht verwandelt das Modell vom Antwortgenerator in einen Ausführer.

3. Die Prompt-Assembly und die Rolle von prompts.ts​

3.1 src/constants/prompts.ts ist der zentrale Kontrollpunkt​

Die Datei ist wichtig, weil sie die Runtime-Instruktionen des Hauptthreads zusammenbaut.

Dazu gehören:

  • Haupt-Systemprompt-Assembly
  • Environment-Injection
  • Tool-Nutzungsregeln
  • Risky-Action-Guidance
  • Session-spezifische Guidance
  • Sprache und Output-Style
  • MCP-Instruktionen
  • Memory-Prompt-Injection
  • Scratchpad-Hinweise
  • Function-Result-Clearing
  • Feature-gesteuerte Sektionen wie brief mode oder token budget

3.2 getSystemPrompt() ist ein Orchestrator​

Die Struktur ist klar in statischen Präfix und dynamischen Suffix geteilt.

Statischer Präfix:

  • getSimpleIntroSection()
  • getSimpleSystemSection()
  • getSimpleDoingTasksSection()
  • getActionsSection()
  • getUsingYourToolsSection()
  • getSimpleToneAndStyleSection()
  • getOutputEfficiencySection()

Dynamischer Suffix:

  • session guidance
  • memory
  • model override
  • env info
  • language
  • output style
  • MCP instructions
  • scratchpad
  • function result clearing
  • summarize tool results
  • numeric anchors
  • token budget
  • brief mode

Claude Code behandelt Prompts als kombinierbare Runtime-Ressourcen.

3.3 Prompt-Cache-Grenzen zeigen Infrastruktur-Denken​

Im Source ist eine Grenze wie SYSTEM_PROMPT_DYNAMIC_BOUNDARY explizit vorhanden. Der Sinn:

  • den Präfix cache-freundlich halten
  • user- und session-spezifische Inhalte dahinter platzieren
  • die Grenze nicht leichtfertig verändern, um Cache-Verhalten nicht zu zerstören

Das ist Prompt-Assembly mit ökonomischem Cache-Bewusstsein.

4. Zerlegung der Prompt-Sektionen​

4.1 getSimpleIntroSection()​

Hier wird festgelegt:

  • Claude ist ein interaktiver Agent
  • die Aufgabe ist Software-Engineering-Unterstützung
  • der Output-Style ist extern steuerbar
  • Cyber-Risk-Guidance ist von Anfang an aktiv
  • URLs dürfen nicht geraten oder erfunden werden

4.2 getSimpleSystemSection()​

Diese Sektion definiert die Runtime-Realität:

  • nicht-tool-basierte Ausgaben sind direkt für den Nutzer sichtbar
  • Tools laufen unter Permission-Modes
  • abgelehnte Tool-Aufrufe dürfen nicht identisch wiederholt werden
  • Tool-Outputs und User-Messages können <system-reminder>-Tags enthalten
  • externe Tool-Outputs können Prompt-Injection enthalten
  • Hooks existieren
  • Kontext kann automatisch komprimiert werden

4.3 getSimpleDoingTasksSection()​

Diese Regeln stabilisieren das Verhalten:

  • keine ungefragten Features
  • keine Überabstraktion
  • keine unnötigen Refactors
  • keine unnötigen Comments, Docstrings oder Type Annotations
  • keine überflüssigen Fallbacks oder Validierungen
  • keine spekulativen future-proof Abstraktionen
  • erst lesen, dann editieren
  • neue Dateien nur bei echter Notwendigkeit
  • keine voreiligen Zeitabschätzungen
  • vor Strategiewechsel erst Diagnose
  • Sicherheitsprobleme beachten
  • klar unnötigen Code löschen
  • Ergebnisse ehrlich berichten

4.4 getActionsSection()​

Hier werden confirm-pflichtige Risikoaktionen definiert:

  • destructive operations
  • hard-to-reverse operations
  • shared-state changes
  • externally visible actions
  • uploads to third-party tools

4.5 getUsingYourToolsSection()​

Die Tool-Grammatik ist explizit:

  • Lesen mit FileRead
  • Editieren mit FileEdit
  • Erstellen mit FileWrite
  • Datei-Suche mit Glob
  • Inhaltssuche mit Grep
  • Bash nur für echte Shell-Fälle
  • Aufgabenverwaltung mit TodoWrite / TaskCreate
  • unabhängige Aufrufe parallelisieren

4.6 Session-spezifische Guidance​

Diese dynamische Ebene injiziert Regeln je nach aktueller Sitzung, etwa zur Verfügbarkeit von AskUserQuestion, AgentTool, Explore- oder Plan-Agents, slash skills oder Verification-Verträgen.

4.7 Output Efficiency​

Hier geht es um Produktqualität:

  • natürlichsprachliche Antworten statt Logs
  • Handlung oder Ergebnis zuerst
  • Updates bei Bedarf, aber ohne Geschwätz
  • keine unnötigen Tabellen
  • kurze, direkte Sätze

4.8 Tone and style​

Regeln wie keine Emoji-Inflation, knappe Antworten oder die Referenzierung von Code-Stellen mit file_path:line_number prägen die Produktanmutung.

4.9 DEFAULT_AGENT_PROMPT​

Die Basisrolle von Sub-Agents lautet:

  • du bist ein Claude-Code-Agent
  • verwende Tools, um die Aufgabe zu erledigen
  • liefere keine halbfertigen Ergebnisse
  • gib am Ende einen knappen Bericht zurück

5. Agent-Prompts und built-in agents​

5.1 AgentTool/prompt.ts als Protokolldokument​

Diese Datei beschreibt für das Modell:

  • wie Agents gelistet werden
  • wie sie beschrieben werden
  • wann man sich selbst forken soll
  • wann subagent_type gesetzt werden muss
  • der Unterschied zwischen fork und fresh agent
  • wann AgentTool nicht verwendet werden sollte
  • wie man Prompts für Sub-Agents schreibt
  • Unterschiede zwischen foreground und background
  • Semantik von worktree und remote isolation

5.2 Warum Fork-Semantik so stark ist​

Beim Forking gilt unter anderem:

  • fehlendes subagent_type bedeutet self-fork
  • der Fork erbt den vollständigen Kontext
  • Research-Tasks eignen sich besonders
  • auch Implementierungsarbeit mit vielen Zwischenergebnissen passt gut
  • Forks sind günstig wegen gemeinsamem Prompt-Cache
  • Model-Wechsel schadet dem Cache-Hit-Ratio
  • Main Thread soll Fork-Ausgaben nicht ausspionieren
  • Ergebnisse des Forks sollen nicht vorweggenommen werden

5.3 „How to write the prompt“ ist sehr wertvoll​

Das Modell wird ausdrücklich zu guter Delegation erzogen:

  • fresh agents haben keinen Kontext
  • Prompts sollen wie ein Briefing an neue Teammitglieder sein
  • Ziel und Grund erklären
  • bereits ausgeschlossene Wege nennen
  • genug Kontext für Urteile liefern
  • Kürze explizit anfordern, wenn gewünscht
  • Task-Verständnis nicht auslagern
  • keine faulen Delegations-Prompts
  • Dateipfade, Zeilen und Änderungswünsche konkret nennen

5.4 Built-in agents stehen für Spezialisierung​

Bestätigte Rollen:

  • General Purpose Agent
  • Explore Agent
  • Plan Agent
  • Verification Agent
  • Claude Code Guide Agent
  • Statusline Setup Agent

5.5 Explore Agent als Read-only-Spezialist​

Explore darf weder Dateien erstellen noch ändern, löschen, verschieben oder temporär schreiben. Auch statusverändernde Kommandos sind verboten. Er nutzt Glob, Grep, FileRead und nur read-only Bash-Befehle, möglichst parallel und schnell.

5.6 Plan Agent als reiner Planer​

Plan bleibt read-only, analysiert Anforderungen und Codebasis und liefert einen schrittweisen Implementierungsplan samt Critical Files for Implementation.

5.7 Verification Agent als adversarial validator​

Der Verification-Agent soll aktiv versuchen, Fehler aufzudecken. Verlangt werden unter anderem:

  • Builds
  • Test-Suites
  • Lints und Type-Checks
  • Frontend-Verifikation per Browser-Automation
  • Backend-Prüfung mit curl oder fetch
  • CLI-Prüfung über stdout, stderr und exit code
  • Migration up/down
  • Public-API-Checks
  • adversarial probes
  • dokumentierte Commands mit beobachtetem Output
  • VERDICT: PASS / FAIL / PARTIAL

6. Die Agent-Orchestrierungskette​

6.1 Gesamtfluss​

Vereinfacht läuft die Kette so:

  1. main model ruft Agent Tool auf
  2. AgentTool.call() analysiert den Input
  3. fork / built-in / teammate / background / remote werden aufgelöst
  4. Agent-Definition wird gewählt
  5. Prompt-Messages werden gebaut
  6. Systemprompt wird aufgebaut oder geerbt
  7. Tool-Pool wird erstellt
  8. agent-spezifischer ToolUseContext entsteht
  9. hooks, skills und MCP servers werden registriert
  10. runAgent() startet
  11. query() übernimmt den eigentlichen Loop
  12. transcript, metadata und cleanup werden behandelt

6.2 AgentTool.call() als Orchestrierungscontroller​

Zu den Aufgaben gehören Input-Parsing, Team-Kontext, Background-Zulässigkeit, Pfadwahl zwischen fork und normal, Agent-Filterung über Permissions, MCP-Prüfung, Remote-Isolation, Prompt-Aufbau, Task-Registrierung und der Aufruf von runAgent().

6.3 fork path vs normal path​

fork path bedeutet Kontextvererbung, Prompt-Cache-Reuse und möglichst identische Tool-Definitionen. normal path bedeutet frischen Agent-Systemprompt, nur relevanten Kontext und agent-spezifische Tool-Restriktionen.

6.4 Cache-identical prefix​

Die Absicht, byte-identische Request-Präfixe zu behalten, zeigt einen klaren Fokus auf Tokenökonomie und Prompt-Cache-Hits.

6.5 foreground und background lifecycles​

Background-Agents haben eigene Abort-Controller, Task-Registrierung und Notification-Rückgabe. Foreground-Agents blockieren den Main Thread stärker und werden progress-getrackt.

6.6 runAgent() als Runtime-Konstruktor​

runAgent() initialisiert agent-spezifische MCP-Server, konfiguriert Kontexte, Permissions, Tools, Hooks, Frontmatter-Skills, startet query() und räumt danach sauber auf.

6.7 agent-spezifische MCP-Server​

Agents können eigene MCP-Server und damit additive Fähigkeiten mitbringen.

6.8 Frontmatter hooks und skills​

Hooks und Skills lassen sich über Frontmatter pro Agent injizieren. Ein Agent ist damit ein konfigurierbarer Prompt-Container.

6.9 query() als finaler Hauptloop​

Die Schichtung ist sauber:

  • AgentTool routet
  • runAgent baut Runtime und Lifecycle
  • query führt den Modell- und Tool-Loop aus

6.10 transcript / metadata / cleanup​

Transcript-Aufzeichnung, Metadaten, Perfetto, Shell-Cleanup und Todo-Cleanup zeigen den Produktisierungsgrad der Laufzeit.

7. Skills, Plugins, Hooks und MCP​

7.1 Skill als Workflow-Paket​

Skills sind first-class primitives.

  • passende tasks müssen den Skill-Tool-Aufruf auslösen
  • bloße Erwähnung reicht nicht
  • slash commands können Skill-Einstiegspunkte sein
  • bereits injizierte skills sollen nicht doppelt geladen werden

7.2 Plugin als Prompt + Metadata + Runtime Constraints​

Plugins können markdown commands, SKILL.md, command metadata, allowed tools, model hints und runtime variables liefern. Sie erweitern das Verhalten des Modells selbst.

7.3 Hook als Governance-Layer​

Hooks unterstützen PreToolUse, PostToolUse und PostToolUseFailure und können Nachrichten, Blocking Errors, Input-Updates, Permission-Verhalten, Stop-Gründe oder zusätzlichen Kontext liefern.

7.4 Hook und Permission-Modell​

Hooks können allow, ask oder deny zurückgeben, aber sie umgehen die zentrale Sicherheitslogik nicht.

7.5 MCP als Verhaltens-Injektion​

MCP injiziert nicht nur Tools, sondern auch Instruktionen zu deren Nutzung. Dadurch wird MCP zu einer behavior-aware integration plane.

8. Permissions, Hooks und Tool-Execution​

8.1 toolExecution.ts​

Die Pipeline umfasst Tool-Lookup, Metadata-Parsing, Schema-Validation, tool-spezifische Validation, Hook-Ausführung, Permission-Entscheidung, Tool-Call, Telemetrie und Post-Hooks.

8.2 Input-Validation​

Fehlerhafte Eingaben werden früh über Schema-Checks und tool-spezifische Validation abgefangen.

8.3 PreToolUse hooks​

Besonders wichtig sind updatedInput, permissionBehavior und preventContinuation.

8.4 resolveHookPermissionDecision()​

Diese Logik verbindet Hook-Semantik und zentrales Permission-Modell sauber miteinander.

8.5 Governance endet nicht nach erfolgreichem Tool-Call​

Auch nach Erfolg oder Fehler können Hooks zusätzlichen Kontext, Blockierungen oder Recovery-Hinweise liefern.

9. Warum Claude Code so stark wirkt​

9.1 Kein Prompt, sondern ein Operating Model​

Der eigentliche Burggraben ist die Kombination aus Prompt-Architektur, Runtime-Governance, Permissions, Hooks, Agent-Spezialisierung, Skills, Plugins, MCP, Cache-Optimierung und Lifecycle-Management.

9.2 Institutionalisierung guten Verhaltens​

Claude Code schreibt gutes Engineering-Verhalten in Prompt und Runtime-Regeln fest, statt es der spontanen Intelligenz des Modells zu überlassen.

9.3 Verständnis für Kontextknappheit​

Systemprompt-Grenzen, Cache-Reuse, on-demand Injection, Result-Clearing und Resume-Mechanismen zeigen, dass Token als Budget behandelt werden.

9.4 Tiefe der Agent-Spezialisierung​

Explore, Plan und Verification trennen Forschung, Planung, Implementierung und Validierung klar voneinander.

9.5 Modellbewusstes Ökosystem​

Das Modell weiß selbst über skill lists, agent lists, MCP instructions und session-specific guidance, welche Erweiterungen existieren und wie sie zu verwenden sind.

10. Wichtige Dateien und nächste Forschungsschritte​

10.1 Prompt-Dateien​

  • src/constants/prompts.ts
  • src/tools/AgentTool/prompt.ts
  • src/tools/SkillTool/prompt.ts
  • src/tools/FileReadTool/prompt.ts
  • src/tools/GlobTool/prompt.ts
  • src/tools/GrepTool/prompt.ts
  • src/tools/BriefTool/prompt.ts

10.2 Agent-Dateien​

  • src/tools/AgentTool/AgentTool.tsx
  • src/tools/AgentTool/runAgent.ts
  • src/tools/AgentTool/resumeAgent.ts
  • src/tools/AgentTool/forkSubagent.ts
  • src/tools/AgentTool/agentMemory.ts
  • src/tools/AgentTool/agentMemorySnapshot.ts
  • src/tools/AgentTool/builtInAgents.ts
  • src/tools/AgentTool/built-in/exploreAgent.ts
  • src/tools/AgentTool/built-in/planAgent.ts
  • src/tools/AgentTool/built-in/verificationAgent.ts
  • src/tools/AgentTool/built-in/generalPurposeAgent.ts
  • src/tools/AgentTool/built-in/claudeCodeGuideAgent.ts
  • src/tools/AgentTool/built-in/statuslineSetup.ts

10.3 Skill / Plugin / Hook / MCP​

  • src/tools/SkillTool/constants.ts
  • src/tools/SkillTool/prompt.ts
  • src/commands.ts
  • src/utils/plugins/loadPluginCommands.ts
  • src/services/tools/toolHooks.ts
  • src/utils/hooks.js
  • src/services/tools/toolExecution.ts
  • src/services/mcp/types.ts
  • src/services/mcp/normalization.ts
  • src/services/mcp/mcpStringUtils.ts
  • src/services/mcp/utils.ts
  • src/entrypoints/mcp.ts

10.4 Nächste gute Vertiefungen​

  1. query.ts
  2. resumeAgent.ts
  3. loadSkillsDir
  4. Plugin-Loading
  5. systemPromptSections.ts
  6. coordinator/*
  7. attachments.ts
  8. AgentSummary

Fazit​

Wenn nur ein Satz bleiben soll, dann dieser:

Das Geheimnis von Claude Code ist kein Systemprompt, sondern ein integriertes System aus Prompt-Architektur, Tool-Runtime, Permission-Modell, Agent-Orchestrierung, Skill-Paketierung, Plugin-System, Hook-Governance, MCP-Integration, Context-Hygiene und Product Engineering.

Darum wirkt Claude Code nicht wie ein Chatbot mit Tools, sondern wie ein governable und erweiterbares Agent Operating System.