Claude Code Blueprint

A battle-tested reference architecture for Claude Code. Not a plugin to install -- a blueprint to learn from and adapt.

11 agents · 17 skills · 10 hooks · 5 rules -- every one battle-tested

English | 日本語 | 한국어 | 简体中文

Quick Start

Copy one file. Get three behavioral rules. Done in 60 seconds.

# In your project root
curl -o CLAUDE.md https://raw.githubusercontent.com/faizkhairi/claude-code-blueprint/main/CLAUDE.md

This gives Claude Code three rules that prevent the most common AI coding mistakes:

Verify-After-Complete · Diagnose-First · Plan-Before-Execute

Ready for more? See the full adoption path or the 30-minute beginner guide.

Before You Start

Important: This is a reference architecture, not a project template. Do not run Claude Code inside this repository -- it will read the blueprint's own CLAUDE.md instead of your project's rules. Fork or cherry-pick files into your own project.

Several files contain placeholder variables ({MEMORYCORE_PATH}, {PROJECTS_ROOT}) that you must replace with your actual paths. Hooks and settings belong in your user-level config (~/.claude/), not in your project directory. See GETTING-STARTED.md for the full setup guide.

What Makes This Different

Other repos give you 135 agents. We give you 11 -- and explain why each one exists.

What's Inside

See agents/README.md for permission modes, cost estimates, and maxTurns.

See skills/README.md for customization and placeholder variable setup.

Plus 2 utility scripts: verify-mcp-sync.sh (MCP config checker) and status-line.sh (branch/project status).

Run bash hooks/test-hooks.sh to verify all hooks pass (35 automated tests).

See hooks/README.md for the full lifecycle, testing guide, and design principles.

See rules/README.md for creating custom rules.

Also included:

Philosophy

1. Hooks for enforcement, CLAUDE.md for guidance -- Hooks fire 100% of the time. CLAUDE.md instructions are followed ~80%. If something MUST happen, make it a hook.

2. Agent-scoped knowledge, not global bloat -- Design principles live in the frontend agent, not in every session's context. Security patterns live in the security-reviewer, not in CLAUDE.md.

3. Context is currency -- Every token loaded into context is a token not available for your code. Keep MEMORY.md under 100 lines. Extract to topic files. Use path-scoped rules so irrelevant rules don't load.

4. Hooks are free, context is cheap -- The 10 hook scripts cost zero tokens (they run outside Claude's context). CLAUDE.md adds ~2,300 tokens per session -- roughly 1-5% of a typical session. The blueprint saves more tokens than it costs by preventing redo cycles. See BENCHMARKS.md.

5. Battle-tested over theoretical -- Every rule in this repo exists because something went wrong without it. The "WHY" matters more than the "WHAT".

Getting Started

Who is this for?

Option A: Fork (recommended)

Fork this repo to customize it as your own living reference. You can pull upstream updates later as the blueprint evolves.

Option B: Clone + Copy

Clone the repo, then selectively copy components into your ~/.claude/ directory.

Option C: Cherry-pick

Browse the repo on GitHub and copy only the specific files you need. No installation required.

Recommended adoption path

1. Start with CLAUDE.md -- the behavioral rules template. Biggest impact with zero setup.
2. Add 2-3 hooks -- protect-config.sh + notify-file-changed.sh + cost-tracker.sh. Copy to ~/.claude/hooks/ and wire into settings.json.
3. Read WHY.md to understand the reasoning -- adapt, don't blindly copy.
4. Add agents as your workflow matures -- start with verify-plan and code-reviewer.
5. Set up the memory system when you need cross-session persistence.

Deep Dives

Troubleshooting

See TROUBLESHOOTING.md for solutions to common issues -- hooks not firing, agents failing, MCP crashes, cost surprises, Windows-specific problems, and more.

This blueprint is designed as a standalone configuration -- no plugins required. In fact, plugins can interfere with a custom setup:

Known issues:

• Plugins that modify CLAUDE.md may overwrite your custom behavioral rules
• Plugins that add hooks on the same events (e.g., Stop, PreToolUse) will stack with your hooks -- this can cause slowdowns or conflicting instructions
• Plugins that inject context consume tokens from your context window, leaving less room for your agents and memory system
• MCP server plugins work well alongside this setup -- they add tools, not rules, so there's no conflict

Recommendation: If you adopt this blueprint, audit your installed plugins and disable any that:

1. Override CLAUDE.md or settings.json hooks
2. Inject prompts on SessionStart (conflicts with your session-lifecycle rule)
3. Add broad permissions that bypass your permission restrictions

Custom setup > generic plugins, because your setup encodes YOUR project's domain knowledge. A plugin can't know your architecture, your team's conventions, or your production constraints.

Acknowledgments

The memory system pattern in this blueprint was inspired by Project-AI-MemoryCore by Kiyoraka -- a comprehensive AI memory architecture with 11 feature extensions (LRU project management, memory consolidation, echo recall, and more). If you want a deeper, more feature-rich memory system than the minimal scaffold included here, check out that project.

How they differ: This blueprint covers the full Claude Code configuration (agents, skills, hooks, rules, settings). The memory-template/ here is a lightweight scaffold. Project-AI-MemoryCore goes deep on the memory layer specifically -- they're complementary, not competing.

License

MIT