Escrevendo ADRs

Criando um ADR

Use archgate adr create para gerar um novo ADR com o template padrão. O comando suporta modos interativo e não-interativo.

Modo interativo

Execute o comando sem argumentos para receber prompts guiados:

archgate adr create

Você será solicitado a fornecer:

1. Domain — um entre backend, frontend, data, architecture ou general
2. Title — um nome curto e descritivo para a decisão
3. File patterns — globs opcionais separados por vírgula que delimitam o escopo da verificação de regras (ex.: src/commands/**/*.ts)

O CLI atribui um ID sequencial baseado no prefixo do domínio (ARCH-001, FE-002, BE-003, etc.) e grava o arquivo em .archgate/adrs/.

Modo não-interativo

Passe --title e --domain para pular os prompts:

archgate adr create --title "API Response Format" --domain backend --files "src/api/**/*.ts"

Flags disponíveis:

Flag	Descrição
--title <title>	Título do ADR (obrigatório no modo não-interativo)
--domain <name>	Domínio: backend, frontend, data, architecture, general
--files <globs>	Padrões de arquivo separados por vírgula para escopo de regras
--rules	Define rules: true no frontmatter
--body <md>	Corpo completo do ADR em markdown (pula o template)
--json	Exibe o resultado como JSON

O template gerado

Quando você cria um ADR sem --body, o CLI gera um template com todas as seções padrão:

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

# API Response Format

## Context

Describe the context and problem statement.

## Decision

Describe the decision that was made.

## Do's and Don'ts

### Do

-

### Don't

-

## Consequences

### Positive

-

### Negative

-

### Risks

-

## Compliance and Enforcement

Describe how this decision will be enforced.

## References

-

Orientações por seção

Context

Explique por que essa decisão foi necessária. Qual problema a motivou? Quais alternativas foram consideradas e por que foram descartadas?

Boas seções de contexto incluem:

• O problema ou ponto de dor que motivou a decisão
• Alternativas avaliadas, com uma breve análise de trade-offs
• Quaisquer restrições que limitaram as opções (tamanho da equipe, runtime, compatibilidade)

## Context

The CLI needs a consistent pattern for defining and registering commands. As the
command surface grows (init, check, adr, login, upgrade, clean), the registration
mechanism must scale without introducing hidden coupling or making the dependency
graph opaque.

**Alternatives considered:**

- **Auto-discovery via `executableDir()`** -- Commander.js supports automatic
  command discovery by scanning a directory. This hides the dependency graph and
  makes dead command detection impossible.
- **Single-file command map** -- Simple but creates a monolithic file that grows
  with every command.

Decision

Declare o que foi decidido. Seja específico e concreto — esta seção não deve deixar ambiguidade sobre o que os desenvolvedores devem fazer.

Inclua restrições numeradas quando a decisão tem múltiplas facetas:

## Decision

Commands live in src/commands/ and export a register\*Command(program) function.
The main entry point (src/cli.ts) explicitly imports and calls each register
function.

**Key constraints:**

1. **One command per file** -- Each .ts file defines exactly one command
2. **Explicit registration** -- Every command must be manually imported in src/cli.ts
3. **Thin commands** -- Command files handle I/O only; no business logic

Do’s and Don’ts

Esta é a seção que desenvolvedores e agentes de IA consultam com mais frequência. Escreva exemplos concretos de padrões corretos e incorretos. Use código real sempre que possível.

## Do's and Don'ts

### Do

- Export a register\*Command function from each command module
- Keep commands thin: parse args, call helpers/engine, format output
- Use src/commands/<name>.ts for top-level commands

### Don't

- Don't put business logic in command files -- move it to src/engine/ or src/helpers/
- Don't use executableDir() for command discovery
- Don't call .parse() in command files -- the entry point handles parsing

Consequences

Divida as consequências em três categorias:

• Positive — benefícios que a equipe ganha com esta decisão
• Negative — trade-offs que a equipe aceita (toda decisão tem)
• Risks — o que pode dar errado, e como você planeja mitigar

## Consequences

### Positive

- In-process execution enables testing without spawning subprocesses
- Explicit imports make all commands visible at a glance in src/cli.ts

### Negative

- Manual import bookkeeping -- each new command requires adding an import

### Risks

- Stale imports when commands are removed. Mitigation: TypeScript catches
  missing modules at compile time.

Compliance and Enforcement

Descreva como esta decisão é aplicada. Existem dois mecanismos de aplicação:

1. Regras automatizadas — arquivos .rules.ts complementares que rodam durante archgate check
2. Aplicação manual — o que revisores de código devem verificar

## Compliance and Enforcement

### Automated Enforcement

- **Archgate rule** ARCH-001/register-function-export: Scans all command files
  and verifies each exports a register\*Command function. Severity: error.

### Manual Enforcement

Code reviewers MUST verify:

1. New commands are imported and registered in src/cli.ts
2. Command files delegate to engine/helpers for business logic

References

Vincule ADRs relacionados, documentação externa ou discussões relevantes:

## References

- [Commander.js documentation](https://github.com/tj/commander.js)
- [ARCH-004 -- No Barrel Files](./ARCH-004-no-barrel-files.md)
- [ARCH-002 -- Error Handling](./ARCH-002-error-handling.md)

Delimitando regras com files

O campo files no frontmatter é um array de padrões glob. Quando definido, archgate check passa apenas os arquivos correspondentes para o ctx.scopedFiles da regra. Isso mantém as regras focadas no código que elas governam.

---
id: ARCH-001
title: Command Structure
domain: architecture
rules: true
files: ["src/commands/**/*.ts"]
---

Se files for omitido, ctx.scopedFiles inclui todos os arquivos do projeto. Isso é apropriado para regras que abrangem todo o projeto, como políticas de dependências.

Padrões comuns:

Padrão	Corresponde a
src/commands/**/*.ts	Todos os arquivos TypeScript em commands
src/**/*.ts	Todos os arquivos TypeScript do código-fonte
package.json	Apenas o package.json raiz
src/api/**/*.ts	Arquivos da camada de API
tests/**/*.test.ts	Arquivos de teste

Quando definir rules: true vs rules: false

Defina rules: true quando você tiver um arquivo .rules.ts complementar com verificações automatizadas. O arquivo deve ter o mesmo nome do arquivo markdown do ADR, mas com a extensão .rules.ts:

.archgate/adrs/
  ARCH-001-command-structure.md          # rules: true
  ARCH-001-command-structure.rules.ts    # companion rules file
  ARCH-002-error-handling.md             # rules: true
  ARCH-002-error-handling.rules.ts       # companion rules file
  GEN-001-code-review-process.md         # rules: false (no automated checks)

Defina rules: false para decisões que são aplicadas apenas por revisão de código — decisões de processo, acordos de equipe ou diretrizes difíceis de verificar programaticamente.

Atualizando ADRs

Use archgate adr update para modificar um ADR existente:

archgate adr update --id ARCH-001 --body "## Context\n\nUpdated context..." --title "New Title"

As flags --id e --body são obrigatórias. Todos os outros campos do frontmatter (--title, --domain, --files, --rules) são opcionais e preservam seus valores existentes quando omitidos.

Flag	Descrição
--id <id>	ID do ADR a ser atualizado (obrigatório)
--body <md>	Corpo markdown de substituição completa (obrigatório)
--title <title>	Novo título (preserva o existente se omitido)
--domain <name>	Novo domínio (preserva o existente se omitido)
--files <globs>	Novos padrões de arquivo (preserva os existentes se omitido)
--rules	Define rules: true
--json	Exibe o resultado como JSON

Dicas para ADRs eficazes

1. Mantenha cada ADR focado em uma única decisão. Se você perceber que está escrevendo sobre dois assuntos não relacionados, divida-os em ADRs separados.

2. Seja específico nos Do’s and Don’ts. Diretrizes vagas como “escreva código limpo” não são acionáveis. Mostre padrões de código concretos.

3. Inclua exemplos de código reais. A seção Do’s and Don’ts é onde desenvolvedores e agentes de IA olham primeiro. Exemplos de código anotados tornam a decisão inequívoca.

4. Documente as alternativas que você rejeitou. Futuros colaboradores perguntarão “por que não usamos X?” A seção Context deve responder a essa pergunta.

5. Declare os trade-offs honestamente. Toda decisão tem consequências negativas. Documentá-las gera confiança e ajuda a equipe a entender o que foi sacrificado.

6. Escreva regras para decisões que podem ser verificadas automaticamente. Se uma regra consegue detectar uma violação antes da revisão de código, defina rules: true e escreva um arquivo .rules.ts complementar. Veja o guia Escrevendo Regras.

7. Use prefixos de domínio para organizar. O campo domain (backend, frontend, data, architecture, general) determina o prefixo do ID e ajuda a filtrar ADRs por área.

Deixe agentes de IA escreverem ADRs para você

Os plugins de editor para Claude Code e Cursor incluem uma skill de ADR Author que cria e atualiza ADRs seguindo as convenções do seu projeto. A skill Quality Manager também propõe novos ADRs quando detecta padrões recorrentes. Inscreva-se para acesso beta.