O framework "Claude Code Kazuba" transforma Claude Code em um Meta Code Orchestrator — uma IA que nao apenas escreve codigo, mas governa a si mesma atraves de tres camadas: CLAUDE.md diz como pensar, Hooks impedem erros em tempo real, e Rust faz tudo isso sem latencia perceptivel.
[PreToolUse] secrets_scanner: BLOCKED — AWS access key detected in config.py
[PreToolUse] bash_safety: BLOCKED — rm -rf / attempted
[PreToolUse] pii_scanner: WARNING — CPF pattern found in user_data.py
[UserPromptSubmit] cila_router: complexity=L3 → routing=detailed_analysis
pip install claude-code-kazuba
# Instalar preset standard no seu projeto (COMPLEMENTA sua config existente)
kazuba install --preset standard --target /path/to/your/project
# Ver o que sera instalado sem escrever nada
kazuba install --preset professional --target . --dry-run
# Listar presets e modulos disponiveis
kazuba list-presets
kazuba list-modulesgit clone https://github.com/gabrielgadea/claude-code-kazuba.git
cd claude-code-kazuba
pip install -e .
kazuba install --preset standard --target /path/to/your/projectImportante:
kazuba installe um complemento a sua configuracao existente do Claude Code. Ele faz merge de hooks, skills e agents no seu.claude/— nunca substitui ou sobrescreve seus arquivos existentes.
Em 5 segundos, seu projeto Claude Code tem:
| O que voce ganha | Camada responsavel |
|---|---|
| Nenhum secret vai para o git | Hook secrets_scanner (enforcement) |
| Qualidade checada em cada arquivo | Hook quality_gate (enforcement) |
| Contexto persistente entre sessoes | Checkpoints TOON (diretiva) |
| Prompts enriquecidos automaticamente | Hook prompt_enhancer + CILA (enforcement) |
| Stack-aware (Python, Rust, TS, Go...) | Templates Jinja2 (diretiva) |
| Deteccao de padroes em nanosegundos | Aho-Corasick (aceleracao Rust) |
O que acabou de acontecer por baixo e o resultado de tres camadas arquiteturais trabalhando em conjunto. Entenda cada uma delas — e por que a ordem importa.
Claude Code sem Kazuba e uma ferramenta que escreve codigo. Com Kazuba, e um orchestrator que governa a si mesmo — sabe como pensar, e impedido de errar, e faz isso sem friccao.
A arquitetura se organiza em tres camadas, cada uma resolvendo uma limitacao especifica da anterior:
┌─────────────────────────────────────────────────────────┐
│ Layer 1 — CLAUDE.md (Diretiva) │
│ "Como Claude deve pensar e planejar" │
│ Plans as code, Meta-Code-First, CILA taxonomy │
├─────────────────────────────────────────────────────────┤
│ Layer 2 — Hooks (Enforcement) │
│ "O que Claude nao pode fazer" │
│ 16 hooks: secrets, PII, bash, quality, routing │
├─────────────────────────────────────────────────────────┤
│ Layer 3 — Rust (Aceleracao) │
│ "Fazer tudo isso sem que o dev perceba" │
│ 7.137 linhas, Aho-Corasick, PyO3, fallback graceful │
└─────────────────────────────────────────────────────────┘
A ordem nao e acidental. Diretivas definem o comportamento desejado. Enforcement garante que o comportamento real corresponde ao desejado. Aceleracao torna o enforcement invisivel. Remova qualquer camada e o sistema degrada: sem diretivas, os hooks nao sabem o que proteger; sem hooks, as diretivas sao sugestoes ignoraveis; sem Rust, o enforcement vira friccao que o desenvolvedor desliga.
As secoes seguintes examinam cada camada em detalhe.
Antes de interceptar erros, Claude precisa saber como pensar. O CLAUDE.md
instalado pelo Kazuba define regras, principios e templates que orientam cada
decisao do Claude Code — desde a forma de nomear variaveis ate a profundidade de
analise por nivel de complexidade.
Mas o diferencial nao esta nas regras em si. Esta em como elas sao geradas.
O CLAUDE.md do Kazuba define um principio fundamental: "Plans are data, not
documents." E aplica esse principio a si mesmo — o proprio plano de
desenvolvimento do framework e codigo executavel, nao markdown manual.
python scripts/generate_plan.py --output-dir plans/ --validate
# → 24 arquivos markdown + 24 scripts de validacao + orquestradorUm script Python gera programaticamente todas as 24 fases do plano (se o plano for extenso assim), com frontmatter YAML padronizado, cross-references validadas e scripts de validacao por fase. A consequencia direta: mudar o plano significa mudar dados em Python e regenerar — nao cacar inconsistencias em 24 arquivos markdown.
5 camadas de geracao/validacao:
generate_plan.py (Python)
→ gera validate_phase_XX.py (Python que valida codigo)
→ que roda pytest (que valida implementacao)
→ que testa hooks (que validam codigo do usuario)
→ que usam Rust (que valida padroes em O(n))
O que torna esse pattern poderoso e a recursividade: codigo gera codigo que gera codigo que valida codigo. Claude Code opera nao como editor, mas como orquestrador de um plano compilavel — le o gerador, executa-o, implementa os arquivos definidos, roda a validacao, e itera se algo falhar.
| Plano Manual | Plano Code-First (Kazuba) |
|---|---|
| Cada autor formata diferente | Frontmatter YAML por template — zero divergencia |
| Revisao humana, subjetiva | --validate verifica existencia, cross-refs, schemas |
| Editar 24 arquivos, cacar refs | Editar dados Python, regenerar idempotentemente |
git diff em markdown e ruido |
git diff em Python mostra mudanca semantica |
Claude Code como orchestrator (detalhes)
No contexto do Kazuba, o fluxo de trabalho de Claude Code e:
- Le
generate_plan.pypara entender a fase atual - Executa o gerador para criar/atualizar o plano
- Implementa os arquivos definidos em
files_to_create - Roda
validate_phase_XX.pypara verificar completude - Itera se validacao falhar
Cada fase define AgentSpec para subagentes paralelos com worktree isolation.
Cada agente trabalha em branch propria, merge coordenado pelo orquestrador.
A distincao entre "planejar" e "implementar" colapsa — o plano e executavel, a
implementacao e validavel, e a validacao e gerada automaticamente.
Diretivas, porem, sao intencoes declaradas. Nao importa quao preciso o
CLAUDE.md seja — sem um mecanismo de enforcement, diretivas sao sugestoes que
Claude pode ignorar. Por isso a proxima camada existe.
Saber o que fazer nao impede erros — interceptar impede. Os hooks do Kazuba
operam em eventos do Claude Code (PreToolUse, UserPromptSubmit, PostToolUse)
e tomam decisoes em tempo real: bloquear (exit 2), alertar (exit 0 com warning),
ou enriquecer contexto.
Sao 16 hooks organizados em tres modulos, cada um com uma funcao especifica na cadeia de governanca:
4 hooks rodam antes de cada escrita de arquivo e antes de cada comando bash:
[PreToolUse] secrets_scanner: BLOCKED — postgresql://admin:pass@host in config.py
[PreToolUse] bash_safety: BLOCKED — rm -rf with wildcard
[PreToolUse] pii_scanner: WARNING — CPF pattern in user_data.py
[PreToolUse] quality_gate: WARNING — debug print() in production code
Secrets nunca chegam ao git. PII nunca entra no codigo. Comandos destrutivos sao bloqueados. O principio subjacente e fail-open: se um hook falhar internamente (excecao Python, timeout), ele retorna exit 0 — nunca trava o Claude Code.
Enforcement nao e apenas bloqueio. Os hooks de routing classificam cada prompt por complexidade (CILA L0-L6) e intent (8 categorias), injetando tecnicas cognitivas automaticamente:
[UserPromptSubmit] prompt_enhancer: intent=debug → chain_of_thought + few_shot + self_validation
[UserPromptSubmit] cila_router: complexity=L3 (multi-step) → routing=detailed_analysis
A implicacao e que Claude Code nao recebe apenas o prompt do usuario — recebe o prompt enriquecido com a estrategia cognitiva apropriada para aquele tipo de problema. Um debug L2 dispara chain-of-thought; uma refatoracao L4 dispara structured output com constitutional constraints.
Tabela completa: 16 hooks em 3 modulos
| Hook | Evento | Modulo | O que faz |
|---|---|---|---|
| Prompt Enhancer | UserPromptSubmit | hooks-essential | Classifica intent (8 categorias) + injeta tecnicas cognitivas |
| Status Monitor | SessionStart | hooks-essential | Reports env info (Python, git branch, TODOs pendentes) |
| Auto Compact | PreCompact | hooks-essential | Salva checkpoint antes de compactacao de contexto |
| Session State Manager | SessionStart/Stop | hooks-essential | Persistencia de estado entre sessoes |
| Post Compact Reinjector | PreCompact | hooks-essential | Reinjecao de contexto critico pos-compactacao |
| Quality Gate | PreToolUse (Write/Edit) | hooks-quality | Limites de tamanho, debug code, docstrings |
| Secrets Scanner | PreToolUse (Write/Edit) | hooks-quality | Bloqueia API keys, tokens, credenciais |
| PII Scanner | PreToolUse (Write/Edit) | hooks-quality | CPF, CNPJ, SSN, email, telefone (BR/US/EU) |
| Bash Safety | PreToolUse (Bash) | hooks-quality | rm -rf, chmod 777, curl|bash, fork bombs |
| SIAC Orchestrator | PreToolUse | hooks-quality | Quality gates com circuit breaker |
| Validate Hooks Health | Heartbeat | hooks-quality | Health check periodico de todos os hooks |
| CILA Router | UserPromptSubmit | hooks-routing | Classificacao L0-L6 com cache (120s TTL) |
| Knowledge Manager | PreToolUse | hooks-routing | 3-tier: cache local → docs → busca externa |
| Compliance Tracker | PostToolUse | hooks-routing | Audit logging JSONL + compliance scoring |
| Auto Permission Resolver | PreToolUse | hooks-routing | Resolucao automatica de permissoes CILA-aware |
| PTC Advisor | UserPromptSubmit | hooks-routing | Advisor de complexidade CILA L0-L6 |
Skills (11), Agents (3) e Commands (6)
Skills: Code-First Planner, Plan Amplifier, Plan Execution, Verification Loop, Supreme Problem Solver, Eval Harness, Skill Master, Skill Writer, Hook Master, Academic Research Writer, Literature Review.
Agents: Code Reviewer (Sonnet — 4 dimensoes), Security Auditor (Sonnet — OWASP Top 10), Meta Orchestrator (Opus — decide HOOK vs SKILL vs AGENT vs MCP).
Commands:
/debug-RCA, /smart-commit, /orchestrate, /verify, /prp-base-create, /prp-base-execute.
Detalhes em MODULES_CATALOG.md.
Ate aqui, o sistema funciona — diretivas orientam, hooks interceptam. Mas ha uma tensao: cada hook adiciona 50-200ms de latencia em Python puro. Com 16 hooks, o desenvolvedor sente a friccao. E governanca que o desenvolvedor sente e governanca que o desenvolvedor desliga. A terceira camada resolve isso.
O objetivo da camada Rust nao e apenas "ser mais rapido". E tornar a governanca invisivel — enforcement que opera abaixo do limiar de percepcao do desenvolvedor, sem jamais comprometer a seguranca.
A implementacao completa em rust/kazuba-hooks/ oferece fallback graceful para
Python: se Rust nao esta compilado, Python assume. A API e identica; o chamador
nunca sabe qual backend respondeu.
O padrao central e a deteccao em duas fases, que transforma O(n×m) em O(n):
Fase 1: Aho-Corasick pre-filter → scan unico O(n)
Procura keywords rapidos: "api_key", "sk-", "ghp_", "-----BEGIN"
Se NENHUM keyword → return [] (zero-cost exit)
Fase 2: RegexSet confirmation → so executa se Fase 1 detectou algo
9 padroes precisos confirmam o match
A razao por que isso importa: a maioria dos arquivos nao contem segredos.
A Fase 1 elimina 95%+ dos arquivos em tempo linear, sem jamais invocar o motor
de regex. Em um projeto com 500 arquivos, ~475 sao descartados por Aho-Corasick
(nanosegundos) em vez de testados por 9 regexes cada. O mesmo padrao two-phase
se repete em bash_safety.rs, skill_match.rs e knowledge.rs.
| Modulo | Linhas | Funcao | Algoritmo |
|---|---|---|---|
rlm_reasoning.rs |
930 | Chain/Tree/Graph-of-Thought | Validacao estrutural de raciocinio |
lib.rs (bindings) |
892 | 25 funcoes PyO3 exportadas | Ponte Python-Rust completa |
learning.rs |
843 | TD(lambda) + Working Memory | Rayon parallel similarity search |
qa.rs |
843 | Issue categorization + ROI | Aho-Corasick batch matching |
knowledge.rs |
686 | Knowledge engine + patterns | Multi-signal scoring |
recovery.rs |
672 | Error-recovery strategies | 10 strategies com auto-apply |
bash_safety.rs |
571 | Validacao de comandos shell | LazyLock + Aho-Corasick O(n) |
subagent.rs |
562 | Skill injection SubagentStart | Category-weighted injection |
code_quality.rs |
321 | Anti-pattern detection | RegexSet multi-pattern |
patterns.rs |
291 | Utilities compartilhados | Aho-Corasick builders |
skill_match.rs |
280 | Hybrid skill matching | 0.6 semantic + 0.4 Aho-Corasick |
secrets.rs |
192 | Deteccao de credenciais | Two-phase: Aho-Corasick + Regex |
Alem de velocidade: o que Rust torna possivel
-
Property Testing com Proptest —
bash_safety.rserecovery.rsusam proptest para gerar inputs aleatorios e verificar que o validator nunca crashe. Fuzzing em tempo de compilacao. -
Rayon para Similarity Search —
learning.rsusapar_iter()para busca paralela em embeddings. Cada core do CPU processando fatias diferentes do vetor de memoria. -
Zero-allocation hot path — Aho-Corasick em Rust opera sem alocacao de heap no caminho principal. Cada match e uma referencia a memoria pre-alocada.
-
Fallback Graceful —
claude_code_kazuba/rust_bridge.pyimplementa o contrato@fail_open:try: result = _rust_check_secrets(content, file_path) if self._use_rust else _python_check_secrets(content) except Exception: result = _python_check_secrets(content) # fallback silencioso
O resultado carrega
backend: "rust" | "python"para observabilidade. -
151 testes nativos + Criterion benchmarks — secrets detection, code quality, bash safety, e no-match fast path.
Quando as tres camadas convergem, algo emerge que nenhuma delas produz sozinha.
As tres camadas nao sao independentes — se amplificam mutuamente. A camada diretiva define que cada hook deve ter implementacao Python e aceleracao Rust opcional. O gerador code-first produz o skeleton de ambos. Os hooks de enforcement validam que o fallback funciona. O benchmark mode comprova que Rust e mais rapido.
generate_plan.py define Phase(files_to_create=["rust/kazuba-hooks/src/new_module.rs"])
→ Claude Code implementa o modulo Rust
→ PyO3 bindings exportam para Python
→ rust_bridge.py detecta automaticamente
→ validate_phase_XX.py confirma fallback funcional
→ Criterion benchmark registra speedup
O resultado e um sistema que se auto-hospeda: o framework e construido com as mesmas ferramentas que oferece. Os hooks que protegem o codigo do usuario protegem o codigo do framework. O plano que gera as fases de desenvolvimento e validado pelos mesmos scripts que ele gera. O principio meta-code-first nao e uma diretriz — e uma propriedade emergente da convergencia das tres camadas.
Portanto, o que o desenvolvedor experimenta na pratica nao sao tres camadas separadas — e uma unica experiencia: instalar, usar, e ter governanca invisivel. As secoes seguintes mostram como isso se materializa.
Cada preset e uma selecao curada de modulos, resolvida por topological sort com base nas dependencias declaradas:
| Preset | Modulos | Ideal para |
|---|---|---|
| minimal | 1 | Templates e regras basicas |
| standard | 5 | Desenvolvimento diario + prompt enhancement |
| research | 6 | Projetos academicos com skills de pesquisa |
| professional | 10 | Engenharia completa com quality gates e agents |
| enterprise | 14 | Orquestracao multi-agente + hypervisor + compliance |
Para ver as tres camadas em acao, examples/ contem projetos-demo com cenarios
de antes/depois:
python-api/— FastAPI:secrets_scannerbloqueiapostgresql://admin:Secret123@prod.dbrust-cli/— CLI Rust:bash_safetybloqueiachmod 777erm -rfcom wildcardtypescript-web/— Next.js:pii_scannerdetecta email/CPF emconsole.log()de API routes
claude-code-kazuba/
├── rust/kazuba-hooks/ # Layer 3: 7.137 linhas, 12 modulos, 25 PyO3 bindings
├── lib/ # Shared: 8 modulos (hook_base, patterns, config, rlm, ...)
├── core/ # Layer 1: Templates Jinja2 + rules universais
├── modules/ # Layer 2: 15 modulos opcionais
│ ├── hooks-essential/ # Prompt enhancer, status monitor, auto compact
│ ├── hooks-quality/ # Secrets, PII, bash safety, quality gate, SIAC
│ ├── hooks-routing/ # CILA router, knowledge manager, compliance
│ ├── skills-*/ # Dev, meta, planning, research (11 skills)
│ ├── agents-dev/ # Code reviewer, security auditor, meta-orchestrator
│ ├── commands-*/ # 6 slash commands (debug-RCA, verify, smart-commit, ...)
│ └── ... # hypervisor, contexts, team-orchestrator, rlm
├── scripts/ # Meta-Code-First: generate_plan.py (3.676 linhas)
├── examples/ # Projetos-demo (Python, Rust, TypeScript)
├── install.sh # Legacy one-command installer (backward compat)
└── tests/ # 1577 testes (phase_00 → phase_22 + integration_v2 + CLI)
| Principio | Como se manifesta |
|---|---|
| Fail-Open | Hooks nunca crasham o Claude Code — erro interno = exit 0 |
| Zero Config | pip install claude-code-kazuba && kazuba install --preset standard e tudo que voce precisa |
| Composable | Cada modulo e independente com dependencias explicitas |
| TDD | 90% coverage per file (nao media), todos os hooks testados |
| Type-Safe | Pydantic v2 para configs, pyright strict para claude_code_kazuba/ |
| Checkpoint | TOON format (msgpack + header) para recovery de estado |
A credibilidade de um framework de governanca se mede pela propria disciplina. O Kazuba aplica a si mesmo o que exige dos projetos que protege:
============================= 1577 passed in 3.01s =============================
| Metrica | Valor |
|---|---|
| Testes Python | 1577 (723 v0.1.0 + 844 v0.2.0 + 10 CLI) |
| Testes Rust nativos | 151 |
| Coverage (claude_code_kazuba/) | 97% |
| Coverage target | 90% per file |
| Lint (ruff) | 0 errors |
| Types (pyright strict) | 0 errors |
| CI | GitHub Actions (lint + typecheck + test) |
| Documento | Descricao |
|---|---|
| ARCHITECTURE.md | Design completo, estrutura, algoritmos, decisoes |
| HOOKS_REFERENCE.md | Todos os 18 eventos de hook com JSON schemas |
| MODULES_CATALOG.md | Catalogo completo com dependencias e presets |
| CREATING_MODULES.md | Guia para criar modulos customizados |
| MIGRATION.md | Migracao para usuarios com .claude/ existente |
| GLOSSARY.md | Terminologia: Kazuba, CILA, TOON, RLM, presets |
- Shared Infrastructure — CircuitBreaker, TraceManager, HookLogger, EventBus
- Rust Acceleration Layer — 7.137 linhas, 12 modulos, 25 PyO3 bindings, two-phase Aho-Corasick
- Core Governance + CILA Formal — Taxonomia CILA L0-L6, StrategyEnforcer, governance rules
- Agent Triggers + Recovery — Dispatch declarativo e escalacao automatica
- Hypervisor Executable — Hypervisor, HypervisorV2, HypervisorBridge
- Advanced Hooks Batch 1 — SessionStateManager, PostCompactReinjector, ValidateHooksHealth
- Advanced Hooks Batch 2 — SiacOrchestrator, AutoPermissionResolver, PtcAdvisor
- RLM Learning Memory — QTable, WorkingMemory, SessionManager, RewardCalculator, facade
- Meta-Code-First Planner — 3.676 linhas gerando 24 fases com validacao automatica
- Integration + Migration — E2E tests, migrate_v01_v02.py, MIGRATION.md
- Benchmark Suite — benchmark_hooks.py CLI + self_host_config.py
- GPU Acceleration — Embeddings e similarity via CUDA/Metal
- Multi-tenant Isolation — Isolamento de contexto por workspace
- Web Dashboard — Visualizacao de metricas de hooks em tempo real
- Criterion Benchmarks Publicados — Rust vs Python speedup numbers
# Setup
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Quality gate completo
pytest tests/ --cov=claude_code_kazuba --cov-report=term-missing
ruff check lib/ scripts/ tests/
ruff format --check lib/ scripts/ tests/
pyright lib/
# Rust (opcional — requer rustup + maturin)
cd rust/kazuba-hooks && cargo test && cargo bench
maturin develop --features pyo3-bindings- Fork o repositorio
- Crie uma branch (
git checkout -b feature/my-module) - Escreva testes primeiro (TDD, 90% coverage por arquivo)
- Implemente as mudancas
- Rode o quality gate:
ruff check && ruff format --check && pyright lib/ && pytest tests/ - Abra um Pull Request
Veja CREATING_MODULES.md para o guia completo.
MIT License. Veja pyproject.toml para detalhes.
Construido com o proprio principio meta-code-first: o plano e codigo, a validacao e gerada, e a governanca nao custa latencia.