Aller au contenu principal

Rapport d'analyse approfondie du code source de Claude Code

1. Périmètre de recherche et conclusion générale​

1.1 Ce qui a réellement été étudié​

L'analyse n'a pas consisté à lire un seul fichier de prompt ni à survoler l'arborescence. Elle a reconstruit les fichiers depuis sourcesContent dans cli.js.map, puis a suivi le runtime de bout en bout.

Les sujets principaux :

  • la structure globale du code source de Claude Code
  • l'assemblage dynamique du prompt système principal
  • les protocoles côté modèle de AgentTool et SkillTool
  • la répartition des rôles entre les built-in agents
  • la chaîne d'orchestration des agents
  • l'intégration de plugins, skills, hooks et MCP
  • la coopération entre permissions, tool execution et hook decisions
  • les raisons pour lesquelles Claude Code paraît bien plus solide qu'un simple « LLM + tool caller »

1.2 Faits confirmés​

Les éléments suivants sont établis :

  1. cli.js.map contient bien un sourcesContent complet
  2. au moins 4756 fichiers source ont pu être reconstruits
  3. le fichier central du main system prompt est src/constants/prompts.ts
  4. le prompt de l'Agent tool est dans src/tools/AgentTool/prompt.ts
  5. le prompt du Skill tool est dans src/tools/SkillTool/prompt.ts
  6. le cœur de l'orchestration d'agents inclut src/tools/AgentTool/AgentTool.tsx et src/tools/AgentTool/runAgent.ts
  7. la chaîne d'exécution d'outils repose notamment sur src/services/tools/toolExecution.ts et src/services/tools/toolHooks.ts

1.3 Le jugement le plus important​

La force de Claude Code ne vient pas d'un prompt magique, mais d'un système logiciel complet.

Ses avantages viennent de la combinaison de :

  • prompt assembly modulaire
  • exécution d'outils gouvernée
  • modèle d'autorisations
  • agents spécialisés
  • packaging de workflows via les skills
  • métadonnées et contraintes runtime des plugins
  • hooks comme couche de politique
  • MCP comme plan d'injection de capacités et d'instructions
  • construction de prompts optimisée pour le cache
  • gestion du cycle de vie asynchrone et en arrière-plan

En une phrase :

Claude Code n'est pas un prompt. C'est un Agent Operating System qui unifie prompts, outils, permissions, agents, skills, plugins, hooks, MCP, cache et runtime produit.

2. Architecture du code source : pourquoi cela ressemble à un Agent Operating System​

2.1 La structure de haut niveau montre déjà la complexité​

L'arborescence src/ expose des modules comme :

  • 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/

On n'est pas face à un simple emballage CLI, mais à une véritable plateforme runtime.

2.2 La couche d'entrée montre une logique de plateforme​

Les entrypoints visibles incluent :

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

La même runtime sert donc au CLI, à l'initialisation, au mode MCP et à des consommateurs SDK.

2.3 Le système de commandes est une control plane​

Les commandes exposées comprennent notamment :

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

Le système charge aussi des plugin commands, skill commands, bundled skills et dynamic skills. Il sert donc d'entrée à l'écosystème.

2.4 La couche d'outils transforme le modèle en exécuteur​

Parmi les outils essentiels :

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

C'est cette couche qui fait passer le modèle d'un simple répondeur à un agent d'exécution.

3. Le rôle réel de prompts.ts​

3.1 src/constants/prompts.ts est le point de contrôle principal​

Ce fichier n'est pas important parce qu'il contient un long texte, mais parce qu'il assemble les instructions runtime du thread principal.

Il gère :

  • l'assemblage du main system prompt
  • l'injection d'informations d'environnement
  • les règles d'usage des outils
  • les règles d'actions risquées
  • la guidance spécifique à la session
  • la langue et le style de sortie
  • les instructions MCP
  • le memory prompt
  • le scratchpad
  • le function result clearing
  • des sections conditionnelles comme brief mode ou token budget

3.2 getSystemPrompt() est un orchestrateur​

La structure centrale sépare un préfixe statique d'un suffixe dynamique.

Préfixe statique :

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

Suffixe dynamique :

  • 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 traite le prompt comme une ressource runtime assemblable.

3.3 La frontière de cache révèle une pensée d'infrastructure​

La présence d'une frontière comme SYSTEM_PROMPT_DYNAMIC_BOUNDARY montre une intention claire :

  • garder le préfixe compatible avec le cache
  • placer les contenus propres à l'utilisateur ou à la session après la frontière
  • éviter de casser la logique de cache

C'est de l'assemblage de prompts avec économie de cache.

4. Décomposition des sections de prompt​

4.1 getSimpleIntroSection()​

Cette section pose :

  • Claude comme interactive agent
  • la mission d'aide au software engineering
  • un output style piloté de l'extérieur
  • la cyber-risk guidance dès le début
  • l'interdiction d'inventer des URL

4.2 getSimpleSystemSection()​

Elle définit la réalité du runtime :

  • les sorties hors outil sont visibles directement par l'utilisateur
  • les outils s'exécutent sous permission modes
  • un appel refusé ne doit pas être rejoué tel quel
  • les messages peuvent inclure <system-reminder>
  • les sorties d'outils peuvent contenir du prompt injection
  • des hooks existent
  • le contexte peut être compacté automatiquement

4.3 getSimpleDoingTasksSection()​

Cette section stabilise fortement le comportement :

  • ne pas ajouter de fonctionnalités non demandées
  • ne pas sur-abstraire
  • ne pas refactorer gratuitement
  • ne pas ajouter inutilement commentaires, docstrings ou annotations de type
  • ne pas ajouter de fallback ou validation sans besoin réel
  • ne pas construire d'abstractions spéculatives
  • lire avant d'éditer
  • éviter les nouveaux fichiers inutiles
  • éviter les estimations de temps hasardeuses
  • diagnostiquer avant de changer de stratégie
  • faire attention à la sécurité
  • supprimer le code clairement inutile
  • rapporter honnêtement ce qui a été vérifié

4.4 getActionsSection()​

Les actions à confirmer incluent :

  • destructive operations
  • hard-to-reverse operations
  • modification d'état partagé
  • actions visibles à l'extérieur
  • envoi à des outils tiers

4.5 getUsingYourToolsSection()​

La grammaire d'utilisation des outils est explicite :

  • lire avec FileRead
  • éditer avec FileEdit
  • créer avec FileWrite
  • chercher des fichiers avec Glob
  • chercher du contenu avec Grep
  • garder Bash pour les vrais besoins shell
  • utiliser TodoWrite / TaskCreate si disponibles
  • paralléliser les appels indépendants

4.6 Guidance spécifique à la session​

Cette couche dynamique injecte des règles locales selon la session : disponibilité de AskUserQuestion, activation de AgentTool, agents Explore/Plan, slash skills, DiscoverSkills, contrat de vérification, etc.

4.7 Output efficiency​

La logique est simple :

  • l'utilisateur lit du langage naturel, pas des logs
  • commencer par l'action ou la conclusion
  • mettre à jour quand c'est utile, sans bavardage
  • éviter les tableaux inutiles
  • écrire court et direct

4.8 Tone and style​

Des détails comme l'absence d'emojis inutiles, les réponses concises et les références de type file_path:line_number contribuent fortement à la sensation produit.

4.9 DEFAULT_AGENT_PROMPT​

Le rôle de base d'un sub-agent est :

  • être un agent de Claude Code
  • utiliser les outils pour finir la tâche
  • éviter les résultats partiels
  • produire un rapport concis à la fin

5. Agent prompts et built-in agents​

5.1 AgentTool/prompt.ts comme document protocolaire​

Cette section explique au modèle :

  • comment les agents sont listés
  • comment ils sont décrits
  • quand il faut se forker soi-même
  • quand il faut préciser subagent_type
  • la différence entre fork et fresh agent
  • quand ne pas utiliser AgentTool
  • comment écrire un prompt pour un sub-agent
  • les différences foreground/background
  • la sémantique de l'isolation worktree/remote

5.2 Pourquoi la sémantique de fork est puissante​

Quand le fork est activé :

  • omettre subagent_type signifie se forker soi-même
  • le fork hérite du contexte complet
  • les tâches de recherche s'y prêtent bien
  • les tâches d'implémentation à gros outputs intermédiaires aussi
  • le coût est réduit grâce au prompt cache partagé
  • changer de modèle nuit au cache
  • le thread principal ne doit pas espionner les outputs du fork
  • il ne doit pas non plus prédire le résultat du fork

5.3 La section « How to write the prompt » est précieuse​

Le modèle est explicitement entraîné à bien déléguer :

  • un fresh agent n'a pas de contexte antérieur
  • le prompt doit ressembler à un briefing pour un nouveau collègue
  • il faut donner l'objectif et la raison
  • préciser ce qui a déjà été écarté
  • fournir assez de contexte pour juger
  • demander explicitement une réponse courte si nécessaire
  • ne pas externaliser la compréhension du problème
  • ne pas déléguer de manière paresseuse
  • donner des chemins de fichiers, lignes et changements concrets

5.4 Les built-in agents matérialisent la spécialisation​

Rôles confirmés :

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

5.5 Explore Agent comme spécialiste read-only​

Explore ne peut ni créer, ni modifier, ni supprimer, ni déplacer des fichiers. Il utilise Glob, Grep, FileRead et seulement des commandes Bash en lecture, avec priorité à la vitesse et à la parallélisation.

5.6 Plan Agent comme planificateur pur​

Plan reste read-only, comprend la demande, inspecte la base de code et produit un plan pas à pas ainsi qu'une liste de Critical Files for Implementation.

5.7 Verification Agent comme adversarial validator​

Le Verification agent doit chercher à casser le changement. Il impose :

  • build
  • tests
  • lint / type-check
  • vérifications spécialisées selon le type de changement
  • automation navigateur pour le frontend
  • curl / fetch pour le backend
  • stdout / stderr / exit code pour les CLI
  • migration up/down
  • vérification de l'API publique
  • adversarial probes
  • commandes et outputs observés
  • VERDICT: PASS / FAIL / PARTIAL

6. La chaîne d'orchestration des agents​

6.1 Vue globale​

Le flux principal ressemble à ceci :

  1. le modèle principal appelle l'Agent tool
  2. AgentTool.call() analyse l'entrée
  3. fork / teammate / built-in / background / remote sont résolus
  4. la définition d'agent est sélectionnée
  5. les prompt messages sont construits
  6. le system prompt est construit ou hérité
  7. le pool d'outils est assemblé
  8. un ToolUseContext spécifique à l'agent est créé
  9. hooks, skills et MCP servers sont enregistrés
  10. runAgent() est lancé
  11. query() prend en charge la boucle principale
  12. transcript, metadata et cleanup sont gérés

6.2 AgentTool.call() est le contrôleur d'orchestration​

Il gère notamment le parsing des inputs, le team context, l'autorisation du background, la séparation fork/normal, les filtres de permissions, les exigences MCP, l'isolation distante, la construction des prompts, l'enregistrement des tâches et l'appel à runAgent().

6.3 fork path vs normal path​

Le fork path privilégie l'héritage de contexte et la réutilisation du cache. Le normal path crée un system prompt propre à l'agent, transmet seulement le contexte nécessaire et applique les restrictions d'outils propres à cet agent.

6.4 Pourquoi un préfixe cache-identical est important​

L'objectif est de conserver un préfixe de requête aussi identique que possible afin d'augmenter les hits du prompt cache et de réduire les coûts en tokens.

6.5 Lifecycles foreground et background​

Les agents en arrière-plan ont leur propre abort controller, leur enregistrement de tâche et reviennent via notifications. Les agents foreground sont suivis dans le thread principal avec progress tracking.

6.6 runAgent() comme constructeur de runtime​

runAgent() initialise les MCP servers spécifiques, prépare le contexte, résout les tools et permissions, enregistre hooks et skills, lance query(), enregistre les transcripts puis nettoie les ressources.

6.7 MCP servers spécifiques à l'agent​

Les agents peuvent embarquer leurs propres MCP servers et donc des capacités additives spécialisées.

6.8 frontmatter hooks et frontmatter skills​

Les hooks et skills peuvent être injectés via le frontmatter. Un agent est donc un conteneur de prompt configurable.

6.9 query() comme boucle finale​

La séparation des rôles est claire :

  • AgentTool route
  • runAgent construit le runtime
  • query exécute la boucle modèle + outils

6.10 transcript / metadata / cleanup​

L'enregistrement des transcripts, les métadonnées, le tracking et le nettoyage montrent un niveau de productisation élevé.

7. Skills / Plugins / Hooks / MCP​

7.1 Skill comme workflow package​

Les skills sont des primitives de premier ordre. Un task qui correspond à un skill doit déclencher le Skill tool, pas seulement citer le skill.

7.2 Plugin comme prompt + metadata + runtime constraints​

Les plugins peuvent fournir des markdown commands, des SKILL.md, des métadonnées, des allowed tools, des hints de modèle et des variables runtime. Ils étendent donc le comportement du modèle lui-même.

7.3 Hook comme couche de gouvernance runtime​

Les hooks PreToolUse, PostToolUse et PostToolUseFailure peuvent renvoyer messages, erreurs bloquantes, input modifié, comportement de permission ou contexte additionnel.

7.4 Intégration mature entre hooks et permissions​

Les hooks peuvent proposer allow, ask ou deny, mais ne contournent pas le modèle de sécurité central.

7.5 MCP comme couche d'injection de comportement​

MCP n'injecte pas seulement des outils, mais aussi les instructions sur la manière de les utiliser.

8. Permissions, hooks et pipeline d'exécution des outils​

8.1 toolExecution.ts​

Le pipeline comprend : lookup du tool, parsing des métadonnées, validation du schéma, validation spécifique, hooks, décision de permission, appel du tool, télémétrie et post-hooks.

8.2 Validation d'entrée​

Les erreurs triviales sont stoppées tôt grâce au parsing du schéma et à la validation spécifique à l'outil.

8.3 PreToolUse hooks​

Les champs les plus importants sont updatedInput, permissionBehavior et preventContinuation.

8.4 resolveHookPermissionDecision()​

Cette logique relie proprement la sémantique des hooks au modèle central de permissions.

8.5 La gouvernance continue après le tool call​

Même après succès ou échec, les hooks peuvent encore injecter du contexte, bloquer la suite ou fournir des indices de récupération.

9. Pourquoi Claude Code paraît si fort​

9.1 Ce n'est pas un prompt, mais un operating model​

Le véritable fossé défensif est l'intégration entre prompt architecture, runtime gouvernée, permissions, hooks, spécialisation des agents, packaging des skills, plugins, MCP, cache et lifecycle management.

9.2 Institutionnalisation des bons comportements​

Claude Code n'attend pas du modèle qu'il improvise de bonnes pratiques. Il les encode dans le prompt et dans les règles runtime.

9.3 Compréhension de la rareté du contexte​

Les frontières de prompt, la réutilisation du cache, l'injection à la demande, le result clearing et les mécanismes de resume montrent que les tokens sont gérés comme un budget.

9.4 Profondeur de la spécialisation des agents​

Explore, Plan et Verification séparent clairement recherche, planification, implémentation et validation.

9.5 Un écosystème visible par le modèle​

Le modèle connaît ses extensions via skill lists, agent lists, MCP instructions et session-specific guidance. C'est ce qui rend l'écosystème réellement utilisable.

10. Fichiers clés et prochaines pistes​

10.1 Fichiers de prompt​

  • 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 Fichiers d'agents​

  • 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 Pistes de recherche suivantes​

  1. query.ts
  2. resumeAgent.ts
  3. loadSkillsDir
  4. le chargement des plugins
  5. systemPromptSections.ts
  6. coordinator/*
  7. attachments.ts
  8. AgentSummary

Conclusion​

S'il ne faut garder qu'une phrase, c'est celle-ci :

Le vrai secret de Claude Code n'est pas un system prompt, mais un système unifié qui combine prompt architecture, runtime des outils, modèle de permissions, orchestration d'agents, packaging des skills, système de plugins, gouvernance par hooks, intégration MCP, hygiène du contexte et product engineering.

C'est pourquoi Claude Code ressemble moins à une interface de chat avec outils qu'à un Agent Operating System extensible et gouvernable.