Practical Claude Code

“Isto não é só uma ferramenta. É uma redefinição do próprio desenvolvimento.”

Meu Encontro com o Claude Code

Na primavera de 2025, digitei um único comando no meu terminal.

claude

Uma palavra só. Não fazia ideia, na época, de que aquilo mudaria minha carreira de engenheiro pela raiz.

Naquele tempo, rodava MCP através do Cursor e me empolgava com o quanto era prático. Para ser honesto, ficava mais fascinado pela evolução das ferramentas periféricas do que pelos LLMs em si. Cheguei a acreditar, equivocadamente, que o segredo do Claude Code era fazer ele funcionar com o GitHub Actions de uma vez. Entendi completamente errado o que faz uma ferramenta de coding com IA.

Quando usei o Claude Code pela primeira vez, percebi algo diferente nos primeiros minutos. Não era nada parecido com as ferramentas de IA que eu havia usado. Ele não sugeria código apenas: entendia o projeto inteiro, captava a intenção do design e, às vezes, apontava problemas que eu mesmo não tinha notado. Era como ter um pair programmer brilhante do outro lado do terminal.

Por Que Escrevi Este Livro

Depois de usar Claude Code por um tempo, me convenci de uma coisa. O valor real desta ferramenta não está em gerar código: está em entender contexto.

E para liberar essa capacidade por completo, o usuário precisa de uma habilidade própria: “desenhar contexto”. Chamo isso de Context Engineering (engenharia de contexto).

Existe muito artigo por aí explicando como usar Claude Code. Mas nenhum livro tinha tratado o essencial de forma sistemática: a filosofia de design, por que o CLAUDE.md importa, como tirar o máximo da colaboração com IA, como aplicar isso em desenvolvimento em equipe.

Então decidi escrever um.

Este livro é o registro completo do que aprendi usando Claude Code intensivamente em produção. Tentei ser o mais honesto possível, contando não só as técnicas que deram certo, mas também as lições que tirei dos fracassos.

Como Ler Este Livro

O livro está dividido em quatro partes principais.

Parte 1: Fundamentos (Capítulos 1–3) Cobre a história da origem do Claude Code, o significado por trás da filosofia de design baseada em terminal, e por que precisamos de desenvolvimento AI-native agora. Se você é novo no Claude Code, comece por aqui.

Parte 2: CLAUDE.md na Prática (Capítulos 4–7) O coração deste livro. Cobre em detalhe a filosofia de design do CLAUDE.md, desenvolvimento document-first, padrões práticos e estratégias para times. Mesmo quem já usa Claude Code há tempos vai encontrar coisas novas aqui.

Parte 3: Aplicações Reais (Capítulos 8–14) Do fluxo de trabalho do dia a dia até integração com design, automação de testes, orquestração multi-ferramenta, colaboração com não-engenheiros, automação de conhecimento e aplicações em negócios. Orientações concretas sobre como usar Claude Code no desenvolvimento real.

Parte 4: O Futuro (Capítulos 15–19) Explora o cerne da revolução de produtividade, a evolução dos agentes de IA, considerações de segurança e políticas, a transformação da profissão de engenheiro e o que vem pela frente.

Não precisa ler do começo ao fim. Fique à vontade para olhar o sumário e pular para o capítulo que mais interessar. Dito isso, recomendo ler os Capítulos 4 e 5 cedo, porque eles montam a base conceitual para o resto do livro.

Bem-vindo ao mundo do Context Engineering.

“Então, que música você está ouvindo agora?” Essa única pergunta começou tudo.

O momento icônico em que o Claude Code nasceu: um protótipo acidental que cristalizou quatro decisões de design.

”Que Música Estou Ouvindo?”

Numa noite de setembro de 2024, o engenheiro da Anthropic Boris Cherny escrevia um app de chat de terminal simples para testar o comportamento da API da empresa.

A primeira ferramenta foi só bash, uma única ferramenta. Era um protótipo sem nada de especial, montado quase inteiramente a partir do código de exemplo da documentação oficial. Para verificar se funcionava, ele digitou:

What music am I listening to?

O modelo escreveu espontaneamente um AppleScript, controlou o player de música do Mac e devolveu o nome da música tocando.

Boris diz que esse foi o momento em que “sentiu AGI pela primeira vez”. Sem nunca ter sido instruído a fazer isso, o modelo quis usar ferramentas. “O modelo quer usar ferramentas. É só isso.” Essa descoberta foi o começo do Claude Code.

Quem é Boris Cherny?

Para contar a história do nascimento do Claude Code, primeiro precisamos conhecer seu criador, Boris Cherny.

Ele é conhecido como autor de Programming TypeScript, publicado pela O’Reilly, e é especialista em sistemas de tipos e design de linguagens de programação. TypeScript carrega uma filosofia de “adaptar o sistema de tipos ao jeito que os programadores escrevem, em vez de forçar os programadores a mudar seus hábitos”. Essa filosofia depois influenciou diretamente os princípios de design do Claude Code.

Quando Boris entrou na Anthropic, não tinha planos de construir um produto como o Claude Code. O que queria era entender mais a fundo a API da empresa. O pequeno app de terminal que ele construiu para isso acabou se tornando um dos agentes de coding com IA mais usados do mundo, algo que nem ele mesmo previu.

Essa história me atrai porque ressoa com minha experiência. Na época em que trabalhei com robótica, construí um pequeno protótipo com um engenheiro francês que cresceu em direções inesperadas. Em vez de desenhar um grande projeto desde o início, há uma sensação de que a descoberta vem quando você põe a mão na massa. Acho que todo engenheiro já sentiu isso em algum momento.

Nascido de um Hackathon Interno: por Acaso

Claude Code não foi resultado de um esforço planejado de desenvolvimento de produto. O app de terminal que Boris construiu para testar comportamento de API era puramente uma ferramenta de experimentação pessoal.

Mas duas coincidências felizes se juntaram.

Coincidência #1: Escolher uma CLI

Boris escolheu uma CLI por uma razão extremamente prática: não precisava construir UI. Pegou o terminal como o protótipo mais barato possível. Sem UI web, sem app desktop. Só texto entrando, texto saindo. A forma mais simples possível.

Esse “atalho” se mostrou a melhor decisão de design. O terminal era o ambiente com o qual desenvolvedores estavam mais familiarizados, e também o ambiente mais natural para modelos usarem ferramentas.

Coincidência #2: Fazer do bash a primeira ferramenta

Ao usar a ferramenta bash direto do código de exemplo da documentação, o modelo ganhou um ambiente onde podia executar comandos livremente. Não foi uma escolha intencional de design. Só aconteceu assim. Mas esse grau de liberdade combinou perfeitamente com a tendência do modelo de “querer usar ferramentas”.

Quando Boris compartilhou esse protótipo internamente, a reação foi inesperada. Engenheiros da Anthropic começaram a usar a ferramenta no trabalho do dia a dia.

”Ninguém Pediu, mas Todo Mundo Precisava”

No fim de 2024, o mercado de ferramentas de coding com IA já tinha players fortes como Cursor e GitHub Copilot. Assistentes de IA integrados a IDE eram o padrão, e praticamente não havia demanda por “escrever código conversando com IA no terminal”.

Mesmo assim, a adoção interna rápida do Claude Code revelou uma verdade importante: as pessoas não sabem do que precisam até terem aquilo nas mãos.

Boris explica isso usando o conceito de “Demanda Latente”. Engenheiros já trabalhavam no terminal. Claude Code era uma ferramenta que se misturou naturalmente ao fluxo de trabalho deles. Você usa o terminal de sempre, trabalha como sempre. Só que agora o Claude está ali do seu lado.

Essa ideia de “colocar o produto na extensão dos padrões de comportamento existentes” é um dos fatores mais importantes por trás do sucesso do Claude Code. Vou tratar disso em detalhe no Capítulo 3.

O Que a Cultura da Anthropic Produziu

Não dá para contar a história do nascimento do Claude Code sem considerar a cultura da Anthropic como empresa.

A Anthropic é única no setor por colocar “segurança em IA” no centro da sua missão corporativa. Persegue os objetivos aparentemente contraditórios de maximizar a capacidade da IA enquanto, ao mesmo tempo, garante sua segurança.

Como essa cultura influenciou o Claude Code fica evidente em várias decisões de design.

Gerenciamento de Permissões para Execução de Ferramentas

Claude Code tem um mecanismo embutido que pede aprovação do usuário quando o modelo modifica arquivos ou executa comandos. Em vez de “deixar a IA fazer o que quiser”, a filosofia de design é deixar o controle nas mãos do humano.

Claude wants to run: rm -rf node_modules && npm install

Allow? (y/n)

Esse prompt pode parecer chato à primeira vista. Mas é a implementação técnica da ênfase da Anthropic em “supervisão humana”.

Projetado para Não Enviar Código para Fora

Claude Code não armazena seu codebase em um vector DB nem constrói índices em servidores externos. A arquitetura em que o modelo busca direto nos arquivos locais via grep/glob é também uma escolha excelente do ponto de vista de segurança.

Essa decisão foi tomada inicialmente por razões técnicas (Agentic Search era mais preciso que RAG), mas se alinhou lindamente com a cultura safety-first da Anthropic.

Consciência de ASL (AI Safety Level)

Boris conversa abertamente em entrevistas sobre riscos como ASL4 (o nível de risco para modelos que se auto-aprimoram recursivamente), uso indevido para armas biológicas e exploits zero-day. O simples fato de um desenvolvedor de ferramenta de coding com IA discutir esses riscos publicamente reflete a cultura da Anthropic.

Quando comecei a usar Claude Code, a primeira coisa que notei foi esse “cuidado com segurança”. Comparado a outras ferramentas de coding com IA, Claude Code restringe intencionalmente o que pode fazer em certas áreas. Mas isso não é limitação: é design. Em vez de soltar a rédea, foi projetado para colaborar com humanos. Essa filosofia é o que cria confiabilidade no uso real.

Vinte Pull Requests por Dia

A evidência mais convincente da efetividade do Claude Code vem dos próprios resultados internos da Anthropic.

O estilo de trabalho de Boris mudou dramaticamente antes e depois de adotar Claude Code:

• Desde o Opus 4.5, ele escreve 100% do código com Claude Code
• Desinstalou a IDE
• Manda 20 pull requests por dia

A equipe como um todo reportou resultados como:

• Aumento de 150% em produtividade por engenheiro
• A previsão do CEO Dario de que “90% do código será escrito pelo Claude” virou realidade
• Dependendo da equipe, 70–90% do código é gerado por IA

O ex-engenheiro do Google Steve Yegge disse que “engenheiros da Anthropic são 1000x mais produtivos que engenheiros do Google na época de ouro do Google”. Pode ser exagero, mas a sensação de que a produtividade mudou para uma dimensão completamente diferente é algo que vivi na pele usando Claude Code intensivamente.

No meu caso, toco cinco projetos em paralelo numa pequena empresa enquanto, ao mesmo tempo, faço cursos de extensão universitária e preparo novos negócios. Esse estilo de trabalho de “vestir vários chapéus” se tornou possível em grande parte graças ao Claude Code. A redução dramática no tempo gasto escrevendo código me permitiu focar em decisão e revisão.

Não Sobra Nenhuma Linha de Código de Seis Meses Atrás

A própria equipe de desenvolvimento do Claude Code pratica uma metodologia de desenvolvimento interessante.

Segundo Boris, nenhuma linha de código de seis meses atrás permanece no codebase do Claude Code. Eles adicionam e removem ferramentas a cada poucas semanas; o código tem expectativa de vida de poucos meses. Reescrevem código constantemente para acompanhar a evolução do modelo.

Isso reflete a filosofia dele de que “scaffolding = dívida técnica”.

Você consegue ganhos de 10–20% em performance com código em volta do modelo (scaffolding). Mas o próximo modelo apaga esses ganhos. É sempre um tradeoff entre construir e esperar.

Boris, segundo se conta, tem o ensaio de Rich Sutton “The Bitter Lesson” emoldurado na parede do escritório. A tese central desse ensaio é que “no longo prazo, escalar computação supera engenhosidade humana”. Em outras palavras, em vez de construir sistemas complexos em volta do modelo, é melhor apostar na evolução do próprio modelo.

Esse pensamento leva ao princípio central do desenvolvimento do Claude Code:

Construa não para o modelo de hoje, mas para o modelo daqui a seis meses.

Mesmo que você ache PMF (Product Market Fit) otimizando para o modelo de hoje, o próximo modelo deixa concorrentes te ultrapassarem. Então você percebe os limites da capacidade do modelo e aposta na fronteira que será resolvida em seis meses.

Esse princípio tem implicações importantes para nós como usuários do Claude Code. Seja em como escrevemos CLAUDE.md ou como desenhamos workflows, a chave não é “hackear em volta das fraquezas do modelo atual”, mas manter as coisas simples, assumindo que o modelo vai evoluir.

Da Coincidência à Inevitabilidade

O nascimento do Claude Code foi coincidente. Um app de terminal para testar API, a ferramenta bash do código de exemplo, escolher uma CLI porque “construir UI dava muito trabalho”. Nada disso foi intencional.

Mas o cenário que se desdobrou a partir dessas coincidências foi nada menos que inevitável:

• Engenheiros já trabalhavam no terminal → CLI
• Modelos queriam usar ferramentas → bash
• Segurança e simplicidade eram necessárias → Agentic Search
• Controle humano era necessário → gerenciamento de permissões baseado em aprovação

Tudo era resposta a demanda que já estava ali.

O que quero passar neste livro não é só como usar Claude Code. Ao entender a filosofia por trás de sua criação (“não brigue com o modelo”, “descubra demanda latente”, “construa para daqui a seis meses”), você vai descobrir princípios para desenvolver junto com IA que vão além do mero uso da ferramenta.

No próximo capítulo, vamos cavar mais fundo na pergunta “Por que o terminal?” e chegar ao coração da filosofia de design do Claude Code.

✅ Pontos-chave

• Claude Code não foi um produto planejado: nasceu acidentalmente de uma ferramenta de teste de API
• A descoberta de que “modelos querem usar ferramentas” foi o começo de tudo
• As escolhas de terminal, bash e Agentic Search foram todas respostas a “demanda existente”
• A cultura de segurança da Anthropic levou a uma filosofia de design que mantém humanos no controle
• “Construa não para o modelo de hoje, mas para o modelo daqui a seis meses” é o princípio central de desenvolvimento do Claude Code

Referências

• Boris Cherny, “Inside Claude Code With Its Creator” — Y Combinator The Light Cone (2026-02-17)

CLAUDE.md não é uma “folha de comandos para o modelo”. É uma “base de conhecimento para o projeto”.

As duas linhas de Boris Cherny

Vou retomar um fato do Capítulo 1. Boris Cherny, criador do Claude Code, tem um CLAUDE.md que ocupa apenas duas linhas.

# CLAUDE.md
- Habilitar automerge ao abrir um PR
- Postar no canal interno do Slack ao abrir um PR

É só isso. Sem convenções de código, sem descrição de arquitetura, sem diretrizes de teste.

Enquanto isso, praticantes do Claude Code escrevem arquivos CLAUDE.md que passam de 100 linhas. Empacotam tudo: a stack do projeto, convenções de código, estrutura de arquivos, estratégia de testes, procedimentos de deploy. O resultado é um CLAUDE.md gigante recheado de toda informação imaginável.

O que essa diferença significa?

Por que Boris consegue se virar com duas linhas

A resposta é simples. O CLAUDE.md de Boris tem duas linhas porque o restante das informações está consolidado no CLAUDE.md compartilhado pelo time.

No projeto do Claude Code existe um CLAUDE.md compartilhado na raiz do repositório, separado dos arquivos CLAUDE.md individuais, e que é atualizado várias vezes por semana. O arquivo pessoal de Boris tem apenas duas linhas porque o CLAUDE.md compartilhado cobre o contexto do time.

Em outras palavras, é arriscado concluir levianamente que “CLAUDE.md deve ser curto”. Mais precisamente, seu CLAUDE.md pessoal pode ser curto, mas o contexto do projeto precisa existir em algum lugar.

Os prós e contras do CLAUDE.md

CLAUDE.md é uma das funcionalidades mais inovadoras do Claude Code, mas também é a mais facilmente mal compreendida. Shingo Yoshida, autor do livro Claude Code in Practice, analisa os prós e contras do CLAUDE.md no contexto do Spec-Driven Development (SDD).

Pró: persistir o conhecimento do projeto

A maior vantagem do CLAUDE.md é ser o único contexto que sobrevive ao /clear.

Sessões do Claude Code são temporárias. Quando a janela de contexto enche ou você reseta com /clear, toda a conversa anterior se perde. Mas a informação escrita no CLAUDE.md persiste de forma permanente no projeto e é carregada automaticamente na próxima sessão.

Sessão 1: instruir "escreva testes com Vitest" → Feito
  ↓ /clear
Sessão 2: "Adicione testes" → não lembra de Vitest ❌

Com CLAUDE.md:
Sessão 2: "Adicione testes" → sabe usar Vitest pelo CLAUDE.md ✅

Isso significa que o CLAUDE.md funciona como memória de longo prazo.

Contra: o problema do inchaço

Porém, o CLAUDE.md funcionar como memória de longo prazo é, ao mesmo tempo, uma causa de inchaço.

Toda vez que o Claude erra durante uma sessão, você adiciona uma regra: “a partir de agora, faça assim”. Toda vez que o projeto cresce, você adiciona novo contexto. Quando vê, o CLAUDE.md inflou para 300, 500, 1000 linhas.

Um CLAUDE.md inchado tem os seguintes problemas:

Problema 1: o modelo começa a ignorar instruções

LLMs tendem a “dar mais peso ao começo e ao fim da entrada”. Instruções enterradas no meio de um CLAUDE.md gigante têm mais chance de serem ignoradas pelo modelo.

Problema 2: instruções contraditórias se acumulam

Quando você fica acrescentando ao longo de muito tempo, instruções antigas e novas podem se contradizer. Uma instrução antiga dizendo “escreva testes com Jest” coexiste com uma nova dizendo “os testes foram migrados para Vitest”.

Problema 3: desperdício da janela de contexto

O CLAUDE.md é carregado por inteiro no início da sessão. Um CLAUDE.md de 1000 linhas come uma fatia significativa da janela de contexto disponível para as tarefas reais.

O próprio Boris deu um conselho claro sobre esse problema:

Se o CLAUDE.md ficar longo demais, apague e comece de novo. Se o modelo desviar, vá empurrando de volta aos poucos. À medida que os modelos melhoram, você precisa adicionar menos.

Sete princípios para o CLAUDE.md

Com os prós e contras em mente, vão aqui princípios práticos de operação. Esses sete princípios sintetizam o conhecimento acumulado pela comunidade.

Princípio 1: mantenha pequeno e focado

# ✅ Bom: o essencial mínimo
Este projeto é Next.js 14 App Router + TypeScript + Prisma.
Os testes usam Vitest. Rode todos os testes com `npm test`.
Comentários em japonês são preferíveis.

# ❌ Ruim: sobrecarga de informação
Este projeto é um site de e-commerce construído com Next.js 14
App Router + TypeScript + Prisma. O desenvolvimento começou em
março de 2024, o time tem 3 membros... (segue indefinidamente)

A meta é menos de 300 linhas, com no máximo 150–200 instruções. A geração automática via /init tende a ser verbosa, então sempre faça curadoria manual depois da geração.

Princípio 2: deixe o estilo de código para os linters/formatters

# ❌ Coisas que não deveriam estar no CLAUDE.md
Use indentação de 2 espaços.
Omita ponto e vírgula.
Use aspas simples para strings.

# ✅ O que fazer no lugar
Configure .prettierrc e .eslintrc
→ Uma única linha no CLAUDE.md: "Siga as regras do Lint/Formatter para o estilo de código"

Esta é a prática de “Não brigue com o modelo” explicada no Capítulo 2. Delegue o controle de formatação às ferramentas e escreva no CLAUDE.md apenas aquilo em que você quer que o modelo exerça julgamento.

Princípio 3: os três elementos essenciais

Há três coisas que o CLAUDE.md deve conter no mínimo:

# CLAUDE.md

## Visão Geral do Projeto
Site de e-commerce em Next.js 14, com gerenciamento de produtos, pedidos e pagamentos.

## Comandos Comuns
- `npm run dev` — iniciar o dev server
- `npm test` — rodar testes
- `npm run build` — build
- `npx prisma migrate dev` — migração do DB

## Pegadinhas específicas do projeto
- Se: schema Prisma mudou → Então: rode sempre `npx prisma generate`
- Se: variável de ambiente foi adicionada → Então: atualize também o `.env.example`
- Se: rota de API foi adicionada → Então: atualize as definições de tipo em `src/lib/api-client.ts`

O terceiro elemento, “pegadinhas específicas do projeto”, é particularmente importante. Escreva as pegadinhas não apenas como proibições, mas no formato “Se X, então Y” (gatilho + ação). Assim fica mais fácil para o modelo entender com precisão.

Princípio 4: divulgação progressiva

Você não precisa colocar tudo no CLAUDE.md. Separe os detalhes em arquivos dedicados em subdiretórios e inclua só as referências no CLAUDE.md.

# CLAUDE.md (raiz)
Veja docs/api-spec.md para a especificação detalhada da API.
Veja docs/testing-strategy.md para a estratégia de testes.
Veja docs/deploy.md para os procedimentos de deploy.

O CLAUDE.md é posicionado de forma hierárquica: o Claude Code lê automaticamente apenas os arquivos relevantes ao diretório em que está trabalhando.

O Claude Code carrega automaticamente o CLAUDE.md do diretório em que está trabalhando. Ao trabalhar em auth, carrega src/auth/CLAUDE.md; ao trabalhar em pagamentos, carrega src/payment/CLAUDE.md. Um design que oferece a informação certa, na hora certa.

Princípio 5: coloque as regras críticas no topo

LLMs tendem a dar mais peso ao começo e ao fim da entrada. Coloque suas regras mais importantes no topo do CLAUDE.md.

# CLAUDE.md

<!-- Regras mais críticas: coloque aqui -->
⚠️ Nunca conecte diretamente ao DB de produção. Use sempre o staging.
⚠️ Nunca commitar arquivos .env.

## Visão Geral do Projeto
...

Princípio 6: faça crescer como documento vivo

O CLAUDE.md não é algo que você escreve uma vez e esquece. Quando o Claude repete o mesmo erro, acrescente uma linha de lição. Quando a situação do projeto muda, atualize. É um documento que exige manutenção contínua.

Mas, se você só acrescenta, ele incha. Revise periodicamente e remova regras que não são mais relevantes. Como diz Boris, às vezes é preciso ter a coragem de “apagar e começar de novo”.

Princípio 7: tenha consciência do escopo

A localização do CLAUDE.md determina seu escopo.

~/.claude/CLAUDE.md          # Global (compartilhado entre todos os projetos)
~/project/CLAUDE.md           # Raiz do projeto
~/project/src/auth/CLAUDE.md  # Específico do módulo
~/project/claude.local.md     # Configurações pessoais (recomendado .gitignore)

Coloque as regras compartilhadas pelo time no CLAUDE.md da raiz do projeto, e as preferências pessoais em claude.local.md, para separar com clareza o conhecimento compartilhado das configurações pessoais.

A pergunta essencial: “O que é contexto?”

Quando você pensa profundamente no design do CLAUDE.md, chega à pergunta fundamental: “O que é contexto?”

Contexto é a informação de que o modelo precisa para tomar decisões corretas. Mas “informação necessária” muda conforme a situação:

• Para captar a visão geral do projeto → descrição da arquitetura
• Para corrigir um bug específico → pegadinhas específicas daquele módulo
• Para escrever testes → estratégia de testes e configuração das ferramentas de teste
• Para fazer deploy → procedimentos de deploy e configurações de ambiente

Fornecer toda a informação de uma vez sobrecarrega a janela de contexto e enterra a informação importante. Fornecer só a informação necessária no momento necessário: esta é a essência do Context Engineering (engenharia de contexto).

O CLAUDE.md é apenas um mecanismo para praticar essa engenharia de contexto.

A conexão com Spec-Driven Development (SDD)

Spec-Driven Development (SDD), defendido por Shingo Yoshida, é uma abordagem que leva a filosofia do CLAUDE.md ainda mais longe.

A diferença em relação ao Vibe Coding (“faça algo legal aí”) é clara:

Vibe Coding:
  "Faça uma funcionalidade de login" → IA implementa livremente → não é o que você esperava

Spec-Driven Development:
  1. Escreva o spec (deixe claro o que construir)
  2. Defina políticas de orientação no CLAUDE.md (deixe claro como construir)
  3. Faça a IA implementar → a implementação segue o spec
  4. Verifique os resultados → atualize o spec

O núcleo do SDD é concentrar o esforço humano não nas “instruções para a IA”, mas na “definição da especificação”. Com um bom spec, a IA chega à implementação correta.

Esta é também a abordagem que pratico no dia a dia. Antes de escrever código, escrevo o spec primeiro. Defino o contexto do projeto no CLAUDE.md. Em seguida, delego a implementação ao Claude Code. O que você deve escrever não é código, é especificação.

Essa ideia se conecta de forma profunda com o “Document-First Development” discutido no próximo capítulo.

Um template prático de CLAUDE.md

Para fechar, segue o template de CLAUDE.md que de fato uso.

# CLAUDE.md

## ⚠️ Regras críticas
- Não acessar o ambiente de produção diretamente
- Não commitar arquivos .env
- Pedir confirmação sempre antes de migrações destrutivas

## Visão Geral do Projeto
[Nome do projeto]: [Descrição em uma linha]

## Stack técnica
- Framework: Next.js 14 (App Router)
- Linguagem: TypeScript (strict mode)
- DB: PostgreSQL + Prisma
- Testes: Vitest + Testing Library
- CI: GitHub Actions

## Comandos
- `npm run dev` — dev server
- `npm test` — rodar testes
- `npm run test:watch` — testes em watch
- `npm run build` — build

## Pegadinhas (Se → Então)
- Se: nova rota de API foi adicionada → Então: atualize os tipos em `src/types/api.ts`
- Se: schema Prisma mudou → Então: rode `npx prisma generate`
- Se: variável de ambiente foi adicionada → Então: atualize `.env.example` + documente no README

## Referências
- Spec da API: docs/api-spec.md
- Estratégia de testes: docs/testing.md

Cabe em 50 linhas. As informações detalhadas ficam separadas em documentos referenciados, e o CLAUDE.md serve como um índice.

O CLAUDE.md de duas linhas de Boris pode ser extremo, mas a direção está certa. Não escreva o que não precisa ser escrito. Coloque a informação necessária no lugar certo, na granularidade certa. Esta é a essência do gerenciamento do CLAUDE.md.

✅ Pontos-chave

• O CLAUDE.md de duas linhas de Boris Cherny funciona porque o CLAUDE.md compartilhado pelo time dá a cobertura
• O inchaço do CLAUDE.md causa três problemas: instruções ignoradas, contradições acumuladas e contexto desperdiçado
• O núcleo dos sete princípios: “mantenha pequeno e focado”, “deixe para os linters” e “pegadinhas no formato Se→Então”
• A divulgação progressiva fornece a informação certa só quando necessária
• Projete o CLAUDE.md não como “ordens para o modelo”, mas como “a base de conhecimento do projeto”

🎯 Pratique você mesmo

1. Escreva um CLAUDE.md para seu projeto: seguindo os sete princípios deste capítulo, escreva um CLAUDE.md de 50 linhas ou menos para um projeto em que você esteja trabalhando agora. Inclua os três elementos essenciais: visão geral do projeto, comandos e pegadinhas (no formato Se→Então).
2. Coloque um CLAUDE.md inchado em dieta: se você já tem um CLAUDE.md, revise-o à luz dos princípios deste capítulo e remova o que não precisa estar lá. Identifique itens que deveriam ficar com os linters/formatters, instruções duplicadas e regras desatualizadas. Compare a contagem de linhas antes e depois.

Referências

• Boris Cherny, “Inside Claude Code With Its Creator”, Y Combinator The Light Cone (17/02/2026)
• Shingo Yoshida, “Introduction to Spec-Driven Development with Claude Code”, SpeakerDeck