# 4 princípios de design de ferramentas que o Claude Code aprendeu após 3 reconstruções > Author: Tony Lee > Published: 2026-03-03 > URL: https://tonylee.im/pt/blog/claude-code-4-tool-design-principles/ > Reading time: 5 minutes > Language: pt > Tags: ai, claude-code, ai-agent, tool-design, software-engineering ## Description A equipe do Claude Code da Anthropic reconstruiu suas ferramentas três vezes. Menos ferramentas fizeram a IA render mais. Aqui estão quatro princípios conquistados na prática. ## Content 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. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/pt/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.