Production-tested hook patterns for Claude Code. Clone, open Claude Code, hooks fire immediately.
git clone https://github.com/Bluepandafox/claude-code-production-patterns
cd claude-code-production-patterns
# Open Claude Code -- session brief fires, architecture guard is active, quality gate runs on writesNo setup scripts. No API keys. Python 3.10+ required.
I spent 4 months building a production Claude Code system — 12 hooks, 10 skills, 142 tests — and kept running into the same problem: no working reference existed for teams adopting hooks and skills beyond the basics. The community had curated link lists and demo projects, but nothing you could clone and actually run in production.
This repo extracts the 3 core hook patterns, the quality validator library, the architecture enforcement, and the hygiene audit from that system. Everything here has been running daily against real work for months.
Every session opens with a live project brief:
╔================================================
║ SESSION BRIEF -- 2026-04-14
╠================================================
║ Tracker : 0 total | 0 in progress | 0 done | 0 archived
║ Follow-ups: none overdue
╠================================================
║ Last learning: none
╚================================================
On a fresh clone, the brief is empty. Once you create tracker.md and follow_ups.md, it reads live project state.
Blocks writes that violate structural constraints:
[ARCHITECTURE GUARD] Blocked to prevent architectural drift:
- Skill ceiling reached: 10/10 user-facing skills.
Per ARCHITECTURE.md rule 7, absorb into an existing skill or retire one first.
Enforces: skill ceiling (10), hook ceiling (12), canonical source rules, skill frontmatter validation.
Domain-specific quality enforcement on file writes:
[QUALITY GATE FAILED] 3 violation(s) in output/draft.md:
- BANNED WORD: "leverage" appears 2x (limit: 0)
- EM DASH: 1 found (limit: 0). Use comma, period, or parenthetical instead.
- STRUCTURAL: 3+ consecutive bullets open with "Built" -- vary opening verb
Validators live in _lib/quality_validators.py. The hook (quality_check.py) is a thin orchestrator: add your own validators by writing functions that take content and return violation strings.
19 deterministic checks. Run anytime:
$ python scripts/hygiene_audit.py
Hygiene Audit -- 19 checks
===================================================
1. Hook count ceiling PASS 3/12
2. Skill count ceiling WARN skills dir missing
3. Hook line counts PASS
4. Manifest integrity WARN MANIFEST.sha256 not found -- run update_manifest.py
5. Settings hooks registered PASS
6. CLAUDE.md line ceiling PASS 33/50
7. Hook syntax PASS
8. UTF-8 safety PASS
9. Canonical source violations PASS 0
10. Skill frontmatter PASS skills dir missing -- skip
11. Write/Edit hook symmetry PASS
12. Root entry count PASS 7
13. Knowledge rules complete PASS 4 files
14. Tracker file present WARN not found at tracker.md
15. Follow-ups file present WARN not found at follow_ups.md
16. ARCHITECTURE.md present PASS
17. Stale root docs PASS
18. Architecture guard registered PASS
19. settings.json valid PASS
===================================================
15 PASS 4 WARN 0 FAIL
WARNs on a fresh clone are expected -- they flag files you create as you customize (tracker, follow-ups, skills, manifest). Zero FAILs means the architecture is intact.
Most Claude Code configuration falls into one of three categories:
- Curated link lists collect tips and resources, but there is no working system to clone
- Skill libraries offer hundreds of skills with no integration, testing, or architecture
- Demo projects show structure but are not systems anyone has actually run in production
This repo is a working system extracted from a 12-hook production deployment used daily for 4 months. It ships the 3 core hook patterns plus the architecture and tooling to build your own.
The key insight: hooks can enforce any organizational rule, not just code style — architecture ceilings, quality standards, team norms. The same management thinking that prevents process sprawl in a 50-person org can prevent structural drift in a codebase.
10 rules enforced by architecture_guard.py. Full doc: .claude/ARCHITECTURE.md.
| # | Rule | What it prevents |
|---|---|---|
| 1 | No skill without a user trigger | Internal logic bloating user-facing skills |
| 2 | One canonical source per concept | Word lists copied to 5 files, drifting out of sync |
| 3 | Skills solve whole workflows | Step-8-of-a-workflow becoming its own skill |
| 4 | Hooks are small and focused | 600-line hook doing 4 unrelated things |
| 5 | Shared logic goes in _lib/ |
Copy-paste between hooks |
| 6 | CLAUDE.md stays under 50 lines | Identity file becoming a manual |
| 7 | Skill ceiling: 10 | Skill sprawl |
| 8 | Hook ceiling: 12 | Hook sprawl |
| 9 | Every new file must justify itself | File-per-concept proliferation |
| 10 | The learning loop is real | Retros nobody acts on |
Hook as domain guardrail. Most hook examples enforce dev rules (syntax, formatting). These hooks enforce domain logic: banned words, structural variation, architecture ceilings. The key insight is that hooks are not just for code quality -- they can enforce any rule your project needs.
Thin orchestrator. quality_check.py is 100 lines. It reads the event, decides if the file is a quality target, routes to validators in _lib/quality_validators.py, collects violations, and blocks or passes. Validators are independently testable functions: content in, violations out. Add your own by writing a function and importing it.
Refinement loop (Karpathy autoresearch). An iterate-and-measure loop for autonomous quality improvement: define one metric, modify one file, score with binary criteria, keep or revert. After 3 reverts, trigger a plateau breaker. Time-boxed, audit-trailed. Full spec: knowledge/rules/refinement_loop.md.
Multi-model verification. The generator and evaluator should be separate models to prevent self-confirmation bias. The default setup uses Ollama with deepseek-r1:14b as the local evaluator. This layer is model-agnostic: swap in any local model (LM Studio, llama.cpp), or call an API-based model (GPT-4o, Gemini). What matters is that the model scoring the output is different from the model that wrote it. Protocol: knowledge/rules/quality_assurance.md.
Learning loop. Log failure patterns with confidence levels (LOW/MEDIUM/HIGH). After 3 HIGH-confidence occurrences, promote to a permanent rule update in the canonical source file. Template: knowledge/rules/learning_log.md.
.claude/
hooks/
architecture_guard.py # PreToolUse: Write -- ceiling + canonical source enforcement
quality_check.py # PostToolUse: Write, Edit -- thin orchestrator for validators
session_start.py # SessionStart -- live project brief from tracker state
_lib/
quality_validators.py # Shared validators (banned words, frequency, structural variation)
settings.json # Hook registrations
ARCHITECTURE.md # 10 architecture rules
knowledge/
rules/
banned_patterns.md # Canonical banned word list (4 tiers + frequency limits)
quality_assurance.md # QA checklist with adversarial review protocol
refinement_loop.md # Karpathy autoresearch pattern spec
learning_log.md # Failure pattern log (append-only)
scripts/
hygiene_audit.py # 19-check workspace audit (--json, --fix flags)
tests/
test_hooks.py # 18 tests across all hooks and the audit
examples/
skill-template/SKILL.md # Annotated template for adding skills
docs/
QUICKSTART.md # 5-minute setup guide
See docs/QUICKSTART.md for the full walkthrough. The short version:
- Edit banned words in
knowledge/rules/banned_patterns.md. The quality gate picks them up automatically. - Change which files are quality-checked via
is_quality_target()inquality_check.py. - Add your own validators as functions in
_lib/quality_validators.py, import inquality_check.py. - Create your tracker as
tracker.mdat project root. The session brief reads it every session. - Add skills in
.claude/skills/my-skill/SKILL.mdwith YAML frontmatter. Seeexamples/skill-template/.
python -m pytest tests/ -v18 tests covering architecture guard, quality validators, hygiene audit, and session brief. All pass on a fresh clone.
MIT
Extracted from a 12-hook, 142-test production system used daily for 4 months. This repo ships the 3 core hooks, the quality validator library, the hygiene audit, and the pattern documentation. The source system adds security hooks (URL allowlisting, integrity verification, injection detection, credential protection) and domain-specific skills.