Claude Code é um harness: CLAUDE.md, hooks, MCP, skills, subagentes e permissões são as peças em volta do modelo. Este guia é o mapa. Cada peça tem um passo a passo publicado, listado abaixo. A Anthropic descreve o impacto do "harness design" em agentes de código de execução longa (março de 2026). A frase "Claude Code é o harness, o Claude é o modelo dentro dele" é de terceiros (MindStudio, WaveSpeed), não da Anthropic.
Mapa dos passos publicados
Este texto é o mapa do Claude Code como harness. O conceito, a camada em volta de qualquer modelo, está em o que é um AI harness. Aqui cada peça do Claude Code aponta para o passo a passo publicado. Leia o mapa e abra o spoke do que você vai configurar agora.
- Como instalar o Claude Code no Windows — PowerShell, CMD, WinGet ou WSL, Git for Windows, PATH, login e os erros de instalação mais comuns. As saídas foram capturadas num Windows Server 2025 limpo.
- Como instalar o Claude Code no macOS e no Linux — Instalador nativo com curl, Homebrew, apt, dnf, Alpine e npm, PATH, login e os erros de instalação mais comuns. As saídas foram capturadas em containers limpos de Ubuntu e Alpine.
- Como escrever um CLAUDE.md — O guide que o Claude lê no início da sessão. O spoke escreve um arquivo linha a linha e um script que revisa esse arquivo no CI.
- Como configurar hooks — O sensor. Três hooks em Python puro, sem jq, nos pontos do ciclo de vida em que a regra precisa valer sempre.
- Como criar uma skill — Uma pasta com SKILL.md que o Claude carrega sob demanda. O exemplo publicado é uma skill que registra uma decisão de arquitetura.
- Como configurar MCP no Claude Code — claude mcp add, o arquivo .mcp.json e os escopos local, project e user. É a configuração, não a escrita do servidor.
- Como criar um servidor MCP em Python — O servidor que expõe ferramentas, recursos e prompts. O resultado de cada chamada entra na janela de contexto do modelo.
- Como criar subagentes — Arquivo em .claude/agents, com prompt, ferramentas e permissões próprios, numa context window separada.
- MCP vs API vs Skills vs CLI — A mesma tarefa pelos caminhos que o Claude Code oferece, e quando cada um é o certo. MCP não substitui uma API.
- Como economizar tokens — Medir com /context, a diferença entre /clear e /compact, o que quebra o prompt cache, e o papel de subagentes e de um CLAUDE.md curto.
Nota: "AI harness" aqui é o conceito de software — a infraestrutura em volta de um LLM que o torna um agente confiável —, não a harness.io (plataforma de CI/CD) nem o chicote/arreio literal da palavra em inglês.
O que o Claude Code diz que é
O repositório do Claude Code o descreve como uma ferramenta de código agêntica que vive no seu terminal e entende seu codebase (github.com/anthropics/claude-code). A frase não usa a palavra harness, e a ressalva sobre isso está mais abaixo. O modelo que roda ali é o mesmo que você chamaria pela API. O que faz o Claude Code funcionar num repositório de verdade é a camada em volta do modelo: acesso a arquivo, ferramentas, permissões e execução de comandos. O Cursor faz o mesmo papel dentro do editor e se apresenta como seu agente de código para construir software ambicioso (cursor.com). A diferença entre os dois é o formato, terminal ou editor. Os dois envolvem o modelo com contexto de projeto, edição de arquivo e execução.
Claude Code já vem com as peças de um harness
O Claude Code já chega com as peças de um harness. O CLAUDE.md guarda as instruções que o Claude lê no início de cada sessão. Hooks rodam sozinhos em pontos do ciclo de vida e podem ser comando shell, chamada HTTP, ferramenta MCP, prompt ou agente. Skills são pastas com um SKILL.md que o Claude carrega sob demanda quando a tarefa pede. O MCP conecta ferramentas e dados externos: você adiciona um servidor com claude mcp add e escolhe se ele fica só com você, no projeto ou em todos os seus projetos. O passo a passo está em como configurar MCP no Claude Code. Subagents trabalham em context windows separados, cada um com prompt e permissões próprios. E as permissões vêm em níveis: o plan mode, por exemplo, só lê. Isso encaixa direto na taxonomia de Birgitta Böckeler (Thoughtworks, 2 de abril de 2026): guides direcionam o agente antes de ele agir; sensors observam depois e ajudam a corrigir.
Cada uma dessas peças tem um passo a passo com código testado: hooks com 3 exemplos prontos, como escrever o CLAUDE.md, como criar uma skill e como criar um servidor MCP em Python. Se você usa Windows, comece por como instalar o Claude Code no Windows.
Uma ressalva de atribuição (e um ponto prático)
Uma ressalva de atribuição, porque a distinção importa. A Anthropic não chama o Claude Code de "um harness" com essas palavras. Ela fala em "harness design" e diz que isso tem impacto substancial na eficácia de agentes de código de execução longa (março de 2026). A frase explícita "Claude Code é o harness, o Claude é o modelo dentro dele" vem de terceiros (MindStudio, WaveSpeed), não da Anthropic. E tem um ponto prático nisso: você não ganha um harness pronto. Você recebe primitivos e engenheira o harness configurando eles. O jeito de engenheirar é o loop do Hashimoto: cada vez que o agente erra, você escreve uma regra permanente no CLAUDE.md, ou num hook se a regra precisa valer sempre, em vez de corrigir na mão.
Recurso por recurso: guide ou sensor
| Recurso do Claude Code | Guide ou sensor | O que faz |
|---|---|---|
| CLAUDE.md | Guide (feedforward) | Instruções persistentes que o Claude lê no início de cada sessão |
| Hooks | Sensor (e gate) | Ações definidas pelo usuário (comando shell, HTTP, ferramenta MCP, prompt ou agente) que rodam automaticamente em pontos do ciclo de vida |
| MCP | Guide | Conecta ferramentas e fontes de dados externas. Configuração com claude mcp add e .mcp.json em como configurar MCP. Quando usar MCP, API, Skill ou CLI: quando usar cada um. |
| Subagents | Guide | Cada um roda no próprio context window, com system prompt, ferramentas e permissões próprios. Passo a passo em como criar subagentes no Claude Code. Também tiram saída verbosa da conversa principal: veja como economizar tokens |
| Permissões | Guide (gate) | Níveis de permissão; o plan mode só lê arquivos e roda comandos de leitura |
| Skills | Guide | Pastas com SKILL.md, instruções e scripts que o Claude carrega sob demanda quando a tarefa pede |
capivaOS: um harness engenheirado sobre o Claude Code
Dá pra ver o padrão num exemplo concreto. O capivaOS é um harness engenheirado em cima do Claude Code: um pipeline de desenvolvimento spec-first e test-enforced, com máquina de estados, instalado como plugin (segundo o README). Ele não substitui o Claude Code. Ele pega os primitivos (CLAUDE.md, hooks, subagents, permissões) e amarra num fluxo disciplinado, com fases, artefatos e gates. É isso que harness engineering permite: engenheirar um harness como uma camada sobre outro.
O harness de código é a parte visível
O harness de código é a parte visível. Claude Code, Cursor, agentes que leem repositório e rodam teste. Configurar bem esses primitivos já muda o resultado. Mas a parte maior, e onde quase ninguém está engenheirando com disciplina, é o harness operacional: o mesmo padrão de guides e sensors aplicado à operação de um negócio inteiro, IA além do código. A camada de código a gente resolve com o capivaOS, o harness open-source sobre o Claude Code. Se você quer entender o conceito antes dos recursos, comece por O que é um AI Harness.
Perguntas frequentes
O Claude Code é um harness?▼
Funciona como um. Os recursos dele encaixam no modelo de guides e sensors: CLAUDE.md, hooks, MCP, subagents e permissões são a camada em volta do modelo. A Anthropic trata isso como "harness design" (março de 2026); a formulação explícita "Claude Code é o harness" é de terceiros (MindStudio, WaveSpeed), não da Anthropic.
Quais recursos do Claude Code formam o harness?▼
CLAUDE.md (instruções persistentes lidas a cada sessão), hooks (ações automáticas em pontos do ciclo de vida), skills (instruções e scripts carregados sob demanda), MCP (conexão com ferramentas e dados externos), subagents (context windows isolados, com prompt e permissões próprios) e permissões em níveis. Juntos, são os guides e sensors em volta do modelo.
O CLAUDE.md é um guide ou um sensor?▼
Um guide: na taxonomia de Böckeler (Thoughtworks, 2026), guides direcionam o agente antes de ele agir. O CLAUDE.md é lido no início de cada sessão, então orienta o comportamento na largada, não depois.
Como os hooks funcionam como sensors?▼
Hooks rodam automaticamente em pontos do ciclo de vida do Claude Code; ligados a testes, linters ou typecheck depois de uma edição, viram sensors que o agente lê e usa para se corrigir. Um hook que falha também pode barrar a ação, funcionando como gate.
O que é o capivaOS e como ele se relaciona com o Claude Code?▼
O capivaOS é um harness open-source engenheirado sobre o Claude Code: um pipeline de desenvolvimento spec-first e test-enforced, com máquina de estados, instalado como plugin (segundo o README). Ele não substitui o Claude Code. Ele transforma os primitivos num fluxo disciplinado, com fases, artefatos e gates.
Como engenheirar meu próprio harness sobre o Claude Code?▼
Em cinco passos, nesta ordem: 1) instale o Claude Code; 2) escreva o CLAUDE.md com as regras do projeto; 3) adicione hooks como sensors (testes, linters, typecheck); 4) empacote fluxos repetidos em skills; 5) conecte ferramentas externas via MCP. Depois rode o loop do Hashimoto: cada erro do agente vira uma regra permanente.
O Claude Code te dá as peças. O harness que decide se o agente funciona, você engenheira.
Explore também: Diagnóstico GEO gratuito