Como Construir uma Camada de Governança para Claude Code com Hooks, Skills e Agentes
Assistentes de IA não têm “memória ruim”. Eles têm uma má governança.
Você já viu isso:
- Você escreveu um guia de arquitetura meticuloso. O modelo ignora.
- Você disse “arquitetura de 4 camadas”. Ele produz 3 camadas.
- Você disse “sem el-input”. Ele solta <el-input v-model=”value” /> como se estivesse fazendo um favor.
Isso não se trata de inteligência. É uma questão de incentivos.
No Claude Code, Skills são um contexto disponível, não uma restrição rígida. Se Claude “sente” que pode responder sem chamar uma Skill, ele o faz. E seu manual do projeto se torna decoração.
Em nossa equipe, ao construir uma base de código RuoYi-Plus com Claude Code, rastreamos isso:
- Sem intervenção, Claude ativava proativamente Skills de projeto apenas ∼25% das vezes.
Portanto, 3 em cada 4 vezes, suas “regras” não são regras. Elas são uma sugestão.
Precisávamos de algo mais rigoroso: um mecanismo que fizesse Claude se comportar menos como um estagiário inteligente e mais como um engenheiro que lê o manual antes de escrever código.
A solução não era mais prompting.
A solução eram os Hooks.
Após ∼1 mês de iteração, lançamos uma pilha de configuração .claude:
- 4 hooks de ciclo de vida (governança)
- 26 Skills de domínio (conhecimento)
- comandos de barra (orquestração de processos)
- agentes (especialistas paralelos)
Resultado:
- Ativação de Skills para tarefas de desenvolvimento: ∼25% → 90%+ Menos código que viola regras, menos ciclos de “por favor, refaça” e muito menos ações de ferramenta arriscadas.
1) Por que o Claude Code “esquece”: Skills são opt-in por padrão
O fluxo padrão do Claude Code é o seguinte:
- Prompt do usuário → Claude responde (pode chamar uma Skill, pode não chamar)
Esse “pode” é o problema.
A heurística interna de decisão do Claude geralmente é:
- – “Posso responder isso rapidamente sem contexto extra?”
- – não “Devo cumprir as regras do repositório?”
Portanto, o sistema tende à conveniência.
O que você quer é uma fricção institucional: um “plano de controle” leve que funcione antes que Claude comece a raciocinar e molde o trabalho toda vez.
2) A descoberta: um hook de avaliação de Skill forçada
Implementamos um hook que é acionado no primeiro momento: UserPromptSubmit.
Ele imprime um breve bloco de política que Claude vê antes de fazer qualquer outra coisa:
- – Avaliar cada Skill: sim/não + motivo
- – Se qualquer “sim”: chamar Skill imediatamente
- – Só então: prosseguir para a implementação
O “hook de avaliação forçada” (lógica central)
Mantemos isso deliberadamente simples e determinístico:
- – detectar comandos de barra (saída de emergência)
- – caso contrário, imprimir o protocolo de avaliação
3) Por que 90% e não 100%?
Porque intencionalmente adicionamos um caminho rápido.
Quando um usuário sabe o que quer, digitar um comando como:
- – /dev build coupon management
- – /crud b_coupon
- – /check
deve ser instantâneo. Portanto, o hook pula a avaliação para comandos de barra e deixa o fluxo de comandos assumir.
Essa é a troca:
- – Governança para prompts livres
- – Velocidade para comandos estruturados
4) Hooks como um plano de controle de ciclo de vida (a pilha de 4 hooks)
Pense nos hooks como um pipeline de CI para uma sessão de agente — exceto que roda ao vivo, no seu terminal.
Usamos quatro pontos-chave:
4.1 Início da Sessão: “olhe para o repositório antes de falar”
Quando uma sessão começa, mostramos:
- – branch git atual
- – mudanças não confirmadas
- – TODOs abertos / status
- – comandos comuns
4.2 UserPromptSubmit: avaliação forçada de Skill (disciplina)
Esse é o portão “deve ler o manual”.
4.3 PreToolUse: a camada de segurança (governança de ferramentas)
Claude Code é poderoso porque pode executar ferramentas: Bash, escrever arquivos, editar código.
Isso também é como acidentes acontecem.
PreToolUse é sua última linha de defesa antes de algo irreversível.
4.4 Stop: “fechar o ciclo” com orientação sobre os próximos passos
Quando Claude termina, nós:
- – resumimos as mudanças de arquivo (novos vs modificados)
- – sugerimos ações seguintes (executar testes, atualizar docs, confirmar)
- – opcionalmente acionamos agentes (revisão de código)
5) Skills: a camada de conhecimento que você pode realmente impor
Uma vez que a ativação é determinística, Skills se tornam o que deveriam ser: uma base de conhecimento específica do domínio.
Construímos 26 Skills em diversas áreas:
- – backend
- – frontend
- – mobile
- – integrações
- – qualidade
- – gerenciamento de engenharia
6) Comandos: fluxos de trabalho, não sugestões
Skills resolvem “o que é correto”.
Comandos resolvem “qual é o processo”.
6.1 /dev: um pipeline de desenvolvimento de 7 etapas
Projetamos /dev como um fluxo de trabalho opinativo:
- esclarecer requisitos
- design (API + módulos + permissões)
- design do banco de dados (SQL + dicionários + menus)
- backend (saída de 4 camadas)
- frontend (política de componentes + roteamento)
- teste/verify
- docs/atualização de progresso
6.2 /crud: gerar um módulo completo a partir de uma tabela
Entrada:
/crud b_coupon
Saída (exemplo):
- – Entidade / BO / VO
- – DAO + regras de wrapper de consulta
- – Serviço + Controlador (sem padrões proibidos)
- – Mapper
- – API frontend + esqueleto de página
6.3 /check: linting de convenções full-stack (legível por humanos)
Aqui transformamos Skills em um verificador:
- – backend: regras de camadas, herança proibida, política de wrapper de consulta
- – frontend: componentes banidos, uso de wrappers
- – mobile: kit de componentes, unidades, importações
7) Agentes: especialistas paralelos (não sobrecarregue o thread principal)
Algumas tarefas devem ser tratadas por um subagente dedicado:
- – @code-reviewer: verificações de convenção com uma lista de verificação rigorosa
- – @project-manager: atualizar docs de status, TODOs, métricas de progresso
8) O sistema completo: governança + conhecimento + processo + divisão do trabalho
Esta é a arquitetura em uma frase:
Hooks impõem comportamento, Skills fornecem padrões, Comandos codificam fluxos de trabalho, Agentes lidam com especialização paralela.
9) Configuração mínima reprodutível (amigável para copiar-colar)
Se você quiser a menor versão que ainda funcione, construa isso:
.claude/
settings.json
hooks/
skills/
Fechamento: “habilidade” não é o gargalo — ativação é
Seu modelo já é capaz.
O que falta é um sistema que torne o comportamento correto automático.
