Documentar

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 os trade-offs que levaram a uma decisão. O código mostra o que foi construído; a documentação explica por que foi construído assim e quais alternativas foram consideradas. Esse contexto é essencial para humanos e agentes que trabalharão no código no futuro.

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 uma funcionalidade que muda o comportamento visível ao usuário
• Ao integrar novos membros do time (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 escreva comentários que apenas repetem o que o código já diz. Não escreva documentação para protótipos descartáveis.

O fluxo

1. Registros de Decisão Arquitetural (ADRs)

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

• Escolher framework, biblioteca ou dependência importante
• Desenhar um modelo de dados ou esquema de banco
• Definir estratégia de autenticação ou arquitetura de API (REST vs. GraphQL vs. tRPC)
• Escolher ferramentas de build, hospedagem ou infraestrutura
• Tomar qualquer decisão cara de reverter

Armazene os ADRs em docs/decisions/ com numeração sequencial:

# ADR-001: Usar PostgreSQL como banco de dados principal

## Status
Aceito | Substituído pelo ADR-XXX | Descontinuado

## Data
2025-01-15

## Contexto
Precisamos de um banco principal para o app de gestão de tarefas. Requisitos:
- Modelo relacional (usuários, tarefas, times com relacionamentos)
- Transações ACID para mudanças de estado das tarefas
- Busca full-text no conteúdo das tarefas; hospedagem gerenciada disponível

## Decisão
Usar PostgreSQL com o ORM Prisma.

## Alternativas consideradas

### MongoDB
- Prós: esquema flexível, fácil de começar
- Contras: nossos dados são inerentemente relacionais
- Rejeitado: dados relacionais em um banco de documentos geram joins complexos ou duplicação

### SQLite
- Prós: zero configuração, embutido, leitura rápida
- Contras: escrita concorrente limitada, sem hospedagem gerenciada para produção
- Rejeitado: inadequado para aplicação web multiusuário em produção

## Consequências
- O Prisma fornece acesso tipado ao banco e gerenciamento de migrações
- Podemos usar a busca full-text do PostgreSQL em vez de adicionar Elasticsearch
- O time precisa conhecer PostgreSQL (habilidade padrão, risco baixo)

Ciclo de vida: PROPOSTO → ACEITO → (SUBSTITUÍDO ou DESCONTINUADO). Nunca apague ADRs antigos — eles preservam o contexto histórico. Quando uma decisão mudar, escreva um novo ADR que referencie e substitua o anterior.

2. Documentação inline (comentários)

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

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

// BOM: explica uma intenção não óbvia
// O rate limit usa janela deslizante — zera o contador no limite da janela,
// não em horário fixo, para evitar ataques em rajada nas bordas da janela
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

O que não fazer:

• Comentar código autoexplicativo
• Deixar comentários TODO para coisas que você deveria fazer agora
• Deixar código comentado — apague; o git guarda o histórico

Documente pegadinhas conhecidas onde elas importam:

/**
 * IMPORTANTE: esta função deve ser chamada antes do primeiro render.
 * Se chamada após a hidratação, causa flash de conteúdo sem estilo,
 * porque o contexto de tema não existe durante o SSR.
 * Veja o ADR-003 para o racional completo do design.
 */
export function initializeTheme(theme: Theme): void { /* ... */ }

3. Documentação de API

Para APIs públicas (REST, GraphQL, interfaces de biblioteca), prefira documentação inline junto aos tipos:

/**
 * Cria uma nova tarefa.
 *
 * @param input - Dados de criação (título obrigatório, descrição opcional)
 * @returns A tarefa criada com ID e timestamps gerados pelo servidor
 * @throws {ValidationError} Se o título for vazio ou exceder 200 caracteres
 * @throws {AuthenticationError} Se o usuário não estiver autenticado
 *
 * @example
 * const task = await createTask({ title: 'Comprar mantimentos' });
 */
export async function createTask(input: CreateTaskInput): Promise<Task> { /* ... */ }

Para APIs REST, mantenha também a especificação OpenAPI/Swagger atualizada, com esquemas de requisição/resposta e códigos de erro.

4. README e changelog

Todo projeto precisa de um README que cubra: descrição em um parágrafo, início rápido (clonar, instalar, configurar .env, rodar), tabela de comandos (dev, test, build, lint), visão geral da arquitetura com link para os ADRs, e como contribuir.

Para funcionalidades lançadas, mantenha um changelog no formato Keep a Changelog, agrupando por Adicionado / Corrigido / Alterado, com número da versão, data e referência às issues.

5. Documentação para agentes de IA

Contexto especial para agentes:

• CLAUDE.md / arquivos de regras — documente as convenções do projeto para que os agentes as sigam
• Arquivos de spec — mantenha as specs atualizadas para que os agentes construam a coisa certa
• ADRs — ajudam agentes a entender decisões passadas (evita "re-decidir")
• Pegadinhas inline — impedem que agentes caiam em armadilhas conhecidas

Racionalizações comuns

Racionalização	Realidade
"O código é autodocumentado"	O código mostra o quê. Não mostra o porquê, as alternativas rejeitadas nem as restrições.
"Escrevemos docs quando a API estabilizar"	APIs estabilizam mais rápido quando documentadas. A doc é o primeiro teste do design.
"Ninguém lê documentação"	Agentes leem. Futuros engenheiros leem. Você mesmo, daqui a 3 meses, lê.
"ADRs são burocracia"	Um ADR de 10 minutos evita um debate de 2 horas sobre a mesma decisão seis meses depois.
"Comentários ficam desatualizados"	Comentários sobre o porquê são estáveis. Os sobre o o quê desatualizam — por isso só se escreve o primeiro tipo.

Sinais de alerta

• Decisões arquiteturais sem racional escrito
• APIs públicas sem documentação nem tipos
• README que não explica como rodar o projeto
• Código comentado em vez de apagado
• Comentários TODO parados há semanas
• Nenhum ADR em um projeto com escolhas arquiteturais significativas
• Documentação que repete o código em vez de explicar a intenção

Portão de aprovação

Apresente: os ADRs novos ou atualizados (com alternativas consideradas e consequências), as mudanças no README/changelog e qualquer doc de API alterada. O humano aprova: o conteúdo de cada ADR — em especial se o racional e as alternativas rejeitadas refletem a decisão real do time — e a exatidão da documentação voltada ao usuário. Só avance para o lançamento (skill lancar) após aprovação explícita.

Verificação

Após documentar:

• Existem ADRs para todas as decisões arquiteturais significativas
• O README cobre início rápido, comandos e visão geral da arquitetura
• Funções de API têm documentação de parâmetros e tipos de retorno
• Pegadinhas conhecidas estão documentadas inline onde importam
• Não restou código comentado
• Arquivos de regras (CLAUDE.md etc.) estão atuais e precisos