Saltar al contenido principal

Informe de investigación profunda del código fuente de Claude Code

1. Alcance de la investigación y conclusión principal​

1.1 Qué se investigó realmente​

La investigación no consistió en leer un único archivo de prompt ni en mirar por encima la estructura del repositorio. Se reconstruyó el código a partir de sourcesContent dentro de cli.js.map y se siguió el flujo real del runtime.

Se cubrieron estos temas:

  • la estructura global del código fuente de Claude Code
  • cómo se ensambla dinámicamente el prompt del sistema principal
  • los protocolos del lado del modelo para AgentTool y SkillTool
  • la división de roles entre los built-in agents
  • la cadena de orquestación de agentes
  • cómo se integran plugins, skills, hooks y MCP
  • cómo cooperan permissions, tool execution y hook decisions
  • por qué Claude Code se siente mucho más sólido que un simple “LLM + tool caller”

1.2 Hechos confirmados​

Se pudieron confirmar al menos estos puntos:

  1. cli.js.map contiene sourcesContent completo
  2. se recuperaron al menos 4756 archivos fuente
  3. el archivo central del main system prompt es src/constants/prompts.ts
  4. el prompt de Agent Tool está en src/tools/AgentTool/prompt.ts
  5. el prompt de Skill Tool está en src/tools/SkillTool/prompt.ts
  6. el núcleo de la orquestación de agentes incluye src/tools/AgentTool/AgentTool.tsx y src/tools/AgentTool/runAgent.ts
  7. la cadena de ejecución de herramientas se apoya en src/services/tools/toolExecution.ts y src/services/tools/toolHooks.ts

1.3 El juicio más importante​

La fortaleza de Claude Code no viene de un system prompt mágico, sino de un sistema de software completo.

Su ventaja nace de combinar:

  • prompt assembly modular
  • ejecución de herramientas gobernada
  • modelo de permisos
  • agents especializados
  • empaquetado de workflows mediante skills
  • metadatos de plugins y runtime constraints
  • hooks como policy layer
  • MCP como plano de inyección de capacidades e instrucciones
  • construcción de prompts optimizada para cache
  • gestión del ciclo de vida asíncrono y en segundo plano

Resumen corto:

Claude Code no es un prompt. Es un Agent Operating System que unifica prompts, herramientas, permisos, agents, skills, plugins, hooks, MCP, cache y runtime de producto.

2. Arquitectura del código fuente: por qué se parece a un Agent Operating System​

2.1 La estructura superior ya revela complejidad de sistema​

En src/ aparecen módulos como:

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

Eso es una plataforma de runtime, no un envoltorio CLI fino.

2.2 La capa de entrada muestra mentalidad de plataforma​

Entrypoints visibles:

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

La misma runtime sirve para CLI, inicialización, modo MCP y consumidores SDK.

2.3 El sistema de comandos es una control plane​

Entre los comandos aparecen:

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

Además integra plugin commands, skill commands, bundled skills y dynamic skills. Es una puerta de entrada al ecosistema.

2.4 La capa de herramientas convierte al modelo en ejecutor​

Herramientas clave:

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

Esta capa transforma al modelo de respondedor en actor.

3. El papel real de prompts.ts​

3.1 src/constants/prompts.ts es el punto central de control​

Su importancia está en ensamblar las instrucciones runtime del hilo principal.

Se encarga de:

  • ensamblaje del main system prompt
  • inyección de entorno
  • reglas de uso de herramientas
  • reglas para acciones riesgosas
  • guidance específica de la sesión
  • idioma y estilo de salida
  • instrucciones MCP
  • memory prompt
  • scratchpad
  • function result clearing
  • secciones condicionadas como brief mode y token budget

3.2 getSystemPrompt() es un orquestador​

Su estructura separa un prefijo estático de un sufijo dinámico.

Prefijo estático:

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

Sufijo dinámico:

  • 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 trata los prompts como recursos runtime ensamblables.

3.3 La frontera de cache demuestra pensamiento de infraestructura​

Una frontera como SYSTEM_PROMPT_DYNAMIC_BOUNDARY deja claro que:

  • el prefijo debe ser cache-friendly
  • el contenido específico del usuario o la sesión debe ir después
  • no conviene alterar esa frontera sin cuidado

Eso es prompt assembly con economía de cache.

4. Desglose de las secciones del prompt​

4.1 getSimpleIntroSection()​

Esta parte fija que:

  • Claude es un interactive agent
  • su trabajo es ayudar en tareas de ingeniería de software
  • el estilo de salida viene controlado externamente
  • la cyber-risk guidance está presente desde el inicio
  • no debe inventar URLs

4.2 getSimpleSystemSection()​

Define la realidad del runtime:

  • la salida no ligada a herramientas se muestra al usuario
  • las herramientas corren bajo permission modes
  • una llamada denegada no debe repetirse igual
  • pueden existir etiquetas <system-reminder>
  • los resultados externos pueden contener prompt injection
  • existen hooks
  • el contexto puede comprimirse automáticamente

4.3 getSimpleDoingTasksSection()​

Esta sección estabiliza el comportamiento:

  • no agregar funciones no pedidas
  • no sobre-abstraer
  • no refactorizar por refactorizar
  • no añadir comentarios, docstrings o type annotations sin necesidad
  • no meter fallback o validación extra innecesaria
  • no construir abstracciones especulativas
  • leer antes de editar
  • evitar crear archivos nuevos sin motivo real
  • no dar estimaciones de tiempo a la ligera
  • diagnosticar antes de cambiar de estrategia
  • atender a la seguridad
  • eliminar lo claramente innecesario
  • reportar con honestidad lo que se verificó

4.4 getActionsSection()​

Las acciones que requieren confirmación incluyen:

  • destructive operations
  • hard-to-reverse operations
  • cambios sobre estado compartido
  • acciones visibles externamente
  • cargas a herramientas de terceros

4.5 getUsingYourToolsSection()​

La gramática de uso de herramientas es explícita:

  • leer con FileRead
  • editar con FileEdit
  • crear con FileWrite
  • descubrir archivos con Glob
  • buscar contenido con Grep
  • reservar Bash para trabajo shell genuino
  • usar TodoWrite / TaskCreate cuando existan
  • paralelizar llamadas independientes

4.6 Guidance específica de la sesión​

Esta capa inyecta reglas locales según el estado de la sesión: disponibilidad de AskUserQuestion, activación de AgentTool, Explore / Plan agents, slash skills, DiscoverSkills y contratos de verificación.

4.7 Output efficiency​

La idea es simple:

  • el usuario quiere lenguaje natural, no logs
  • decir primero la acción o la conclusión
  • actualizar cuando haga falta, sin ruido
  • evitar tablas innecesarias
  • escribir corto y directo

4.8 Tone and style​

Reglas como no abusar de emojis, responder de forma concisa y citar código con file_path:line_number mejoran mucho la sensación de producto.

4.9 DEFAULT_AGENT_PROMPT​

El rol base de un sub-agent es:

  • ser un agente de Claude Code
  • usar herramientas para completar la tarea
  • no dejar el trabajo a medias
  • devolver un informe breve al final

5. Agent prompts y built-in agents​

5.1 AgentTool/prompt.ts como documento de protocolo​

Explica al modelo:

  • cómo se presentan los agents
  • cómo se describen
  • cuándo debe forkearse a sí mismo
  • cuándo usar subagent_type
  • la diferencia entre fork y fresh agent
  • cuándo no usar AgentTool
  • cómo redactar un prompt para un sub-agent
  • diferencias foreground / background
  • significado de worktree y remote isolation

5.2 Por qué la semántica de fork es tan potente​

Con fork activado:

  • omitir subagent_type significa self-fork
  • el fork hereda el contexto completo
  • las tareas de investigación encajan muy bien
  • también las tareas de implementación con mucho output intermedio
  • el coste baja por compartir prompt cache
  • cambiar el modelo empeora la reutilización del cache
  • el hilo principal no debería espiar el output del fork
  • tampoco debería predecir su resultado por adelantado

5.3 La sección “How to write the prompt” es valiosa​

El modelo recibe reglas claras para delegar bien:

  • un fresh agent no tiene contexto previo
  • el prompt debe parecer un briefing a un nuevo compañero
  • explicar objetivo y razón
  • decir qué ya se descartó
  • aportar contexto suficiente
  • pedir brevedad si se necesita
  • no externalizar la comprensión del problema
  • no delegar de forma perezosa
  • dar rutas de archivo, líneas y cambios concretos

5.4 Los built-in agents representan especialización​

Roles confirmados:

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

5.5 Explore Agent como especialista read-only​

Explore no puede crear, modificar, borrar ni mover archivos. Usa Glob, Grep, FileRead y solo comandos Bash de lectura, priorizando velocidad y paralelización.

5.6 Plan Agent como planificador puro​

Plan permanece read-only, entiende la solicitud, explora el código y entrega un plan paso a paso con Critical Files for Implementation.

5.7 Verification Agent como adversarial validator​

El Verification agent debe intentar romper el cambio. Exige:

  • build
  • test suite
  • lint / type-check
  • verificaciones específicas según el tipo de cambio
  • automatización de navegador para frontend
  • curl / fetch para backend
  • stdout / stderr / exit code para CLI
  • migraciones up/down
  • verificación de API pública
  • adversarial probes
  • commands con outputs observados
  • VERDICT: PASS / FAIL / PARTIAL

6. La cadena de orquestación de agents​

6.1 Flujo general​

El flujo principal se resume así:

  1. el modelo principal llama al Agent tool
  2. AgentTool.call() analiza la entrada
  3. resuelve fork / built-in / teammate / background / remote
  4. selecciona la definición de agent
  5. construye prompt messages
  6. construye o hereda el system prompt
  7. arma el pool de herramientas
  8. crea un ToolUseContext específico del agent
  9. registra hooks, skills y MCP servers
  10. llama a runAgent()
  11. query() ejecuta el bucle principal
  12. se gestionan transcript, metadata y cleanup

6.2 AgentTool.call() es el controlador de orquestación​

Se encarga de parsear la entrada, manejar team context, decidir background, separar fork path y normal path, filtrar agents por permissions, revisar MCP, construir prompts, registrar tareas y lanzar runAgent().

6.3 fork path vs normal path​

fork path hereda contexto y maximiza la reutilización del prompt cache. normal path crea un system prompt nuevo, pasa solo el contexto necesario y aplica restricciones propias del agent.

6.4 Por qué importa el cache-identical prefix​

El objetivo es mantener un prefijo de request lo más idéntico posible para maximizar hits del prompt cache y reducir gasto de tokens.

6.5 Lifecycles foreground y background​

Los agents en background tienen abort controllers propios, registro de tareas y retorno vía notificaciones. Los foreground bloquean más al hilo principal y tienen progress tracking.

6.6 runAgent() como constructor de runtime​

runAgent() inicializa MCP servers del agent, prepara contexto, resuelve tools y permissions, registra hooks y skills, ejecuta query() y limpia recursos.

6.7 MCP servers específicos del agent​

Los agents pueden traer sus propios MCP servers, añadiendo capacidades especializadas al runtime.

6.8 frontmatter hooks y frontmatter skills​

Hooks y skills pueden inyectarse por frontmatter, lo que convierte al agent en un prompt container configurable.

6.9 query() como bucle principal final​

La separación es clara:

  • AgentTool enruta
  • runAgent construye runtime y lifecycle
  • query ejecuta el bucle modelo + herramientas

6.10 transcript / metadata / cleanup​

El registro de transcript, metadata, tracking y limpieza demuestra un alto nivel de productización.

7. Skills / Plugins / Hooks / MCP​

7.1 Skill como workflow package​

Las skills son primitivas de primer nivel. Si una tarea coincide con una skill, el modelo debe invocar el Skill tool, no solo mencionar la skill.

7.2 Plugin como prompt + metadata + runtime constraints​

Los plugins pueden aportar markdown commands, SKILL.md, metadatos, allowed tools, hints de modelo y variables runtime. Extienden el comportamiento del modelo.

7.3 Hook como runtime governance layer​

Los hooks PreToolUse, PostToolUse y PostToolUseFailure pueden devolver mensajes, errores bloqueantes, inputs modificados, comportamiento de permisos o contexto adicional.

7.4 Integración madura entre hooks y permissions​

Los hooks pueden devolver allow, ask o deny, pero no evitan el modelo central de seguridad.

7.5 MCP como capa de inyección de comportamiento​

MCP inyecta no solo herramientas, sino también instrucciones sobre cómo usarlas.

8. Permissions, hooks y tool execution pipeline​

8.1 toolExecution.ts​

El pipeline incluye lookup del tool, parseo de metadata, validación de esquema, validación específica, hooks, decisión de permisos, ejecución del tool, telemetría y post-hooks.

8.2 Validación de entrada​

Los errores básicos se bloquean pronto con schema parsing y validación específica.

8.3 PreToolUse hooks​

Los campos más importantes son updatedInput, permissionBehavior y preventContinuation.

8.4 resolveHookPermissionDecision()​

Esta lógica conecta la semántica de hooks con el modelo central de permisos.

8.5 La gobernanza continúa después del tool call​

Incluso tras éxito o fallo, los hooks pueden inyectar contexto, bloquear continuidad o aportar pistas de recuperación.

9. Por qué Claude Code se siente tan fuerte​

9.1 No es un prompt, sino un operating model​

Su verdadero foso competitivo es la integración entre prompt architecture, runtime gobernado, permissions, hooks, especialización de agents, skills, plugins, MCP, cache y lifecycle management.

9.2 Institucionaliza el buen comportamiento​

Claude Code no deja los buenos hábitos a la improvisación del modelo; los codifica en prompts y reglas runtime.

9.3 Entiende que el contexto es escaso​

Las fronteras de prompt, la reutilización de cache, la inyección bajo demanda, el result clearing y los mecanismos de resume muestran que los tokens se gestionan como presupuesto.

9.4 Profundidad de la especialización de agents​

Explore, Plan y Verification separan investigación, planificación, implementación y validación.

9.5 Ecosistema visible para el modelo​

El modelo conoce sus extensiones mediante skill lists, agent lists, MCP instructions y session-specific guidance. Por eso el ecosistema realmente funciona.

10. Archivos clave y próximas líneas de investigación​

10.1 Archivos 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 Archivos de 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 Próximas áreas para profundizar​

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

Conclusión​

Si hubiera que quedarse con una sola frase, sería esta:

El verdadero secreto de Claude Code no es un system prompt, sino un sistema unificado que combina prompt architecture, tool runtime, permission model, agent orchestration, skill packaging, plugin system, hook governance, MCP integration, context hygiene y product engineering.

Por eso Claude Code se parece menos a un chat con herramientas y más a un Agent Operating System extensible y gobernable.