Conteúdo detalhado
🪧 Regra = sugestão forte (não determinística)
Uma regra é uma sugestão forte ao modelo — não uma garantia. É a placa "não entre" na beira da estrada: a maioria respeita, mas nada impede fisicamente quem decidir entrar. Regras são não-determinísticas: o modelo as segue na maior parte das vezes, mas pode escorregar, sobretudo no fundo de uma conversa longa.
🌱 Novo aqui?
Determinístico = sempre acontece igual, sem depender de julgamento. Não-determinístico = depende do modelo "decidir" na hora, então varia. Uma regra escrita no CLAUDE.md é não-determinística: é texto que influencia, não código que obriga.
💡 Quando uma regra basta
Para preferências e bom senso — "prefira tabelas a parágrafos", "use sempre tom formal com clientes" — a regra é perfeita: barata, flexível e fácil de ajustar. O problema é confiar nela onde um deslize custa caro.
Por que aprender
Porque saber que regra é "mole" calibra a confiança certa. Você para de tratar todo limite como inquebrável e reserva a artilharia pesada (ganchos) para o que realmente não pode falhar. Entender essa distinção é o coração da camada de cercas.
Conceitos-chave
🔒 Gancho = determinístico (sempre/nunca)
Um gancho (hook) é determinístico: ele sempre faz ou nunca deixa fazer, sem depender do julgamento do modelo. É a porta trancada — não importa o quão fundo na conversa o OS esteja, o gancho dispara igual. "Nunca me deixe enviar um e-mail com minha certidão de nascimento anexada" vira gancho, não regra.
Como ler: a mesma ação arriscada (seta vermelha) bate nas duas cercas. Na regra (cerca tracejada) ela pode vazar; no gancho (porta sólida trancada) ela é bloqueada toda vez. Por isso o que dói de verdade vira gancho.
Por que aprender
Porque a diferença regra/gancho é a decisão de segurança mais importante do OS. PII, dinheiro e escrita em banco não podem depender de o modelo "lembrar" — precisam de um mecanismo que dispara sempre. Saber traduzir um limite em gancho é o que torna o OS seguro o suficiente para usar de verdade.
Conceitos-chave
📑 Graduar o CLAUDE.md inchado pra rules/
Lembra da disciplina do Módulo 2.1 — manter o CLAUDE.md enxuto? Quando ele começa a inchar de "sempre faça X / nunca faça Y", é hora de graduar essas linhas para uma pasta rules/ dedicada. A identidade fica curta; as regras ganham um lar organizado em rules/always.md e rules/never.md.
📗 rules/always.md
O que o OS deve sempre fazer.
- ✓"Sempre converter valores para CAD."
- ✓"Sempre citar a fonte da política."
📕 rules/never.md
O que o OS nunca deve fazer.
- ✗"Nunca misturar despesa pessoal com a do negócio."
- ✗"Nunca prometer algo fora do playbook."
💡 Graduar é mover, não duplicar
Ao mover uma regra para rules/, tire-a do CLAUDE.md e deixe lá só um ponteiro ("consulte rules/"). Duplicar é o caminho mais rápido para regras que se contradizem.
Por que aprender
Porque é assim que a base cresce sem virar bagunça: a identidade permanece enxuta e as regras viram um conjunto auditável. Separar always de never também deixa explícito o que é "sempre" — candidato a virar gancho determinístico.
Conceitos-chave
⚡ Reflex hooks: bloquear PII no push
O caso mais clássico de gancho é o reflex hook (gancho de reflexo): um mecanismo que dispara na hora diante de um gatilho perigoso. O exemplo do autor: se você tenta subir algo para o GitHub com PII — número de identidade (SIN), cartão de crédito — o reflexo bloqueia imediatamente e você vê "ação bloqueada".
🌱 Novo aqui?
PII (Personal Identifiable Information) é qualquer dado que identifica você: CPF/SIN, número de cartão, certidões. Push pro GitHub = enviar seus arquivos para um repositório remoto na nuvem. Juntando os dois: um push com PII pode vazar dados sensíveis publicamente — exatamente o que o reflex hook impede de acontecer.
🛟 Reflexo, não memória
A graça do reflexo é não depender de o modelo lembrar. Mesmo que o OS "esqueça" a regra no fundo de uma sessão longa, o gancho continua de guarda. É a diferença entre pedir cuidado e garantir cuidado.
Por que aprender
Porque os erros mais caros são os silenciosos — um vazamento de PII que você só descobre depois. Um reflex hook transforma "espero que não aconteça" em "não pode acontecer". É a camada que deixa o OS seguro para tarefas reais com dados sensíveis.
Conceitos-chave
⚙️ settings.json: banir comandos de escrita
O harness traz, pronto de fábrica, um arquivo settings.json. É ali que você cria ganchos de permissão: peça ao Claude Code para banir comandos de escrita — por exemplo, nunca escrever numa tabela específica do banco — salvo override explícito. Ele adiciona esses comandos a uma lista de bloqueio do Bash, e pronto: a escrita perigosa fica proibida por padrão.
🌱 Novo aqui?
O Bash é o terminal por onde o OS executa comandos no seu computador. O settings.json tem uma seção permissions.deny que recusa certos comandos antes de rodarem. Override = uma exceção que só você libera de propósito. Assim, o padrão é seguro e o risco só existe quando você decide.
✓ Padrão seguro
- ✓Escrita em tabelas sensíveis: negada.
- ✓Comandos destrutivos do Bash: na lista de bloqueio.
- ✓Você libera caso a caso, com intenção.
✗ Sem o gancho
- ✗Um comando errado no fundo do contexto apaga dados.
- ✗Você confia que o modelo "não vai fazer".
- ✗O erro só aparece quando já é tarde.
Por que aprender
Porque o settings.json é o lugar onde "nunca escreva aqui" deixa de ser texto persuasivo e vira regra de máquina. É o gancho mais fácil de instalar e um dos de maior retorno: protege seus dados de um único comando descuidado.
Conceitos-chave
🔍 Pre-commit hook de PII
Um irmão do reflex hook é o pre-commit hook: um verificador que roda antes de cada commit e dá uma última conferida. O uso do autor: toda vez que algo vai ser enviado ao GitHub, o pre-commit checa duas vezes se não há nada específico dele — PII — naquele conteúdo. Se houver, o commit é barrado.
Como ler: todo commit passa pelo verificador (ciano). Arquivo limpo segue para o GitHub (verde); arquivo com PII é barrado (vermelho) e devolvido. O backup acontece — mas só do que é seguro.
Por que aprender
Porque você vai querer versionar e fazer backup do OS no GitHub (Trilha 5), e backup sem guarda é uma porta de vazamento. O pre-commit de PII é o gancho que deixa você ter backup tranquilo: ele garante que o sensível nunca cruza a fronteira — combinando com o .gitignore do que é privado.
Conceitos-chave
🧪 Done-check: pior erro → never-rule + 1 reflexo
O critério de pronto desta camada é simples e poderoso: pense no pior erro possível do seu domínio e garanta que ele esteja escrito como uma never-rule clara em rules/never.md — e que você tenha identificado pelo menos 1 reflexo automático (gancho) para o que dói mais.
✅ O done-check em 3 passos
Nomeie o pior erro: "o que, se acontecesse, eu não conseguiria desfazer ou defender?".
Escreva-o como never-rule clara em rules/never.md (texto, a cerca mole).
Reforce com 1 reflexo determinístico (settings.json ou pre-commit) — a porta trancada.
⚠️ O erro de parar na regra
Escrever a never-rule e achar que terminou é a armadilha. Regra é sugestão; se o pior erro é irreversível, ele precisa de um reflexo determinístico em cima. Regra + reflexo = a cerca dupla que de fato segura.
Por que aprender
Porque é um critério acionável que você aplica em qualquer domínio em 5 minutos. Ele força a pergunta certa ("o que não pode falhar?") e a resposta na dose certa (texto para o resto, gancho para o irreversível). É exatamente o done-check que o /os-coach cobra na Trilha 4.
Conceitos-chave
⚡ Prático: settings.json com deny de escrita
Hora de instalar uma porta trancada de verdade. Abaixo está um .claude/settings.json copy-run: ele nega comandos de escrita/destrutivos do Bash (gancho de permissão) e adiciona um PreToolUse hook que bloqueia escritas no banco salvo override. Troque só os trechos entre <colchetes>.
🎯 Objetivo
Sair desta seção com um gancho determinístico real: o OS fisicamente recusa comandos de escrita perigosos, sem depender de "lembrar" da regra.
Salve em .claude/settings.json — copy-run
json{
"permissions": {
"deny": [
"Bash(rm:*)",
"Bash(git push:*)",
"Bash(psql:*)",
"Bash(sqlite3:*)",
"Bash(<sua-cli> write:*)",
"Bash(<sua-cli> delete:*)"
]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' | grep -qiE '(INSERT|UPDATE|DELETE|DROP|TRUNCATE).*<tabela_sensivel>' && [ \"$ALLOW_DB_WRITE\" != \"1\" ] && { echo 'Escrita no banco bloqueada (gancho). Use ALLOW_DB_WRITE=1 para override.' >&2; exit 2; } || exit 0"
}
]
}
]
}
}
✔️ Como verificar
- 1.Peça ao OS para rodar um git push ou um rm — deve ser recusado pela lista deny.
- 2.Peça um comando que escreve na <tabela_sensivel> — o PreToolUse hook deve barrar com a mensagem (exit 2).
- 3.Repita com ALLOW_DB_WRITE=1 no ambiente — agora passa (override explícito funcionando).
- 4.Um SELECT (leitura) NÃO é bloqueado — o gancho mira só escrita.
💡 Por que isto é um gancho, não uma regra
Nada aqui depende do modelo "decidir" obedecer: o deny e o exit 2 do hook são código que dispara antes do comando rodar. É a porta trancada do Tópico 2, agora em arquivo. Exemplo ilustrativo — ajuste os comandos e o padrão ao seu harness e banco.
Por que aprender
Porque transforma toda a teoria das cercas em proteção real, em minutos. Com este arquivo você já tem o "1 reflexo" do done-check do Tópico 7 — e a base pronta para os OS de produção da Trilha 5, onde dinheiro e dados sensíveis tornam isto obrigatório.
Conceitos-chave
✅ Resumo do módulo
Concluiu a base do OS!
Com Identidade, Substrato e Cercas prontos, a próxima trilha dá capacidade: Habilidades, Ferramentas e Agentes. → Trilha 3 · Técnica II 🤖