Padrão Oficial de Documentação

Onze documentos. Todo projeto da AEX os mantém vivos e atualizados. Documentação faz parte da entrega — não documentado é não entregue.

---

Princípios

• A documentação vive no repositório, versionada junto ao código.
• É atualizada no mesmo Pull Request que muda o comportamento. PR sem documentação não é mesclado.
• É legível para humanos e para IA — clara, concisa e organizada.
• Cada documento tem um template em templates/project/. Comece por ele.

---

Os onze documentos obrigatórios

README.md, PROJECT_CONTEXT.md e CLAUDE.md ficam na raiz; os demais vivem em docs/.

---

O que cada documento contém

README.md

Porta de entrada do repositório.

• Descrição curta do projeto e seu objetivo.
• Stack e pré-requisitos.
• Como rodar localmente, testar e buildar.
• Links para os demais documentos.

PROJECT_CONTEXT.md

O porquê do projeto.

• Problema que resolve e para quem.
• Proposta de valor e objetivos de negócio.
• Métricas de sucesso.
• Escopo e, explicitamente, o que está fora de escopo.

CLAUDE.md

Regras para a IA atuar no repositório do projeto.

• Identidade do projeto, stack e convenções.
• Comandos essenciais (rodar, testar, buildar).
• Guardrails: o que a IA nunca deve fazer.
• Segue as convenções da engenharia (ver CLAUDE.md da raiz): objetivo, conciso, abaixo de ~200 linhas.

PRD.md

Requisitos do produto.

• Visão e personas.
• Requisitos funcionais e não-funcionais.
• Fluxos principais e critérios de aceite.
• Fora de escopo.

ARCHITECTURE.md

Arquitetura e decisões estruturais.

• Visão geral e diagrama de componentes.
• Camadas (frontend, backend, dados, infraestrutura) e responsabilidades.
• Integrações externas.
• Decisões-chave (as decisões detalhadas ficam em DECISIONS.md).

API.md

Contrato da API.

• Convenções gerais e autenticação.
• Cada endpoint: método, rota, parâmetros, request e response.
• Formato de erros.
• Exemplos de uso.

DATABASE.md

Modelo de dados.

• Diagrama entidade-relacionamento.
• Tabelas, colunas e relações.
• Índices e migrações.
• Políticas de acesso (ex.: RLS no Supabase).

DEPLOY.md

Processo de publicação do projeto.

• Ambientes e pipeline.
• Passo a passo do deploy e do rollback.
• Segue o DEPLOY_STANDARD.

ENVIRONMENT.md

Configuração de ambiente.

• Lista de variáveis: nome, descrição, obrigatória ou opcional.
• Onde obter cada valor.
• Espelha o .env.example; nunca contém segredos reais.

DECISIONS.md

Registro de decisões técnicas (ADRs).

• Uma entrada por decisão: data, contexto, decisão tomada, alternativas consideradas, consequências.
• Decisões são acrescentadas, não apagadas — o histórico é a memória do projeto.

CHANGELOG.md

Histórico de mudanças por versão.

• Versões em SemVer, da mais recente para a mais antiga.
• Agrupado por tipo: Adicionado, Alterado, Corrigido, Removido.

---

Como manter viva

• Atualize a documentação no mesmo PR que altera o comportamento.
• O checklist de code review verifica documentação — PR sem doc atualizada não passa.
• Documento desatualizado é pior que ausente: corrija assim que notar.

---

Regras (resumo)

1. Todo projeto mantém os onze documentos obrigatórios.
2. README.md, PROJECT_CONTEXT.md e CLAUDE.md na raiz; os demais em docs/.
3. Documentação é atualizada junto com a mudança de código.
4. Nenhum documento contém segredos reais.
5. Comece cada documento pelo template correspondente.