Convenções, Ciclo e Governança

11. Convenção de nomenclatura de arquivos

11.1. Estrutura geral

A convenção de nomes deverá seguir o padrão:

<PV>-<TIPO>-<NUM>--<descricao-curta>.md

Onde:

• PV = ponto de vista geral;
• TIPO = tipo do artefato, história ou documento;
• NUM = número sequencial com 4 dígitos (0001–9999);
• descricao-curta = resumo objetivo, sem acentos, sem caracteres especiais, separado por hífen.

Nota de design: o uso de 4 dígitos foi adotado para garantir capacidade de escala em projetos de alta volumetria de artefatos.

11.2. Pontos de vista gerais

Sigla	Ponto de vista
ESP (Especificação)	Especificação
INF (Infraestrutura)	Infraestrutura
PRO (Prototipação)	Prototipação
IMP (Implementação)	Implantação e Construção
GTI (Governança de TI)	Governança de TI
GDA (Governança de Dados)	Governança de Dados
PDP (Proteção de Dados Pessoais)	Proteção de Dados Pessoais

11.3. Tipos de histórias da especificação

HNI, HNE, HNU, HS, HI, HRD, HUX, HC, HAI, HAC, HIVC

11.4. Tipos de histórias da infraestrutura

HII, HSI, HATI, HCTI, HCI, HSII, HAII, HIS, HSE, HDISP, HAUT, HMON, HSIS, HDEP, HAMB, HIOP, HAIS

11.5. Tipos documentais complementares

Sigla	Documento
VIS	Vision Document
BRD	Business Requirements Document
PRD	Product Requirements Document
RFC	Request for Comments
ADR	Architecture Decision Record
SDD	System Design Document
TDD	Technical Design Document
DOM	Domain Model
ERD	Data Model / Entity-Relationship Diagram
API	API Contract
TPL	Test Plan
DOD	Definition of Done
RUN	Runbook / Playbook
PMT	Postmortem
RDM	Roadmap
CHG	Changelog
REL	Release Notes
EVD	Evidência
CHK	Checklist
DEC	Decisão
IDX	Índice
REF	Referência
CTX	Context Map
STY	Style Guide

11.6. Exemplos

ESP-HNI-0001--diretrizes-institucionais-de-atendimento.md
ESP-HAI-0004--autenticacao-govbr-por-nivel.md
INF-HMON-0003--regras-de-alerta-e-escalonamento.md
INF-HAUT-0002--pipeline-ci-cd-da-solucao.md
IMP-TDD-0001--implementacao-do-login-externo.md
GTI-ADR-0001--validacao-cruzada-obrigatoria-por-ia.md
GDA-ERD-0001--modelo-relacional-principal.md
PDP-RUN-0001--tratamento-de-incidente-com-dados-pessoais.md
ESP-CTX-0001--mapa-de-contexto-versao-atual.md
ESP-STY-0001--style-guide-identidade-visual.yaml

---

12. Repositórios, documentação e navegação

12.1. Organização de repositórios

Cada ponto de vista geral deverá possuir repositório próprio, segregado dos demais, com histórico próprio, responsáveis próprios e trilha própria de evolução.

No mínimo: repositórios ESP (Especificação), INF (Infraestrutura), PRO (Prototipação), IMP (Implementação), GTI (Governança de TI), GDA (Governança de Dados) e PDP (Proteção de Dados Pessoais).

Sincronização entre repositórios: a rastreabilidade bidirecional deverá ser garantida por:

• referência explícita ao identificador do artefato de origem em todo artefato derivado;
• arquivo IDX de índice cruzado em cada repositório;
• detecção automatizada de divergências pelo Artefato Orquestrador quando um artefato referenciado for alterado sem atualização correspondente;
• autoridade documental definida: ESP (Especificação) é autoridade sobre requisitos; INF (Infraestrutura) sobre padrões de infraestrutura; GTI (Governança de TI) sobre decisões.

Alternativa para Modo Ágil: projetos classificados no Modo Ágil poderão utilizar monorepo com workspaces segregados por ponto de vista.

12.2. Organização da documentação em pastas

/00-indice
/01-visao-geral
/02-historias
/03-decisoes
/04-evidencias
/05-checklists
/06-modelos
/07-referencias
/08-publicado

12.3. Regra de documentação curta

• Um documento deve tratar de um assunto principal;
• Documentos longos deverão ser quebrados em partes;
• A navegação deverá ocorrer por índice, links, referências e pastas temáticas.

12.4. Versionamento

Tudo deverá ser versionado: histórias, protótipos, decisões, artefatos de infraestrutura, códigos, testes, modelos de dados, políticas, documentação e evidências. O versionamento deverá permitir identificar: versão vigente, versões anteriores, data de cada alteração, autores ou responsáveis, justificativa e artefatos afetados.

12.5. Documentação automatizada

Deverá existir ferramenta de geração automatizada de documentação funcional, técnica, operacional e de governança. Esta ferramenta é parte integrante do Artefato Orquestrador e constitui pré-requisito operacional para viabilidade do framework.

Todo documento gerado deverá apresentar, de forma visível: data da última alteração, autores, versão vigente, vínculos com artefatos correlatos e evidências relacionadas.

---

13. Ciclo operacional do framework

flowchart TD
    A[Consolidação de histórias ESP (Especificação) por IA] --> B{Validação cruzada\nIA + humano}
    B -->|Aprovado| C[PRO — prototipação preliminar]
    B -->|Rejeitado| A
    C --> D[Reunião a quente com demandante\n+ registro obrigatório]
    D --> E[Histórias aprovadas e refinadas]
    E --> F[INF — estruturação de ambientes\nautenticação, monitoração, CI/CD]
    E --> G[IMP — construção por IA agêntica]
    F --> G
    G --> H{Validação cruzada\nIA + critério de divergência}
    H -->|Divergência relevante| I[Escalada ao Validador Técnico]
    H -->|Aprovado| J[Linter de Governança]
    I --> J
    J -->|Conforme| K[Gate de promoção de ambiente]
    J -->|Não conforme| G
    K --> L[Dossiê automatizado + evidências]
    L --> M[GTI (Governança de TI) / GDA (Governança de Dados) / PDP — supervisão contínua]

Responsáveis por etapa

Etapa	Responsável principal	Apoio de IA
Consolidação de histórias	IA primária (ESP (Especificação))	—
Validação cruzada de histórias	IA secundária + Validador de Negócio	Briefing por papel
Prototipação preliminar	IA agêntica (PRO (Prototipação))	—
Reunião de refinamento	Demandante + IA	Registro estruturado obrigatório
Estruturação de infraestrutura	IA agêntica (INF (Infraestrutura)) + Validador Técnico	—
Construção	IA agêntica (IMP (Implementação))	—
Validação cruzada da implementação	IA secundária + Validador Técnico	Relatório de impacto
Linter de Governança	Artefato Orquestrador	Automático
Gate de promoção	Validador Técnico + Validador de Negócio	IA assiste
Dossiê e evidências	Artefato Orquestrador	Automático
Supervisão contínua	GTI (Governança de TI) + GDA (Governança de Dados) + PDP (Proteção de Dados Pessoais)	IA monitora

Compatibilidade com iterações ágeis

O framework é compatível com metodologias ágeis. Recomenda-se cadência de refinamento de histórias a cada sprint (ciclo de duas semanas), com o ciclo operacional mapeado para as cerimônias de refinamento, planejamento e revisão.

13.1. Condições de exceção e retorno

Condição	Ação obrigatória
Divergência relevante entre engines de IA	Escalada imediata ao Validador humano; execução bloqueada
Rejeição de história na validação humana	Retorno à ESP (Especificação) com registro formal de rejeição
Não-conformidade no Linter de Governança	Bloqueio do avanço de fase; correção obrigatória
Conflito entre validação de IA e humana	Decisão pertence ao humano; divergência registrada como DEC
Rollback após promoção	Acionamento via pipeline; postmortem obrigatório para produção
Ausência de registro em reunião a quente	Decisões não reconhecidas para fins de rastreabilidade

---

14. Cláusula de transparência operacional

Sempre que aplicável, as soluções construídas sob este framework deverão informar ao usuário:

• identificação de que a solução ou parte dela opera com assistência de IA;
• indicação das limitações funcionais relevantes conhecidas;
• mecanismo de autenticação utilizado e nível de autenticação requerido;
• finalidade do uso de dados pessoais, quando aplicável;
• canal e momento adequados para apresentação dos disclaimers.

---

15. Resultado esperado

A adoção deste framework deverá permitir que a instituição desenvolva sistemas com: maior velocidade de construção, maior padronização de artefatos, maior reaproveitamento de conhecimento institucional, maior capacidade de rastreamento, auditoria e geração de evidências, maior aderência a normas e políticas, maior qualidade técnica e maior segurança jurídica, operacional e informacional no uso intensivo de inteligência artificial.

15.1. Indicadores de desempenho do framework

Indicador	Descrição	Meta orientativa
Tempo de spec-to-deploy	Tempo entre aprovação das primeiras histórias e entrega em produção	A definir por projeto
Cobertura de testes automatizados	Percentual de cobertura gerada por IA	≥ 80% no Modo Completo
Taxa de divergência relevante	Proporção de artefatos com divergência que obrigou escalada	Monitorar tendência
Tempo médio de aprovação humana	Tempo entre submissão ao validador e aprovação	A definir por nível
Volume de evidências automáticas	Proporção de evidências obrigatórias geradas automaticamente	100% das obrigatórias
Taxa de bloqueio no Linter	Proporção de artefatos bloqueados antes do gate	Tendência decrescente

---

16. Glossário

Termo	Definição
Agente agêntico / IA agêntica	Sistema de IA capaz de executar sequências de ações de forma autônoma com objetivo definido
Alucinação	Geração de conteúdo factualmente incorreto ou inventado por um modelo de IA
Artefato Orquestrador	Agente central responsável por coordenar o ciclo operacional do framework
Contexto distinto	Configuração em que a segunda engine opera com modelo, provedor, sessão e perspectiva diferentes da engine primária
CTX (Context Map)	Artefato que resume o estado atual do projeto para alimentar o contexto dos agentes de IA
Engine de IA	Modelo de linguagem utilizado para produzir, validar ou avaliar artefatos do framework
Grounding	Ancoragem de respostas de IA em dados e documentos verificáveis
HITL (Human-in-the-Loop)	Modelo de operação em que um humano participa da decisão em pontos definidos do fluxo
Linter de Governança	Mecanismo que verifica se artefatos possuem todos os metadados, vínculos e evidências obrigatórias
Modo de aplicação	Configuração de uso do framework proporcional à criticidade: Completo, Essencial ou Ágil
Ponto de vista (PV)	Perspectiva estruturada e segregada de análise do sistema
STY (Style Guide)	Arquivo estruturado (JSON/YAML) com parâmetros de identidade visual e acessibilidade
Validação cruzada	Submeter um artefato gerado por uma engine à avaliação de outra engine em contexto distinto
Vendor lock-in	Dependência excessiva de um provedor que dificulta a migração para alternativas

---

17. Modos de aplicação

O framework deverá ser aplicado de forma proporcional à criticidade, sensibilidade e complexidade do projeto.

17.1. Modo Completo — Alta Criticidade

Indicado para: sistemas com dados pessoais sensíveis, impacto financeiro relevante, risco à vida, obrigação legal, exposição pública ou dependência operacional crítica.

Dimensão	Especificação
Pontos de vista	Todos os 7 (ESP (Especificação), INF (Infraestrutura), PRO (Prototipação), IMP (Implementação), GTI (Governança de TI), GDA (Governança de Dados), PDP (Proteção de Dados Pessoais))
Histórias ESP (Especificação)	11 tipos individuais (HNI a HIVC)
Repositórios	7 segregados
Validações	IA primária + IA secundária + humano
Evidências	Todas as obrigatórias por seção
Linter de Governança	Obrigatório em todos os gates
Cobertura de testes	≥ 80%

17.2. Modo Essencial — Média Criticidade

Indicado para: sistemas internos sem dados pessoais sensíveis, aplicações de suporte operacional.

Dimensão	Especificação
Pontos de vista	ESP (Especificação), IMP (Implementação), GTI (Governança de TI), PDP (Proteção de Dados Pessoais) obrigatórios; INF (Infraestrutura), PRO (Prototipação), GDA (Governança de Dados) quando aplicável
Histórias ESP (Especificação)	5 grupos temáticos
Repositórios	4 segregados ou monorepo com workspaces
Validações	IA primária + humano por amostragem
Evidências	Simplificadas — apenas as mínimas obrigatórias

Agrupamento de histórias ESP (Especificação) no Modo Essencial:

Grupo	Tipos agrupados
Negócio	HNI + HNE + HNU
Sistema	HS + HRD
UX e Conformidade	HUX + HC + HAC + HIVC
Integração	HI
Autenticação	HAI

17.3. Modo Ágil — Baixa Criticidade

Indicado para: protótipos, MVPs, sistemas de apoio e ferramentas internas de baixo impacto.

Dimensão	Especificação
Pontos de vista	ESP (Especificação), IMP (obrigatórios)
Histórias ESP (Especificação)	2 grupos: Negócio e Sistema
Repositórios	Monorepo com workspaces por ponto de vista
Validações	IA primária
Evidências	Mínimas — aprovação e rastreabilidade básica

---

18. Artefato Orquestrador

18.1. Finalidade

O Artefato Orquestrador é o componente central de automação do framework, responsável por tornar operacional a execução das regras, evidências e fluxos definidos neste documento.

O Artefato Orquestrador não é opcional. Sem ele, a execução do framework depende inteiramente de intervenção humana manual, o que inviabiliza o ganho de velocidade e a consistência de evidências prometidos.

18.2. Responsabilidades

• monitorar os repositórios dos pontos de vista e detectar artefatos aprovados, alterados ou em pendência;
• disparar automaticamente a validação cruzada quando um artefato for submetido para aprovação;
• acionar a geração de prototipação preliminar quando histórias suficientes forem aprovadas na ESP (Especificação);
• executar o Linter de Governança antes de cada gate de promoção;
• gerenciar o fluxo de promoção entre fases e ambientes;
• detectar divergências entre repositórios e gerar alertas de sincronização;
• gerar automaticamente o dossiê de entrega, as evidências obrigatórias e o Context Map (CTX);
• registrar o histórico de inferências das engines de IA para fins de auditoria;
• controlar e reportar consumo de tokens por projeto e por engine.

18.3. Arquitetura mínima

• integrar-se aos repositórios de todos os pontos de vista ativos;
• possuir interface de configuração dos critérios de divergência e dos gates de aprovação;
• expor trilha de auditoria própria de todas as ações automatizadas;
• ser versionado e rastreado como qualquer outro artefato do framework.

---

Apêndice A — Stack de referência

Este apêndice é não prescritivo. As ferramentas listadas são referências de mercado compatíveis com os requisitos do framework. A adoção de qualquer ferramenta específica deverá ser decidida pela GTI (Governança de TI) conforme as políticas institucionais vigentes.

Categoria	Ferramentas de referência
CI/CD	GitHub Actions, GitLab CI, ArgoCD
Documentação automatizada	MkDocs, Docusaurus, Obsidian
Agentes de IA	LangChain, AutoGen, CrewAI
Banco vetorial para grounding (GDA (Governança de Dados))	Chroma, Weaviate, pgvector
Prototipação assistida por IA	Figma com plugins de IA, Galileo AI
Gestão de repositórios	GitHub, GitLab, Bitbucket
Observabilidade	Prometheus, Grafana, OpenTelemetry
Containers e ambientes	Docker, Kubernetes, Colima
Gestão de segredos	HashiCorp Vault, AWS Secrets Manager

---

← Anterior: Pontos de Vista · Início: Framework SinergIA