Um padrão de estrutura que serve para design, programação, governança e segurança ao mesmo tempo — e que a IA lê igual a um humano. Clique em qualquer item da árvore para ver o que ele é, o que entra nele e como criá-lo.
A regra que substitui todas as outras: organize por pergunta, não por área nem por ferramenta. Se um designer, um dev, um auditor e um agente chegam no mesmo projeto com a mesma dúvida, eles têm que cair na mesma pasta.
Tentar organizar por área produz quatro silos, quatro convenções concorrentes e nada com dono claro — porque a mesma informação pertence a mais de uma área. Em vez disso, organize pelas cinco perguntas que qualquer projeto precisa responder.
| Problema | O que acontece na prática |
|---|---|
| Informação compartilhada | O requisito de segurança nasce no design, é implementado no código e auditado na governança. Em qual das quatro pastas ele mora? Em todas — logo, em nenhuma. |
| Subpadrões concorrentes | Design faz v1/final/final2/. Dev faz old/. Governança faz 2026/atas/. Um projeto, quatro convenções. |
| Sem dono | Pasta de área é de todos, ou seja, de ninguém. Ninguém pode dizer “isso está errado aqui”. |
| Quem chega não acha | Vale igual para a IA: o agente lê a raiz e tem que adivinhar onde está o resto. |
À esquerda, a estrutura. À direita, a ficha do item selecionado: o que ele é, quem é dono, o que entra (e o que não entra) e o comando que cria.
Não é “uma raiz com todos os projetos dentro”, e não é “uma raiz por projeto isolada”. São as duas coisas, em camadas diferentes — e a camada de cima não contém as de baixo.
Uma só para a área ou empresa. Contém o padrão escrito, o template vazio, o catálogo de projetos e o que é genuinamente compartilhado. Não contém o conteúdo dos projetos.
Cada projeto tem a sua: docs/, src/, ops/, controle/. Nasce do template e morre (ou é arquivada) sozinha, sem mexer nos outros.
O que dois ou mais projetos usam de verdade: design system, conectores de dados, componentes de dashboard. Vive em repositório próprio — não é pasta dentro de um projeto que os outros importam por caminho relativo.
| # | Pergunta | Se sim | Se não |
|---|---|---|---|
| 1 | Quem aprova a mudança? Afeta mais de um projeto? | Sobe para a raiz de padrão | Fica no projeto |
| 2 | Se este projeto morrer amanhã, essa informação morre com ele? | É do projeto | É de cima |
| 3 | O dono é o mesmo dos outros projetos? | Pode compartilhar pasta | Não pode — é questão de segurança, não de gosto |
Uma árvore única não consegue dizer “esse projeto é restrito, o outro é aberto”. Ou você abre tudo, ou fecha tudo.
Um projeto acaba e você não consegue arquivar: teria que mexer na raiz de todos os outros.
Um repositório com todos os projetos: um PR de um projeto arrasta revisão de todos, e o AGENTS.md da raiz contamina todo mundo com regras que não são de ninguém.
Quem trabalha no projeto A abre o repositório e vê mais sete. O contexto — humano e da IA — enche de coisa irrelevante.
Você consegue arquivar um projeto inteiro movendo uma única pasta — e nada mais quebra. E o inverso: criar um projeto novo é copiar o template e já ter tudo no lugar. Se arquivar exige mexer em outros, a raiz está errada.
Cada área tem um lugar para escrever e uma pergunta que ela responde. Ninguém precisa inventar pasta — e nada fica sem dono.
| Área | Escreve em | Lê de | Responde por |
|---|---|---|---|
| Design | design/ · ADRs de UX | docs/requisitos/, controle/dados/ | como deve parecer e ser usado |
| Programação | src/ · tests/ · ops/ | docs/arquitetura/, ADRs | como faz funcionar |
| Governança | controle/governanca/ · ADRs | tudo | o que está vigente, quem aprovou |
| Segurança | controle/seguranca/ · controle/dados/ | docs/arquitetura/, requisitos | o que pode, qual o risco |
| IA (agente) | nada novo — lê e propõe | AGENTS.md → todo o resto | como executa sem perguntar |
Todo mundo que toma uma decisão com efeito futuro escreve no mesmo lugar: docs/adr/. É o único arquivo onde design, dev, segurança e governança aparecem juntos — e é o que impede que cada área guarde o “porquê” no próprio canto.
A IA não é o motivo da estrutura — ela é um dos leitores. Se ela precisa de uma pasta só dela,
a estrutura falhou em ser legível. A ponte é um único arquivo: o AGENTS.md na raiz.
AGENTS.md na raiz contém: o mapa (“procurando X, vá em Y”), as invariantes de cada área e quem é dono de cada pasta. Todo agente lê o mesmo arquivo — Claude Code, Antigravity, VS Code/Copilot, Codex. Você não tem dois sistemas: tem um sistema e dois tipos de leitor.
O portfólio tem o seu: por onde o agente entra na raiz de padrão e entende que ali não se escreve conteúdo de projeto. O projeto tem o seu: por onde ele entra no projeto. Nenhum repete o conteúdo do outro — cada um aponta. E como cada projeto é repositório próprio, o AGENTS.md do projeto é o topo da busca: o do portfólio não vaza para dentro dele.
| Ferramenta | Regras do projeto | Skills / procedimentos |
|---|---|---|
| Claude Code | AGENTS.md (ou CLAUDE.md contendo @AGENTS.md) | .claude/skills/<nome>/SKILL.md · regras por path em .claude/rules/ |
| Antigravity | AGENTS.md (raiz e subpastas, cumulativo) | .agents/skills/ · regras em .agents/rules/ com trigger: obrigatório |
| VS Code | AGENTS.md — formato cross-agent | .github/instructions/ · .claude/rules |
| Camada | Onde | Quem escreve | Quando carrega |
|---|---|---|---|
| Organização | Política gerenciada (ex.: /etc/claude-code/CLAUDE.md) | TI / DevOps — ninguém sobrescreve | sempre |
| Pessoal | ~/.claude/CLAUDE.md · ~/.claude/rules/ | você | sempre / sob demanda |
| Projeto | AGENTS.md na raiz (versionado) | o time | sempre |
| Local | CLAUDE.local.md · settings.local.json | você, naquele projeto (.gitignore) | sempre |
AGENTS.mdO que todo mundo precisa saber sempre: comandos de build/test, convenções, arquitetura, os “nunca”. Teto prático: 200 linhas. Passou disso, extraia.
AGENTS.mdSó vale quando ele mexe em SQL, ou só no front. Carrega quando o arquivo casa — e desaparece do contexto no resto do tempo.
.claude/rules/sql.mdMulti-passo, material de referência, fluxo invocável por /nome. O corpo só carrega quando é usado.
Instrução é pedido; hook e permissão são enforçados. Use para o que não pode depender da boa vontade do modelo.
settings.json → hooks / permissionsDecisão com efeito futuro (vira ADR, com dono humano) · permissão e segredo (vive em controle/ e em variável de ambiente, nunca em arquivo versionado) · classificação de dado (decide o que pode sair de onde). O agente propõe, o dono aprova. Se o resultado não tem um nome humano atrás, não é decisão — é acidente.
Sete passos, uma tarde. Nada de faxina preventiva: o resto só migra quando alguém procura e não acha.
Nome do arquivo: NNNN-titulo-com-dashes.md (ex.: 0001-adotar-superset-no-lugar-do-power-bi.md). ADR aceito não se edita — se substitui, e o antigo ganha status substituído pelo 0007.
# 0001 — Adotar Superset no lugar do Power BI ## Status proposto | aceito | substituido pelo 0007 ## Contexto Quais forcas estao em jogo. Fatos, nao opiniao. Restricoes tecnicas, de prazo, de custo, de time. ## Decisao "Nos vamos ..." — voz ativa, frase completa. ## Consequencias O que muda depois disso. Positivas, negativas e neutras — listar TODAS, nao so as boas.
Estrutura não morre de desenho ruim. Morre de adoção: ninguém atualiza, e em três meses o mapa mente.
Se está em dois, está errado — e alguém vai atualizar o errado.
Dono = quem aprova mudança nela. Pasta sem dono é pasta abandonada com atraso.
rascunho / vigente / substituído. O que não tem status vira ruído — e contamina a leitura da IA também.
Histórico de decisão é imutável. O que muda é o status e o ponteiro para a decisão nova.
Confortável com um projeto, insuportável com cinco — e quebra permissão, ciclo de vida e git de uma vez.
“Depois a gente organiza” é o nome que a pasta abandonada recebe no primeiro dia.
Se o README e o AGENTS.md têm o mesmo conteúdo copiado, um dos dois vai mentir — e você não vai saber qual.