Construir do zero com Claude Code: spec, subagentes e governança

Tem material por aí ensinando a colar um "prompt de configuração" no Claude. Funcionava em 2024. Hoje o jogo é outro: o agente entende linguagem natural, lê o seu repositório e raciocina sobre contexto. Construir do zero com Claude Code não é mais achar o prompt mágico, é montar um ambiente onde o agente sabe o que construir, como construir e com qual disciplina, gastando token onde importa. Esse é o guia que eu queria ter quando comecei.

A virada: de prompt mágico para engenharia de contexto

O erro mais comum é tratar o agente como um chat que precisa de "aja como engenheiro sênior". Modelo bom não precisa disso. O que ele precisa é de contexto, objetivo e restrição. Em vez de adjetivo, dê material: o que já existe, o que você quer, o que não pode acontecer e como saber que deu certo.

A habilidade que separa quem extrai dez vezes mais não é prompt, é engenharia de contexto: decidir o que entra no contexto do agente, quando entra e o que fica de fora. O resto desse guia é isso, aplicado a um projeto novo.

Comece pelo spec, não pelo código

Código é a parte barata. Cara mesmo é construir a coisa errada rápido. Antes de pedir qualquer linha, escreva um spec curto, que o próprio agente vai ler:

• Objetivo em uma frase (o resultado, não a tecnologia).
• Escopo e, principalmente, o fora-de-escopo.
• Critérios de aceite: como você sabe que terminou.
• Riscos e decisões em aberto.

Salve no repo (um SPEC.md ou em docs/). O agente passa a decidir com base nele e você para de corrigir rumo no meio do caminho.

O CLAUDE.md como constituição do projeto

Se o spec é o "o quê", o CLAUDE.md é o "como". É o arquivo que o Claude Code lê sozinho em toda sessão. Pense nele como o onboarding de um sênior que acabou de chegar.

# Projeto: [NOME]

## Stack
- linguagem, framework, gerenciador de pacote, banco

## Comandos
- dev / test / lint / build (o agente roda antes de dizer "pronto")

## Convenções
- estrutura de pastas, padrão de commit, estilo, onde criar coisa nova

## Do / Don't
- PODE: editar src, criar testes, refatorar
- NÃO PODE: editar migrations à mão, tocar pasta legada, commitar segredo

## Glossário
- termos do domínio que não são óbvios

Truques que poucos usam: CLAUDE.md por subpasta (regras locais de um módulo), @arquivo pra importar outro doc, e o # no chat pra gravar uma regra nova direto na memória do projeto na hora.

Plan mode: pense antes de gastar token

O maior desperdício de token é o agente sair editando e você mandar refazer. Plan mode resolve. Com Shift+Tab você coloca o Claude Code em modo de planejamento: ele explora o código sem editar nada, propõe um plano e espera sua aprovação. Só depois mexe.

Use em tudo que não é trivial. Aprovar um plano de 30 segundos economiza meia hora de retrabalho e um monte de token.

Níveis de esforço: quando puxar o ultrathink

O Claude Code escala o raciocínio conforme você pede: "think", "think hard", "think harder" e "ultrathink", do mais leve ao mais profundo. Cada nível dá mais espaço pro agente pensar antes de responder.

A regra de ouro: gaste esforço alto onde a decisão é cara (arquitetura, modelagem de dados, o plano de execução) e esforço baixo na tarefa mecânica (renomear, aplicar um padrão repetido). Ultrathink num plano de arquitetura vale ouro; ultrathink pra trocar um texto é desperdício.

Subagentes: divida o trabalho e proteja o contexto

Subagente é um Claude com contexto e ferramentas próprias, que faz uma tarefa e te devolve só a conclusão. Dois ganhos grandes: paralelismo (vários trabalhando ao mesmo tempo) e isolamento de contexto (o trabalho pesado acontece na janela deles, não na sua, que fica limpa).

Padrões que funcionam:

• Exploração: um subagente varre o código e volta com o mapa, sem encher seu contexto de arquivo.
• Revisão adversarial: um subagente revisa o que o outro escreveu, com a missão de achar o que está errado.
• Fatias paralelas: tarefas independentes rodando juntas.

Defina os seus em .claude/agents/. Pro trabalho que repete, isso vira um time.

Slash commands e os comandos que quase ninguém usa

O inner loop, o que você faz dez vezes por dia, tem que virar comando. O Claude Code traz vários nativos e deixa você criar os seus.

Nativos que valem decorar:

• /init gera um CLAUDE.md inicial lendo o projeto.
• /context mostra quanto do contexto você já gastou. É o termômetro do token.
• /compact resume a conversa pra liberar espaço (pode dar foco: "compacta mantendo as decisões").
• /clear zera o contexto entre tarefas sem relação.
• /rewind volta o projeto e a conversa pra um checkpoint anterior. Desfazer de verdade.
• /agents, /hooks e /mcp configuram subagentes, automações e integrações.

Os menos conhecidos e de alto impacto: Shift+Tab pro plan mode, ultrathink pro esforço máximo, # pra gravar memória na hora, @arquivo pra apontar o contexto exato, e os seus próprios comandos em .claude/commands/ pra repetir um workflow inteiro com uma linha só.

Economia de token: gaste onde importa

Token é orçamento. Onde ele vaza e como tampar:

• Contexto gigante sem foco. Não despeje arquivo, deixe o agente buscar o que precisa.
• Conversa que não acaba. Use /clear entre tarefas e /compact quando crescer.
• Retrabalho. Plan mode antes de editar.
• Reexplicação. O que você repete vai pro CLAUDE.md.
• Trabalho pesado no contexto principal. Joga pra um subagente e recebe só o resultado.

Governança e compliance desde o primeiro commit

Velocidade sem controle é dívida. O que blindar desde o início:

• Testes antes de "pronto". Peça o teste junto da feature e exija rodar verde antes de fechar.
• Revisão adversarial. Um subagente revisor caçando bug, falha de segurança e simplificação antes do merge.
• Hooks. Automatize lint, teste e varredura de segredo nos momentos certos (antes ou depois de cada edição), via .claude/settings.json.
• Permissões. Defina o que o agente pode rodar sozinho. Nunca use o modo que pula permissão fora de um ambiente isolado.
• Segredos. Sempre em variável de ambiente, nunca no repo nem no CLAUDE.md (ele vai pro git).
• Trilha de decisão. Registre as decisões de arquitetura num ADR ou log, pra auditoria e pra não se recontradizer depois.
• LGPD/GDPR. Consentimento, mínimo de dado e caminho de exclusão pensados no design, não remendados no fim.

O fluxo do zero ao deploy

1. Escreva o spec

   Objetivo, escopo, fora-de-escopo e critérios de aceite. Curto e no repo.

2. Monte o CLAUDE.md

   Stack, comandos, convenções, do e don't. Comece com 15 linhas e cresça por dor.

3. Planeje com esforço alto

   Plan mode mais ultrathink pra arquitetura e pro plano. Aprove antes de codar.

4. Execute por fatias, com subagentes

   Quebre em tarefas pequenas e independentes. Delegue o que dá pra paralelizar.

5. Teste e revise

   Teste verde e revisão adversarial antes de fechar qualquer parte.

6. Commit atômico e deploy

   Um commit por mudança coesa, mensagem clara, e só então o deploy.

Os erros que queimam token e confiança

Com agente, a habilidade rara não é escrever prompt. É desenhar o contexto e o processo onde um bom agente não tem como errar feio.

Seu próximo passo

Novo no Claude? Veja o Starter Kit Claude 2026. Quer turbinar o Claude Code? Pegue as 20 skills mais usadas. E quando sair do código pro produto, use o workflow do problema ao agente.

Se quiser estruturar esse jeito de construir dentro da sua empresa, o diagnóstico é gratuito e sem compromisso: fmsolutions.ai.