ADR-0022 — Cabeçalho de arquivo com referências para agentes de IA

Status

Aprovado

Contexto

O projeto EBDbe possui regras de negócio (PRD, TDD), regras de implementação (ADRs, padrões de código) e dependências de ambiente (Firebase, Flutter, Firestore). Agentes de IA e desenvolvedores precisam saber rapidamente quais regras se aplicam a cada arquivo, sem ter de ler o documento inteiro nem replicar trechos no código.

Replicar o texto das regras no cabeçalho do arquivo poluiria o código e criaria duplicação; o que se deseja é apontar (referenciar) os documentos e seções relevantes.

Decisão

Todo arquivo de código-fonte do projeto (TypeScript, Dart e demais linguagens de implementação) deve ter, no início do arquivo, um bloco de comentário que inclua:

1. Context e Responsibility (já adotados conforme ADR-0020), identificando camada e responsabilidade do arquivo.
2. Apontamentos opcionais (quando aplicável), em linhas dedicadas, referenciando por identificador curto — sem replicar o texto da regra:
   • Regras de negócio: PRD, TDD ou documento equivalente (ex.: PRD perfil-usuario, TDD perfil-ebd, TDD api gateway).
   • Regras de implementação: ADRs ou convenções (ex.: ADR-0007, ADR-0013, ADR-0021).
   • Ambiente / dependências: quando relevante para o arquivo (ex.: Cloud Functions, Firestore, Flutter Web).

O objetivo é orientar o agente de IA e o leitor humano: onde buscar a regra, não qual é a regra. Os apontamentos devem ser concisos (nomes de doc, números de ADR, referência de seção quando útil).

Formato recomendado

TypeScript (JSDoc):

/**
 * Context: Application
 * Responsibility: Gateway de ações do usuário (perfil, papéis, aprovações).
 * Business rules: PRD perfil-usuario, TDD perfil-ebd, TDD api gateway
 * Implementation: ADR-0007, ADR-0013, ADR-0014, ADR-0021
 * Environment: Cloud Functions
 */

Dart (dartdoc):

/// Context: Infrastructure
/// Responsibility: Perfil via HTTP (userGatewayHttp).
/// Business rules: PRD perfil-usuario, TDD perfil-ebd
/// Implementation: ADR-0007, ADR-0013, ADR-0021

• Context e Responsibility são obrigatórios (consistente com ADR-0020).
• Business rules, Implementation e Environment são opcionais; incluir apenas quando houver regras ou ambiente relevantes para aquele arquivo.
• Usar identificadores curtos (nome do doc, número do ADR). Não colar trechos das regras no comentário.

Consequências

• Agentes de IA podem, ao abrir um arquivo, saber onde procurar regras de negócio e implementação.
• Reduz-se a necessidade de replicar texto de PRD/TDD/ADR no código.
• Novos arquivos passam a ser criados já com cabeçalho que aponta para as regras aplicáveis.
• A convenção complementa o ADR-0020 (comentários intencionais) e o ADR-0007 (organização de código), sem substituí-los.