4 princípios de design de ferramentas que o Claude Code aprendeu após 3 reconstruções

Menos ferramentas, e a IA passou a funcionar melhor. Ao construir um agente, o instinto mais natural é pensar: “se falta alguma funcionalidade, dá mais uma ferramenta para ele.” A equipe da Anthropic passou um ano desenvolvendo o Claude Code e descobriu exatamente o oposto. Cada ferramenta adicional aumenta o custo cognitivo da IA — “devo chamar essa ferramenta ou não?” — e esse custo se acumula.

Eu caí na mesma armadilha construindo meus próprios agentes, por isso o relato do Thariq, desenvolvedor da equipe do Claude Code, me atingiu em cheio. Aqui vai o percurso cronológico de como eles adicionaram, removeram e redesenharam suas ferramentas.

Uma ferramenta, um papel — ou a IA trava

Esse foi o primeiro problema que a equipe do Claude Code enfrentou. Eles precisavam de uma funcionalidade para fazer perguntas ao usuário, então embutiram isso na ferramenta de “planejamento”. A implementação foi rápida, mas a IA tentava formular um plano e uma pergunta ao mesmo tempo. Quando a resposta do usuário contradizia o plano, a IA não conseguia resolver o conflito.

Na segunda tentativa, fizeram a IA gerar as perguntas em formato Markdown. A IA ignorava o formato ou adicionava texto desnecessário. Na terceira tentativa, separaram a funcionalidade em uma ferramenta dedicada — AskUserQuestion — e aí sim tudo se estabilizou. Uma ferramenta, um papel. Parece óbvio, mas você só entende de verdade quando se queima.

• Plano + pergunta combinados — A IA chamava a mesma ferramenta duas vezes por engano
• Saída em formato Markdown — A IA adicionava frases ou ignorava a estrutura
• Ferramenta dedicada separada — Respostas estruturadas finalmente funcionaram de forma confiável
• Não importa quão bom seja o design, se a IA não quer chamar a ferramenta, não serve para nada

Ferramentas têm prazo de validade

Separar bem as ferramentas não é o fim da história. Eu chamaria isso de “validade das ferramentas (tool decay)” — o fenômeno em que uma ferramenta que antes era essencial se torna um empecilho após uma atualização do modelo.

No início, o Claude Code tinha uma ferramenta de lista de tarefas (Todo), e o sistema enviava lembretes a cada cinco turnos: “Não esqueça sua lista de tarefas.” Depois que o modelo melhorou, esses lembretes tiveram o efeito contrário. A IA insistia teimosamente no plano original mesmo quando deveria se adaptar. Quando o Opus 4.5 possibilitou a colaboração entre subagentes, a estrutura Todo existente simplesmente não permitia o compartilhamento de tarefas entre agentes.

No final, substituíram tudo pelo Task Tool.

• TodoWrite substituído pelo Task Tool — Compartilhamento de dependências entre agentes habilitado
• “Essa ferramenta ainda é válida?” requer revisão periódica, tão importante quanto adicionar ferramentas novas
• Suportar menos modelos acelera essas decisões
• A forma da ferramenta importa mais que a quantidade — precisa corresponder às capacidades do modelo

Dar o contexto mastigado para a IA a torna pior

Ao longo do processo de adicionar e remover ferramentas, a equipe do Claude Code descobriu um padrão mais fundamental: deixar a IA encontrar a informação por conta própria funciona melhor do que injetá-la.

No início, eles usavam um banco de dados vetorial RAG para pré-carregar o contexto. Era rápido e poderoso, mas a indexação quebrava conforme o ambiente, e a IA ficava passiva — dependendo apenas do que recebia. Quando deram à IA uma ferramenta Grep para buscar diretamente no código, a qualidade do contexto melhorou. Adicionaram arquivos Skills por cima, criando uma estrutura onde a IA podia explorar recursivamente os arquivos referenciados dentro de outros arquivos.

Isso é o que eu chamaria de revelação progressiva (progressive disclosure) — em vez de despejar tudo de uma vez, a IA descobre o que precisa por conta própria.

• RAG — Alta dependência do ambiente, IA consome contexto passivamente
• Grep + Skills — IA explora ativamente múltiplas camadas de arquivos
• Em um ano, de “IA que não consegue achar contexto” para “IA que acha sozinha”
• Capacidades expandidas apenas com arquivos Skills, sem ferramentas novas

Expandir capacidades sem adicionar ferramentas

Esse padrão de revelação progressiva provou seu valor em outro caso. Usuários perguntavam como usar o Claude Code e ele não sabia responder. Poderiam ter colocado toda a documentação no prompt do sistema, mas essa pergunta só aparece de vez em quando. Quando informações pouco usadas ocupam permanentemente a janela de contexto, degradam o desempenho na tarefa principal — escrever código. Eu chamo isso de ruído contextual (context rot).

A solução foi um subagente dedicado. Quando chegava uma pergunta sobre uso, um agente guia buscava na documentação e devolvia apenas a resposta. O número de ferramentas continuou o mesmo, mas as capacidades da IA aumentaram.

• Toda informação no prompt do sistema — Ruído contextual degradou a qualidade do código
• Apenas fornecer links da documentação — A IA carregava resultados demais no contexto
• Subagente dedicado + instruções de busca — Respostas limpas e focadas
• Resolvido mudando a estrutura, não adicionando ferramentas

Não existe fórmula mágica

Adicionar, remover e redesenhar ferramentas — não existe fórmula universal para esse processo. Quando os modelos mudam, as ferramentas precisam mudar também. A estrutura ótima de ontem pode ser o gargalo de amanhã.

Uma coisa que a equipe da Anthropic repetiu ao longo do ano: ler a saída da IA, experimentar e corrigir de novo. No fim das contas, quem constrói os melhores agentes é quem sabe se colocar no lugar da IA.