Guia para agentes de IA¶

Como consumir esta documentação sem varrer o repositório inteiro.

1. Como localizar uma especificação¶

Não use grep por padrão de texto como primeiro passo. Comece por metadata/catalog.yaml — uma entrada por documento, com id, type, title, path, status, domains, components e related. Filtre por domains ou components para achar o que já existe sobre uma área antes de propor algo novo (é a checagem 1 da seção "Antes de criar um documento novo" abaixo).

Se o catálogo não bastar, specifications/index.md e fixes/index.md têm a lista completa em tabela, com domínio e status. Só desça para o corpo de uma spec/fix individual depois de identificar o ID pelo catálogo ou pelo índice — abrir dezenas de arquivos para procurar um assunto é o padrão que este catálogo existe para evitar.

Para a pergunta "isto já existe no produto?", o roadmap.md é o retrato mais direto — o que já existe, o que falta, as decisões pendentes, com arquivo:linha. É um retrato datado: confira no código antes de afirmar que o produto não faz algo.

2. O que ler antes de implementar¶

Na ordem — cada camada responde a uma pergunta diferente:

A spec ou o fix correspondente (docs/specifications/ ou docs/fixes/) — a fonte de verdade sobre o que construir e por quê: regras de negócio numeradas (RN), critérios de aceite (CA), autorização e isolamento.
docs/product/business-rules.md — regras transversais que não pertencem a uma spec só (paginação, isolamento de tenant, TenantSettings).
docs/architecture/ — como as peças se encaixam (containers, camadas da API, modelo de dados) — para saber onde uma mudança se encaixa antes de escrever código.
docs/decisions/ — se a mudança tocar algo que uma ADR já decidiu (ex.: mexer no design system, ou em compatibilidade de contrato), leia a ADR antes de reabrir a decisão.
O CLAUDE.md da raiz e o do app específico (apps/api/CLAUDE.md, apps/web/CLAUDE.md, apps/e2e/CLAUDE.md) — como o trabalho anda (seção Fluxo de desenvolvimento da raiz) e convenções de código que não são "documentação de produto": camadas, data-testid, fixtures de teste. Esses arquivos não foram movidos para docs/ — continuam onde o código os espera.

3. Como relacionar requisito, arquitetura, ADR, código e teste¶

O campo related do front matter (specs, fixes, tweaks, decisions, tests) é a aresta explícita entre documentos — segue o mesmo formato em todo tipo, então uma consulta no catálogo alcança o grafo inteiro sem precisar abrir cada arquivo. Código e teste não entram no catálogo (ele indexa documentos, não o repositório inteiro) — a spec/fix aponta para eles em texto (seção "Impacto por app" / "Correção", com arquivo:linha).

4. Quais arquivos são fontes oficiais¶

Pergunta	Fonte oficial	Não é fonte
O que uma funcionalidade faz e por quê	`docs/specifications/<slug>/specification.md`	memória da conversa, suposição
Contrato de API atual	Swagger ao vivo (`/api/docs`, `/api/openapi.json`) — ver `api/index.md`	um `openapi.yaml` desatualizado
Convenção de código de um app	`apps/<app>/CLAUDE.md`	um padrão observado em um arquivo só
Se algo já foi decidido e por quê	`docs/decisions/ADR-*.md`	inferir da leitura do código
Quantidade (testes, cobertura, lint)	o comando (`make test-count`, `make test-cov`, `make lint`) — nunca um número escrito em prosa	`CLAUDE.md`, esta documentação

5. Como atualizar a documentação¶

Spec ou fix novo — o Superpowers conduz (brainstorming → writing-plans para funcionalidade, systematic-debugging para defeito); os skills /spec, /fix e /tweak foram removidos em 2026-10-15. O registro é gravado aqui, não no docs/superpowers/ padrão do plugin: docs/specifications/NNNN-slug/specification.md (com o plano em plan.md ao lado) ou docs/fixes/NNNN-slug.md, sobre o template de doc-templates/, com o número de scripts/proximo-numero-spec.sh ou scripts/proximo-numero-fix.sh. Ninguém mais atualiza o catálogo por você: acrescente a entrada em docs/metadata/catalog.yaml e a linha no índice da pasta. A fonte é a seção Fluxo de desenvolvimento do CLAUDE.md da raiz.
Ajuste direto — não gera documento; o registro é a mensagem de commit. docs/tweaks/ é histórico e não recebe arquivo novo.
ADR — à mão, sobre doc-templates/adr.md, com a linha em decisions/index.md e a entrada no catálogo.
Documento de arquitetura/produto/operações — edite direto; atualize updated: no front matter e, se for documento novo, adicione a entrada em catalog.yaml (mesmo formato das existentes).
Nunca altere silenciosamente uma spec aprovada ou concluída. Se a implementação divergiu do que a spec descreve, isso é uma seção "Registro" (specs) ou uma nota explícita — não uma edição silenciosa da regra original.

6. Validações a rodar antes de concluir uma tarefa que tocou `docs/`¶

python3 scripts/docs_lint.py        # front matter, IDs duplicados, catálogo consistente
mkdocs build --strict               # site inteiro — link quebrado ou aviso falha o build

Para conferir pela web antes do merge, bash scripts/publicar-preview-docs.sh <branch> publica a branch em docs.garantora.com.br (ver operations/documentation-platform.md).

Se a tarefa não tocou docs/, essas validações não se aplicam — não rode por rotina. Se tocou specs/fixes/ADRs, rode as duas antes de considerar o trabalho pronto; um link relativo errado só aparece no mkdocs build --strict, não no lint de front matter.