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 compensações 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ões Arquiteturais (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

Modelo de ADR

Siga a localização e numeração de ADRs existente no repositório; use docs/decisions/ apenas se não houver convenção. As seguintes decisões e alternativas são suposições fictícias do projeto, não rankings universais de banco de dados:

# 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: Our measured concurrent-write requirements exceed the selected deployment's constraints; assess SQLite for the actual workload before rejecting it

### 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 muda, escreva um novo ADR que referencie e substitua o antigo.

Documentação Inline

Quando Comentar

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

// BAD: Restates the code
// Increment counter by 1
counter += 1;

// GOOD: Explains non-obvious intent
// This simple counter resets its window on the first request after expiry.
// It is not a sliding-window limiter; assess bursts near the boundary.
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

Quando NÃO Comentar

// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// Don't leave TODO comments for things you should just do now
// TODO: add error handling  ← Just add it

// Don't leave commented-out code
// const oldImplementation = () => { ... }  ← Delete it, git has history

Documente "Gotchas" Conhecidos

/**
 * IMPORTANTE: Esta função deve ser chamada antes da primeira renderização.
 * Se chamada após a hidratação, causa um flash de conteúdo não estilizado
 * porque o contexto do tema não está disponível durante o SSR.
 *

…