Pular para conteúdo

AGENTS.md - SOT AuthN/AuthZ

Objetivo

Este repositório e a fonte de verdade (SOT) de governanca para os dominios AuthN e AuthZ do ConectaFapes.

Fonte de governanca

As regras oficiais de governanca, SDLC e contribuicao estao centralizadas em CONTRIBUTING.md.

Escopo

  • Documentacao arquitetural e de governanca.
  • Planejamento segmentado por dominio/subdominio e por fase:
  • plan/dev: features de desenvolvimento fim a fim.
  • plan/ops: atividades e tasks operacionais.
  • quando necessario: plan/<fase>/<dominio>/<subdominio>/...
  • Diretrizes para sincronizacao entre SOT e repositorios de implementacao.

Regras operacionais para agentes

  1. Sempre ler plan/repos.yaml antes de qualquer acao de implementacao ou planejamento.
  2. Se a demanda citar um repositorio que nao exista localmente, clonar no caminho artifacts/<repo_slug> usando a URL do manifesto.
  3. Todo item novo deve ter rastreabilidade por IDs:
  4. EPIC-<dominio>-NNN
  5. ADR-<dominio>-NNN
  6. STORY-<dominio>-YYYYWW-NN
  7. TASK-<dominio>-YYYYWW-NN
  8. Itens operacionais devem usar IDs de ops:
  9. OPSTASK-<dominio>-YYYYWW-NN
  10. OPSINC-<dominio>-YYYYWW-NN (quando aplicavel)
  11. Story e task de desenvolvimento devem referenciar:
  12. uma sprint em plan/dev[/<dominio>/<subdominio>]/sprints
  13. uma issue no repositorio de implementacao
  14. ADR aplicavel (quando houver impacto arquitetural)
  15. Tasks operacionais devem referenciar:
  16. uma sprint em plan/ops[/<dominio>/<subdominio>]/sprints
  17. ambiente impactado, janela operacional e validacao pos-mudanca
  18. Toda mudanca arquitetural relevante exige ADR no SOT antes ou junto da implementacao.
  19. Toda atualizacao de sprint deve atualizar status de sincronizacao com issues e PRs.
  20. Nao duplicar detalhes de codigo no SOT; o SOT guarda direcao, decisao, integracao e rastreabilidade.

Regra de sincronizacao de contexto distribuido

  • Ritmo minimo semanal:
  • atualizar progresso de sprint no SOT
  • reconciliar status com issues/PRs dos repositorios de implementacao
  • registrar desvios, riscos e decisoes
  • Em incidentes criticos de seguranca (AuthN/AuthZ), atualizar SOT no mesmo dia.

Estrutura esperada

  • docs/: documentacao para humanos (mkdocs/techdocs).
  • plan/: governanca de planejamento.
  • plan/dev: planejamento de desenvolvimento E2E por dominio/subdominio.
  • plan/ops: planejamento operacional por dominio/subdominio.
  • agents/: instrucoes e skills para agentes (dev, ops, plan).