Guardrails for Claude Code. Shell hooks that actually block bad behavior, not just markdown that asks nicely.
Claude Code in long sessions tends to:
- Edit the same file 5+ times chasing symptoms instead of finding root cause
- See an error and immediately change code without understanding it
- Lose track of what it was doing after context compaction
Markdown rules help, but Claude can ignore them. Hooks can't be ignored — they run as shell scripts and exit 2 physically blocks the operation.
Three shell scripts that run automatically before/after Claude's actions:
streak-breaker.sh — Tracks per-file edit counts. Warns at 3, hard-blocks at 5. Forces Claude to stop and find the root cause instead of endlessly patching.
Here's what it looks like in practice:
You: "Fix the login validation bug in auth.py"
Claude: I'll fix the validation logic.
[Edit src/auth.py — fix email regex]
Claude: The regex wasn't enough, let me also add length check.
[Edit src/auth.py — add input length validation]
Claude: That broke the existing tests, let me adjust.
[Edit src/auth.py — fix test compatibility]
⚠️ EDIT NOTE: File src/auth.py has been edited 3 times.
Quick check: are these edits building toward a goal,
or fixing previous edits?
Claude: Let me try a different approach to the validation.
[Edit src/auth.py — rewrite validation layer]
Claude: Almost there, one more adjustment...
[Edit src/auth.py — blocked]
🛑 EDIT CHECKPOINT
File src/auth.py has been edited 5 times this session.
Reflect:
1. Are these edits progressing toward a goal,
or fixing previous edits?
2. If fixing previous edits: pause and look
for the root cause.
Claude: You're right. Looking at all 5 edits, I was patching
symptoms. The real issue is that the User model's
validate() method is called before sanitization.
Let me fix it at the source instead.
Without the hook, Claude would keep editing auth.py indefinitely — each fix creating the next bug. The hook forces a pause that leads to root-cause discovery.
pre-edit-guard.sh — Checks docs/debug-log.md for unverified hypotheses. If you're debugging and haven't finished the process, it blocks source code edits until you do.
You: "The API is returning 500 errors on /users endpoint"
Claude: Let me investigate.
[Bash: curl localhost:3000/users]
→ 500 Internal Server Error
Claude: I think it's a database connection issue. Let me fix
the connection pool config.
[Edit src/db.py — blocked]
🛑 docs/debug-log.md has 2 unverified hypotheses.
Please complete the debugging process (verify or
eliminate hypotheses) before editing source code.
Claude: Right, I haven't verified my hypothesis yet.
Let me check the actual error logs first.
[Bash: tail -50 logs/error.log]
→ TypeError: Cannot read property 'map' of undefined
at UserSerializer.format (src/serializers.py:42)
Claude: The error is in the serializer, not the database.
My first hypothesis was wrong. Let me update
debug-log.md and then fix the actual issue.
Without the hook, Claude would have "fixed" the database config — a perfectly working component — and the real bug would remain.
post-error-remind.sh — Detects error patterns (test failures, crashes, build errors) in command output and injects a debugging discipline reminder before Claude can react impulsively.
Claude: Let me run the tests.
[Bash: pytest tests/]
→ FAILED tests/test_auth.py::test_login - AssertionError
→ 1 failed, 23 passed
⚡ Error encountered — debugging checklist:
1. Resist modifying code immediately
2. Fully understand the error message
3. List >=3 possible causes
4. Only then fix
Claude: Before jumping in, let me understand the failure.
The test expects a 200 but gets 401. Three possible
causes:
1. Token generation changed (check auth.py changes)
2. Test fixture uses expired mock token
3. Middleware order changed after recent refactor
Let me verify each...
Without the hook, Claude's instinct is to immediately open the test or source file and start editing. The reminder forces a diagnostic pause.
Auto-injected markdown in .claude/rules/ — Claude sees them when operating on matching files. Not as strong as hooks, but provides structure:
- Debugging process: gather → hypothesize → verify → fix (no skipping)
- Pre-edit checklist: understand the file, know the impact, fix root cause
- Mole-whacking detection: recognize the pattern, stop, report
- Phase discipline: stay in research/plan/implement, don't jump ahead
- Multi-task gates: complete tasks in order, confirm each before moving on
- Tech stack rules for Python, JS/TS, embedded, RTL, mobile
- reviewer — Reviews your modification plan in a separate context. Challenges assumptions, suggests alternatives, checks for missing edge cases.
- investigator — Researches the codebase in isolation. Returns structured findings without polluting your main conversation.
git clone https://github.com/TechHU-GS/cc-discipline.git ~/.cc-discipline
cd your-project
bash ~/.cc-discipline/init.shThe installer is interactive — pick your tech stack, name your project, done.
Already have a .claude/ setup? The installer detects this and runs in append mode:
- Your
CLAUDE.mdis never overwritten - Your
settings.jsonhooks are preserved (cc-discipline hooks are merged in viajq) - Your custom rules, agents, and docs are untouched
- A timestamped backup is created before any changes
Upgrading? Just run init.sh again. It detects the existing installation and updates framework files while preserving your configuration.
.claude/
├── rules/ # Auto-injected when Claude operates on matching files
│ ├── 00-core-principles.md
│ ├── 01-debugging.md
│ ├── 02-before-edit.md
│ ├── 03-context-mgmt.md
│ ├── 04-no-mole-whacking.md
│ ├── 05-phase-discipline.md
│ ├── 06-multi-task.md
│ └── stacks/ # Picked during install
├── hooks/ # Shell scripts, exit 2 = block operation
│ ├── streak-breaker.sh
│ ├── pre-edit-guard.sh
│ └── post-error-remind.sh
├── agents/
│ ├── reviewer.md
│ └── investigator.md
├── skills/
│ └── commit/SKILL.md # /commit: test → update docs → commit
└── settings.json # Hook registration
docs/
├── progress.md # Claude maintains this, read after compact
└── debug-log.md # Debug session tracking
CLAUDE.md # Your project info (you fill this in)
Adjust hook strictness:
# In .claude/hooks/streak-breaker.sh
WARN_THRESHOLD=3 # Warn after N edits to same file
STOP_THRESHOLD=5 # Hard block after N editsAdd your own rules:
cat > .claude/rules/my-rule.md << 'EOF'
---
globs: "src/api/**/*"
description: "API layer rules"
---
- All API changes must be backwards-compatible
- New endpoints need OpenAPI spec updates
EOFWrite your own hooks:
Any script in .claude/hooks/ can be registered in settings.json. The key behaviors:
exit 0= allow (stdout can inject context via JSON for PreToolUse hooks)exit 2+ stderr = block operation, stderr message shown to Claude
See Claude Code hooks docs for the full spec.
Is this just markdown rules? No. The hooks are the real enforcement — they're shell scripts that physically block operations. The rules are supplementary structure.
Does it slow things down? No. Hooks are lightweight shell scripts, typically <100ms. Rules add ~8KB to context (~2%).
Should I commit .claude/ to git?
Yes. Team members get the same guardrails. Hook paths use $CLAUDE_PROJECT_DIR, so they work across machines.
Does it work with existing projects?
Yes. The installer has an append mode that merges with your existing .claude/ configuration without overwriting anything. Run init.sh and it auto-detects.
PRs welcome — especially new hooks. The hooks are where the real value is.