Pular para o conteúdo
PROCS AI

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
  • settings-projeto: template/modelos/settings-projeto.json.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: da governança ao projeto gov-procs-ai repositório de governança: o padrão 9 agentes (modelos) 7 skills próprias 13 hooks modelos de regras 132 decisões vivas documentos em docs/ sincronizador skill procs-ai-atualiza-gov confere, depois --apply, depois o portão projeto o que passa a valer nele agentes, já ativos skills arquivos dos hooks regras de agentes e skills settings.json: os gatilhos dos hooks se ligam à mã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.
#ItemOnde moraSituação
1Stack, arquitetura e banco padrãodocs/01-golden-path/, D-001 a D-004documentado
2Padrão de identidade visual e de componentesD-009; pacote de design systemNão encontrado tarefa T007 "A definir"
3Template de projeto e geradores (scaffold)template/Não encontrado o scaffold; T007 e T008 "A definir"
4Governança de IAdocs/02-governanca-ia/documentado; autonomia em rascunho
5Segurança e isolamento, com credenciais fora do host do agentedocs/03-seguranca-isolamento/documentado; ver seção 11
6Evals do pipelinedocs/04-evals/documentado; alvos em lacuna
7Posicionamento comercial, oferta e preçofora 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.

Fonte: rules-agentes:82-84; D-033; protocolo-task:92

Fluxo de uma tarefa, com as portas humanas 0 Aberturahook session-state lembrete: só avisa 1 Gatilhosessão: "task" ou número 2 Número T<n>sessão, linha no BOARD hook: nega número alheio 3 Roteamentosessão dispara agentes lembrete 4 Requisitoanalista porta humana: aprova 5 Desenhoarquiteto, bloco D-00n porta humana: decide 6 Construçãofront, backoffice, dba hooks: escrita e custo 7 Revisãorevisor BLOQUEIA: declarado 8 Documentoarquiteto, analista, documentador 9 Integraçãosessão: commit e push hook: portão do push 10 Fechamentosessão, 4 condições hook: laço de melhoria 11 Deploysessão e devops porta humana: só a pedido 12 Depoissai do board; próxima rodada
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
PassoQuemO que aconteceO que confere
0 Aberturahook session-stateimprime onde parou, o board e avisossó avisa
1 Gatilhosessãomensagem começa com task ou é número de pendênciasenão é conversa protocolo-task:13-18
2 NúmerosessãoT<n> é o maior do board e do arquivo, mais 1; ganha linha no BOARD.mdnumero-de-task.mjs nega número de outra tarefa protocolo-task:40-43
3 Roteamentosessãodispara os agentes sinalizados ou diz por que nãolembrete rules-agentes:358-361
4 Requisitoanalistaespecificação em Status: propostaINCOMPLETA espera resposta; o dono aprova
5 Desenhoarquitetoproposta e bloco D-00no dono decide
6 Construçãofront, backoffice ou sessão, dbacódigo e testes; até 3 em paraleloguardas de escrita e de custo; fatia não aprovada espera rules-agentes:181
7 RevisãorevisorvereditoBLOQUEIA impede o commit Declarada rules-agentes:122
8 Documentoarquiteto, analista, documentadordocumento relidono mesmo commit ou no seguinte, antes do push
9 Integraçãosessãocommit, bloco GIT, push em comando separadoguarda de comando e portão do push; reprovado nega o push
10 Fechamentosessão4 condições; bloco de conclusão ou pendências, uma por vezlaco-de-melhoria.mjs; pendência vira Issue aberta à mão protocolo-task:79-86; controle-de-tarefas.md:43-60, 90-92
11 Deploysessão e devopssó por ordem do dono; documentação HTML, publicação, verificação de saúdedeploy reprovado reabre a task protocolo-task:92
12 Depoissessãoa task concluída sai do board; o arquivo da próxima rodada é sobrescritofluxo-do-time.md:33-34

Fonte geral: CLAUDE.md, .claude/rules/fluxo-do-time.md, docs/02-governanca-ia/controle-de-tarefas.md

05

Agentes

O que é
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.

Fonte: rules-agentes:152-155; guarda-de-escrita.mjs:181-187

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.

Fonte: roteamento-do-pedido.mjs:58-64; guarda-de-escrita.mjs:262-268

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

Os nove agentes em volta da sessão cadeia, na ordem 1, 2, 3, 4 1 analista 2 arquiteto 3 front 3 backoffice 4 documentador 4 qa revisor dba devops apoio, fora da cadeia sessão dispara roteamento-do-pedido sugere agentes guarda-de-escrita avisa a sessão
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

Hooks na linha do tempo da sessão AberturaSessionStart Pedido chegaUserPromptSubmit Antes de comandoPreToolUse Bash, PowerShell Antes de escreverou disparar agentePreToolUse Edit, Write, Agent Depois da ferramentaPostToolUse SubagenteSubagentStart, SubagentStop Fim da respostaStop session-state.mjsL roteamento-do-pedidoL guarda-de-comando.shB P conformidade-...push.shB numero-de-task.mjsB guarda-de-escritaB P L custo-de-orquestracaoB P orcamento-de-contextoL eco-de-comportamentoL formatar-arquivo.shF custo-de-orquestracaoR licao-do-agente.mjsB hook de traceoff laco-de-melhoria.mjsB orcamento-de-contextoL hook de traceoff B bloqueia · P pede confirmação · L lembra · R registra · F formata · tracejado: só no modelo de 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
HookEventoO que fazRepo de governançaModelo de projetoEfeito
session-state.mjsSessionStart; com --check vira portãomostra onde parou, o board e 26 checagensligadoligadoLembra na abertura; --check reprova :669-673
guarda-de-comando.shPreToolUse Bash, PowerShellnega --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êncialigadoligadoBloqueia Pede lê só o texto do comando :31-34, 73-75, 84-91, 101-104, 111-119
conformidade-antes-do-push.shPreToolUse em git pushnega commit e push no mesmo comando; roda o portão e nega se reprovarligadoligadoBloqueia :101-105
numero-de-task.mjsPreToolUse gitnega commit ou merge com o número de outra tarefaligadoligadoBloqueia :97-108
custo-de-orquestracao.mjsPreToolUse Agent; SubagentStart e Stoppede confirmação se o briefing passa de 8 KB; nega o 4º subagente e o 2º que escreve sem worktree; grava ORQUESTRACAO.jsonlligadoligadoBloqueia falha aberta: se o hook der erro, o disparo passa :24-25
licao-do-agente.mjsSubagentStopbloqueia relatório de agente sem a linha "Licao"; promove a lição ao APRENDIZADOS.mdligadoligadoBloqueia
laco-de-melhoria.mjsStopno fechamento, bloqueia sem melhoria sugerida, sem linha Cadeia ou com HEAD fora do remoto; grava FECHAMENTOS.jsonlligadoligadoBloqueia cobrança do push só com PROCS_BRANCH_INTEGRACAO :54, 302-339
orcamento-de-contexto.mjsPostToolUse e Stopavisa saída acima de 15 mil caracteres, mais de 150 chamadas, janela acima de 200 milligadoligadoLembra
eco-de-comportamento.mjsPostToolUse Write, Editlembra de procurar frase antiga ao editar hook, settings, agente ou regraligadoligadoLembra
guarda-de-escrita.mjsPreToolUse Edit, Write e Agentsubagente fora do eixo é negado; sessão editando settings, hooks ou CLAUDE.md precisa confirmar; nega subagente disparando subagente; lembra a sessãonão ligadoligadoBloqueia onde ligado; não cobre Bash rules-agentes:65-69
roteamento-do-pedido.mjsUserPromptSubmitsugere agentes pelo texto do pedidonão ligadoligadoLembra
hook de traceStop e SubagentStopenvia o rastro (trace) dos agentes a um serviço externo, só com a variável de ativação ligadanão ligadopresente, desligado por padrãonão bloqueia
formatar-arquivo.shPostToolUse Write, Editroda o Prettier se o projeto tivernão existeligadonã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çãoRegraPessoa aprova?EstadoEvidência
Ler códigopermitidonãonão se aplicaautonomia.md:24
Escrever código (classe A)permitidonãoParcial o eixo vale para subagente e só para editar e escrever arquivo; para a sessão é declaradoguarda-de-escrita.mjs:301-316
Commit e push na branch de integraçãopermitidonãoParcial cobrado só com PROCS_BRANCH_INTEGRACAO definidalaco-de-melhoria.mjs:54, 328
Deploysó quando o dono pedesimDeclaradaautonomia.md:27; D-084
Publicar em classe B; alterar o núcleo do upstreamproibido sem aprovaçãosimDeclaradaautonomia.md:28-29
Ler .env ou credencialproibidonão se aplicaParcialguarda-de-comando.sh:89-91; permissions.deny do modelo
Acessar o banco diretoproibidonão se aplicaDeclaradaautonomia.md:31
Excluir dadopede aprovaçãosimParcial reconhecido pelo texto do comandoguarda-de-comando.sh:111-120; D-033
Mexer em infraestruturapede aprovaçãosimDeclarada sem mecanismoD-033
Migração de schema, dependência nova (classe A)age e avisanãoDeclaradaautonomia.md:80-82
Contornar o portão (--no-verify)proibidonão se aplicaEnforced só local; o CI registra e não impedeguarda-de-comando.sh:73-75; portao.yml:7-9
Push com portão vermelhonegadonão se aplicaEnforced só localconformidade-antes-do-push.sh:101-105
Push que reescreve ou apaga referênciapede uma pessoasimEnforced por confirmaçãoguarda-de-comando.sh:101-104
git add -Apede confirmaçãosimEnforcedguarda-de-comando.sh:84-86
Editar os próprios limites (settings, hooks, CLAUDE.md)pede uma pessoasimEnforced no projetoguarda-de-escrita.mjs:238-245
Subagente disparar subagenteproibidonão se aplicaEnforced no projetoguarda-de-escrita.mjs:181-187
Até 3 subagentes; o 4º entra em filapermitidonãoEnforced com falha abertacusto-de-orquestracao.mjs:145-147
2º agente que escreve, sem worktreenegadonão se aplicaEnforcedcusto-de-orquestracao.mjs:150-152
Decidir estrutura sem registroproibidosimParcial o portão cobra o campo de guardaautonomia.md:35
Preencher fato sem fonteproibidonão se aplicaDeclaradaautonomia.md:36-37
Sessão escrever no eixo de outro agentepermitidonãoLembreteguarda-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.

Fonte: DECISOES.md:46; arquivo/DECISOES-superadas.md

Registrar

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 de uma decisão 1. Propostao arquiteto devolve o bloco D-00n 2. Aprovação humanao dono decide; o agente só propõe 3. Registroficha com alternativa descartada e Guardaíndice gerado; portão cobra o campo 4. Consultamapa por assunto, índice, grepdecidido não se rediscute 5. Revisãonunca se apaga: "Superada por D-00n"e vai para o arquivo de superadas nova decisão substitui
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:

  1. revisão de licença antes de qualquer código (bloqueante)
  2. commit do upstream fixado
  3. customização em camada separada
  4. acompanhamento de aviso de segurança, com responsável
  5. 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.
  • 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

  • Portão de presença (D-058)

    Documentadoobservabilidade-e-erro.md:157-166

    ImplementadoNão comprovado

  • Coletor de erro

    Documentadonão documentado

    ImplementadoNão declarado inexistente observabilidade-e-erro.md:115-118

  • Trace dos agentes (D-125, D-128 a D-130)

    Documentadoobservabilidade-e-erro.md §9

    ImplementadoParcial o hook existe e vem desligado; o que está no ar não se prova pelo repositório

  • Retenção de log

    Documentadolacuna declarada observabilidade-e-erro.md:176

    Implementadonão se aplica

Fonte geral: docs/03-seguranca-isolamento/isolamento.md, docs/04-evals/evals.md, docs/05-observabilidade/observabilidade-e-erro.md

As três camadas do portão

Um portão pode morar em três lugares. Hoje só o primeiro impede.

  1. Hook local, na estação. Nega push com portão vermelho e nega --no-verify.
  2. CI no servidor. Roda em push e PR, registra e avisa. Não impede.
  3. Proteção de branch. Ausente: o plano atual do serviço de repositório não a oferece em repositório privado.

Consequência, escrita no próprio workflow: um push vermelho chega à main do mesmo jeito.

Fonte: conformidade-antes-do-push.sh:101-105; guarda-de-comando.sh:73-75; portao.yml:7-9

Camadas de portão git push na estação push sem hook local 1. Hook local conformidade-antes-do-push nega portão vermelho e --no-verify ENFORCED, LOCAL verde segue 2. CI no servidor (portao.yml) roda em push e PR; registra e avisa não impede PARCIAL 3. Proteção de branch: AUSENTE o plano atual do serviço não a oferece em repositório privado branch main: o push vermelho chega aqui
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ê.

Fonte: docs/02-governanca-ia/entrar-no-padrao.md:53

Obrigatórios, nesta ordem

Condicionais

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 0 · Declarar a classeem B: licença antes, bloqueante 1 · Sete arquivos de contextoe o hook que os mede 2 · Ponteiro Visão e escopono CLAUDE.md 3 · Cortar aos tetosarquivando 4 · Instalar a skillprocs-ai-atualiza-gov 4.4 · Rodar o sincronizadorconferir, --apply, portão 5 · Documentaçãoestado-doc.mjs escolhe o verbo 6 · Portão no servidoro CI do portão 7 · Divergênciaregistrada num D-00n só 8 · Só classe Alayout por módulo, task própria --apply só apóso dono ver a lista gatilhos no settingsligados à mão Conforme o projeto .claude/eixos.json PROCS_BRANCH_INTEGRACAO sem tela: sem os agentes de fim trace por projeto
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.