⚙ Claude Code: o motor
Os 8 elementos centrais que separam usuário casual de quem opera Claude Code como time de engenharia: claude.md, plan mode, subagentes, worktrees, e a hierarquia CLI>API>Skill>MCP.
🖥 Terminal vs aba Code
Claude Code roda em duas interfaces com engine único: CLI no terminal (mais rápido depois que acostuma — comandos atalhos, integração nativa com tmux, screen) ou aba Code no Claude Desktop (interface gráfica, ideal pra começar). Mesmo modelo, mesmas features, mesmas skills.
Se você é não-coder vindo do N3, comece pela aba Code. Migre pra CLI quando sentir necessidade de velocidade.
📜 claude.md — o arquivo que treina Claude no seu jeito
Markdown na raiz do projeto. Claude lê em toda nova conversa. Conteúdo típico:
## Objetivo
<1 parágrafo>
## Stack
- Next.js 14, TypeScript estrito
- Supabase (PG)
- Vercel
## Convenções
- Componentes em PascalCase
- Hooks em camelCase com prefixo use*
- Testes em __tests__/<arquivo>.test.ts
## Regras
- Nunca usar <em-dash> em texto
- Sempre criar branch antes de mexer em src/
- PR sem teste = recusado
@docs/arquitetura.md
@docs/glossario.md
Regra de ouro: ≤200 linhas. Pra detalhes longos, use @arquivo.md — Claude lê só quando precisa, sem inflar contexto.
🔁 Atualizar claude.md quando Claude errar
Quando Claude cometer erro recorrente, diga literalmente: "Atualize o claude.md pra não fazer isso de novo." Em semanas, o arquivo treina Claude no seu padrão.
A própria Anthropic faz isso. É o loop que separa N4 médio (Claude aceitável) de N4 dominante (Claude que parece treinado pra você).
📋 Plan mode + Opus Plan
Plan mode: Shift+Tab 2x ativa. Claude lê código, apresenta plano detalhado, espera aprovação antes de executar. Você revisa, pede ajustes, e só então libera.
Opus Plan (setting escondido): Opus faz o planejamento, Sonnet executa o trabalho. Resultado: custo de Sonnet, qualidade de Opus. Reduz gasto pela metade sem perder rigor.
👥 Subagentes especializados
Subagentes são Claudes com papel específico: tests (roda + analisa testes), security (audita vulnerabilidades), docs (gera/atualiza documentação), code-reviewer (revisa PRs). Cada um em contexto isolado.
Vantagem: noise de um não contamina outro. Você efetivamente monta um time de engenharia onde cada papel é especializado e múltiplos rodam em paralelo.
Limitação atual (até teams no N5): não conversam diretamente entre si — comunicam via sessão principal.
🌳 Worktrees: 3-4 Claudes em paralelo
claude-worktree feature-name cria workspace git isolado numa branch própria. Abra outro terminal, rode de novo, pronto: 2 Claudes trabalhando em features diferentes sem conflito de arquivos.
Boris Cherny (criador do Claude Code) roda 5 sessões em paralelo todo dia em terminais numerados. Cada uma em worktree própria. Volta depois e revisa as PRs prontas.
Sweet spot: 3-4 sessões. Mais que isso vira babá novamente.
🔗 MCP com asterisco: CLI > API > Skill > MCP
A própria Anthropic recomenda: se existe CLI pro trabalho (gh, aws, gcloud, kubectl), use CLI antes de MCP. Gasta 60-70% menos tokens — nada entra no contexto até você executar.
Hierarquia oficial:
- 1. CLI (gh, aws, gcloud, kubectl, docker) — primeiro
- 2. Endpoints REST — quando CLI não cobre
- 3. Skills — quando workflow é repetitivo
- 4. MCP — só quando nada acima funciona
🔧 Tool search e deferred loading
Janeiro/2026: quando o overhead de MCP passa de 10% da janela de contexto, Claude defere o carregamento dos tools até precisar. Reduz overhead em 85%, zero configuração.
É a feature que torna MCP viável em sessões longas. Mas a regra "CLI antes" ainda vale — deferred loading é só pra quando MCP é mesmo necessário.
📚 Resumo do Módulo
Próximo Módulo:
4.2 — Movimentos de alto impacto: /compact, auto mode, verificação, slash commands, /insights.