Make Claude Code smarter, safer, and more consistent -- for any project, at any skill level. Not a plugin to install -- a blueprint to learn from and adapt.
11 agents · 17 skills · 10 hooks · 5 rules -- every one battle-tested
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.mdThis 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. New to Claude Code? See who this is for or the FAQ.
Want more than CLAUDE.md? Install hooks, agents, and settings automatically:
# From a cloned/forked copy of this repo
./setup.sh --preset=standardOr let Claude do it -- paste into a Claude Code session: "Set up the Claude Code Blueprint. Copy CLAUDE.md to my project root, set up hooks and settings in ~/.claude/. Show me each step."
See SETUP.md for all setup options including a verification checklist.
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.
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 |
Level 1 -- Start here (60 seconds) Copy CLAUDE.md into your project. Three behavioral rules. Immediate impact.
Level 2 -- Add safety nets (5 minutes) Add 2-3 hooks. Zero token cost. Automated config protection and edit verification.
Level 3 -- Customize as you grow (ongoing) Add agents, skills, rules, and memory as your workflow matures. See Presets for ready-to-copy configurations.
Other repos give you 135 agents. 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 |
| 3 behavioral rules that prevent AI coding mistakes | Lists of settings to copy |
| Cross-tool guide for 10 tools (Copilot, Cursor, Cline, Roo Code, OpenCode, and more) | Single-tool only |
| Beginner-friendly with 6 adoption personas | Assumed expertise |
| Smoke-tested hooks with 35 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 |
11 Agents -- Specialized subagents with model tiering (opus/sonnet/haiku)
| 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 |
| api-documenter | haiku | OpenAPI specs, integration guides (read-only) |
See agents/README.md for permission modes, cost estimates, and maxTurns.
17 Skills -- Natural-language-triggered workflows (no slash commands needed)
| Category | Skills | Triggers |
|---|---|---|
| Code Quality | review, review-diff | "is this secure?", "scan diff", "check for vulnerabilities" |
| 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 | "let's build", "new feature", multi-step tasks |
| Session | load-session, save-session, session-end, save-diary | Session start/end, "save", "bye", "done" |
| Project | init-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.
10 Hooks -- Deterministic lifecycle automation (100% compliance, unlike ~80% for CLAUDE.md rules)
| Event | Hook | Purpose |
|---|---|---|
| SessionStart | session-start.sh | Inject workspace context |
| PreToolUse (Bash) | block-git-push.sh | Protect remote repos |
| PreToolUse (Write/Edit) | protect-config.sh | Guard linter/build configs |
| PostToolUse (Write/Edit) | notify-file-changed.sh | Verify reminder |
| PostToolUse (Bash) | post-commit-review.sh | Post-commit review |
| PreCompact | precompact-state.sh | Serialize state to disk |
| Stop | security check + cost-tracker.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).
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.
5 Rules -- Path-scoped behavioral constraints (load only when editing matching files)
| 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 |
| session-lifecycle | Always | Session start/end behaviors |
| memorycore-session | **/memory-core/** |
External memory integration |
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 | Dual: auto-memory + external git-backed persistence |
-
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.
-
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 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.
-
Battle-tested over theoretical -- Every rule in this repo exists because something went wrong without it. The "WHY" matters more than the "WHAT".
Fork this repo to customize it as your own living reference. You can pull upstream updates later as the blueprint evolves.
Clone the repo, then selectively copy components into your ~/.claude/ directory.
Browse the repo on GitHub and copy only the specific files you need. No installation required.
Run ./setup.sh from a cloned or forked copy. Choose a preset (minimal/standard/full) and the script handles directory creation, file copying, settings merge, and placeholder replacement. See SETUP.md.
- 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 -- start with
verify-planandcode-reviewer. - Set up the memory system when you need cross-session persistence.
| 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 5 more |
| FAQ | Getting Started | Troubleshooting |
| Top community questions answered | From zero to productive in 30 minutes | Common issues and fixes |
| Setup Guide | Examples | Roadmap |
| Automated installer + verification checklist | Framework-specific CLAUDE.md templates | Project direction and what's next |
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.
Plugin Compatibility
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.
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.
MIT