CLAUDE.md é a lei da física do seu projeto

CLAUDE.md é a gravidade do projeto

A peça ignorada que decide se o AIOX vai funcionar, ou virar bug em cima de bug. A maioria das pessoas instala o AIOX, olha pro CLAUDE.md de relance e segue mexendo em agente, criando Story, chamando PO. Esse é o erro número um. Antes de qualquer agente atuar, existe um arquivo decidindo *como* eles atuam. Esse arquivo é o CLAUDE.md. Pedro Valério tem a melhor analogia que já escutei pra isso: "se vocês forem pensar no que é o CLAUDE.md para dentro do AIOX, para dentro do sistema, é como se fossem as leis da física no nosso ambiente. Existem leis que regem todo aquele planeta. Por mais que depois você tenha configurações específicas de região, de projeto, de módulo: existem leis maiores que tudo segue." Eu vou ser direto, esse arquivo é absurdamente importante. Não é "legal ter um CLAUDE.md". Se ele não estiver bem estabelecido, todo o resto começa a dar bug. Os agentes vão se atropelar, vão sugerir caminhos errados, e você vai culpar o modelo quando o problema está na lei da física do seu planeta.

1arquivo que governa o comportamento

4equivalentes por IDE

3leis base do AIOX

Mapa da aula

Use este mapa para entender a sequência da aula antes de entrar nos detalhes.

Legenda de coresO que cada cor sinaliza nesta aula

Existe peçauma estrutura ou arquivo que rege comportamento

Lei da físicaregra permanente que puxa todo agente para o jeito certo

Movimento do operadoração concreta de auditar, atualizar ou escrever a lei

Gravidade erradadrift, white label ou regra desatualizada puxando para trás

Coerência arquiteturalCLAUDE.md, CoreConfig e PRD contando a mesma história

Como entender sem virar técnico

1. Existe um planetaSeu projeto tem regras próprias, objetivos, stack e forma correta de trabalhar.

2. Existe uma gravidadeO arquivo de regras puxa todo agente para esse jeito de trabalhar.

3. Existem órbitasPO, Dev, QA, DevOps e Architect atuam dentro dessas regras.

4. Existe driftSe o arquivo fica antigo, o sistema continua obedecendo uma física errada.

O Claude Code é um planeta. O CLAUDE.md é a gravidade.

Por que esse arquivo atrai e governa todos os outros agentes do AIOX.

Pedro descreve o Claude Code assim: "uma arquitetura de LLM, engenharia de contexto, execução de tools. Ele já faz gestão ali de sub-agents, de chamadas. Esse planeta do Claude Code: quais são as leis da física dele? Está no CLAUDE.md." Traduzindo pro operacional: o Claude Code orbita em torno de três peças estruturais - o PRD, o CoreConfig e o CLAUDE.md. Quando você chama qualquer agente (PO, SM, Dev, DevOps, Architect), ele não nasce no vácuo. Ele é puxado pela gravidade dessas três peças. Se a gravidade está fraca ou white label, o agente vai inventar contexto. Por isso eu insisto: o CLAUDE.md "é a gravidade que vai atrair todos os outros agentes. E eles vão atuar no meio desse cara aqui". Os agentes precisam atuar dentro dessas leis, assim como um objeto físico precisa obedecer à gravidade do planeta em que ele está. Não tem como burlar, ou as leis te puxam pra frente, ou te puxam pra trás. Detalhe técnico que pouca gente percebe: quando o Claude Code carrega, ele literalmente procura por uma pasta `.claude/` e por um `CLAUDE.md` na raiz. Se existe, ele lê *aquilo* como os "dez mandamentos" do projeto. É assim que ele sabe quem é você, o que é o seu sistema e como ele deve se comportar.

o caminho invisível antes da resposta

Você chama o agente

A conversa parece começar no prompt, mas o agente busca contexto antes.

Claude lê as leis

CLAUDE.md define autoridade, convenções, validação, modo de trabalho e limites.

CoreConfig orienta

Stack, tools, flags e integrações mostram o ambiente real do projeto.

Resposta nasce governada

O agente não responde livre. Ele responde dentro da física que você escreveu.

Lei da física não é promptPrompt é pedido momentâneo. CLAUDE.md é gravidade permanente. Se a gravidade estiver errada, todo prompt bom ainda pode cair para o lado errado.

As 3 leis que todo CLAUDE.md do AIOX impõe

Não são opinião. São leis físicas, toda inteligência do Claude Code vai te puxar pra elas.

Lei 1 - Story-Driven

Todo desenvolvimento passa por uma Story em docs/stories/. Pular essa lei reorienta toda a inteligência do Claude Code de volta para o fluxo Story-Driven.

FLOWdocs/stories/

Lei 2 - Agent Authority

Cada agente tem autoridade exclusiva. Só @devops faz push, tag, PR, release. Só @db-sage executa migration em produção. Tentar burlar = bloqueio por hook.

AUTHenforce-hooks

Lei 3 - Quality First

Lint, typecheck e validators passam antes de qualquer merge. CLAUDE.md amarra npm run doctor no pre-push. Superpoder novo vira parágrafo no CLAUDE.md.

GATEdoctor

1. Lei 1: Story-Driven

Todo desenvolvimento passa por uma Story em docs/stories/. Se você chamar o PO sem Story, ou tentar pular pra Dev sem briefing validado, toda a inteligência do Claude Code vai redirecionar você pro fluxo Story-Driven. Não é frescura, é a primeira lei que o instalador escreve no seu CLAUDE.md.

docs/stories/{epic}/{story}.mdAC + checkboxes + File ListValidar com PO antes de Dev

2. Lei 2: Agent Authority

Cada agente tem autoridade exclusiva sobre um domínio. Só @devops faz push, tag, PR, release e deploy. Só @db-sage executa migration em produção. Os outros propõem, esses dois executam. Tentar burlar essa lei resulta em bloqueio por hook (`enforce-git-push-authority.sh`).

@dev implementa@devops aprova e empurraConflito vira bug, não revolução

3. Lei 3: Quality First

Lint, typecheck e validators precisam passar antes de qualquer merge. O CLAUDE.md amarra o `npm run doctor` no pre-push. Se você quiser superpoderes: "minha ferramenta sempre escolhe o LLM de menor custo": você não pede gentilmente, você escreve a regra no CLAUDE.md. Aí a lei da física passa a te dar velocidade.

doctor passa → push liberadoctor falha → push bloqueiaRegra nova vira parágrafo no CLAUDE.md

Cada IDE tem o seu próprio arquivo de leis

CLAUDE.md, AGENTS.md, GEMINI.md, RULES.md: todos eles são a mesma camada conceitual.

O CLAUDE.md não é uma invenção do Claude Code. É o arquivo de "regras universais" que toda IDE de IA modernamente tem. O nome muda: o papel não. Se você trabalha com Codex (OpenAI), o arquivo é AGENTS.md. E uma observação prática: no Codex você praticamente *só* tem o AGENTS.md. Não tem CoreConfig, não tem Skills no mesmo formato. Tudo que você quer ensinar pro agente entra ali. Se você trabalha com Gemini CLI, o arquivo é GEMINI.md. O Gemini novo que o Google lançou ficou basicamente em paridade com o Claude Code, ele tem essa mesma camada de regras universais, e o AIOX já está atualizado pra funcionar com ele equivalentemente. Se você trabalha com Antigravity (Google), o arquivo é RULES.md. Mesma ideia: regras universais que o agente vai respeitar antes de qualquer prompt. O peso que cada IDE dá pra esse arquivo é levemente diferente, mas quase todas dão um peso enorme. Saber qual arquivo escrever, e *o que* escrever nele, é o que separa quem opera o AIOX em uma IDE só de quem opera o AIOX em qualquer IDE.

Não confundaCLAUDE.md

Lei da física do Claude Code.

Esclareça: Use para ensinar regras permanentes ao Claude Code naquele projeto.

Não confundaAGENTS.md

Lei da física do Codex.

Esclareça: No Codex, esse arquivo pesa muito porque concentra quase toda a orientação do agente.

Não confundaGEMINI.md

Lei da física do Gemini CLI.

Esclareça: Mesmo conceito, nome diferente: regras universais antes do prompt.

Não confundaRULES.md

Lei da física do Antigravity.

Esclareça: Serve para manter o agente dentro das regras do projeto naquela IDE.

Instalação errada vs. instalação certa: o caso do white label

Eu mostrei na aula passada duas formas erradas de instalar o AIOX. Existe uma única forma certa.

Na aula anterior eu mostrei duas formas erradas de instalar o AIOX: clonar repo à mão, copiar pasta, configurar tudo manualmente. O resultado é sempre o mesmo: você acaba com um CLAUDE.md genérico, ou com o CLAUDE.md *do projeto exemplo*, que não tem nada a ver com o seu negócio. A única forma certa é pegar o comando npx, colar no terminal e dar enter. Esse comando faz o setup completo: `.env`, `.gitignore`, `.claude/`, `core-config.yaml`, e escreve um CLAUDE.md que já chega sabendo o que é SINKRA, o que é AIOX, quais são os agentes que orbitam, quais são as leis físicas básicas. Você pode escolher os módulos no caminho (ETL? Slides? Brand?) e o instalador monta o CLAUDE.md de acordo. Houve um aluno que reclamou: com razão: que uma versão anterior do instalador sobrescrevia o CLAUDE.md existente. Eu já mudei o script, agora ele faz backup antes de tocar no arquivo. Mas a regra-mestra continua: se você não tem ali a informação do que é SINKRA, do que é o AIOX, de como os agentes se relacionam: vai começar a dar problema. A gravidade fica fraca, os agentes ficam confusos, o time perde tempo explicando o óbvio em cada nova conversa. Pedro fechou bem na aula: "as leis da física do seu ambiente vão ficar te puxando pra trás, porque elas estão relacionadas a regras que serviam para um projeto *white label*: que é quando o AIOX acaba de ser instalado." Em outras palavras: ninguém atualiza o CLAUDE.md depois do primeiro PRD, e essa é a maior fonte de atrito silencioso do AIOX hoje. Pergunta de aluno na aula: "que comando eu uso pra atualizar meu CLAUDE.md?" Resposta sincera nossa: ainda não tem: estamos construindo. Antes de mudar uma lei da física, a gente precisa rastrear cada mudança no Tech Stack, Source Tree, Code Standard e Database Schema. Mudar CLAUDE.md sem isso quebra mais do que conserta.

White label puxa o projeto para trás

O aluno acha que instalou AIOX, mas o arquivo de leis ainda fala como projeto genérico.

Rota · pain + plus + bench

Começou comoInstalação manual com CLAUDE.md genérico ou copiado.

VirouInstalação oficial com leis, agentes e SINKRA já escritos no projeto.

ProvaQuando CLAUDE.md, CoreConfig e PRD contam histórias diferentes, todo agente precisa ser reexplicado.

LiçãoLei da física errada não é detalhe; é gravidade puxando o sistema para o lado errado.

1Instalação erradaCopia arquivos, perde contexto e herda regra que não representa o projeto.

2SintomaAgentes respondem como se estivessem em outro planeta.

3CorreçãoInstalação oficial escreve a física certa antes da execução.

Quando CLAUDE.md, CoreConfig e PRD contam histórias diferentes, todo agente precisa ser reexplicado.
Lei da física errada não é detalhe; é gravidade puxando o sistema para o lado errado.
Se você precisa explicar tudo toda vez, o arquivo de leis falhou.
Instalação errada: Copia arquivos, perde contexto e herda regra que não representa o projeto.
Sintoma: Agentes respondem como se estivessem em outro planeta.
Correção: Instalação oficial escreve a física certa antes da execução.

Instalação que cria física errada

Clonar repo e copiar pasta sem entender o setup.
Usar CLAUDE.md white label do projeto exemplo.
Sobrescrever regra existente sem backup.
Atualizar PRD e esquecer de atualizar as leis.

Instalação que cria física AIOX

Rodar o comando oficial de instalação.
Deixar o instalador escrever regras com SINKRA, AIOX e agentes.
Fazer backup antes de alterar arquivo de regra.
Tratar atualização de CLAUDE.md como mudança arquitetural.

Meu arquivo de leis ainda representa o projeto?

Use essa pergunta sempre que o projeto mudar de escopo, stack ou modo de trabalho.

Coerente

CLAUDE.md, CoreConfig e PRD contam a mesma história.

action

White label

O arquivo ainda fala como projeto exemplo, não como seu projeto real.

pain

↓ ↓ ↓

Desatualizado

PRD mudou, stack mudou, mas o arquivo de leis não mudou.

bench

↓ ↓ ↓

A física puxa para frente?

Se ela te obriga a explicar tudo de novo em cada conversa, está puxando para trás.

Pode executar Story com confiança.CLAUDE.md, CoreConfig e PRD contam a mesma história.

Pare e corrija antes de chamar Dev.O arquivo ainda fala como projeto exemplo, não como seu projeto real.

Faça revisão de arquitetura antes de alterar as regras.PRD mudou, stack mudou, mas o arquivo de leis não mudou.

Tabela de referência: o arquivo de leis em cada IDE

Cole no seu repositório. Vai te economizar tempo toda vez que você for testar uma nova IDE de IA.

CLAUDE.md (Claude Code)

Arquivo na raiz do projeto. Lido automaticamente pelo Claude Code junto com a pasta .claude/. Define identidade do projeto, agentes, autoridades, convenções, validators, gotchas. É a peça que o AIOX preenche no install.

AGENTS.md (Codex / OpenAI)

Arquivo equivalente no Codex. Diferente do Claude Code, no Codex você praticamente só tem esse arquivo: não há CoreConfig nem skills no mesmo formato. Tudo que você quer impor ao agente entra ali.

GEMINI.md (Gemini CLI)

Arquivo equivalente no Gemini CLI. A versão atual do Gemini ficou em paridade com o Claude Code, e o AIOX já roda nele com o mesmo conjunto de leis.

RULES.md (Antigravity)

Arquivo equivalente no Antigravity (IDE do Google). Mesma camada de regras universais. Peso levemente diferente, mas o mesmo papel arquitetural.

CoreConfig (core-config.yaml)

Companheiro do CLAUDE.md, dentro do AIOX core. Se o CLAUDE.md são as leis da física, o CoreConfig são as regras *sociais* daquele projeto: Tech Stack, Code Standard, Source Tree, model routing. Mais variáveis que as leis físicas, mas igualmente importantes.

Portão da aulaVocê entendeu quando consegue abrir um projeto e dizer qual arquivo governa a IA naquela IDE, se ele está coerente com o PRD e se a gravidade puxa para frente ou para trás.

Prática: audite a gravidade do projeto

Abra um projeto real e veja se as leis ainda puxam para a direção certa.

◇▶ signal_plus_action

Sequência para auditar a gravidade do projeto

Use sempre que o projeto mudar de escopo, stack ou modo de trabalho: antes de chamar Dev.

localizar arquivo→comparar com PRD→marcar drift→decidir→atualizar antes de executar

Localizar — Abra o arquivo de leis da sua IDE: CLAUDE.md, AGENTS.md, GEMINI.md ou RULES.md.
Comparar — Leia o PRD/briefing e veja se o arquivo conta a mesma história.
Drift — Anote regra genérica, white label, desatualizada ou contraditória.
Decidir — Com drift, trate como mudança arquitetural: atualize as leis ANTES de executar Story.

Exemplo preenchido: auditoria de um projeto SaaS B2B

LocalizarProjeto usa Claude Code. Arquivo: CLAUDE.md na raiz, 412 linhas, última edição há 3 meses.

CompararPRD foi atualizado há 2 semanas: stack migrou de Postgres para Supabase, adicionou Vercel Edge, removeu Stripe e adotou Pagar.me.

Drift encontradoCLAUDE.md ainda fala em Postgres direto, menciona Stripe webhooks e tem 4 regras sobre edge functions que não existem mais.

DecisãoNão chamar @dev. Abrir tarefa de atualização do CLAUDE.md primeiro, listando as 7 regras que precisam mudar + 2 que precisam nascer.

Critério de prontoAgente novo abre o repo e consegue propor próxima Story sem precisar perguntar nada sobre stack, integrações ou autoridades.

Teste rápidoSe você precisa explicar o mesmo contexto em todo prompt, a gravidade do projeto está fraca.

Localize: Abra o arquivo de regras da IDE que você usa: CLAUDE.md, AGENTS.md, GEMINI.md ou RULES.md.
Compare: Leia o PRD ou briefing do projeto e veja se o arquivo de regras conta a mesma história.
Marque drift: Anote qualquer regra genérica, white label, desatualizada ou contraditória.
Decida: Se houver drift, não peça execução ainda. Abra uma tarefa de atualização das leis antes.

Bloco de código: leis mínimas

Um CLAUDE.md/AGENTS.md fraco quase sempre falha por não declarar regras executáveis.

aula.markdown6 linhas

01## Regras do projeto02- Preserve mudanças existentes do usuário.03- Rode `npm run typecheck` antes de concluir.04- Rode `npm run lint` antes de concluir.05- Não altere stack, tokens ou CSS global sem decisão explícita.06- Reporte arquivos alterados e validações executadas.