I have been using Claude Code seriously for months. And I kept hitting the same frustrations:
- Session context vanishes. You pick up the next day and Claude has forgotten everything.
- Config lives on one machine. Move to another and you rebuild from scratch.
- Hooks get written, then lost. No single place to keep them.
- Claude starts coding before you finish explaining the problem.
So I built a reference architecture that fixes these. Then I open-sourced it.
What Is It?
Claude Code Blueprint is a library of ready-to-copy files: CLAUDE.md, hooks, agents, skills, and rules. You copy what you need into your own project. Nothing more.
It is not a framework. It is not a wrapper. It is configuration files that change how Claude Code behaves.
12 agents * 17 skills * 12 hooks * 6 rules
60 seconds to start:
ash
curl -o CLAUDE.md https://raw.githubusercontent.com/faizkhairi/claude-code-blueprint/main/CLAUDE.md
The Three Rules That Matter Most
The CLAUDE.md ships with three behavioral rules that prevent the most common AI coding mistakes:
1. Diagnose-First
Before writing any fix, Claude must run four checks: git state, error source, existing suppression, minimum viable diagnosis. This stops the most common waste -- building an elaborate fix for a problem that was already solved in a previous commit.
2. Plan-First
Any change touching more than one file goes through plan mode. No exceptions. Claude proposes, you approve, then it executes. This prevents the pattern where Claude charges into a 15-file refactor and produces something you did not ask for.
3. Verify-After-Complete
After finishing any task, Claude runs a verification pass appropriate to the work type. API endpoint? It curls the live URL. Config change? It confirms the value was actually picked up. File edit? It re-reads the changed block. This alone catches a significant proportion of errors before you do.
The Memory System
This was the hardest part to get right. Claude Code has no native persistent memory between sessions. The blueprint solves this with a file-based memory system:
- Per-session context: saved at session end, loaded at session start
- User memories: role, preferences, things to avoid
- Project memories: ongoing work, decisions, deadlines
- Feedback memories: corrections from past sessions
Every session starts with a load-session hook that reads these files. Every session ends with a save-session hook that writes them. The result: Claude picks up where it left off, even days later.
Agents: Sonnet for Grunt Work, Opus for Reasoning
One of the things I learned the hard way: running everything on the expensive model wastes quota on mechanical work.
The blueprint ships with 12 agents, each pinned to the right model tier:
- Opus for reasoning, planning, architecture review
- Sonnet for mechanical work: writing tests, generating docs, running grep sweeps, refactoring
The main Claude Code session (Opus) orchestrates. Sonnet subagents do the bulk work. Your expensive quota goes to the decisions that need it.
Skills: Repeatable Workflows
Skills are slash commands that invoke multi-step workflows. The blueprint ships 17:
| Skill | What It Does |
|---|---|
| eview-full | Full PR review across security, logic, tests, style |
| deploy-check | Pre-deploy checklist for your stack |
| est-check | Run tests, check coverage, flag gaps |
| sprint-plan | Turn a backlog into a sprint with estimates |
| load-session | Restore context from memory at session start |
| save-session | Write session state to memory at session end |
| self-review | Review your own diff before pushing |
Hooks: Zero Token Cost
Hooks run outside Claude's context window. They cost zero tokens. They are the highest-leverage place to add guardrails.
The blueprint ships 12:
- pre-commit-secret-scan: blocks commits with hardcoded credentials
- protect-config: blocks edits to CLAUDE.md and hook files without confirmation
- cost-tracker: tracks token spend per session
- session-checkpoint: saves state every N minutes automatically
- block-git-push: enforces push policy (feature branches only, no direct main)
Who Is It For?
Any developer using Claude Code who wants more reliable, consistent behavior. The blueprint is framework-agnostic -- it configures Claude's behavior, not your code.
There are four presets if you want a guided start:
ash
./setup.sh --preset=minimal # CLAUDE.md + 3 core hooks
./setup.sh --preset=standard # + agents + skills
./setup.sh --preset=full # everything
Translations
The README and setup docs are available in Japanese, Korean, and Chinese. The community contributed these.
Get It
GitHub: github.com/faizkhairi/claude-code-blueprint
MIT licensed. Copy what you need. Leave the rest.
If it is useful, a star helps others find it.