Claude Code Blueprint

Prevent the most common AI coding mistakes — a library of ready-to-copy files (CLAUDE.md, hooks, agents) you mix into your own project to make Claude Code more reliable.

60 seconds to start. Copy one file. Add more as your project grows. Works with any language, any framework, any skill level.

12 agents · 17 skills · 12 hooks · 6 rules — copy only what you need, or install a preset (minimal / standard / core / full)

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

Heads up before you copy: This is a reference repo, not a project template — you'll copy files OUT of it into your own project. Don't run Claude Code inside this repository (it'll load this blueprint's CLAUDE.md instead of yours). See GETTING-STARTED.md for the full walkthrough.

Quick Start

Do this first. Copy one file into your project and you're done in 60 seconds:

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

That gives Claude Code four behavioral rules that prevent the most common AI coding mistakes: Verify-After-Complete · Diagnose-First · Plan-First · Verify-Before-Exit-Plan. That's the whole first step — try it, then come back for more.

./setup.sh --preset=standard

New to Claude Code, or want the guided version? The beginner guide walks you through the same thing step by step. Curious who this is for? See Who Is This For below.

What It Costs You (Token Budget)

Every file you copy is a recurring per-session context cost. Here is what each component costs and when it loads, so you can decide what to add. Numbers are measured from the actual files (~4 characters per token):

The economics: hooks cost zero tokens, and path-scoped rules cost nothing until you touch a matching file. The recurring baseline is just CLAUDE.md (~2,300 tokens, roughly 3-5% of a typical session) — and a single prevented redo cycle saves far more than that. See the full breakdown and savings math.

Who Is This For?

Any developer, any framework, any skill level. The blueprint configures Claude Code's behavior -- it doesn't care what language or framework your project uses.

Your Progression

Grow as you need to: start with CLAUDE.md (above), add a few hooks, then add agents/skills/rules as your workflow matures. The core preset is a good middle step. The exact order is in the Recommended adoption path below, and Presets has ready-to-copy configurations for each tier.

What Makes This Different

Other repos dump dozens of agents on you. We give you 12 -- and explain why each one exists.

What's Inside

Also included:

Philosophy

1. Hooks for enforcement, CLAUDE.md for guidance -- Hooks fire deterministically every time. CLAUDE.md instructions are followed most of the time, but not guaranteed -- the model can forget or deprioritize a rule. 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 12 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

Quick Start above is the fast path -- copy CLAUDE.md and you're going in 60 seconds. For the next step, pick the doc that fits you: new to Claude Code? Read GETTING-STARTED.md (concepts + a guided walkthrough). Just want the install commands and presets? Go straight to SETUP.md (every option + a verification checklist).

Then grow into the rest with this order:

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 — opt-in during ./setup.sh (answer Y).

Deep Dives

Common Questions

Works with my framework? Yes. The blueprint is framework-agnostic -- it configures Claude Code, not your stack. More...

Too advanced for me? No. Start with one file (CLAUDE.md). Add more only when you need it. More...

Which plan do I need? Works on Pro, Max, Team, Enterprise, and API. Hooks are free on all plans. More...

A colleague sent you this? Start here: quickstart for referrals.

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 lean built-in version here, check out that project.

How they differ: This blueprint covers the full Claude Code configuration (agents, skills, hooks, rules, settings) and ships a built-in opt-in memory in memory/. Project-AI-MemoryCore goes deep on the memory layer specifically — they're complementary, not competing.

License

MIT