Vamos construir o harness do Claude Code (passo a passo)

Cobriremos tudo o que envolve a construção de uma estrutura de codificação (harness), o loop do agente, planejamento, subagentes, sandboxing, memória e checkpointing, construídos passo a passo.

Se você já tentou construir seu próprio agente de codificação, sabe como é. Você conecta um modelo a ferramentas de arquivos e um shell, aponta para uma base de código real, e ele quebra em menos de uma dúzia de chamadas de ferramentas.

Ele lê os arquivos errados, perde o objetivo no meio do caminho e enche seu contexto com saída que não precisa mais.

Então a mesma tarefa passa pelo Claude Code e termina perfeitamente. A conclusão fácil é que a Anthropic simplesmente tem um modelo melhor, e essa conclusão perde onde o trabalho realmente acontece.

A diferença é a estrutura (harness). Uma estrutura é o código comum em volta do modelo, e ela lida com planejamento, execução de ferramentas, memória e segurança, enquanto o modelo apenas decide o próximo passo.

Aqui está a aparência de um agente totalmente estruturado quando você o desenha:

GIF

A imagem parece complexa, mas se divide em quatro grupos:

• Memória alimenta o modelo com seu contexto de trabalho mais fatos que aprendeu entre sessões.
• Habilidades codificam como o agente deve operar, ou seja, os procedimentos, restrições e heurísticas que ele segue.
• Protocolos conectam o agente a usuários, ferramentas e outros agentes.
• O núcleo da estrutura une tudo com orquestração de subagentes, um sandbox, um avaliador, um loop de aprovação, observabilidade e compressão de contexto.

A Anthropic descreve essa divisão como o cérebro e as mãos. O modelo é o cérebro que escolhe cada ação, e a estrutura são as mãos que a executam e mantêm a execução no rumo.

Então, a diferença entre seu agente e o Claude Code não é o modelo, é a maquinaria em volta do modelo.

O Claude Code é uma das estruturas mais capazes em produção hoje, e é construído a partir de um conjunto surpreendentemente pequeno das camadas nessa ilustração. Para ver quanto dessa maquinaria você teria que construir sozinho, eu a reconstruí no CrewAI, um framework de código aberto para orquestrar agentes.

Mais disso mapeou para recursos integrados do que eu esperava, e a parte que não mapeia é onde a engenharia real mora.

Vamos construí-la camada por camada, começando com o loop principal e adicionando planejamento, subagentes, sandboxing e memória por cima. Em cada etapa, marcaremos onde o framework termina e onde seu trabalho começa.

Como funciona a estrutura do Claude Code

No centro do Claude Code está um loop de agente simples. Você envia uma mensagem, o modelo decide o que fazer em seguida, e ele responde diretamente ou solicita uma ferramenta. Se solicitar uma, a ferramenta é executada, o resultado volta para a conversa, e o modelo decide novamente.

Isso se repete até que o modelo retorne uma resposta final sem mais chamadas de ferramenta.

Dentro desse loop, o modelo lê arquivos, edita código, executa comandos de shell e executa testes. Esses não são modos separados. São apenas chamadas de ferramenta diferentes dentro do mesmo loop.

O loop sozinho não é suficiente para um agente de codificação confiável, no entanto. O Claude Code adiciona planejamento, ferramentas de arquivo, subagentes, memória e um sistema de permissão e sandbox em volta dele. Essas camadas não substituem o loop, elas o tornam seguro e confiável o suficiente para trabalho real.

Essa é a arquitetura que reconstruiremos, primeiro o loop principal, depois cada camada por cima, mapeando cada camada para o recurso do CrewAI que a gerencia.

O loop principal do agente

O loop executa a mesma sequência até que a tarefa seja concluída:

1. Peça ao modelo para realizar a tarefa.
2. O modelo responde diretamente ou solicita uma ou mais ferramentas.
3. Se ferramentas forem solicitadas, execute-as e retorne os resultados para o modelo.
4. Repita com a conversa atualizada.
5. Quando o modelo responder sem solicitar nenhuma ferramenta, a tarefa está concluída.

1while True:
2    reply = model(messages, tools)
3    calls = [b for b in reply if b.type == "tool_use"]
4    if not calls:            # texto simples, sem chamada de ferramenta: o trabalho está feito
5        return reply.text
6    messages += [reply, run_all(calls)]

Cada chamada de ferramenta completa uma etapa, dá ao modelo novas informações e alimenta a próxima decisão. Uma pergunta simples pode terminar em uma iteração, enquanto corrigir um bug complexo ou refatorar uma grande base de código pode levar dezenas de iterações antes que o modelo tenha informações suficientes para produzir uma resposta final.

O CrewAI fornece esse loop de execução automaticamente assim que você cria um agente. Você não implementa o loop while sozinho, você define o agente e atribui a ele uma tarefa.

Construindo o primeiro agente

Vamos criar um agente simples de Correção de Bugs.

1from crewai import LLM, Agent, Crew, Task
2
3bug_fixer = Agent(
4    role="Bug Fixer",
5    goal="Find and describe the fix for the reported bug in the codebase.",
6    backstory="You read directories and files to build an accurate picture of the code.",
7    llm="claude-sonnet-4-6",
8)
9
10task = Task(
11    description="Find the fix for {objective}.",
12    expected_output="A short description of the fix and which file it belongs in.",
13)
14
15result = Crew(agents=[bug_fixer], tasks=[task]).kickoff(
16    inputs={"objective": "the overdraft bug in account.py"}
17)

Três conceitos para entender aqui:

• Um Agente define quem faz o trabalho, através de seu papel, objetivo, LLM e ferramentas.
• Uma Tarefa descreve a atribuição.
• Uma Crew reúne agentes e tarefas. Chamar kickoff() executa o mesmo loop de execução descrito acima, independentemente de o modelo subjacente ser Anthropic, OpenAI, Google ou outro.

Dando ferramentas ao agente

Ferramentas são o que permitem que um modelo que só gera texto realmente trabalhe em uma base de código. Elas leem arquivos, escrevem-nos, executam comandos de shell e chamam APIs externas.

O CrewAI fornece ferramentas de sistema de arquivos prontas para uso:

• FileReadTool lê arquivos.
• DirectoryReadTool lista diretórios.
• FileWriterTool escreve arquivos.

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]

Elas também funcionam como memória externa. Em vez de manter um grande resultado de pesquisa no contexto do modelo, o agente pode escrevê-lo em um arquivo, manter apenas o nome do arquivo e lê-lo de volta quando necessário.

Isso mantém a janela de contexto menor e o modelo mais focado, que é o que a Anthropic chama de engenharia de contexto.

As ferramentas internas cobrem apenas fluxos de trabalho comuns. Para qualquer coisa mais específica, você expõe uma função Python como ferramenta com o decorador @tool.

O docstring atua como o manual de instruções, dizendo ao modelo o que a ferramenta faz, quando usá-la e o que 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

Planejando tarefas de longa duração

À medida que as tarefas ficam mais complexas, um loop de execução simples começa a perder o objetivo original. Depois de chamadas de ferramenta suficientes, leituras de arquivos e resultados intermediários, o contexto se enche e o objetivo é ofuscado por tudo que veio depois.

Essa degradação lenta é o que as pessoas chamam de apodrecimento do contexto (context rot).

O planejamento aborda isso diretamente. O agente constrói um plano passo a passo antes de fazer qualquer trabalho e mantém esse plano no contexto durante toda a execução.

O plano não faz o trabalho. É um roteiro que mantém o modelo conectado ao objetivo original, que é o mesmo trabalho que a lista de tarefas do Claude Code faz.

O CrewAI adiciona isso no nível da crew com planning=True. Ele gera um plano antes da execução e o mantém disponível conforme a tarefa progride.

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 padrão, o CrewAI usa gpt-4o-mini para planejamento, e você pode trocar por qualquer LLM de sua preferência para essa etapa.

Agentes individuais também podem raciocinar sobre seu próprio trabalho com reasoning=True:

1from crewai import Agent
2
3bug_fixer = Agent(
4    role="Bug Fixer",
5    goal="Find and describe the fix for the reported bug in the codebase.",
6    backstory="You read directories and files to build an accurate picture of the code.",
7    tools=[FileReadTool()],
8    reasoning=True,
9    max_reasoning_attempts=3  # Opcional: Define um número máximo de tentativas de raciocínio
10)

Planejamento e raciocínio resolvem problemas diferentes. O planejamento constrói um roteiro de alto nível para a tarefa geral, enquanto o raciocínio dá a um agente tempo para pensar sobre sua própria abordagem antes de agir.

Quando o raciocínio está ativado, o agente:

1. Reflete sobre a tarefa e elabora um plano de execução.
2. Avalia se o plano está pronto.
3. Refina o plano, se necessário, até ficar satisfeito ou atingir max_reasoning_attempts.
4. Injeta o plano de raciocínio finalizado na tarefa antes da execução.

Juntos, eles mantêm o agente ancorado em tarefas de longa duração e reduzem o desvio do objetivo original.

Delegando com subagentes

O planejamento mantém o agente focado, mas não reduz a quantidade de informação que o modelo precisa armazenar. Em uma base de código grande, até mesmo uma tarefa bem planejada pode exceder uma única janela de contexto.

Encontrar um bug pode exigir a leitura de dezenas de arquivos, e o agente principal não precisa manter todos eles na memória.

Os subagentes resolvem isso através da delegação. O agente principal entrega uma tarefa específica a um agente auxiliar, que trabalha em seu próprio contexto e retorna um resumo curto. O agente principal vê a conclusão, não as etapas intermediárias.

O CrewAI suporta isso através de fluxos de trabalho hierárquicos, onde um agente gerente delega para agentes especialistas e combina seus resultados.

Na nossa configuração anterior, um único agente de Correção de Bugs fazia todo o trabalho pesado. Vamos dividir o trabalho entre um gerente e três especialistas:

• Explorador de Código explora o código e mapeia o repositório.
• Engenheiro de Software implementa a mudança solicitada.
• Executor de Testes executa os testes no sandbox e relata aprovação ou falha.
• Líder de Engenharia supervisiona os três especialistas.

1from crewai import Crew, Agent, Task, Process
2
3explorer = Agent(
4    role="Codebase Explorer",
5    goal="Map the repository and surface the files relevant to the task.",
6    backstory="You read directories and files to build a picture of the code.",
7    tools=[read_file, list_dir],
8    llm=llm,
9)  # O mesmo para os outros dois agentes especialistas
10
11manager = Agent(
12    role="Engineering Lead",
13    goal="Break the request into steps and delegate each to the right specialist.",
14    backstory="You decide who does what, review tests, finish once change is done.",
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)

Uma coisa a notar é que allow_delegation está desabilitado por padrão, então deve ser explicitamente ativado no gerente.

Sandboxing: Protegendo a execução do agente

Um agente com acesso ao shell pode executar um comando destrutivo, e dizer ao modelo para não fazer algo não é uma salvaguarda.

A proteção real vem de duas camadas:

1. Um sistema de permissão que exige aprovação para ações sensíveis.
2. Um sandbox que isola a execução, para que mesmo comandos aprovados não possam tocar na máquina host.

A Anthropic usa a mesma abordagem. Mover a execução do código para um sandbox reduz a frequência com que um usuário precisa aprovar ações, enquanto ainda protege o sistema host.

Sandboxing no CrewAI

Executar código dentro de um sandbox em vez de na máquina host aplica essa segunda camada. Nesta configuração, o código é executado dentro do E2B, que cria uma VM nova por sessão e a destrói depois.

Comandos de shell e Python são executados inteiramente dentro desse ambiente isolado.

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

Aprovação com humano no loop

Definir human_input=True em uma Tarefa pausa a crew após ela gerar uma resposta. Você revisa a saída e então a aprova ou a envia de volta para outra iteração.

Quando a execução atinge essa tarefa, o CrewAI aguarda seu feedback através da entrada padrão.

1from crewai import Task
2
3task = Task(
4    description=(
5        "In the working directory ./workspace, {objective}. "
6        "Explore the code first, make the change, then run the tests and report."
7    ),
8    expected_output="A summary of the files changed and the final test output.",
9    human_input=True,
10)

Se sua crew estiver rodando por trás de um aplicativo web ou interface de chat em vez de um terminal, o sistema de humano no loop baseado em webhook do CrewAI lida com a mesma etapa de revisão.

Memória e checkpointing

Por padrão, um agente esquece tudo quando uma execução termina. Volte amanhã para corrigir outro bug no mesmo projeto e ele começará do zero.

Dois mecanismos permitem que um agente carregue informações entre execuções, e cada um serve a um propósito diferente:

• Checkpointing salva o estado do agente durante uma execução, para que ele possa retomar após uma interrupção ou continuar do mesmo ponto por um caminho diferente.
• Memória persistente armazena fatos entre conversas separadas, incluindo preferências de projeto como "sempre formatar o código final antes de terminar".

Memória no CrewAI

O CrewAI fornece uma interface de Memória unificada, em vez de tipos separados de memória de curto prazo, longo prazo, de entidade e externa. Ao salvar, ele usa um LLM para identificar detalhes importantes, organizá-los e torná-los recuperáveis mais tarde.

Definir memory=True na crew dá a ela memória entre execuções. Após cada tarefa, o CrewAI extrai fatos úteis da saída e os armazena, e em execuções futuras, ele recupera memórias relevantes e as adiciona ao prompt da tarefa.

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

Todos os agentes em uma crew compartilham sua memória, a menos que um agente receba a sua própria.

Checkpointing no CrewAI

Um checkpoint é um instantâneo do progresso de um agente, incluindo sua configuração, estado da tarefa, memória, resultados intermediários, entradas e histórico de execução.

Por padrão, o CrewAI cria um checkpoint sempre que uma tarefa termina, permitindo que o fluxo de trabalho seja retomado desse ponto se for interrompido.

Os checkpoints podem residir em um de dois armazenamentos integrados:

• JsonProvider salva cada checkpoint como um arquivo JSON separado, que é fácil de ler e inspecionar manualmente.
• SqliteProvider armazena todos os checkpoints em um único banco de dados SQLite, que se mantém melhor sob checkpointing frequente e cargas de trabalho maiores.

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

Crew, Flow e Agent aceitam um argumento checkpoint, e os filhos herdam do pai a menos que definam seu próprio valor.

Juntando tudo

Aqui está a estrutura completa em uma tarefa, com o loop de execução, ferramentas, planejamento, subagentes, sandboxing e memória trabalhando 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="Codebase Explorer", goal="Map repo, surface relevant files.",
18    tools=[read_file, list_dir], llm=llm)
19coder = Agent(role="Software Engineer", goal="Implement requested change.",
20    tools=filesystem_tools, reasoning=True, llm=llm)
21tester = Agent(role="Test Runner", goal="Run tests in sandbox, report pass/fail.",
22    tools=sandbox_tools + [read_file] + [run_tests], llm=llm)
23manager = Agent(role="Engineering Lead", goal="Delegate steps, finish once tests pass.",
24    allow_delegation=True, llm=llm)
25
26task = Task(
27    description="In ./workspace, {objective}. Explore, edit, test, report.",
28    expected_output="Summary of changes and test output.", 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": "fix failing tests in account.py"})

As estruturas de agente são mais fáceis de avaliar quando o sucesso pode ser verificado automaticamente. Um conjunto de testes dá ao agente um objetivo concreto, para que ele possa planejar, editar, testar e repetir até que tudo passe.

Então, isso foi testado em uma pequena base de código, uma classe BankAccount com dois bugs reais e cinco testes, dos quais três falharam. A regra era corrigir apenas a implementação, não os testes.

Isso reflete como a Anthropic avalia agentes de codificação internamente. Um exemplo publicado mostra Claude reconstruindo um clone da interface do claude.ai contra um grande conjunto de testes com falha.

Aqui, a estrutura levou o projeto de 3 falhas e 2 sucessos para todos os 5 sucessos, com a regra de apenas implementação bloqueando o atalho de editar ou remover os testes com falha.

O que ainda é seu trabalho

Algumas partes do sistema não são coisas que o framework constrói para você:

• Os prompts. O comportamento de cada agente vem de seu papel, objetivo e história. Acertar isso leva tempo de teste e iteração, e nenhum sinalizador de configuração substitui isso.
• O ambiente de execução. O sandbox, seja E2B ou uma VM autogerenciada, precisa ser configurado e conectado.
• Seleção de ferramentas. Quais ferramentas cada agente recebe e qual agente deve ter acesso a quê é uma decisão de design que o framework não toma.

Há também um custo para a própria estrutura. Planejamento, subagentes e looping adicionam chamadas de API, então uma configuração de agente complexa pode acabar mais cara do que uma tarefa que uma única chamada de modelo resolveria diretamente.

E há uma limitação de longo prazo que vale a pena ter em mente. À medida que os modelos melhoram, parte do arcabouço deixa de ser necessário, porque parte do que é construído em uma estrutura hoje é uma solução alternativa para os limites atuais do modelo, em vez de um requisito permanente.

A Anthropic usava redefinições de contexto para impedir que o Claude Sonnet 4.5 terminasse tarefas cedo demais, e elas não eram mais necessárias com o Claude Opus 4.5, mais capaz.

Concluindo

Essa é a descoberta completa. A capacidade de um agente de codificação reside principalmente na estrutura, e um framework de orquestração entrega mais dessa estrutura do que você imagina.

O loop, planejamento, delegação, sandboxing e memória chegam todos como configuração, enquanto os prompts, o ambiente de execução e as escolhas de ferramentas permanecem seus.

Se você quiser executar isso em sua própria base de código, a documentação do CrewAI cobre todos os recursos usados aqui, e o framework é totalmente open source.

Confira a Documentação do CrewAI →

Encontre todo o código aqui →

Obrigado por ler!

Um abraço! :)