Governança de IA, para quem nunca abriu o repositório
Como o gov-procs-ai organiza o trabalho de agentes de IA
O gov-procs-ai é o repositório que define como os projetos da PROCS AI trabalham com agentes de IA: quem faz o quê, o que o agente pode fazer sozinho e o que precisa de uma pessoa. Esta página explica isso em cerca de 10 minutos.
Cada afirmação traz a fonte. Quando uma regra só está escrita e nenhum mecanismo a faz valer, a página diz isso com todas as letras.
9agentes
CLAUDE.md:30
7skills próprias
.claude/skills/ (D-088)
13hooks
.claude/hooks/ (12) e template/hooks/ (1)
132decisões vivas
DECISOES.md:46
Como ler esta página
Os selos dizem se uma regra tem mecanismo que a faça valer:
Enforced um hook ou código impede ou cobra
Parcial o mecanismo cobre só parte do caso
Declarada está escrita, sem mecanismo encontrado
Lembrete avisa e deixa seguir
Template modelo, ainda não ativo onde está
Os quadros com borda à esquerda marcam o que falta ou não fecha: Lacuna declarada (o próprio padrão admite), Não encontrado (procurado e ausente), Divergência entre fontes (dois documentos dizem coisas diferentes) e Implementação não comprovada (o código existe ou é citado, mas ninguém mediu).
As fontes citam arquivos do gov-procs-ai no formato caminho:linha, na versão 2026.11.18.4. Abreviações usadas:
rules-agentes e rules-skills: template/modelos/rules-agentes.md.modelo e rules-skills.md.modelo
protocolo-task e atualiza-gov: o SKILL.md dessas skills, em .claude/skills/
DECISOES.md: .claude/team/DECISOES.md; D-nnn é o número de uma decisão registrada ali
hooks: .claude/hooks/<nome>; portao.yml: o workflow de CI do portão
Mapa geral. O padrão mora no gov-procs-ai. Uma skill sincronizadora leva agentes, skills, hooks e regras para cada projeto.
Descrição do diagrama
Três blocos, de cima para baixo. No alto, o gov-procs-ai, com 9 agentes em forma de modelo, 7 skills próprias, 13 hooks, modelos de regras, 132 decisões vivas e os documentos em docs/. No meio, o sincronizador, que é a skill procs-ai-atualiza-gov: primeiro confere, depois aplica com --apply, depois roda o portão. Embaixo, o projeto, onde os agentes passam a valer, junto com skills, arquivos de hooks e regras. Os gatilhos dos hooks no settings.json não chegam ligados: o sincronizador entrega esse arquivo como passo manual.
Fontes: rules-agentes:10-11; atualiza-gov:58-60 e 67-69; entrar-no-padrao.md:204-214; D-088.
01
Objetivo
O que é
O gov-procs-ai é a esteira interna da empresa: o padrão que os projetos consomem. Ele não é entrega para cliente.
Para que serve
Fazer todo projeto trabalhar com agentes de IA do mesmo jeito, com regras, limites e pontos em que uma pessoa aprova.
O objetivo da empresa, escrito pelo dono, é construir e colocar em operação a PROCS AI, empresa AI-native especializada em automatizar processos empresariais com IA.
Fonte: docs/00-visao/visao.md:11-12
O documento de visão amarra o repositório a esse objetivo: nenhuma decisão do padrão pode sair dele. Decisão que não serve ao objetivo volta para o registro como alternativa descartada, com o motivo.
Fonte: visao.md:14-15
A governança de IA é o item 4 do escopo: regras, skills, permissões, limites de autonomia e pontos de aprovação humana.
Fonte: visao.md:55
O repositório não tem classe de origem (seção 10). As classes descrevem a origem de um projeto de software, e o padrão não é um. A visão declara isso de propósito.
Fonte: visao.md:41-42
02
Premissas
O que é
As suposições sobre as quais o padrão foi montado.
Para que serve
Quando o mundo muda, saber qual suposição caiu e quais regras dependem dela.
A tese do modelo operacional
Agentes de IA executam a maior parte do ciclo de desenvolvimento. O agente recebe objetivo e requisitos e consegue arquitetar, implementar, testar e colocar em produção. A equipe humana é enxuta e atua em decisão, revisão e aprovação de deploy.
A visão explica o porquê: não é economia de gente, é onde a atenção humana rende mais. Duas decisões existem para sustentar a tese sem que ela vire promessa: a D-014 (autonomia menor em projeto derivado) e a D-007 (portões no servidor).
Fonte: visao.md:27-33
03
Escopo
O que é
Os sete itens que o dono numerou na visão. Seis estão neste repositório.
Para que serve
Saber o que o padrão cobre, onde cada parte mora e o que ainda não existe.
#
Item
Onde mora
Situação
1
Stack, arquitetura e banco padrão
docs/01-golden-path/, D-001 a D-004
documentado
2
Padrão de identidade visual e de componentes
D-009; pacote de design system
Não encontrado tarefa T007 "A definir"
3
Template de projeto e geradores (scaffold)
template/
Não encontrado o scaffold; T007 e T008 "A definir"
4
Governança de IA
docs/02-governanca-ia/
documentado; autonomia em rascunho
5
Segurança e isolamento, com credenciais fora do host do agente
docs/03-seguranca-isolamento/
documentado; ver seção 11
6
Evals do pipeline
docs/04-evals/
documentado; alvos em lacuna
7
Posicionamento comercial, oferta e preço
fora deste repositório (D-011)
fora do escopo
Fonte: visao.md:46-61; .claude/team/BOARD.md:52-61 (T007 e T008 na seção "A definir"); autonomia.md:3
04
Fluxo de trabalho
O que é
O caminho de uma task (uma unidade de trabalho com número T<n>) desde a abertura da sessão até o deploy.
Para que serve
Mostrar em que ponto cada agente entra, onde uma pessoa precisa aprovar e onde um mecanismo automático confere.
A sessão é a conversa principal entre a pessoa e o assistente de IA. Ela coordena tudo. Uma mensagem só vira task quando começa com a palavra task ou quando é a resposta numérica a uma pendência aberta. Fora disso é conversa.
Fonte: protocolo-task:13-18
Um hook é um script que roda sozinho num evento da sessão, por exemplo antes de executar um comando. Ele pode deixar passar, pedir confirmação ou negar. Um portão é uma verificação que precisa passar para o trabalho seguir, como a que roda antes do push.
Há três portas humanas no fluxo: o dono aprova o requisito, decide o desenho e manda fazer o deploy. Os agentes de início propõem e não decidem.
Fluxo de uma tarefa. Âmbar cheio: porta humana. Verde: hook que confere. Tracejado neutro: lembrete. Âmbar tracejado: regra só declarada.
Descrição do diagrama
Treze passos em linha vertical, de 0 a 12. Abertura (hook session-state, só avisa). Gatilho (a sessão reconhece "task" ou um número de pendência). Número da task (hook nega número de outra tarefa). Roteamento (lembrete para disparar agentes). Requisito pelo analista (porta humana: o dono aprova). Desenho pelo arquiteto (porta humana: o dono decide). Construção por front, backoffice ou sessão e dba (hooks de escrita e de custo). Revisão (o BLOQUEIA do revisor está só declarado). Documento relido. Integração (hook do portão antes do push). Fechamento (hook do laço de melhoria). Deploy (porta humana: só por ordem do dono). Depois (a task sai do board).
Os passos, com quem age e o que confere
Passo
Quem
O que acontece
O que confere
0 Abertura
hook session-state
imprime onde parou, o board e avisos
só avisa
1 Gatilho
sessão
mensagem começa com task ou é número de pendência
senão é conversa protocolo-task:13-18
2 Número
sessão
T<n> é o maior do board e do arquivo, mais 1; ganha linha no BOARD.md
numero-de-task.mjs nega número de outra tarefa protocolo-task:40-43
3 Roteamento
sessão
dispara os agentes sinalizados ou diz por que não
lembrete rules-agentes:358-361
4 Requisito
analista
especificação em Status: proposta
INCOMPLETA espera resposta; o dono aprova
5 Desenho
arquiteto
proposta e bloco D-00n
o dono decide
6 Construção
front, backoffice ou sessão, dba
código e testes; até 3 em paralelo
guardas de escrita e de custo; fatia não aprovada espera rules-agentes:181
7 Revisão
revisor
veredito
BLOQUEIA impede o commit Declaradarules-agentes:122
8 Documento
arquiteto, analista, documentador
documento relido
no mesmo commit ou no seguinte, antes do push
9 Integração
sessão
commit, bloco GIT, push em comando separado
guarda de comando e portão do push; reprovado nega o push
10 Fechamento
sessão
4 condições; bloco de conclusão ou pendências, uma por vez
laco-de-melhoria.mjs; pendência vira Issue aberta à mão protocolo-task:79-86; controle-de-tarefas.md:43-60, 90-92
11 Deploy
sessão e devops
só por ordem do dono; documentação HTML, publicação, verificação de saúde
deploy reprovado reabre a task protocolo-task:92
12 Depois
sessão
a task concluída sai do board; o arquivo da próxima rodada é sobrescrito
Nove papéis especializados. Cada um é um subagente: uma instância de IA com instruções e ferramentas próprias, disparada pela sessão para uma parte do trabalho.
Para que serve
Dividir o trabalho por responsabilidade. Cada agente tem um eixo, o conjunto de pastas em que pode escrever.
Só a sessão principal dispara agentes. Um agente não chama outro. No modelo de projeto, um hook nega o disparo que venha de um subagente.
A cadeia tem ordem: analista, arquiteto, front e o resto do código, depois documentador e qa. O backoffice constrói o código que não é tela e pode ser a própria sessão. Revisor, dba e devops apoiam fora da cadeia.
Fonte: rules-agentes:15-16; CLAUDE.md:30; D-085
Nada dispara agente sozinho. O que é automático é só lembrete: um hook sugere agentes pelo texto do pedido, e outro avisa a sessão quando ela escreve no eixo de outro agente.
A sessão dispara sem pedir licença. Ficam a pedido do dono: how-to, teste de ponta a ponta (qa) e publicação (devops).
Fonte: D-126; rules-agentes:216 e 126; D-083
A sessão no centro. Linha verde contínua: a sessão dispara o agente. Linha âmbar tracejada: lembrete automático que chega à sessão. Não há linha entre agentes: um agente não chama outro.
Descrição do diagrama
Um círculo central, a sessão, ligado por linhas contínuas a nove agentes. Na metade de cima, a cadeia numerada: 1 analista, 2 arquiteto, 3 front e 3 backoffice, 4 documentador e 4 qa. Na metade de baixo, os três de apoio: revisor, dba e devops. Embaixo, dois hooks ligados à sessão por linhas tracejadas: roteamento-do-pedido, que sugere agentes, e guarda-de-escrita, que avisa a sessão quando ela escreve no eixo de outro. Não existe nenhuma ligação direta entre dois agentes.
Os nove, um por um
Todos pré-carregam duas skills: superpowers:verification-before-completion e andrej-karpathy-skills:karpathy-guidelines. No repositório de governança os nove são Template: não existe ali uma pasta .claude/agents/. Eles passam a valer num projeto quando o sincronizador os copia.
Fonte: rules-agentes:10-11; atualiza-gov:67-69; tabela conferida com D-103 (DECISOES.md:1520-1531)
analista
Template
Papel
transforma uma situação em especificação funcional
Acionado quando
chega um pedido, uma reclamação ou uma ideia
Entrega
uma seção em docs/10-especificacoes/aprovado-e-nao-construido.md em Status: proposta, perguntas, e o veredito PRONTA ou INCOMPLETA
Modelo
opus
Skills extras
nenhuma
Posição
abre a cadeia
Fonte: rules-agentes:20; analista.md:251-276
arquiteto
Template
Papel
desenha antes do código; propõe e não decide
Acionado quando
a demanda foi aprovada, ou a task cria módulo, integração, camada, dependência ou invariante
Entrega
docs/02-arquitetura/** e um bloco D-00n
Modelo
fable, esforço alto
Skills extras
procs-ai-change-impact
Posição
abre a cadeia
Fonte: rules-agentes:21
front
Template
Papel
dono do código de tela e do padrão visual
Acionado quando
a task mexe em tela, componente ou estilo
Entrega
telas e verificação visual
Modelo
opus
Skills extras
impeccable, vercel-react-best-practices
Posição
constrói
Fonte: rules-agentes:22; front.md:197-210
backoffice
Template
Papel
código que não é tela; orquestra a cadeia; pode ser a própria sessão
Acionado quando
regra de negócio, serviço, API, script
Entrega
código e testes de unidade e de integração
Modelo
fable (herda todas as ferramentas)
Skills extras
superpowers:test-driven-development
Posição
constrói e orquestra; fica fora da linha de registro da cadeia
Fonte: D-085; rules-agentes:106
documentador
Template
Papel
mantém a documentação viva
Acionado quando
no fim de uma task que tornou falsa uma afirmação de docs/; how-to só a pedido
Entrega
a árvore docs/, menos as pastas 02 e 10
Modelo
sonnet
Skills extras
nenhuma
Posição
fecha a cadeia
Fonte: rules-agentes:26; D-083
qa
Template
Papel
testes de ponta a ponta (e2e) com Playwright; reporta defeito sem consertar
Acionado quando
só quando o dono pede
Entrega
tests/e2e/**
Modelo
sonnet
Skills extras
procs-ai-click-path-audit
Posição
fecha a cadeia
Fonte: rules-agentes:27; D-083
revisor
Template
Papel
lê o diff antes do commit; não escreve
Acionado quando
o diff toca dado sensível, sessão, permissão, migration ou dinheiro
Entrega
APROVA, ALERTA ou BLOQUEIA
Modelo
opus, esforço alto
Skills extras
procs-ai-change-impact
Posição
apoia
Fonte: rules-agentes:117; revisor.md:80-86
dba
Template
Papel
dono do banco de dados
Acionado quando
tabela, índice, migration, dado
Entrega
migrations, schema, plano de consulta (EXPLAIN)
Modelo
opus
Skills extras
nenhuma
Posição
apoia
Fonte: rules-agentes:118
devops
Template
Papel
leva do commit até o ar
Acionado quando
o dono manda publicar; CI, imagem, serviço
Entrega
versões publicadas e teste rápido de fumaça (smoke)
Modelo
sonnet
Skills extras
nenhuma
Posição
apoia
Fonte: rules-agentes:120
Detalhes técnicos: revisor, paralelismo e briefing
Revisor: um por onda, antes do commit. Dois independentes em ponto crítico de dado e em migration destrutiva. No máximo 3 rodadas; depois decide o dono. rules-agentes:117-125
Antes do deploy: a sessão roda gerar-doc-html.mjs, depois entra o devops. rules-agentes:119-120; D-143
Documentos vivos: o arquiteto e o analista são os revisores fixos. D-082
Paralelo: até 3 agentes ao mesmo tempo. Do segundo que escreve em diante, cada um trabalha numa worktree: uma cópia de trabalho do mesmo repositório git, em outra pasta e outra branch, para dois agentes não colidirem. rules-agentes:209-231
O que o agente recebe: não há contrato formal de entrada por agente. Existe a regra do briefing: a task em uma linha, os arquivos, os trechos com fonte, teto de 8 KB. rules-agentes:193-198
06
Skills
O que é
Uma skill é um pacote de instruções que o agente carrega quando o assunto aparece. O padrão tem 7 próprias, em .claude/skills/.
Para que serve
Fazer a mesma tarefa sempre do mesmo jeito, sem depender de memória. Nenhuma skill própria mora em template.
Fonte: D-088
procs-ai-protocolo-task
Blocos de andamento, de git, de pendência e de fechamento.
Gatilho: mensagem começa com task, ou resposta numérica a uma pendência. Quem usa: a sessão. Casos de teste: 3.
protocolo-task:13-18
procs-ai-atualiza-gov
Confere e aplica o .claude/ do projeto; verbos de documentação.
Gatilho: só por comando. Quem usa: o dono. Casos de teste: sim (evaluations).
atualiza-gov (disable-model-invocation: true)
procs-ai-agents
Lista os agentes lendo os arquivos deles, nunca de memória.
Gatilho: "quais agentes eu tenho?". Quem usa: a sessão. Casos de teste: 3.
.claude/skills/procs-ai-agents/SKILL.md
procs-ai-avaliar-agentes
Avaliação (eval) dos agentes, com repetição (pass^k).
Gatilho: só por comando. Quem usa: só o dono. Casos de teste: sem eval.
rules-skills:32
procs-ai-change-impact
Prevê o impacto antes da mudança e confere contra o diff depois.
Gatilho: mudança que cruza módulo, contrato ou migration. Quem usa: pré-carregada no arquiteto e no revisor. Casos de teste: sem eval.
rules-skills
procs-ai-click-path-audit
Segue cada botão até o estado final.
Gatilho: tela com botão que muda estado. Quem usa: pré-carregada no qa. Casos de teste: sem eval.
rules-skills
procs-ai-migrar-modulos
Migra o src/ de um projeto para módulos.
Gatilho: só por comando. Quem usa: só o dono, em classe A. Casos de teste: sem eval.
rules-skills
Três skills têm casos de teste (protocolo-task, agents e atualiza-gov). As outras quatro não têm eval, e o padrão registra isso como dívida medida.
Fonte: .conformidade-base
Skills de terceiros
O padrão declara, sem copiar, plugins e skills de terceiros: os plugins superpowers, andrej-karpathy-skills e skill-creator, e as skills impeccable, break-ui e vercel-react-best-practices.
Fonte: skills-externas.json; rules-skills:20-23
07
Hooks e portões
O que é
Os 13 hooks do padrão: scripts que rodam sozinhos em eventos da sessão e podem bloquear, pedir confirmação ou só lembrar.
Para que serve
Transformar regra escrita em mecanismo. Regra com hook vira ENFORCED; regra sem hook continua DECLARADA.
São 12 arquivos em .claude/hooks/ e mais um, formatar-arquivo.sh, só no template. O que liga cada hook a um evento é o arquivo settings.json. No repositório de governança há 15 gatilhos ligados; no modelo de projeto, 21.
Fonte: .claude/settings.json; settings-projeto
Os hooks no tempo da sessão. Verde: o hook pode bloquear. Neutro: lembra, registra ou formata. Contorno tracejado: o gatilho só existe no modelo de projeto, não no repositório de governança.
Descrição do diagrama
Uma linha do tempo vertical com sete eventos. Na abertura, session-state.mjs lembra. Quando o pedido chega, roteamento-do-pedido.mjs lembra (só no modelo de projeto). Antes de um comando de terminal, guarda-de-comando.sh bloqueia e pede confirmação, conformidade-antes-do-push.sh bloqueia e numero-de-task.mjs bloqueia. Antes de escrever arquivo ou disparar agente, guarda-de-escrita.mjs bloqueia, pede e lembra (só no modelo de projeto) e custo-de-orquestracao.mjs bloqueia e pede. Depois de uma ferramenta, orcamento-de-contexto.mjs e eco-de-comportamento.mjs lembram, e formatar-arquivo.sh formata (só no modelo). Quando um subagente começa ou termina, custo-de-orquestracao.mjs registra, licao-do-agente.mjs bloqueia e o hook de trace fica desligado por padrão. No fim da resposta, laco-de-melhoria.mjs bloqueia, orcamento-de-contexto.mjs lembra e o hook de trace fica desligado.
Os 13 hooks: onde estão ligados e o que fazem
Hook
Evento
O que faz
Repo de governança
Modelo de projeto
Efeito
session-state.mjs
SessionStart; com --check vira portão
mostra onde parou, o board e 26 checagens
ligado
ligado
Lembra na abertura; --check reprova :669-673
guarda-de-comando.sh
PreToolUse Bash, PowerShell
nega --no-verify, despejo de .env e operação destrutiva de banco fora do dba; pede confirmação para git add -A e push que reescreve ou apaga referência
ligado
ligado
BloqueiaPede lê só o texto do comando :31-34, 73-75, 84-91, 101-104, 111-119
conformidade-antes-do-push.sh
PreToolUse em git push
nega commit e push no mesmo comando; roda o portão e nega se reprovar
ligado
ligado
Bloqueia:101-105
numero-de-task.mjs
PreToolUse git
nega commit ou merge com o número de outra tarefa
ligado
ligado
Bloqueia:97-108
custo-de-orquestracao.mjs
PreToolUse Agent; SubagentStart e Stop
pede confirmação se o briefing passa de 8 KB; nega o 4º subagente e o 2º que escreve sem worktree; grava ORQUESTRACAO.jsonl
ligado
ligado
Bloqueia falha aberta: se o hook der erro, o disparo passa :24-25
licao-do-agente.mjs
SubagentStop
bloqueia relatório de agente sem a linha "Licao"; promove a lição ao APRENDIZADOS.md
ligado
ligado
Bloqueia
laco-de-melhoria.mjs
Stop
no fechamento, bloqueia sem melhoria sugerida, sem linha Cadeia ou com HEAD fora do remoto; grava FECHAMENTOS.jsonl
ligado
ligado
Bloqueia cobrança do push só com PROCS_BRANCH_INTEGRACAO:54, 302-339
orcamento-de-contexto.mjs
PostToolUse e Stop
avisa saída acima de 15 mil caracteres, mais de 150 chamadas, janela acima de 200 mil
ligado
ligado
Lembra
eco-de-comportamento.mjs
PostToolUse Write, Edit
lembra de procurar frase antiga ao editar hook, settings, agente ou regra
ligado
ligado
Lembra
guarda-de-escrita.mjs
PreToolUse Edit, Write e Agent
subagente fora do eixo é negado; sessão editando settings, hooks ou CLAUDE.md precisa confirmar; nega subagente disparando subagente; lembra a sessão
não ligado
ligado
Bloqueia onde ligado; não cobre Bash rules-agentes:65-69
roteamento-do-pedido.mjs
UserPromptSubmit
sugere agentes pelo texto do pedido
não ligado
ligado
Lembra
hook de trace
Stop e SubagentStop
envia o rastro (trace) dos agentes a um serviço externo, só com a variável de ativação ligada
não ligado
presente, desligado por padrão
não bloqueia
formatar-arquivo.sh
PostToolUse Write, Edit
roda o Prettier se o projeto tiver
não existe
ligado
não bloqueia
Fonte: .claude/hooks/* e template/hooks/*; .claude/settings.json; settings-projeto. O nome do arquivo do hook de trace fica fora desta página porque contém o nome de um provedor.
08
O agente pode fazer isso sozinho?
O que é
A lista do que o agente faz sem pedir, do que pede uma pessoa e do que é proibido.
Para que serve
Responder rápido "posso deixar o agente fazer isto?" e saber se a resposta tem mecanismo por trás ou só está escrita.
Cada ação, a regra, se precisa de uma pessoa e o que a faz valer
Ação
Regra
Pessoa aprova?
Estado
Evidência
Ler código
permitido
não
não se aplica
autonomia.md:24
Escrever código (classe A)
permitido
não
Parcial o eixo vale para subagente e só para editar e escrever arquivo; para a sessão é declarado
guarda-de-escrita.mjs:301-316
Commit e push na branch de integração
permitido
não
Parcial cobrado só com PROCS_BRANCH_INTEGRACAO definida
laco-de-melhoria.mjs:54, 328
Deploy
só quando o dono pede
sim
Declarada
autonomia.md:27; D-084
Publicar em classe B; alterar o núcleo do upstream
proibido sem aprovação
sim
Declarada
autonomia.md:28-29
Ler .env ou credencial
proibido
não se aplica
Parcial
guarda-de-comando.sh:89-91; permissions.deny do modelo
Acessar o banco direto
proibido
não se aplica
Declarada
autonomia.md:31
Excluir dado
pede aprovação
sim
Parcial reconhecido pelo texto do comando
guarda-de-comando.sh:111-120; D-033
Mexer em infraestrutura
pede aprovação
sim
Declarada sem mecanismo
D-033
Migração de schema, dependência nova (classe A)
age e avisa
não
Declarada
autonomia.md:80-82
Contornar o portão (--no-verify)
proibido
não se aplica
Enforced só local; o CI registra e não impede
guarda-de-comando.sh:73-75; portao.yml:7-9
Push com portão vermelho
negado
não se aplica
Enforced só local
conformidade-antes-do-push.sh:101-105
Push que reescreve ou apaga referência
pede uma pessoa
sim
Enforced por confirmação
guarda-de-comando.sh:101-104
git add -A
pede confirmação
sim
Enforced
guarda-de-comando.sh:84-86
Editar os próprios limites (settings, hooks, CLAUDE.md)
pede uma pessoa
sim
Enforced no projeto
guarda-de-escrita.mjs:238-245
Subagente disparar subagente
proibido
não se aplica
Enforced no projeto
guarda-de-escrita.mjs:181-187
Até 3 subagentes; o 4º entra em fila
permitido
não
Enforced com falha aberta
custo-de-orquestracao.mjs:145-147
2º agente que escreve, sem worktree
negado
não se aplica
Enforced
custo-de-orquestracao.mjs:150-152
Decidir estrutura sem registro
proibido
sim
Parcial o portão cobra o campo de guarda
autonomia.md:35
Preencher fato sem fonte
proibido
não se aplica
Declarada
autonomia.md:36-37
Sessão escrever no eixo de outro agente
permitido
não
Lembrete
guarda-de-escrita.mjs:262-268
"Só local": o hook roda na estação de quem trabalha. "No projeto": o hook está ligado no modelo de projeto e não no repositório de governança. "Falha aberta": se o próprio hook falhar, a ação passa.
09
Decisões
O que é
O registro das decisões estruturais, numeradas como D-nnn. São 132 vivas e 11 superadas; a numeração vai até D-143.
Para que serve
Não rediscutir o que já foi decidido e saber por que cada regra existe, inclusive a alternativa que perdeu.
Cada decisão é um bloco ## D-00n com a alternativa descartada e o campo Guarda, que diz qual teste, hook ou portão a faz valer. A ficha fica no arquivo vivo e a íntegra em arquivo/DECISOES-detalhe.md. O índice é gerado por script.
Fonte: fluxo-do-time.md:16-49
Consultar
O caminho é: mapa por assunto, depois o índice, depois a busca grep -n "^## D-0nn". Os agentes consultam o índice antes de decidir. Regra decidida não se rediscute.
Fonte: D-093; DECISOES.md:17-18; fluxo-do-time.md
Rever
Decisão não se apaga. Ela recebe "Superada por D-00n" e vai para o arquivo de superadas. O portão cobra a contagem, duplicatas e o campo de guarda.
Fonte: DECISOES.md:9-11
Como está o campo de guarda
62 decisões têm mecanismo. 6 dizem "SEM GUARDA". 64 não têm o campo, e o padrão registra isso como dívida. Todas têm alternativa descartada.
Fonte: .conformidade-base
Ciclo de vida. Da proposta à revisão, com uma porta humana no passo 2. A revisão abre uma nova proposta; a antiga fica arquivada.
Descrição do diagrama
Cinco caixas de cima para baixo. 1, proposta: o arquiteto devolve o bloco D-00n. 2, aprovação humana: o dono decide. 3, registro: ficha com alternativa descartada e campo Guarda, índice gerado, e o portão cobra o campo. 4, consulta: mapa por assunto, índice e busca; o que foi decidido não se rediscute. 5, revisão: a decisão nunca se apaga, recebe "Superada por D-00n" e vai para o arquivo de superadas. Uma seta volta da revisão para a proposta: uma nova decisão substitui a antiga.
10
Classes A, B e C
O que é
A classe diz de onde o projeto veio. Todo projeto declara a sua no CLAUDE.md.
Para que serve
Ajustar a exigência à origem: o que nasce no padrão segue tudo; o que veio de fora segue o essencial e tem cuidados próprios.
Fonte: D-012 (DECISOES.md:948-985)
A · Nativo
Nasce do scaffold do padrão. É a única classe em que a stack padrão é obrigatória.
D-012
B · Derivado
Vem de um terceiro com upstream vivo (o projeto original continua sendo mantido). Só entra em produção com cinco obrigações:
revisão de licença antes de qualquer código (bloqueante)
commit do upstream fixado
customização em camada separada
acompanhamento de aviso de segurança, com responsável
divergência registrada num D-00n só
D-013 (DECISOES.md:987-1009)
C · Incorporado
Já existia antes e não tem upstream.
O que vale para as três
Segurança, observabilidade, memória, protocolo de task e board são obrigatórios em qualquer classe.
Fonte: D-012
Autonomia menor na classe B
Em projeto derivado, o agente lê antes de escrever e escreve em camada. Publicar exige aprovação humana até existir eval do projeto. Alterar o núcleo do upstream é sempre decisão humana.
Fonte: D-014 (DECISOES.md:1011-1018)
11
Segurança, evals e observabilidade
O que é
O que o padrão documenta para proteger o caminho do código, medir os agentes e enxergar erros, lado a lado com o que existe de fato.
Para que serve
Separar intenção de mecanismo. Quem adota o padrão precisa saber o que já está protegido e o que ainda depende de cuidado manual.
TemaDocumentadoImplementado
Runner efêmero e cofre (D-006)
Documentadoisolamento.md:44-47
ImplementadoNão o agente roda na estação autonomia.md:19-20, 30
Cofre do CI (D-030)
Documentadoisolamento.md:116-119
ImplementadoNão comprovado
Segredo de runtime
Documentadolacuna declarada isolamento.md:133-135
ImplementadoNão
Portão no servidor (D-007, D-035)
Documentadoisolamento.md:57-60
ImplementadoParcial o CI roda em push e PR, com actions fixadas por SHA; avisa e não impede portao.yml:7-9
Agente sem acesso ao banco (D-008)
Documentadoisolamento.md:72-76
ImplementadoNão só a guarda de operação destrutiva
Guardas locais
Documentadofluxo-do-time.md:82-84
ImplementadoSim os hooks da seção 7
Conteúdo externo é dado, não instrução (D-099)
DocumentadoCLAUDE.md:46
ImplementadoNão verificado mecanismo não verificado
4 métricas do pipeline (D-034)
Documentadoevals.md:23-28; alvos em lacuna
ImplementadoParcial FECHAMENTOS.jsonl e ORQUESTRACAO.jsonl guardam duração e tokens; a suíte da T009 está "A definir"; o tempo até produção não tem fonte evals.md:93-94
Eval dos agentes (D-107)
Documentadoskill procs-ai-avaliar-agentes
ImplementadoParcial 7 cenários para 7 dos 9 agentes (faltam documentador e backoffice); nenhum resultado registrado
Observabilidade de produto (D-010, D-056 a D-059)
Documentadoobservabilidade-e-erro.md §2 a §8
ImplementadoNão nenhum código; só o modelo de documento
Camadas de portão. O hook local nega; o CI registra; a proteção de branch não existe. Um push que não passa pelo hook local chega à main.
Descrição do diagrama
Dois pontos de partida no alto. À esquerda, um push feito na estação, que entra na camada 1, o hook local, que nega portão vermelho e --no-verify (ENFORCED, local); só o push verde segue. À direita, em vermelho tracejado, um push que não passa pelo hook local: ele pula a camada 1. Os dois caminhos atravessam a camada 2, o CI no servidor, que registra e avisa mas não impede (PARCIAL), e a camada 3, a proteção de branch, que está ausente. No fim, a branch main recebe o push, inclusive o vermelho.
O laço de aprendizado
Todo relatório de subagente termina com uma linha "Licao". O hook licao-do-agente.mjs leva essa lição sozinho para o APRENDIZADOS.md, marcada como não revisada. A triagem é do dono.
Fonte: D-077; D-106
12
Adoção
O que é
O roteiro para um projeto entrar no padrão, na ordem do documento entrar-no-padrao.md.
Para que serve
Levar um projeto ao padrão sem pular etapa. O documento avisa: a ordem não é sugestão, porque cada passo produz o que o seguinte lê.
Linhas de entrar-no-padrao.md, salvo indicação. As marcações não são salvas: servem só para acompanhar a leitura.
Roteiro de adoção. À esquerda, os passos na ordem do documento. À direita, tracejado, o que depende do projeto.
Descrição do diagrama
Uma coluna de dez passos, de cima para baixo: 0 declarar a classe (em B, a licença vem antes e bloqueia); 1 sete arquivos de contexto e o hook que os mede; 2 ponteiro Visão e escopo; 3 cortar aos tetos, arquivando; 4 instalar a skill procs-ai-atualiza-gov; 4.4 rodar o sincronizador (conferir, aplicar, portão); 5 documentação; 6 portão no servidor; 7 divergência num D-00n só; 8 só classe A, layout por módulo. Ao lado do passo 4.4, dois condicionais: aplicar só depois de o dono ver a lista, e ligar os gatilhos do settings à mão. Embaixo, à direita, o que depende do projeto: o arquivo de eixos, a variável PROCS_BRANCH_INTEGRACAO, a dispensa dos agentes de fim em projeto sem tela e o trace por projeto.