Claude Guardrails
teddyoomz/claude-guardrails
Regras auditáveis e continuidade entre sessões para projetos Claude
Ver no GitHubSkill de aplicação de regras universais para projetos assistidos por Claude, com continuidade entre sessões e auditoria por grep. Inclui templates de rules, skills de auditoria, hooks pré-commit e protocolo de handoff de sessão para manter a consistência do projeto sem compressão de contexto.
Instalação
npx convez-ai teddyoomz/claude-guardrails1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Enforçar padrões de código e arquitetura em projetos com IA
- Manter continuidade de regras entre múltiplas sessões Claude
- Auditar violações de regras e rastrear bugs sistemáticos
- Automatizar verificações pré-commit e gates de qualidade
Veredito

Abordagem rigorosa e prática contra drift de IA em equipes. Prioriza auditoria grep-nativa e templates versionáveis em vez de resumos com perda de contexto. Útil para times que precisam de rastreabilidade forte, mas exige disciplina na manutenção das regras.
README
A tradução para o português deste README ainda está na fila.
claude-guardrails
Universal rule enforcement for any Claude-assisted project. Grep-auditable. No AI compression. Strict cross-session continuity. Violation catalog grows from real bugs — not hypothetical best practices.
Designed to be git clone'd into every new project you start with Claude.
Rules, audits, session-handoff protocol — all stack-agnostic, all template-based.
You fill in the [FILL-IN] placeholders once per project, and the methodology
enforces itself across every session afterwards.
Why
AI coding assistants drift. Rules you told them last week get quietly re-interpreted this week. Memory tools that "summarize your project" make this worse — they compress your iron-clad rules into fuzzy summaries that grep can't find and audits can't verify.
claude-guardrails is the opposite approach:
- Rules live in plain markdown files, numbered, greppable.
- Every rule carries an anti-example — a real bug that motivated it.
- Every bug adds a new audit invariant to a skill file you can grep.
- No summarization, no vector DB, no background worker.
- Checked into your repo → team-enforced, not per-user.
What you get
your-project/
├── .claude/
│ ├── rules/ ← 5 rule files (iron-clad, workflow, stack, culture)
│ ├── skills/ ← Audit + meta skills with numbered invariants
│ │ ├── audit-anti-vibe-code/ ← Rule-of-3, crypto, orphan collections
│ │ ├── audit-rules/ ← Lint the rule files themselves (LR1-LR10)
│ │ ├── audit-health/ ← Methodology adoption dashboard (H1-H10)
│ │ ├── capability-scout/ ← Classify a task → Tier 1-5 (CS1-CS8)
│ │ ├── research-gap/ ← 5-tier research before guessing (RG1-RG8)
│ │ ├── skill-autoinstall/ ← Find + install skill/tool/MCP (SA1-SA7)
│ │ ├── skill-relevant/ ← File path → skill recommendations (SR1-SR7)
│ │ └── _template/ ← Starter for new skills (evidence required)
│ ├── hooks/ ← Pre-commit grep-pair verifier (shell script)
│ └── settings.template.json ← 6 hooks: PostToolUse × 2 / PreToolUse / SessionStart / UserPromptSubmit × 2
├── .agents/
│ ├── AGENTS.md ← Trust priority (rules always win on conflict)
│ ├── active.md ← Hot-state for next session
│ └── sessions/ ← Session checkpoints with resume prompts
└── docs/
├── methodology.md ← How to write rules that don't drift (6 principles)
├── growth-engine.md ← The 4 compounding mechanisms — Engines 1-4
├── violation-log.md ← Catalog of past bugs + lessons
├── starter-violations.md ← 15 universal V-entries to pre-seed new projects
├── triangle-rule.md ← Universal 3-source verification (any project)
├── research-mode.md ← Rule G.3 + /research-gap skill philosophy
├── continuous-improvement.md ← Rule D: bug → test + rule + skill cycle
├── capability-expansion.md ← Rule G + G.2 decision tree
├── cross-session.md ← Session handoff protocol (zero drift)
└── feedback-loop.md ← Bidirectional learning: project → guardrails
🧭 Master Flow (in 00-session-start.md) — a single-source skill
orchestration that classifies every task into a tier (T0 trivial → T3
release) and fires only that tier's gates, so a typo stays a one-liner while
a feature gets the full design-gate + audits + real-adversarial verification.
📊 Graphify lifecycle: session-start reads graphify-out/GRAPH_REPORT.md
to model the codebase from the graph (cheaper + clearer than raw files);
session-end runs graphify update . to keep it fresh — a compounding loop.
Optional 🎀 ponytail code-style layer plugs in at the lowest precedence
(lazy/minimal code; yields to your rules).
Install
# Clone + run installer (takes 10 seconds, zero runtime deps)
git clone https://github.com/teddyoomz/claude-guardrails
cd claude-guardrails
./install.sh /path/to/your-project
The installer copies templates only into your target project — no runtime, no background worker, no SaaS. Already-present files are never overwritten (safe to re-run).
First time in a project:
./install.sh .in your project root- Fill in
[FILL-IN]placeholders in:CLAUDE.md— stack + env + deploy command (5 min).claude/rules/00-session-start.md— character + expectations (5 min).claude/rules/01-iron-clad.md— rules B, E, H per your stack (10 min).claude/rules/02-workflow.md— test/build/deploy commands (2 min).claude/rules/03-stack.md— stack gotchas (grows over time).claude/rules/04-culture.md— domain rules (grows over time)
- Read
docs/methodology.md— the core philosophy (15 min) - Read
docs/cross-session.md— the protocol for new chats (10 min)
Total first-time setup: ~45 min. After that, every new session reads the same files automatically — zero setup per session.
Cross-session continuity (strict mode)
The killer feature: every new Claude chat resumes exactly where the last left off, with zero drift on iron-clad rules.
Protocol:
- Every session ends with an updated
SESSION_HANDOFF.md+ a paste-ready Resume Prompt - User pastes the Resume Prompt into the new chat
- New Claude reads
CLAUDE.md→SESSION_HANDOFF.md→.agents/active.md→.claude/rules/00-session-start.md(mandatory, before any tool call) - Context resumes deterministically — iron-clad rules loaded verbatim, no summarization
Full detail: docs/cross-session.md.
How it works
1. Rules as code
Instead of CLAUDE.md with vague guidance, use numbered invariants:
### C2. Security by default
- Never use `Math.random()` for URL tokens → use `crypto.getRandomValues`
- Never commit secrets under `src/` or `api/` → env vars only
- Never put `user.uid` in world-readable Firestore docs
Claude grep-reads these before every turn. You grep them in audit skills. Violations are catchable in CI.
2. Audit skills
A skill is a greppable list of invariants. Example:
# /audit-anti-vibe-code
AV1: grep `Math.random\(\)\.toString\(36\)` in src/ → token collision risk
AV2: grep `allow.*if true` in *.rules → missing gate
AV3: grep duplicate helper definitions (Rule of 3) → extract shared
...
Run /audit-anti-vibe-code before every release. Each invariant stays
greppable forever — never AI-compressed.
3. Violation log
When a bug ships, catalog it:
### V7 — 2026-04-19 — Second `vercel --prod` without re-asking
- Bug: deployed `eb0ea01` after user only authorized `79f4ccc`
- Root cause: treated "session has deploy authorization" as rolling
- Rule added: every `vercel --prod` needs explicit THIS-TURN authorization
- Audit invariant: grep history for multi-deploy patterns
V1, V2, ..., V10 catalog grows with you. New sessions read the catalog and don't repeat old mistakes.
4. Continuous improvement
Every bug → adversarial test + rule file + audit skill invariant.
Not just a fix. A fix + test + rule + audit. So the same class of bug can't come back silently.
5. Research Mode — admit ignorance cheaply, never hallucinate
The #1 AI failure mode is confident hallucination: inventing a plausible-looking URL / field / method / config based on training-data pattern-matching. Code type-checks, tests mock the invention, production fails.
Rule G.3 + /research-gap flip the incentive:
- Catch phrase: "I think", "probably", "the standard way is", "usually" → that's a gap signal. STOP.
- Invoke
/research-gap: 5-tier search (local code → project docs → official docs via WebFetch → WebSearch → MCP/skill registry). - If the gap is "capability missing", invoke
/skill-autoinstall— handles Anthropic-bundled skills, deferred tools, MCP servers, and community skills. Zero-cost installs auto-execute; external-write installs ask for consent.
Result: the agent now has a scripted path for admitting ignorance that's faster than guessing. Hallucinations become rare by design, not by willpower.
6. Growth Engine — the compounding loop
Four mechanisms feed each other:
- Rule D (learning) — bug → test + rule + audit invariant
- Rule G.2 (consolidation) — manual rep ≥ 3 → promote to skill
- Feedback loop (cross-project) — native learning → bridge file → guardrails template
- Session handoff (continuity) — checkpoint → next session reads → no context loss
Drop any one → loop breaks. Wire all four → toolkit sharpens every
session forever. Full diagram + diagnostics in docs/growth-engine.md.
vs alternatives
| Tool | Mechanism | Rule drift risk |
|---|---|---|
| claude-mem | SQLite + vector DB, AI-summarized | HIGH — summarization loses rule text |
| GenericAgent | 5-layer hierarchy, L1-L4 AI-crystallized | HIGH — lower layers drift |
| evolver | Genes/Capsules, "self-evolution" | HIGH — AI refactors memory |
| claude-guardrails | Plain markdown + grep + human review | ZERO — no AI compression anywhere |
Scope: what this IS and ISN'T
IS:
- A template repo with examples
- A methodology for writing durable rules
- A violation-catalog format
- Checked-in-repo team enforcement
ISN'T:
- A runtime / background worker
- A plugin that auto-executes
- AI-summarized memory
- Framework-specific (works with any stack)
Success metric
Not stars. Not installs.
Violations catalogued by users. If 5+ teams publish their V1..Vn logs within 6 months, the methodology has value. If 0, it was one team's artifact.
Status
v0.1 MVP (2026-04-21) — templates + docs + 2 audit skill examples.
Roadmap:
- v0.2:
npx claude-guardrails initone-shot installer - v0.3: 4+ audit skill examples (security, react-patterns, forms, a11y)
- v1.0: stack-specific example packs (react-firebase, next-supabase, python-django)
License
MIT. Use, fork, adapt. Publish your own violation catalog — the methodology is worth more when many teams contribute patterns.
Origin
Extracted from the rule/audit setup of a production clinic app
(.claude/rules/ + audit skills + .agents/ layer + violation catalog V1-V10)
that has caught 10 real regressions across 12 phases of development.
The methodology was worth more than the clinic-specific content — hence
this package.