Skill ADR Author

A skill adr-author é a camada de autoria autoritativa para Architecture Decision Records (ADRs). Ela escreve e edita ADRs que correspondem à estrutura, ao tom e à profundidade dos registros existentes do projeto — e é a única skill que cria ou modifica arquivos de ADR. Toda outra skill que precisa de um ADR escrito ou alterado delega ao adr-author em vez de editar os arquivos diretamente.

O que ela faz

A skill assume a responsabilidade pela qualidade do ADR de ponta a ponta:

• Entende o contexto da decisão — pesquisa o codebase, os ADRs existentes e o espaço do problema antes de escrever
• Escreve ADRs completos — produz registros completos com todas as seções obrigatórias em qualidade de produção
• Mantém a consistência — segue a estrutura exata, a ordem dos campos do frontmatter e as convenções de ID de domínio do projeto
• Edita cirurgicamente — ao atualizar um ADR, preserva a identidade do registro (ID e nome de arquivo nunca mudam)

Modos de operação

Modo de Criação

Usado quando um novo ADR é necessário. A skill escreve o corpo completo do zero, determina o próximo ID de ADR a partir da lista existente, gera o slug do nome de arquivo a partir do título e escreve o arquivo completo em .archgate/adrs/<ID>-<slug>.md. O próximo ID é calculado listando os ADRs existentes, filtrando pelo prefixo do domínio e incrementando o maior número (preenchido com zeros até três dígitos).

Modo de Edição

Usado quando um ADR existente precisa de modificação. A skill lê o registro atual, aplica as alterações solicitadas e escreve o resultado de volta no mesmo caminho — usando edições cirúrgicas para pequenas mudanças ou uma reescrita completa ao reestruturar. O ID e o nome de arquivo do ADR são imutáveis.

O modo é escolhido pela intenção: um ID de ADR a atualizar significa Modo de Edição; uma nova decisão a documentar significa Modo de Criação.

As seis seções obrigatórias

Todo ADR que a skill produz segue esta ordem exata de seções:

1. Context — a definição do problema, os pontos de dor sem padronização, uma análise de 3 a 4 alternativas concorrentes com críticas específicas, a motivação específica do projeto e referências cruzadas a ADRs relacionados.

2. Decision — o mandato concreto e prescritivo em linguagem forte (“MUST”, “will”), o escopo (o que ele cobre e o que não cobre), a integração com outros ADRs e as principais capacidades.

3. Do’s and Don’ts — 5 a 10 Do’s (cada um prefixado com DO, nomeando comandos/APIs/padrões exatos) e 5 a 8 Don’ts (cada um prefixado com DON'T, nomeando um antipadrão específico). Cada item deve ser objetivamente verificável.

4. Consequences — Positivas (5 a 10 itens), Negativas (3 a 5 trade-offs honestos) e Riscos (2 a 4 itens, cada um com uma mitigação explícita — nenhum risco órfão).

5. Compliance and Enforcement — aplicação automatizada (verificações do Archgate, CI, linting), itens de checklist de revisão manual, scaffolding e o processo de exceções.

6. References — ADRs relacionados via caminhos relativos e documentação externa.

As seções opcionais — Implementation Pattern (exemplos de código bom/ruim), Key Definitions, Approved Exceptions e Review Checklist — são adicionadas quando agregam valor.

Frontmatter e nomenclatura

Todo arquivo de ADR fica em .archgate/adrs/<ID>-<slug>.md e começa com frontmatter YAML em uma ordem fixa de campos: id → title → domain → rules → files (se presente). rules nunca é omitido; o padrão é false.

---
id: BE-002
title: Backend Framework
domain: backend
rules: true
files:
  - "src/backend/**"
---

O prefixo do ID é derivado do domínio — architecture → ARCH, backend → BE, frontend → FE, data → DATA, general → GEN. Os projetos podem registrar domínios customizados; a skill sempre consulta a lista mesclada de domínios antes de escolher e confirma com você antes de registrar um novo.

Arquivos companheiros de regras

Quando rules: true, a skill cria o arquivo companheiro .rules.ts em .archgate/adrs/<ID>-<slug>.rules.ts na mesma invocação — nunca um sem o outro. O arquivo de regras referencia as declarações de tipo ambientes e exporta um RuleSet cujas verificações rodam durante o archgate check. Cada regra pode ser error (um bloqueio definitivo), warning (exibido, mas sem bloquear) ou info.

Nota

As APIs RuleContext e RuleSet usadas em arquivos .rules.ts são mais recentes do que a maioria dos cortes de treinamento dos modelos. A skill carrega o guia autoritativo de autoria de regras — veja a skill cli-reference e a referência em cli.archgate.dev para a API exata.

Calibração de tom e qualidade

Os ADRs são escritos em linguagem prescritiva, específica e equilibrada: “MUST” e “will” em vez de “should” ou “could” (ambiguidade que as verificações automatizadas não conseguem validar), nomes exatos de ferramentas e arquivos em vez de orientações vagas, e trade-offs honestos em vez de defesa unilateral. O tamanho acompanha o escopo — cerca de 80 a 120 linhas para uma decisão conceitual, até ~400 linhas para a escolha de um framework com múltiplos exemplos de código.

Como se encaixa no fluxo

adr-author é a camada de escrita compartilhada por baixo do restante do sistema de governança:

• A skill onboard a chama (via sub-agentes paralelos) para escrever o backlog inicial de ADRs.
• A skill lessons-learned a chama sempre que um padrão capturado vira um ADR novo ou ampliado.
• A skill reviewer verifica o código em relação aos ADRs que o adr-author produz.

Esse design de camada única de autoria garante que todo ADR — independentemente de como ele se origine — atenda ao mesmo nível de qualidade.

Architecture Decision Records O conceito autoritativo de ADR e a referência da CLI em cli.archgate.dev.