
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Assistentes de IA não têm “memória ruim”. Eles têm  . má governança Você já viu: 
 
 
 
 Você escreveu um guia de arquitetura meticuloso. O modelo o ignora. Você disse “arquitetura de 4 camadas”. Ele produz 3 camadas. Você disse “sem  ”. Ele descarta   como se estivesse fazendo um favor. el-input <el-input v-model="value" /> Isso não é sobre inteligência. É sobre incentivos. No Claude Code, **Habilidades são contexto disponível**, não uma restrição rígida. Se o Claude “sentir” que pode responder sem chamar uma Habilidade, ele o fará. E  . o manual do seu projeto se torna decoração Em nossa equipe, construindo uma base de código RuoYi-Plus com Claude Code, rastreamos isso: 
 
 Sem intervenção, o Claude ativou proativamente as Habilidades do projeto apenas em ~25% do tempo. Portanto, 3 de cada 4 vezes, suas “regras” não são regras. São uma sugestão. Queríamos algo mais rigoroso: um mecanismo que faça o Claude se comportar menos como um estagiário esperto e mais como um engenheiro experiente que lê o manual antes de escrever código. A solução não foi mais prompts. A solução foram os **Hooks**. Após ~1 mês de iteração, lançamos uma pilha de configuração  : .claude 
 
 
 
 
  (governança) 4 hooks de ciclo de vida  (conhecimento) 26 Habilidades de domínio  (orquestração de processos) comandos de barra  (especialistas paralelos) agentes Resultado: 
 
  Menos código violando regras, menos ciclos de “por favor, refaça”, e muito menos ações de ferramenta arriscadas. Ativação de Habilidade para tarefas de desenvolvimento: ~25% → 90%+ Este artigo detalha a arquitetura para que você possa reproduzi-la em seu próprio repositório. 1) Por que o Claude Code “esquece”: Habilidades são opt-in por padrão O fluxo padrão do Claude Code se parece com isto: Prompt do usuário → Claude responde (talvez chame uma Habilidade, talvez não)
 Esse “talvez” é o problema. A heurística de decisão interna do Claude geralmente é: 
 
 
 “Posso responder isso rapidamente sem contexto adicional?” não “Eu   cumprir as regras do repositório?” devo Portanto, o sistema tende para a conveniência. O que você quer é  : um “plano de controle” leve que roda   que o Claude comece a raciocinar e molda o trabalho todas as vezes. atrito institucional antes 2) O avanço: um hook de avaliação forçada de Habilidade Implementamos um hook que dispara no momento mais inicial:  . UserPromptSubmit Ele imprime um pequeno bloco de políticas que o Claude vê   de fazer qualquer outra coisa: antes 
 
 
 
 Avaliar cada Habilidade: sim/não + motivo Se algum “sim”: chamar Habilidade imediatamente Somente então: prosseguir para a implementação O hook “avaliação forçada” (lógica principal) Nós o mantemos deliberadamente simples e determinístico: 
 
 
 detectar comandos de barra (válvula de escape) caso contrário, imprimir o protocolo de avaliação // .claude/hooks/skill-forced-eval.js (ideia principal, simplificada)
const prompt = process.env.CLAUDE_USER_PROMPT ?? "";
​
// Válvula de escape: se o usuário invocou um comando de barra, pular avaliação forçada
const isSlash = /^\/[^\s/]+/.test(prompt.trim());
if (isSlash) process.exit(0);
​
const skills = [
  "crud-development",
  "api-development",
  "database-ops",
  "ui-pc",
  "ui-mobile",
  // ... continuar (temos 26)
];
​
const instructions = [
  "## Protocolo Obrigatório de Ativação de Habilidade (DEVE SEGUIR)",
  "",
  "### Passo 1 — Avaliar",
  "Para CADA habilidade, produza: [habilidade] — Sim/Não — Motivo",
  "",
  "### Passo 2 — Ativar",
  "Se ALGUMA habilidade for Sim → chamar Habilidade(<nome>) imediatamente.",
  "Se TODAS forem Não → declarar 'Nenhuma habilidade necessária' e continuar.",
  "",
  "### Passo 3 — Implementar",
  "Somente após o Passo 2 ser concluído, iniciar a solução real.",
  "",
  "Habilidades disponíveis:",
  ...skills.map(s => `- ${s}`)
].join("\n");
​
console.log(instructions);
 O que muda na prática Antes (sem hook): 
 
 “Construir gerenciamento de cupons.” Claude começa a codificar… e ignora sua arquitetura de 4 camadas ou componentes proibidos. Depois (hook de avaliação forçada): O Claude deve primeiro produzir uma tabela de decisão explícita, depois ativar as Habilidades e, em seguida, implementar. A mudança comportamental é dramática porque você está eliminando a “conformidade opcional”. 3) Por que 90% e não 100%? Porque adicionamos intencionalmente um  . caminho rápido Quando um usuário sabe o que quer, digitar um comando como: 
 
 
 
 /dev construir gerenciamento de cupons /crud b_coupon /check deve ser instantâneo. Portanto, o hook pula a avaliação para comandos de barra e deixa o fluxo de comando assumir. Essa é a troca: 
 
 
 Governança para prompts de forma livre Velocidade para comandos estruturados 4) Hooks como um plano de controle de ciclo de vida (a pilha de 4 hooks) Pense em hooks como um pipeline de CI para uma sessão de agente — exceto que ele roda ao vivo, em seu terminal. Usamos quatro pontos-chave: 4.1 SessionStart: “olhe o repositório antes de falar” Quando uma sessão começa, mostramos: 
 
 
 
 
 branch git atual alterações não commitadas TODOs abertos / status comandos comuns Exemplo de saída: 🚀 Sessão iniciada: RuoYi-Plus-Uniapp
Tempo: 2026-02-16 21:14
Branch: master
​
⚠️ Alterações não commitadas: 5 arquivos
📋 TODO: 3 abertos / 12 concluídos
​
Atalhos:
  /dev    construir funcionalidade
  /crud   gerar módulo
  /check  verificar convenções
  O Claude para de agir como se estivesse entrando em uma sala vazia. Por que importa: 4.2 UserPromptSubmit: avaliação forçada de Habilidade (disciplina) Este é o portão do “tem que 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. É também assim que os acidentes acontecem. PreToolUse é sua última linha de defesa antes que algo seja irreversível. Bloqueamos uma pequena lista negra (e avisamos em uma lista cinza mais ampla): // .claude/hooks/pre-tool-use.js (conceitual)
const cmd = process.env.CLAUDE_TOOL_INPUT ?? "";
​
const hardBlock = [
  /rm\s+(-rf|--recursive).*\s+\//i,
  /drop\s+(database|table)\b/i,
  />\s*\/dev\/sd[a-z]\b/i,
];
​
if (hardBlock.some(p => p.test(cmd))) {
  console.log(JSON.stringify({
    decision: "block",
    reason: "Padrão de comando perigoso detectado"
  }));
  process.exit(0);
}
​
// Opcionalmente: avisar/confirmar sobre ações sensíveis (exclusões em massa, chmod -R, etc.)
 Isso não é paranoia. Já vimos modelos “limparem arquivos temporários” com   no diretório errado. Você quer uma proteção que não dependa do modelo ser cuidadoso. rm -rf 4.4 Stop: “fechar o ciclo” com orientação do próximo passo Quando o Claude termina, nós: 
 
 
 
 resumimos as alterações de arquivos (novos vs. modificados) sugerimos próximas ações (executar testes, atualizações de documentação, commit) opcionalmente acionamos agentes (revisão de código) Exemplo: ✅ Concluído — 8 arquivos alterados
​
Próximos passos:
- @code-reviewer para convenções de backend
- SQL alterado: sincronizar scripts de migração
- Considerar: git commit -m "feat: módulo de cupom"
 O objetivo: eliminar a lacuna “funcionou no chat”. 5) Habilidades: a camada de conhecimento que você pode realmente impor Uma vez que a ativação é determinística, as Habilidades se tornam o que deveriam ser: uma  . base de conhecimento específica do domínio Construímos 26 Habilidades em: 
 
 
 
 
 
 
 backend (CRUD, API, DB, anotações, tratamento de erros) frontend (política de componentes de PC, gerenciamento de estado) mobile (kits de UI, restrições da plataforma uniapp) integrações (pagamentos, WeChat, OSS) qualidade (desempenho, segurança, detecção de bugs) gerenciamento de engenharia (arquitetura, fluxo de trabalho git, decisões técnicas) Uma estrutura de arquivo de Habilidade que escala Cada   segue o mesmo esqueleto: SKILL.md # Nome da Habilidade
​
## Quando acionar
- Palavras-chave:
- Cenários:
​
## Regras principais
### Regra 1
Explicação + exemplo
​
### Regra 2
Explicação + exemplo
​
## Proibido
- ❌ ...
​
## Código de referência
- path/to/file
​
## Checklist
- [ ] ...
 Essa consistência importa porque o modelo aprende como   Habilidades. consumir 6) Comandos: fluxos de trabalho, não sugestões Habilidades resolvem “o que é correto”. Comandos resolvem “qual é o processo”. 6.1  : um pipeline de desenvolvimento de 7 etapas /dev Projetamos   como um fluxo de trabalho opinativo: /dev 
 
 
 
 
 
 
 
 clarificar 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) testar/verificar documentação/atualização de progresso É basicamente: “como seniors querem que juniors trabalhem” codificado como um script executável. 6.2  : gerar um módulo completo a partir de uma tabela /crud Entrada: /crud b_coupon
 Saída (conjunto de exemplo): 
 
 
 
 
 
 Entidade / BO / VO Regras de DAO + wrapper de consulta Serviço + Controlador (sem padrões proibidos) Mapper API frontend + scaffold de página Esforço manual:     Comando:   (mais revisão) 2–4 horas 5–10 minutos 6.3  : linting de convenção full-stack (legível por humanos) /check É aqui que transformamos Habilidades em um verificador: 
 
 
 
 backend: regras de camadas, herança proibida, política de wrapper de consulta frontend: componentes proibidos, uso de wrapper mobile: kit de componentes, unidades, imports 7) Agentes: especialistas paralelos (não sobrecarregue a thread principal) Algumas tarefas devem ser tratadas por um subagente dedicado: 
 
 
 : verificações de convenção com um checklist rigoroso @code-reviewer : atualizar documentos de status, TODOs, métricas de progresso @project-manager A vantagem não é “mais inteligência”. É   e redução da poluição de contexto na sessão principal. separação de preocupações Um padrão prático: 
 
 
 
 
 agente principal gera código hook Stop sugere revisão você invoca  @code-reviewer o revisor retorna um diff estruturado + lista de correções 8) O sistema completo: governança + conhecimento + processo + divisão de trabalho Esta é a arquitetura em uma frase: 
 
 Hooks impõem comportamento, Habilidades fornecem padrões, Comandos codificam fluxos de trabalho, Agentes lidam com expertise paralela. E sim — é assim que você transforma um “assistente de IA geral” em um “colega de equipe nativo do repositório”. 9) Configuração mínima reproduzível (amigável para copiar e colar) Se você quiser a versão menor que ainda funciona, construa isso: .claude/
  settings.json
  hooks/
    skill-forced-eval.js
    pre-tool-use.js
  skills/
    crud-development/
      SKILL.md
  mínimo (hook UserPromptSubmit) settings.json {
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/skill-forced-eval.js"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/pre-tool-use.js"
          }
        ]
      }
    ]
  }
}
 Em seguida, itere: 
 
 
 
 
 
 adicione SessionStart adicione Stop aumente as Habilidades apenas quando você capturar “comportamento incorreto” repetido codifique fluxos de trabalho repetidos como comandos descarregue tarefas de revisão/gerenciamento para agentes Conclusão: “habilidade” não é o gargalo —   é ativação Seu modelo já é capaz. O que falta é um  . sistema que torne o comportamento correto automático Um novo contratado inteligente sem um manual irá improvisar. Um novo contratado inteligente com: 
 
 
 
 
 checklists impostos padrões proibidos claros fluxos de trabalho repetíveis especialistas para revisões e gerenciamento …torna-se consistente rapidamente. Claude é o mesmo.

This story contains AI-generated text. The author has used AI either for research, to generate outlines, or write the text itself. 

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Branch

Read My Stories

Este áudio é produzido no idioma original da história!

Como construir uma camada de governança para o código Claude com ganchos, habilidades e agentes

About Author

COMENTARIOS

Rótulos

ESTE ARTIGO FOI APRESENTADO EM

Related Stories

Vazamento do prompt do sistema Claude Sonnet 3.5: uma análise forense

O guia completo para uma migração bem-sucedida para a nuvem: estratégias e práticas recomendadas

As camadas invisíveis: por que as entrevistas com usuários são um ativo insubstituível

Digital Nomads Ouçam: O que você precisa saber sobre o novo visto DTV da Tailândia

Vazamento do prompt do sistema Claude Sonnet 3.5: uma análise forense

O guia completo para uma migração bem-sucedida para a nuvem: estratégias e práticas recomendadas

As camadas invisíveis: por que as entrevistas com usuários são um ativo insubstituível

Digital Nomads Ouçam: O que você precisa saber sobre o novo visto DTV da Tailândia

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps