Registros de Decisão Arquitetural

Um Architecture Decision Record (ADR) é um documento curto que captura uma única decisão arquitetural junto com seu contexto e consequências. ADRs respondem à pergunta: por que essa decisão foi tomada, e quais são seus trade-offs?

O Archgate expande o conceito de ADR dando a cada decisão duas expressões: um documento que humanos e agentes de IA leem, e um arquivo de regras opcional que máquinas executam.

Duas Expressões de um ADR

ADR como Documento

O documento é um arquivo Markdown com frontmatter YAML armazenado em .archgate/adrs/. Ele descreve a decisão em linguagem simples: qual problema resolve, quais alternativas foram consideradas, o que a equipe decidiu, e quais consequências seguem.

Tanto humanos quanto agentes de IA consomem esse documento. Quando um agente de IA de codificação está prestes a escrever código, ele lê os ADRs relevantes para entender as restrições antes de gerar qualquer coisa.

Automatize isso com plugins de editor

Com o plugin do Claude Code ou Cursor, seu agente de IA lê os ADRs aplicáveis automaticamente antes de cada tarefa de codificação — sem necessidade de copiar e colar manualmente nos prompts. Inscreva-se para acesso beta.

ADR como Regras

O arquivo de regras é um arquivo .rules.ts complementar que exporta um objeto simples tipado com satisfies RuleSet. Quando você executa archgate check, a CLI carrega cada ADR que tem rules: true em seu frontmatter, executa o arquivo de regras complementar contra seu codebase, e reporta quaisquer violações com caminhos de arquivo e números de linha.

Nem todo ADR precisa de regras. Algumas decisões são melhor aplicadas apenas por revisão de código. Defina rules: false quando nenhuma verificação automatizada for prática.

Convenção de Nomenclatura de Arquivos

Os arquivos de ADR seguem uma convenção de nomenclatura estrita que codifica o prefixo do domínio, número de sequência e um slug legível:

{PREFIX}-{NNN}-{slug}.md            # The document
{PREFIX}-{NNN}-{slug}.rules.ts      # The companion rules file (optional)

Por exemplo, um ADR do domínio de arquitetura sobre estrutura de comandos produziria:

ARCH-001-command-structure.md
ARCH-001-command-structure.rules.ts

O prefixo vem do domínio do ADR (veja Domínios). O número de sequência é preenchido com zeros até três dígitos e auto-incrementado por archgate adr create.

Frontmatter YAML

Todo documento ADR começa com um bloco de frontmatter YAML entre delimitadores ---. O frontmatter é o metadado legível por máquina que o Archgate usa para carregar, filtrar e definir o escopo das regras.

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único como ARCH-001 ou BE-003
title	string	Sim	Título legível da decisão
domain	string	Sim	Nome de domínio registrado. Integrados: backend, frontend, data, architecture, general. Domínios personalizados podem ser adicionados via archgate adr domain add.
rules	boolean	Sim	Se este ADR tem um arquivo .rules.ts complementar
files	string array	Não	Padrões glob que definem quais arquivos as regras verificam
respectGitignore	boolean	Não	Se deve filtrar arquivos ignorados pelo .gitignore. Padrão: true.

O campo files é opcional. Quando presente, restringe a execução das regras apenas aos arquivos que correspondem aos globs fornecidos. Quando ausente, as regras são executadas contra todos os arquivos do projeto. Por exemplo, files: ["src/commands/**/*.ts"] limita as verificações apenas aos arquivos de comando.

O campo respectGitignore também é opcional. Por padrão, arquivos listados no .gitignore são excluídos de todas as operações de busca de arquivos (ctx.scopedFiles, ctx.glob(), ctx.grepFiles()). Defina respectGitignore: false para incluir arquivos ignorados pelo git — útil para regras que precisam inspecionar saída de build ou arquivos gerados.

Seções do Corpo do ADR

Após o frontmatter, o corpo do ADR segue uma estrutura de seções padrão:

Context

Descreve o problema ou situação que motivou a decisão. Inclua alternativas que foram consideradas e por que foram rejeitadas.

Decision

Declara a decisão em si e suas restrições principais. Esta é a seção que os agentes de IA mais observam ao decidir como escrever código.

Do’s and Don’ts

Orientação concreta e acionável dividida em duas subseções. Funcionam como uma lista de verificação rápida para desenvolvedores e agentes de IA.

Consequences

Dividida em três subseções:

• Positive — benefícios que a decisão proporciona
• Negative — trade-offs aceitos
• Risks — coisas que podem dar errado e como mitigá-las

Compliance and Enforcement

Descreve como a decisão é aplicada, tanto por regras automatizadas (com IDs de regra e severidades) quanto por checklists de revisão manual.

References

Links para ADRs relacionados, documentação externa ou documentos de design.

Exemplo Completo

Abaixo está um ADR completo com frontmatter e todas as seções preenchidas.

---
id: BE-001
title: API Response Envelope
domain: backend
rules: true
files: ["src/api/**/*.ts"]
---

## Context

The API returns data in inconsistent shapes across endpoints. Some endpoints
wrap responses in `{ data, error }`, others return raw arrays, and error
responses vary between plain strings and structured objects.

**Alternatives considered:**

- **No envelope** -- Return raw data and rely on HTTP status codes alone.
  Simple, but clients cannot distinguish between "the endpoint returned an
  empty array" and "the endpoint errored."
- **GraphQL-style errors array** -- Use `{ data, errors: [] }`. Flexible
  but adds complexity for simple REST endpoints.

The chosen envelope balances consistency with simplicity.

## Decision

All API endpoints MUST return responses in a standard envelope:

- Success: `{ data: T }`
- Error: `{ error: { code: string, message: string } }`

HTTP status codes remain the primary success/failure signal. The envelope
provides a predictable structure for clients to parse.

## Do's and Don'ts

### Do

- Wrap all API responses in the `{ data }` or `{ error }` envelope
- Use specific error codes (e.g., `VALIDATION_FAILED`, `NOT_FOUND`)
- Include the HTTP status code that matches the error semantics

### Don't

- Don't return raw arrays or primitives from API endpoints
- Don't nest envelopes (no `{ data: { data: ... } }`)
- Don't put stack traces in the error message field

## Consequences

### Positive

- Clients can parse every response with the same logic
- Error responses always have a machine-readable code for programmatic handling

### Negative

- Adds a small amount of boilerplate to every endpoint handler
- Slightly larger payloads due to the wrapper object

### Risks

- Developers may forget the envelope on new endpoints. Mitigated by
  the automated rule that scans for non-conforming return statements.

## Compliance and Enforcement

### Automated Enforcement

- **Archgate rule** BE-001/response-envelope: Scans API handler files for
  return statements and verifies they use the envelope helper. Severity: error.

### Manual Enforcement

Code reviewers MUST verify:

1. New API endpoints use the response envelope
2. Error responses include a specific error code, not a generic message

## References

- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines)
- [ARCH-002 -- Error Handling](./ARCH-002-error-handling.md)