Harness tunado vs. instalação limpa: o que skills, agents e MCPs realmente compram no Claude Code

TL;DR

• Testei a mesma tarefa em dois harnesses: um vazio (sem AGENTS.md, sem skills locais) e um tunado (este repositório, com skills, regras e índice de agents).
• O harness tunado usou 7 turns contra 17, gastou cerca de 438 mil tokens contra 769 mil, e custou US$ 0,46 contra US$ 0,57.
• Toda citação de arquivo do harness tunado foi conferida e existe. O harness vazio se autodeclarou incerto em dois dos três pontos.
• Isso é uma tacada, não uma lei geral. O ganho vem de contexto local específico, não de "ter mais agents".

Exemplo concreto: pedir "qual skill gera o carrossel do LinkedIn e onde ela está?" custou 17 idas e vindas num repositório vazio e 7 num repositório com o índice de skills já carregado.

Todo mundo com um .claude/ cheio de skills, subagents e servidores MCP acredita que isso torna o agente melhor. Quase ninguém mede quanto. A alternativa também é comum: começar do zero, sem nada configurado, e assumir que o modelo "já sabe se virar". As duas crenças raramente encontram um número.

Rodei um teste simples para trocar a crença por um dado: a mesma pergunta, no mesmo dia, com o mesmo modelo, em dois ambientes diferentes: um vazio e um com o harness deste repositório carregado. Não é um benchmark acadêmico nem uma amostra grande; é uma medição única, reproduzível e barata o suficiente para qualquer time rodar no próprio repositório antes de decidir investir em tuning.

Minha tese é simples: tuning de harness não compra "inteligência" extra do modelo. Compra menos exploração às cegas e respostas mais verificáveis, porque informação que já é local não precisa ser redescoberta a cada sessão. O ganho aparece em turns, tokens e taxa de acerto verificável; ele desaparece quando o repositório não tem contexto real para oferecer ou quando o tuning só empilha regras que ninguém consulta.

O que "harness tunado" significa aqui e o que não significa

Neste artigo, harness tunado é um Claude Code configurado com os elementos que o time efetivamente mantém: AGENTS.md/CLAUDE.md do projeto, skills locais (.agents/skills/, .claude/skills/), um índice de subagents com responsabilidade clara e, quando existem, servidores MCP relevantes para a tarefa. Harness limpo é a mesma CLI, a mesma conta, o mesmo modelo, mas apontada para um diretório vazio: sem instrução de projeto, sem skill local, sem índice de agents específico.

Uma ressalva necessária: "harness limpo" aqui não é uma instalação sem nenhuma configuração de máquina. O diretório de projeto estava vazio, mas a CLI ainda enxerga configuração global do usuário (~/.claude/), porque isolar completamente exigiria uma home limpa, o que foge do escopo de um teste rodado em produção. O efeito medido é o de contexto de repositório, não de uma reinstalação zero absoluta. Isso está declarado aqui porque uma medição sem esse aviso soaria mais definitiva do que é.

Como o benchmark foi rodado

A tarefa foi fixa e verificável: "responda em até três bullets qual é a skill exata para gerar um carrossel do LinkedIn a partir de um artigo, qual arquivo define o padrão de commit semântico usado aqui, e qual skill gera a thumbnail do blog, citando o path exato de cada evidência." As três respostas existem neste repositório e podem ser conferidas com find e grep.

Configuração idêntica nos dois lados: mesmo modelo (claude-sonnet-5), mesmo dia, mesma conta, --print --output-format json, ferramentas limitadas a leitura (Read, Grep, Glob, sem escrita), teto de orçamento de US$ 1,50 para evitar loop custoso. A diferença entre as execuções foi apenas o diretório de trabalho: um repositório Git vazio versus este repositório com seu harness completo.

# harness limpo (diretório vazio)
cd /tmp/harness-bench/clean-repo
claude -p --output-format json --max-budget-usd 1.5 --model sonnet \
  --allowedTools "Read,Grep,Glob" -- "$(cat task.txt)"

# harness tunado (este repositório)
cd /Volumes/lemon-ssd/projects-ssd/blog/writer
claude -p --output-format json --max-budget-usd 1.5 --model sonnet \
  --allowedTools "Read,Grep,Glob" -- "$(cat task.txt)"

Os números

O custo em dólares caiu menos que os tokens porque a maior parte do gasto, nos dois casos, veio de leitura de cache (cache_read_input_tokens), que é cobrada mais barato que tokens novos; o harness limpo ainda assim pagou mais no total porque precisou ler muito mais coisa para chegar à mesma pergunta.

Onde a diferença aparece de fato

O harness limpo respondeu, mas se autodeclarou incerto:

"Path físico da skill não achado em ~/.claude/skills nem hub (…) só existe referência no agent file, sem SKILL.md local localizável."

"Path físico não localizado via find em ~/.claude/skills nem hub plugins, só existe entrada na lista de skills carregadas, sem arquivo SKILL.md achável nesta busca."

Ele não inventou um caminho falso. Isso importa, porque hallucination costuma significar "afirmar algo falso com confiança", não "admitir que não achou". Mas gastou 17 turns fazendo find em diretórios que não existiam neste projeto, porque não tinha um índice local para consultar, e terminou com dois terços da resposta marcados como não verificados.

O harness tunado respondeu direto, com evidência checável:

"Carrossel LinkedIn: skill linkedin-carousel-generator (…) evidência: listagem de skills disponíveis (…) Thumbnail do blog: skill lemon-blog-generate-thumb, evidência: .agents/skills/lemon-blog-thumb-upload/SKILL.md."

Conferi as três citações depois da execução:

find . -iname "SKILL.md" -path "*linkedin-carousel-generator*"
# ./.agents/skills/linkedin-carousel-generator/SKILL.md

find . -iname "SKILL.md" -path "*lemon-blog-generate-thumb*"
# ./.claude/skills/lemon-blog-generate-thumb/SKILL.md

test -f .agents/skills/lemon-blog-thumb-upload/SKILL.md && echo existe
# existe

As três batem. A diferença não foi o modelo "saber mais". Foi o modelo não precisar adivinhar onde procurar.

Por que isso acontece: menos entropia de busca, não mais capacidade

O modelo é o mesmo nos dois lados. O que muda é quanto do trabalho é busca às cegas versus leitura direcionada. Um harness tunado reduz o espaço de busca de três formas mensuráveis neste teste:

1. Índice explícito. Uma listagem de skills com descrição de uma linha (como a que aparece na seção de skills disponíveis desta sessão) permite ao agente ir direto ao candidato certo em vez de varrer diretórios.
2. Convenção de path. Saber que skills locais vivem em .agents/skills/ e .claude/skills/ corta a maior parte das tentativas de find genérico.
3. Fronteira declarada. O harness tunado também respondeu corretamente que o padrão de commit vem de um skill externo ao repositório: ele não inventou um arquivo local para a pergunta 2, porque a ausência de correspondência local também é informação, e o harness deixou isso claro em vez de forçar uma resposta.

Nenhum desses três pontos exige um modelo mais forte. Exige que a informação local esteja onde o agente já sabe olhar.

Quando tuning não compensa

O resultado não generaliza para "sempre configure tudo". Três casos em que o harness limpo é a escolha certa:

• Tarefa de propósito geral sem contexto de repositório. Perguntar sobre uma API pública, escrever um script isolado ou explicar um conceito não se beneficia de skills locais; carregar índice extra só adiciona tokens de sistema sem reduzir busca.
• Repositório novo, sem convenção ainda estabelecida. Tuning documenta o que já existe. Num projeto no dia um, não há convenção para indexar, e um AGENTS.md especulativo tende a virar o problema descrito no item seguinte.
• Skill ou regra que ninguém mantém. Um índice desatualizado pode custar mais do que ajuda: o agente confia na entrada errada com a mesma convicção que confiaria numa correta. Um harness tunado malfeito não é neutro: é pior que vazio, porque adiciona uma fonte de erro com aparência de autoridade.

Checklist antes de investir em tuning

• A tarefa repetida realmente depende de saber "onde" algo vive neste repositório?
• As skills/agents listados têm descrição de uma linha específica o bastante para o agente escolher sem abrir o arquivo?
• Cada regra local tem dono e é revisada quando o código que ela descreve muda?
• Existe alguma forma barata de medir turns/tokens antes e depois de uma mudança de harness, mesmo que seja um teste único como este?
• O harness admite "não sei" quando não há correspondência local, em vez de forçar uma resposta?

Limites deste teste

Uma execução por condição não é significância estatística; é uma amostra. O teto de orçamento pode ter truncado comportamento em cenários mais longos. A tarefa escolhida favorece harnesses com índice de skills, porque é exatamente o tipo de pergunta que um índice resolve; uma tarefa de raciocínio puro provavelmente mostraria uma diferença menor. Reproduzir isso no seu próprio repositório, com sua própria tarefa recorrente, vale mais do que confiar nestes números fora de contexto.

Referências primárias

• Anthropic, How Claude remembers your project. Verificado em setembro de 2026.
• Anthropic, Claude Code security. Verificado em setembro de 2026.
• Anthropic, Best practices for Claude Code. Verificado em setembro de 2026.
• Anthropic, MCP in Claude Code. Verificado em setembro de 2026.
• Dados de benchmark: execução própria via claude -p --output-format json, mesma conta, mesmo modelo, mesmo dia, comandos reproduzidos acima.