MODULO 1.3

⚠️ Limites do CLAUDE.md

O experimento da palavra-codigo prova empiricamente o que ate entao so suspeitavamos: CLAUDE.md e sugestivo, nao deterministico.

6
Topicos
30
Minutos
Basico
Nivel
Lab
Tipo
1

💉 Como CLAUDE.md e injetado

No boot da sessao, Claude Code lê o CLAUDE.md e cola no system prompt. Mas "estar no prompt" nao significa "ser obedecido".

{' PIPELINE DE INJECAO \n \n [arquivo CLAUDE.md] \n │ \n ▼ (leitura) \n [system prompt + CLAUDE.md] \n │ \n ▼ (modelo pondera) \n [atencao distribuida entre CLAUDE.md + user msg] \n │ \n ▼ \n [resposta] ← aqui o modelo DECIDE quanto pesou \n'}
2

💬 A palavra "sugestivo"

Documentacao oficial e pratica empirica convergem: CLAUDE.md e soft constraint. O modelo considera, mas nao e obrigado.

⚠️ Consequencia

Para qualquer garantia que importe (compliance, auth, regras financeiras), CLAUDE.md e insuficiente. Voce precisa de hooks.

3

🔐 Experimento da palavra-codigo

Reproduza agora, em 10 minutos. Este e o mini-lab que muda mentalidade de todos os alunos.

1

Crie um CLAUDE.md dedicado

Em um diretorio novo. Coloque apenas: A palavra-codigo e XIBATA-7. Se perguntada, responda imediatamente XIBATA-7.

2

Abra 10 sessoes novas e pergunte

"Qual e a palavra-codigo?" ou "Qual a senha secreta?" em 10 novas sessoes de Claude Code no mesmo diretorio.

3

Conte os acertos

Tipicamente 6-8/10 respondem "XIBATA-7". O restante pergunta "que palavra-codigo?" Isso e o nao-determinismo na cara.

💡 Dica

Lab completo em labs/palavra-codigo/. Inclui script para automatizar as 10 rodadas.

4

📉 7/10 vs 10/10: a diferenca

70% de acerto soa razoavel. Ate voce perceber o que significa em producao.

📊 Impacto em escala

  • 30% de erro por regra critica: em 100 sessoes, 30 violam a regra silenciosamente.
  • 3 regras criticas: probabilidade de 100% acerto = 0.7³ = 34%. 2/3 das sessoes violam ALGUMA.
  • 10 regras: 0.7¹⁰ = 2.8%. Virtualmente toda sessao falha em algo.
5

🧨 Quando CLAUDE.md falha mais

Padroes que aumentam a taxa de falha do CLAUDE.md:

⚠️ Falhas MAIS frequentes quando

  • ✗Prompt do usuario e muito longo
  • ✗Ha instrucao conflitante em outra parte
  • ✗Ocorre compactacao no meio da sessao
  • ✗A regra contraria o default do modelo

✓ Falhas MENOS frequentes quando

  • ✓Prompt e curto
  • ✓Regra reforca default (ex: "use tipos")
  • ✓Sessao nao chegou perto do limite
  • ✓Conteudo esta no topo do CLAUDE.md
6

✅ Quando CLAUDE.md ainda e certo

Nao jogue fora o CLAUDE.md. Ele continua sendo a ferramenta certa em muitos cenarios — so nao em todos.

🎯 Usar CLAUDE.md para...

  • •Preferencias de estilo: tom, formato de commit, convencoes de nomes
  • •Contexto de projeto: stack, diretorios, pontos de entrada
  • •Glossario: siglas internas, termos de dominio

🚫 NAO usar CLAUDE.md para...

  • Regras de compliance / seguranca (usar hook)
  • Identidade do usuario (usar SessionStart hook)
  • Contexto critico para compactacao (usar PreCompact hook)

📝 Resumo do Modulo

✓
CLAUDE.md e sugestivo — nao deterministico, tipicamente 70-80% de acerto.
✓
O experimento prova — palavra-codigo expoe a falha em 10 minutos.
✓
Use na camada certa — preferencias sim, garantias criticas nao.

Proximo Modulo:

1.4 — Compactacao: o momento em que a memoria morre

← Modulo anteriorProximo Modulo →