Construyamos el harness de Claude Code (paso a paso)

Cubriremos todo lo que implica construir un arnés de codificación: el bucle del agente, la planificación, los subagentes, el sandboxing, la memoria y los puntos de control, todo construido paso a paso.

Si alguna vez has intentado construir tu propio agente de codificación, sabes cómo funciona. Conectas un modelo a herramientas de archivos y una terminal, lo apuntas a un código base real y se descompone en menos de una docena de llamadas a herramientas.

Lee los archivos equivocados, pierde el objetivo a mitad de camino y llena su contexto con resultados que ya no necesita.

Luego, la misma tarea pasa por Claude Code y se completa limpiamente. La conclusión fácil es que Anthropic simplemente tiene un mejor modelo, y esa conclusión pasa por alto dónde ocurre realmente el trabajo.

La diferencia es el arnés. Un arnés es el código común que envuelve al modelo, y maneja la planificación, la ejecución de herramientas, la memoria y la seguridad, mientras que el modelo solo decide el siguiente paso.

Así es como se ve un agente completamente equipado con un arnés cuando lo dibujas:

GIF

La imagen parece cargada, pero se divide en cuatro grupos:

• Memoria: alimenta al modelo con su contexto de trabajo más los hechos que ha aprendido entre sesiones.
• Habilidades: codifican cómo debe operar el agente, es decir, los procedimientos, restricciones y heurísticas que sigue.
• Protocolos: conectan al agente con usuarios, herramientas y otros agentes.
• El núcleo del arnés: lo une todo con orquestación de subagentes, un sandbox, un evaluador, un bucle de aprobación, observabilidad y compresión de contexto.

Anthropic describe esta división como el cerebro y las manos. El modelo es el cerebro que elige cada acción, y el arnés son las manos que la ejecutan y mantienen la ejecución en curso.

Así que la brecha entre tu agente y Claude Code no es el modelo, es la maquinaria alrededor del modelo.

Claude Code es uno de los arneses más capaces en producción hoy en día, y está construido a partir de un conjunto sorprendentemente pequeño de las capas en esa ilustración. Para ver cuánto de esa maquinaria tendrías que construir tú mismo, lo reconstruí en CrewAI, un framework de código abierto para orquestar agentes.

Más de lo esperado se asigna a funciones integradas, y la parte que no lo hace es donde reside la verdadera ingeniería.

Construyámoslo capa por capa, comenzando con el bucle central y apilando planificación, subagentes, sandboxing y memoria encima. En cada paso marcaremos dónde termina el framework y dónde comienza tu trabajo.

Cómo funciona el arnés de Claude Code

En el centro de Claude Code hay un bucle de agente simple. Le envías un mensaje, el modelo decide qué hacer a continuación, y responde directamente o solicita una herramienta. Si solicita una, la herramienta se ejecuta, el resultado vuelve a la conversación y el modelo decide nuevamente.

Esto se repite hasta que el modelo devuelve una respuesta final sin más llamadas a herramientas.

Dentro de ese bucle, el modelo lee archivos, edita código, ejecuta comandos de terminal y ejecuta pruebas. Estas no son modalidades separadas. Son solo diferentes llamadas a herramientas dentro del mismo bucle.

Sin embargo, el bucle por sí solo no es suficiente para un agente de codificación confiable. Claude Code añade planificación, herramientas de archivos, subagentes, memoria y un sistema de permisos y sandbox a su alrededor. Estas capas no reemplazan el bucle, lo hacen seguro y confiable para el trabajo real.

Esa es la arquitectura que reconstruiremos: primero el bucle central, luego cada capa encima, asignando cada capa a la función de CrewAI que la maneja.

El bucle central del agente

El bucle ejecuta la misma secuencia hasta que la tarea está completa:

1. Pide al modelo que realice la tarea.
2. El modelo responde directamente o solicita una o más herramientas.
3. Si se solicitan herramientas, ejecútalas y devuelve los resultados al modelo.
4. Repite con la conversación actualizada.
5. Cuando el modelo responde sin solicitar herramientas, la tarea está completa.

1while True:
2    reply = model(messages, tools)
3    calls = [b for b in reply if b.type == "tool_use"]
4    if not calls:            # plain text, no tool call: the job is done
5        return reply.text
6    messages += [reply, run_all(calls)]

Cada llamada a herramienta completa un paso, le da nueva información al modelo y alimenta la siguiente decisión. Una pregunta simple podría terminar en una iteración, mientras que corregir un error complejo o refactorizar un código base grande puede requerir docenas de iteraciones antes de que el modelo tenga suficiente para producir una respuesta final.

CrewAI proporciona este bucle de ejecución automáticamente tan pronto como creas un agente. No implementas el bucle while tú mismo, defines el agente y le asignas una tarea.

Construyendo el primer agente

Creemos un agente simple de Corrector de Errores.

1from crewai import LLM, Agent, Crew, Task
2
3bug_fixer = Agent(
4    role="Corrector de Errores",
5    goal="Encontrar y describir la solución para el error reportado en el código base.",
6    backstory="Lee directorios y archivos para construir una imagen precisa del código.",
7    llm="claude-sonnet-4-6",
8)
9
10task = Task(
11    description="Encuentra la solución para {objective}.",
12    expected_output="Una breve descripción de la solución y en qué archivo pertenece.",
13)
14
15result = Crew(agents=[bug_fixer], tasks=[task]).kickoff(
16    inputs={"objective": "el error de sobregiro en account.py"}
17)

Tres conceptos que entender aquí:

• Un Agente define quién hace el trabajo, a través de su rol, objetivo, LLM y herramientas.
• Una Tarea describe la asignación.
• Un Crew reúne agentes y tareas. Llamar a kickoff() ejecuta el mismo bucle de ejecución descrito anteriormente, independientemente de si el modelo subyacente es Anthropic, OpenAI, Google u otro.

Dándole herramientas al agente

Las herramientas son lo que permite que un modelo que solo genera texto trabaje realmente en un código base. Leen archivos, los escriben, ejecutan comandos de terminal y llaman a APIs externas.

CrewAI incluye herramientas del sistema de archivos listas para usar:

• FileReadTool lee archivos.
• DirectoryReadTool lista directorios.
• FileWriterTool escribe archivos.

1from crewai_tools import DirectoryReadTool, FileReadTool, FileWriterTool
2
3read_file = FileReadTool()
4write_file = FileWriterTool()
5list_dir = DirectoryReadTool()
6
7filesystem_tools = [read_file, write_file, list_dir]

Estas también funcionan como memoria externa. En lugar de mantener un gran resultado de búsqueda en la ventana de contexto del modelo, el agente puede escribirlo en un archivo, conservar solo el nombre del archivo y leerlo de nuevo cuando sea necesario.

Esto mantiene la ventana de contexto más pequeña y al modelo más enfocado, que es lo que Anthropic llama ingeniería de contexto.

Las herramientas integradas solo cubren flujos de trabajo comunes. Para algo más específico, expones una función de Python como herramienta con el decorador @tool.

El docstring actúa como el manual de instrucciones, diciéndole al modelo qué hace la herramienta, cuándo usarla y qué espera como entrada.

1from crewai.tools import tool
2import subprocess
3
4@tool("run_tests")
5def run_tests(path: str = "tests/") -> str:
6    """Run the pytest suite at the given path and return the result."""
7    result = subprocess.run(
8        ["pytest", path, "-q"], capture_output=True, text=True, timeout=120
9    )
10    output = result.stdout + result.stderr
11    return output[-4000:] if len(output) > 4000 else output

Planificación de tareas de larga duración

A medida que las tareas se vuelven más complejas, un bucle de ejecución simple comienza a perder de vista el objetivo original. Después de suficientes llamadas a herramientas, lecturas de archivos y resultados intermedios, el contexto se llena y el objetivo queda desplazado por todo lo que vino después.

Esta degradación lenta es lo que se llama podredumbre de contexto.

La planificación lo aborda directamente. El agente construye un plan paso a paso antes de hacer cualquier trabajo y mantiene ese plan en contexto durante toda la ejecución.

El plan no hace el trabajo. Es una hoja de ruta que mantiene al modelo conectado con el objetivo original, que es el mismo trabajo que hace la lista de tareas de Claude Code.

CrewAI añade esto a nivel del crew con planning=True. Genera un plan antes de la ejecución y lo mantiene disponible mientras avanza la tarea.

1from crewai import Crew, LLM
2
3crew = Crew(
4    agents=self.agents,
5    tasks=self.tasks,
6    planning=True,
7    planning_llm=LLM(model="gpt-4o-mini"),
8)

Nota: Por defecto, CrewAI usa gpt-4o-mini para la planificación, y puedes cambiarlo por cualquier otro LLM que prefieras para ese paso.

Los agentes individuales también pueden razonar sobre su propio trabajo con reasoning=True:

1from crewai import Agent
2
3bug_fixer = Agent(
4    role="Corrector de Errores",
5    goal="Encontrar y describir la solución para el error reportado en el código base.",
6    backstory="Lee directorios y archivos para construir una imagen precisa del código.",
7    tools=[FileReadTool()],
8    reasoning=True,
9    max_reasoning_attempts=3  # Opcional: Establecer un número máximo de intentos de razonamiento
10)

La planificación y el razonamiento resuelven problemas diferentes. La planificación construye una hoja de ruta de alto nivel para la tarea general, mientras que el razonamiento le da a un agente tiempo para pensar en su propio enfoque antes de actuar.

Cuando el razonamiento está habilitado, el agente:

1. Reflexiona sobre la tarea y redacta un plan de ejecución.
2. Evalúa si el plan está listo.
3. Refina el plan si es necesario, hasta que esté satisfecho o alcance max_reasoning_attempts.
4. Inyecta el plan de razonamiento finalizado en la tarea antes de la ejecución.

Juntos, mantienen al agente anclado en tareas de larga duración y reducen la desviación del objetivo original.

Delegando con subagentes

La planificación mantiene al agente enfocado, pero no reduce la cantidad de información que el modelo tiene que retener. En un código base grande, incluso una tarea bien planificada puede exceder una sola ventana de contexto.

Encontrar un error puede requerir leer docenas de archivos, y el agente principal no necesita mantenerlos todos en memoria.

Los subagentes resuelven esto mediante la delegación. El agente principal entrega una tarea específica a un agente auxiliar, que trabaja en su propio contexto y devuelve un resumen breve. El agente principal ve la conclusión, no los pasos intermedios.

CrewAI admite esto a través de flujos de trabajo jerárquicos, donde un agente gestor delega a agentes especialistas y combina sus resultados.

En nuestra configuración anterior, un solo agente Corrector de Errores hacía todo el trabajo pesado. Dividamos el trabajo entre un gestor y tres especialistas:

• Explorador de Código Base explora el código y mapea el repositorio.
• Ingeniero de Software implementa el cambio solicitado.
• Ejecutor de Pruebas ejecuta las pruebas en el sandbox e informa si pasan o fallan.
• Líder de Ingeniería supervisa a los tres especialistas.

1from crewai import Crew, Agent, Task, Process
2
3explorer = Agent(
4    role="Explorador de Código Base",
5    goal="Mapear el repositorio y mostrar los archivos relevantes para la tarea.",
6    backstory="Lee directorios y archivos para construir una imagen del código.",
7    tools=[read_file, list_dir],
8    llm=llm,
9)  # Lo mismo para los otros dos agentes especialistas
10
11manager = Agent(
12    role="Líder de Ingeniería",
13    goal="Dividir la solicitud en pasos y delegar cada uno al especialista adecuado.",
14    backstory="Decides quién hace qué, revisas las pruebas, terminas cuando el cambio está hecho.",
15    llm=llm,
16    allow_delegation=True,
17)
18
19crew = Crew(
20    agents=[explorer, coder, tester],
21    tasks=[task],
22    manager_agent=manager,
23    process=Process.hierarchical,
24)

Algo a tener en cuenta es que allow_delegation está deshabilitado por defecto, por lo que debe habilitarse explícitamente en el gestor.

Sandboxing: Asegurando la ejecución del agente

Un agente con acceso a la terminal puede ejecutar un comando destructivo, y decirle al modelo que no haga algo no es una salvaguarda.

La protección real proviene de dos capas:

1. Un sistema de permisos que requiere aprobación para acciones sensibles.
2. Un sandbox que aísla la ejecución, de modo que incluso los comandos aprobados no puedan tocar la máquina anfitriona.

Anthropic usa el mismo enfoque. Mover la ejecución de código a un sandbox reduce la frecuencia con la que el usuario necesita aprobar acciones, al mismo tiempo que protege el sistema anfitrión.

Sandboxing en CrewAI

Ejecutar código dentro de un sandbox en lugar de en la máquina anfitriona aplica esa segunda capa. En esta configuración, el código se ejecuta dentro de E2B, que inicia una VM fresca por sesión y la destruye después.

Los comandos de terminal y Python se ejecutan completamente dentro de ese entorno aislado.

1from crewai_tools import E2BExecTool, E2BPythonTool
2sandbox_tools = [E2BExecTool(), E2BPythonTool()]  # ejecutar pruebas / ejecutar código

Aprobación con intervención humana

Establecer human_input=True en una Tarea pausa al crew después de que genera una respuesta. Revisas el resultado, luego lo apruebas o lo devuelves para otra iteración.

Cuando la ejecución llega a esa tarea, CrewAI espera tu retroalimentación a través de la entrada estándar.

1from crewai import Task
2
3task = Task(
4    description=(
5        "En el directorio de trabajo ./workspace, {objective}. "
6        "Explora el código primero, haz el cambio, luego ejecuta las pruebas e informa."
7    ),
8    expected_output="Un resumen de los archivos modificados y el resultado final de las pruebas.",
9    human_input=True,
10)

Si tu crew se ejecuta detrás de una aplicación web o una interfaz de chat en lugar de una terminal, el sistema de intervención humana basado en webhooks de CrewAI maneja el mismo paso de revisión.

Memoria y puntos de control

Por defecto, un agente olvida todo una vez que termina una ejecución. Vuelves al día siguiente para corregir otro error en el mismo proyecto y comienza desde cero.

Dos mecanismos permiten que un agente transporte información entre ejecuciones, y cada uno sirve un propósito diferente:

• Puntos de control guardan el estado del agente durante una ejecución, para que pueda reanudarse después de una interrupción o continuar desde el mismo punto por un camino diferente.
• Memoria persistente almacena hechos a través de conversaciones separadas, incluyendo preferencias del proyecto como "siempre formatear el código final antes de terminar".

Memoria en CrewAI

CrewAI proporciona una interfaz de Memoria unificada en lugar de tipos separados de memoria a corto plazo, largo plazo, de entidades y externa. Al guardar, usa un LLM para identificar detalles importantes, organizarlos y hacerlos recuperables más tarde.

Establecer memory=True en el crew le da memoria entre ejecuciones. Después de cada tarea, CrewAI extrae hechos útiles del resultado y los almacena, y en ejecuciones futuras recupera recuerdos relevantes y los añade al prompt de la tarea.

1from crewai import Crew
2
3crew = Crew(
4    agents=[explorer, coder, tester],
5    tasks=[task],
6    memory=True,
7)

Todos los agentes en un crew comparten su memoria a menos que un agente tenga la suya propia.

Puntos de control en CrewAI

Un punto de control es una instantánea del progreso de un agente, incluyendo su configuración, estado de la tarea, memoria, resultados intermedios, entradas e historial de ejecución.

Por defecto, CrewAI crea un punto de control cada vez que una tarea termina, lo que permite reanudar el flujo de trabajo desde ese punto si se interrumpe.

Los puntos de control pueden residir en uno de dos almacenes integrados:

• JsonProvider guarda cada punto de control como un archivo JSON separado, que es fácil de leer e inspeccionar manualmente.
• SqliteProvider almacena todos los puntos de control en una sola base de datos SQLite, que se comporta mejor bajo puntos de control frecuentes y cargas de trabajo más grandes.

1from crewai import Crew
2
3crew = Crew(
4    agents=[explorer, coder, tester],
5    tasks=[task],
6    checkpoint=True,
7)

Crew, Flow y Agent aceptan un argumento checkpoint, y los hijos heredan de su padre a menos que establezcan su propio valor.

Poniéndolo todo junto

Aquí está el arnés completo en una tarea, con el bucle de ejecución, herramientas, planificación, subagentes, sandboxing y memoria trabajando juntos:

1from crewai import Agent, Crew, LLM, Process, Task
2from crewai.tools import tool
3from crewai_tools import (DirectoryReadTool, FileReadTool, FileWriterTool,
4E2BExecTool, E2BPythonTool)
5
6llm = LLM(model="anthropic/claude-sonnet-4.6")
7
8list_dir = DirectoryReadTool(directory="./workspace")
9filesystem_tools = [FileReadTool(), FileWriterTool(), list_dir]
10sandbox_tools = [exec_tool, E2BPythonTool()]
11
12@tool("run_tests")
13def run_tests(path: str = "tests/") -> str:
14    """Sync ./workspace into the sandbox, then run pytest there."""
15    return E2BExecTool().run(command=sync_and_test_command(path))
16
17explorer = Agent(role="Explorador de Código Base", goal="Mapear el repositorio, mostrar archivos relevantes.",
18    tools=[read_file, list_dir], llm=llm)
19coder = Agent(role="Ingeniero de Software", goal="Implementar el cambio solicitado.",
20    tools=filesystem_tools, reasoning=True, llm=llm)
21tester = Agent(role="Ejecutor de Pruebas", goal="Ejecutar pruebas en el sandbox, informar si pasan o fallan.",
22    tools=sandbox_tools + [read_file] + [run_tests], llm=llm)
23manager = Agent(role="Líder de Ingeniería", goal="Delegar pasos, terminar una vez que las pruebas pasen.",
24    allow_delegation=True, llm=llm)
25
26task = Task(
27    description="En ./workspace, {objective}. Explora, edita, prueba, informa.",
28    expected_output="Resumen de cambios y resultado de pruebas.", human_input=True,
29)
30crew = Crew(
31    agents=[explorer, coder, tester], tasks=[task],
32    manager_agent=manager, process=Process.hierarchical,
33    planning=True, memory=True, checkpoint=True,
34)
35result = crew.kickoff(inputs={"objective": "corregir pruebas que fallan en account.py"})

Los arneses de agentes son más fáciles de evaluar cuando el éxito se puede verificar automáticamente. Un conjunto de pruebas le da al agente un objetivo concreto, para que pueda planificar, editar, probar y repetir hasta que todo pase.

Así que esto se probó contra un código base pequeño, una clase BankAccount con dos errores reales y cinco pruebas, de las cuales tres fallaban. La regla era corregir solo la implementación, no las pruebas.

Esto refleja cómo Anthropic evalúa internamente a los agentes de codificación. Un ejemplo publicado tiene a Claude reconstruyendo un clon de la interfaz de claude.ai contra un gran conjunto de pruebas fallidas.

Aquí, el arnés llevó el proyecto de 3 fallas y 2 éxitos a 5 éxitos, con la regla de solo implementación cerrando el atajo de editar o eliminar las pruebas fallidas.

Lo que sigue siendo tu trabajo

Algunas partes del sistema no son cosas que el framework construya por ti:

• Los prompts. El comportamiento de cada agente proviene de su rol, objetivo e historia de fondo. Lograrlos correctamente requiere pruebas e iteración, y ninguna bandera de configuración lo sustituye.
• El entorno de ejecución. El sandbox, ya sea E2B o una VM autogestionada, debe configurarse y conectarse.
• Selección de herramientas. Qué herramientas recibe cada agente, y qué agente debería tener acceso a qué, es una decisión de diseño que el framework no toma.

También hay un costo asociado al arnés en sí. La planificación, los subagentes y el bucle añaden llamadas a la API, por lo que una configuración de agente compleja puede terminar siendo más costosa que una tarea que una sola llamada al modelo habría resuelto directamente.

Y hay una limitación a largo plazo que vale la pena tener en cuenta. A medida que los modelos mejoran, parte del andamiaje deja de ser necesario, porque parte de lo que se construye en un arnés hoy es una solución temporal para los límites actuales del modelo, más que un requisito permanente.

Anthropic originalmente usaba reinicios de contexto para evitar que Claude Sonnet 4.5 terminara las tareas demasiado pronto, y ya no eran necesarios con el más capaz Claude Opus 4.5.

Conclusión

Ese es el hallazgo completo. La capacidad de un agente de codificación reside principalmente en el arnés, y un framework de orquestación te entrega más de ese arnés de lo que imaginas.

El bucle, la planificación, la delegación, el sandboxing y la memoria llegan todos como configuración, mientras que los prompts, el entorno de ejecución y las elecciones de herramientas siguen siendo tuyos.

Si quieres ejecutar esto contra tu propio código base, la documentación de CrewAI cubre todas las funciones utilizadas aquí, y el framework es completamente de código abierto.

Consulta la documentación de CrewAI →

Encuentra todo el código aquí →

¡Gracias por leer!

¡Saludos! :)