Documentação e ADRs

Visão Geral

Documente decisões, não apenas código. A documentação mais valiosa captura o porquê — o contexto, as restrições e as trocas que levaram a uma decisão. O código mostra o que foi construído; a documentação explica por que foi construído dessa forma e quais alternativas foram consideradas. Esse contexto é essencial para futuros humanos e agentes que trabalham na base de código.

Quando Usar

• Ao tomar uma decisão arquitetural significativa
• Ao escolher entre abordagens concorrentes
• Ao adicionar ou alterar uma API pública
• Ao lançar um recurso que altera o comportamento voltado para o usuário
• Ao integrar novos membros da equipe (ou agentes) ao projeto
• Quando você se pega explicando a mesma coisa repetidamente

Quando NÃO usar: Não documente código óbvio. Não adicione comentários que reafirmem o que o código já diz. Não escreva documentação para protótipos descartáveis.

Registros de Decisão Arquitetural (ADRs)

ADRs capturam o raciocínio por trás de decisões técnicas significativas. Eles são a documentação de maior valor que você pode escrever.

Quando Escrever um ADR

• Ao escolher um framework, biblioteca ou dependência principal
• Ao projetar um modelo de dados ou esquema de banco de dados
• Ao selecionar uma estratégia de autenticação
• Ao decidir sobre uma arquitetura de API (REST vs. GraphQL vs. tRPC)
• Ao escolher entre ferramentas de build, plataformas de hospedagem ou infraestrutura
• Qualquer decisão que seria cara de reverter

Combine a convenção existente primeiro

Antes de criar um ADR, inspecione o contexto do repositório disponível em busca de uma convenção estabelecida — ADRs existentes, instruções do projeto e configuração ou ferramentas relacionadas a ADRs (por exemplo, um arquivo .adr-dir). Uma convenção estabelecida substitui os padrões abaixo. Combine:

• Localização e formato — por exemplo, docs/adr/*.md, Documentation/Decisions/*.rst, um layout MADR ou uma configuração adr-tools. Combine o diretório existente, a extensão do arquivo e a marcação (Markdown vs. reStructuredText).
• Numeração e nomenclatura — continue a sequência existente e o padrão de nome de arquivo (ADR-004-Title.rst, 0004-title.md, …); não reinicie em 001 nem introduza um segundo esquema.
• Títulos de seção — reutilize o conjunto de títulos do projeto em vez de impor este modelo.

Se as evidências disponíveis conflitarem, apresente o conflito em vez de introduzir silenciosamente outro esquema. Somente quando nenhuma convenção puder ser estabelecida, você aplicará o padrão abaixo.

Modelo de ADR

Armazene ADRs em docs/decisions/ com numeração sequencial (a menos que o projeto já use outro local — veja acima):

# ADR-001: Use PostgreSQL for primary database

## Status
Proposed | Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)

## Decision
Use PostgreSQL with Prisma ORM.

## Alternatives Considered

### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication

### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production

### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements

## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)

Ciclo de Vida do ADR

PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)

• Não exclua ADRs antigos. Eles capturam o contexto histórico.
• Quando uma decisão mudar, escreva um novo ADR que referencie e substitua o antigo.

Documentação Inline

Quando Comentar

Comente o porquê, não o o quê:

// RUIM: Reafirma o código
// Incrementa o contador em 1
counter += 1;

// BOM: Explica a intenção não óbvia
// O rate limit usa uma janela deslizante — reinicia o contador no limite da janela,

…