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 · 19 skills · 15 hooks · 6 rules, copy only what you need, or install a preset (minimal / standard / core / full)
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. Install one file and you're done in 60 seconds:
# Installs globally for every project
mkdir -p ~/.claude && curl -o ~/.claude/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, applied to every project on your machine. That's the whole first step; try it, then come back for more. See where config belongs if you also want project-specific conventions.
Once CLAUDE.md is working, add the rest. Easiest path: run the installer from a cloned/forked copy:
./setup.sh --preset=standard
Or let Claude do it: paste into a Claude Code session: "Set up the Claude Code Blueprint. Install CLAUDE.md to ~/.claude/CLAUDE.md, set up hooks and settings in ~/.claude/. Show me each step."
For every install option (fork / clone / cherry-pick / presets) plus a verification checklist, see SETUP.md.
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):
| Component | Token Cost | When It Loads |
|---|---|---|
| CLAUDE.md | ~2,300 | Every session start |
| An always-on rule (session-lifecycle) | ~700 | Every session |
| A path-scoped rule (testing, schema, api) | ~850-1,450 | Only when editing matching files, otherwise zero |
| A skill (review-full, test-check, deploy-check) | ~480-1,070 | Only when its trigger phrase is used |
| Hooks (all of them) | Zero | They run outside Claude's context |
| An agent (per spawn) | Full context window | Only when you invoke it |
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.
| You Are | Start Here | Time to Value |
|---|---|---|
| Complete beginner | Start Here | 1 minute: just copy CLAUDE.md |
| Solo dev, small project | CLAUDE.md + 2 hooks | 5 minutes |
| Small startup (2-5 devs) | Above + shared rules + 2-3 agents | See Team Setup |
| Established team (5+ devs) | Full blueprint, adapted | Fork, customize, commit shared config |
| Learning to code | GETTING-STARTED.md only | Ignore agents/skills/memory until comfortable |
| Coming from another tool | CROSS-TOOL-GUIDE.md | Concepts transfer; see Copilot/Cursor in depth sections |
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 11, and explain why each one exists.
| This Blueprint | Generic Config Repos |
|---|---|
| Every component has a battle story explaining why it exists | Configs without context |
| 4 behavioral rules that prevent AI coding mistakes | Lists of settings to copy |
| Cross-tool guide for 10 other tools (Copilot, Cursor, Cline, Roo Code, OpenCode, and more) | Single-tool only |
| Beginner-friendly with 6 adoption personas | Assumed expertise |
| Smoke-tested hooks with 55 automated tests | Untested scripts |
| Safety-first: config placement guide, privacy warnings, graceful degradation | No safety guidance |
| Framework-agnostic: works with any language and stack | Assumes a specific language/framework |
What's Inside
| Agent | Model | Role |
|---|---|---|
| project-architect | opus | System design, architecture decisions, technology choices |
| backend-specialist | sonnet | API endpoints, services, database operations, middleware |
| frontend-specialist | sonnet | UI components, state management, forms, styling |
| code-reviewer | sonnet | Code quality, patterns, best practices (read-only) |
| security-reviewer | sonnet | OWASP Top 10, auth flaws, injection attacks (read-only) |
| db-analyst | sonnet | Schema analysis, query optimization, migration planning (read-only) |
| devops-engineer | sonnet | Deployment configs, CI/CD, Docker, infrastructure (read-only) |
| qa-tester | sonnet | Unit tests, integration tests, E2E tests |
| verify-plan | sonnet | 7-point mechanical plan verification (read-only) |
| docs-writer | haiku | README, API docs, changelogs, architecture docs |
| architecture-reviewer | sonnet | Dependency direction, god files, dead code, modularity (read-only) |
| memory-curator | sonnet | Audits your memory directory for orphans, index drift, broken links, stale entries (report-only) |
See agents/README.md for permission modes, cost estimates, and maxTurns.
| Category | Skills | Triggers |
|---|---|---|
| Code Quality | review-full, review-diff | "is this secure?", "scan diff", "check for vulnerabilities" |
| PR Review | pr-review | "review this PR", "review PR #N", "post a PR review" |
| Testing | test-check, e2e-check | "run the tests", "browser test", "are tests passing?" |
| Deployment | deploy-check | "deploy", "push to prod", "ready to ship" |
| Planning | sprint-plan, elicit-requirements, self-audit | "let's build", "new feature", "audit yourself", "did you check everything?" |
| Session | load-session, save-session, session-end, save-diary | Session start/end, "save", "bye", "done" |
| Project | scaffold-project, register-project, status, changelog | "new project", "status", "changelog" |
| Database | db-check | "check the schema", "validate models" |
| Utilities | tech-radar | "what's new?", "should we upgrade?" |
See skills/README.md for customization and placeholder variable setup.
| Event | Hook | Purpose |
|---|---|---|
| SessionStart | session-start.sh | Inject workspace context |
| InstructionsLoaded | instructions-loaded.sh | Log which rules loaded and why |
| PreToolUse (Bash) | block-git-push.sh | Protect remote repos |
| PreToolUse (Bash) | pre-commit-secret-scan.sh | Block commits containing secrets |
| PreToolUse (Write/Edit) | protect-config.sh | Guard linter/build configs |
| PreToolUse (Write/Edit) | protect-claude-settings.sh | Confirm edits to safety keys in your own settings.json |
| PostToolUse (Write/Edit) | notify-file-changed.sh | Verify reminder |
| PostToolUse (Write/Edit) | no-dash-check.sh | Warn on a prose-style violation (example: em-dashes) |
| PostToolUse (Bash) | post-commit-review.sh | Post-commit review |
| PostToolUse (Agent/Task) | verify-subagent-findings.sh | Treat subagent findings as hypotheses to verify |
| PreCompact | precompact-state.sh | Serialize state to disk |
| Stop | security check + cost-tracker.sh + session-checkpoint.sh | Last defense + metrics |
| SessionEnd | session-checkpoint.sh | Guaranteed final save |
Plus 2 utility scripts: verify-mcp-sync.sh (MCP config checker) and status-line.sh (branch/project status), both deployed by the full preset, and a companion tool check-no-dash-file.py (a pre-post prose sanitizer for the no-dash-check.sh hook). The last file in the folder is test-hooks.sh, the local test harness, run via bash hooks/test-hooks.sh to verify all hooks. It's the only one not deployed to ~/.claude/hooks/, and isn't counted in the "15 hooks" total.
Run bash hooks/test-hooks.sh to verify all hooks pass (55 automated tests).
See hooks/README.md for the full lifecycle, testing guide, and design principles.
| Rule | Activates On | Purpose |
|---|---|---|
| api-endpoints | **/server/api/**/*.{js,ts} |
API route conventions |
| database-schema | **/prisma/**, **/drizzle/**, **/migrations/** |
Schema design patterns |
| testing | **/*.test.*, **/*.spec.* |
Test writing conventions |
| testing-general | **/*.test.*, **/*.spec.* |
Framework-agnostic testing conventions (companion to testing) |
| session-lifecycle | Always | Session start/end behaviors |
| memory-session | **/memory/** |
Memory repository session management |
See rules/README.md for creating custom rules.
Also included:
| Component | Purpose |
|---|---|
| CLAUDE.md | Battle-tested behavioral rules template |
| Settings Template | Full hook + permission configuration |
| Memory System | Built-in opt-in: Claude remembers preferences and session context across runs (git-ignored for privacy) |
Philosophy
-
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.
-
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.
-
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.
-
Hooks are free, context is cheap: The 15 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.
-
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
- Start with CLAUDE.md: the behavioral rules template. Biggest impact with zero setup.
- Add 2-3 hooks:
protect-config.sh+notify-file-changed.sh+cost-tracker.sh. Copy to~/.claude/hooks/and wire intosettings.json. - Read WHY.md to understand the reasoning; adapt, don't blindly copy.
- Add agents as your workflow matures, starting with
verify-planandcode-reviewer. - Set up the memory system when you need cross-session persistence, opt-in during
./setup.sh(answer Y).
Deep Dives
| Architecture | Settings Guide | Battle Stories |
| System design, hook lifecycle, component relationships | Every env var, permission, and hook explained with rationale | The incidents and lessons behind every component |
| Benchmarks | Presets | Cross-Tool Guide |
| Token savings, cost impact, quality metrics | Ready-to-copy configs for solo, team, and CI/CD | Copilot, Cursor, Cline, Roo Code, OpenCode, and more (10 other tools) |
| FAQ | Getting Started | Troubleshooting |
| Top community questions answered | From zero to productive in 30 minutes | Common issues and fixes |
| Setup Guide | Case Studies | Roadmap |
| Automated installer + verification checklist | Adopter stories and before/after metrics (submission-driven, be the first) | Project direction and what's next |
| Self-Monitoring | ||
| Optional patterns: gitleaks pre-commit + memory-curator agent |
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.
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:
- Override CLAUDE.md or settings.json hooks
- Inject prompts on SessionStart (conflicts with your session-lifecycle rule)
- 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 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
No comments yet
Be the first to share your take.