Skip to content

Jeonhui/claude-code-blueprint

BranchesTags

Repository files navigation

Claude Code Blueprint

Give every AI coding agent full context about your project — automatically.

Version License MCP

Quick Start · blueprint · blueprint-mcp · blueprint-audit · Project Structure

한국어

What is Claude Code Blueprint?

AI coding agents (Claude Code, GitHub Copilot, OpenAI Codex, Google Gemini) work best when they deeply understand your project — its conventions, architecture, tech stack, and tooling. But maintaining that context manually is tedious, error-prone, and has to be repeated for every agent.

Claude Code Blueprint (CCB) treats AI context as infrastructure. One command scans your project and generates everything AI agents need to work effectively — managed from a single .claude/ directory.

What Makes CCB Different

  • Markdown-native — No database, no build step. All config is plain markdown — readable, diffable, version-controllable.
  • Write once, run on every agent — Define context once in .claude/, export to Claude, Codex, Gemini, and Copilot with one command.
  • Composable knowledge — Skills, rules, agents, commands, and hooks as independent blocks. Mix, match, swap freely.
  • Role Specification Protocol — Audit commands are generic executors. Swap the agent file → behavior changes entirely.
  • Zero intrusion — Everything in .claude/. Delete the folder to fully revert. Source code untouched.
  • Auto-detect + manual override — Scans your stack automatically, but every generated file is hand-editable.
block-beta
  columns 3
  block:bp["blueprint"]:1
    bp1[".claude/ management"]
    bp2["CLAUDE.md generation"]
    bp3["Skills, Agents"]
    bp4["Hooks, Commands"]
    bp5["Cross-agent export"]
  end
  block:mcp["blueprint-mcp"]:1
    mcp1["Stack analysis"]
    mcp2["MCP server generation"]
    mcp3["Auto dependency setup"]
  end
  block:audit["blueprint-audit"]:1
    audit1["Code quality review"]
    audit2["Agent-driven fix"]
    audit3["Backlog/Archive/Ledger"]
  end

  space:3

  block:out["Generated Output"]:3
    o1["CLAUDE.md\n(Claude)"]
    o2["AGENTS.md\n(Codex)"]
    o3["GEMINI.md\n(Gemini)"]
    o4["copilot-instructions\n(Copilot)"]
  end

  bp --> out
  mcp --> out
  audit --> out
Loading

Key Concepts

CCB organizes AI context into composable building blocks inside .claude/:

Concept Location Description
Skills .claude/skills/ Domain knowledge packages — reusable sets of conventions and best practices (e.g., REST API design, strict TypeScript rules)
Rules .claude/rules/ Path-scoped coding standards — automatically applied when the agent works on matching files
Agents .claude/agents/ Specialized role definitions — YAML frontmatter + markdown body that define what an agent focuses on and how it behaves
Commands .claude/commands/ Custom slash commands — prompt templates you can invoke with /command-name
Hooks .claude/settings.json Event-driven shell commands — triggered on tool use events (PreToolUse, PostToolUse, etc.)
MCP Servers .claude/mcp-internal/ Project-specific Model Context Protocol servers — generated from your tech stack

These building blocks are independent and composable. Install only what you need, customize freely, and export to other AI agents.

Three Plugins, One System

Plugin Role When to use
blueprint Environment management Always — this is the core that sets up .claude/ and manages all configuration
blueprint-mcp MCP server generation When you want auto-generated MCP servers tailored to your frameworks and databases
blueprint-audit Quality audit When you want agent-driven code review with structured issue tracking and autonomous fixes

Each plugin is installed independently and works standalone, but they share the same .claude/ directory and complement each other.

Requirements

  • Claude Code CLI installed and authenticated
  • Plugin support enabled (Claude Code v1.0+)

Quick Start

# 1. Install plugins
/plugin marketplace add Jeonhui/claude-code-blueprint

/plugin install blueprint@claude-code-blueprint
/plugin install blueprint-mcp@claude-code-blueprint
/plugin install blueprint-audit@claude-code-blueprint

# 2. Initialize project
/blueprint:init
/blueprint:claudemd-generate
/blueprint:export --target all

# 3. Run your first audit
/blueprint-audit:review
/blueprint-audit:status
/blueprint-audit:fix --next

blueprint

Core environment manager — initializes .claude/, generates project context, and manages all Claude Code configuration.

The blueprint plugin is the foundation of CCB. It analyzes your codebase to generate a comprehensive CLAUDE.md that captures your project's tech stack, directory layout, coding conventions, and available scripts. It also provides a full management layer for skills, agents, commands, hooks, and cross-agent exports — letting you build a tailored AI development environment through simple slash commands.

Setup & Diagnostics

Command Description
/blueprint:init Create .claude/ directory structure — never overwrites existing files
/blueprint:status Report memory layers, MCP servers, skills, agents, and rules
/blueprint:claudemd-generate Generate CLAUDE.md with tech stack, commands, and conventions
/blueprint:doctor Diagnose .claude/ integrity, validate paths, auto-fix issues

Content Management

Command Description
/blueprint:skill-add Install a built-in skill (domain knowledge package)
/blueprint:skill-list List installed and available skills
/blueprint:agent-add Install a built-in agent template
/blueprint:agent-list List installed and available agents
/blueprint:agent-create Create a custom agent with model, tools, and system prompt
/blueprint:agent-scaffold Scaffold a standalone Anthropic Agent SDK project
/blueprint:hook-add Add an event-driven hook (event + matcher + shell command)
/blueprint:hook-list List all configured hooks
/blueprint:command-add Create a custom slash command with a prompt template
/blueprint:command-list List custom commands

Cross-Agent Export & MCP

Command Description
/blueprint:inject-directive Inject .claude/ index into root CLAUDE.md
/blueprint:export Generate guide files for Codex, Gemini, and Copilot
/blueprint:tool-generate Create an MCP server template in .claude/mcp-internal/
/blueprint:tool-link Register internal MCP servers in .mcp.json
Built-in Skills
Name Description
rest-api-guide REST conventions — HTTP methods, status codes, URL naming, pagination, error formats
test-convention Testing best practices — AAA pattern, naming rules, mocking strategies
typescript-strict Strict TypeScript — no any, discriminated unions, Result types
git-workflow Git conventions — Conventional Commits, branching strategy, PR guidelines
Built-in Agents
Name Model Tools Role
code-reviewer sonnet Read, Glob, Grep Code quality analysis with severity-rated feedback
debugger sonnet Read, Glob, Grep, Bash Systematic debugging with root cause analysis
test-engineer sonnet Read, Glob, Grep, Bash, Write, Edit Test writing, coverage analysis, flaky test fixes
architect opus Read, Glob, Grep Architecture trade-off analysis and recommendations
security-reviewer sonnet Read, Glob, Grep, Bash OWASP Top 10 audit, secrets detection, CVE checks

blueprint-mcp

Analyzes your project tech stack and generates a custom MCP server tailored to your frameworks, databases, and API patterns.

The blueprint-mcp plugin reads your package.json, config files, and source directory structure to identify which frameworks, ORMs, API patterns, and infrastructure tools you use. It then generates a fully functional MCP server with tools specific to your stack — for example, Prisma schema introspection, Next.js route listing, or GraphQL query helpers. The generated server is placed in .claude/mcp-internal/ and auto-registered in .mcp.json.

Command Description
/blueprint-mcp:analyze Detect frameworks, databases, API patterns, and directory structure
/blueprint-mcp:generate Generate a complete MCP server matching your stack
/blueprint-mcp:setup Install dependencies and register in .mcp.json
Detected Technologies
Category Detected
Frameworks Next.js, Express, NestJS, Fastify, React, Vue, Svelte, Hono, Remix, Vite, Jest, Vitest
Database/ORM Prisma, TypeORM, Drizzle, Mongoose, Sequelize, Knex, Kysely
API Patterns REST, GraphQL (Apollo, Yoga), tRPC, gRPC, WebSocket (Socket.IO, ws)
Styling Tailwind CSS, Emotion, styled-components
Infrastructure Monorepo (workspaces, Turborepo, Nx, Lerna), Package manager (npm, yarn, pnpm, bun)

blueprint-audit

Markdown-based quality audit framework — agent personas scan your code, create structured issues, and apply autonomous fixes, tracked in a human-readable backlog/archive/ledger system.

The blueprint-audit plugin brings structured code quality management to your project. Instead of relying on a single linter or review tool, it uses role-specialized agents — each with its own focus area, checklist, and severity criteria — to scan your code and produce actionable issues. Issues are tracked entirely in markdown files (no external database), making them easy to read, diff, and version-control. Optimizer agents can then autonomously fix issues, with all changes logged in a ledger for full traceability.

How It Works

flowchart LR
  A["Agents\naudit-logic\naudit-style\ncustom..."] -->|"review\nscan + create"| B["Backlog\nREVIEW-2026-02-20-001.md\n(all issues in one file)"]
  B -->|"fix\nupdate status + log"| C["Archive\nREVIEW-2026-02-20-001.md\n(all FIXED)"]
  B --> L["LEDGER.md\nfull fix history"]
  C --> L
Loading

Each review run produces a single consolidated file containing all issues found. Issues are fixed in-place by updating their status. When all issues in a review file are resolved, the file moves to archive.

Workflow Overview

1. REVIEW ──→ 2. STATUS ──→ 3. FIX ──→ 4. STATUS
   scan code     check        fix an      verify
   create        dashboard    issue       progress
   issues

Step 1 — Review: Auditor agents scan your code and create issues.

/blueprint-audit:review

Step 2 — Check status: See what was found.

/blueprint-audit:status

Step 3 — Fix: Apply a fix to the highest-priority issue.

/blueprint-audit:fix --next

Step 4 — Repeat until all issues are resolved.

Role Specification Protocol

Review and fix are generic executors — all behavior comes from the agent's role spec file.

# .claude/agents/audit-logic.md
---
name: audit-logic
type: auditor                    # "auditor" for review, "optimizer" for fix
focus: "Logic defects, race conditions, null references"
scan_patterns:
  - "src/**/*.{ts,tsx,js,jsx}"
ignore_patterns:
  - "**/*.test.*"
---
# Review Checklist
- Infinite loops or unbounded recursion
- Missing exception handling ...
  • Swap the agent file → review/fix behavior changes entirely
  • Custom agents work identically to built-in ones
  • Name resolution: -b logic and -b audit-logic both resolve to audit-logic.md

Commands Reference

Review

Scan project files with auditor agents and create issues in the backlog.

/blueprint-audit:review                    # run all auditor agents
/blueprint-audit:review -b logic           # specific agent (short form)
/blueprint-audit:review -b audit-logic     # specific agent (full form)
/blueprint-audit:review -s "src/**/*.ts"   # limit scan scope
/blueprint-audit:review -p high            # only report high+ priority
/blueprint-audit:review --dry-run          # preview without creating files
/blueprint-audit:review -b logic -s "src/**/*.ts" -p high --dry-run  # combined
Flag Description
-b, --by <agent> Run a specific auditor agent
-s, --scope <glob> Override agent's scan_patterns
-p, --priority <level> Filter by minimum priority (critical, high, medium, low)
--dry-run Preview issues without writing to backlog

Fix

Fix a specific issue using an optimizer agent, then update status and ledger.

/blueprint-audit:fix -i AUDIT-20260220-001    # fix by ID
/blueprint-audit:fix --next                # auto-pick highest priority
/blueprint-audit:fix --all                 # fix ALL open issues in priority order
/blueprint-audit:fix --next -v             # fix + QA verification
/blueprint-audit:fix --next -b fixer       # use specific optimizer
/blueprint-audit:fix -i AUDIT-20260220-003 --dry-run  # preview fix plan
Flag Description
-i, --id <id> Fix a specific issue by ID
-n, --next Auto-select highest-priority open issue
-a, --all Fix all open issues sequentially in priority order
-b, --by <agent> Use a specific optimizer agent (default: audit-fixer)
-v, --verify Run audit-qa to verify the fix after applying
--dry-run Show what would be changed without editing files

Status

Display the quality audit dashboard.

/blueprint-audit:status                    # full dashboard
/blueprint-audit:status --brief            # one-line summary
/blueprint-audit:status -b logic           # filter by agent
/blueprint-audit:status -p high            # filter by priority

Agent Management

/blueprint-audit:agent-add -n security -t auditor        # create auditor → audit-security.md
/blueprint-audit:agent-add -n perf -t auditor --minimal  # quick create with defaults
/blueprint-audit:agent-add -n opt -t optimizer --from ./spec.md  # import from file
/blueprint-audit:agent-add -n a11y -t auditor --custom   # write your own full spec body

Instructions (for cross-agent use)

/blueprint-audit:review-instruction  # print auditor role specs + review commands
/blueprint-audit:fix-instruction     # print optimizer role specs + fix commands

Copy-paste the output into another agent's context to give it audit capabilities.

Default Audit Agents
Name Type Focus
audit-logic auditor Logic defects, infinite loops, race conditions, null references, resource leaks
audit-style auditor CLAUDE.md compliance, naming conventions, formatting, import organization
audit-fixer optimizer Pattern-based code fixes, minimal targeted changes, best practice application
audit-qa optimizer Fix verification, regression checks, test generation for fixed code
Review File Format

Each review run creates a single consolidated file in .claude/audit/backlog/:

---
review_id: REVIEW-2026-02-20-001
date: 2026-02-20
agents: [audit-logic]
scope: "src/**/*.ts"
total_issues: 3
---

# Review: REVIEW-2026-02-20-001

| ID | Priority | Status | Reviewer | Target | Title |
|:---|:---|:---|:---|:---|:---|
| AUDIT-20260220-001 | high | TO_FIX | audit-logic | src/api/handler.ts:42 | Unhandled null reference |
| AUDIT-20260220-002 | medium | TO_FIX | audit-logic | src/utils/parse.ts:15 | Missing error handling |
| AUDIT-20260220-003 | low | TO_FIX | audit-logic | src/config.ts:8 | Unused variable |

---

## AUDIT-20260220-001: Unhandled null reference in request parser
- **status:** TO_FIX
- **reviewer:** audit-logic
- **priority:** high
- **target:** src/api/handler.ts:42

### Description
The `parseBody()` call on line 42 can return null when...

### Improvement Suggestion
Add a null check before accessing `body.data`...

---

## AUDIT-20260220-002: Missing error handling in parse utility
- **status:** TO_FIX
...

When an issue is fixed, its status changes to FIXED in-place. When all issues in the file are resolved, the file moves to .claude/audit/archive/.

Audit Directory Structure 
graph TD
  agents[".claude/agents/"] --> al["audit-logic.md\nauditor — logic defects"]
  agents --> as["audit-style.md\nauditor — style compliance"]
  agents --> af["audit-fixer.md\noptimizer — code fixes"]
  agents --> aq["audit-qa.md\noptimizer — verification & tests"]
  agents --> ac["...\ncustom agents"]

  audit[".claude/audit/"] --> backlog["backlog/\nREVIEW-*.md (open issues)"]
  audit --> archive["archive/\nREVIEW-*.md (all resolved)"]
  audit --> ledger["LEDGER.md\nFix history log"]
Loading

Project Structure

graph TD
  root["my-project/"] --> claude_md["CLAUDE.md\nProject guide"]
  root --> agents_md["AGENTS.md\nOpenAI Codex"]
  root --> gemini_md["GEMINI.md\nGoogle Gemini"]
  root --> github[".github/"]
  github --> copilot["copilot-instructions.md\nGitHub Copilot"]

  root --> dotclaude[".claude/"]
  dotclaude --> dc_claude["CLAUDE.md\nProject memory"]
  dotclaude --> dc_settings["settings.json\nHooks & preferences"]
  dotclaude --> dc_rules["rules/\nPath-scoped coding rules"]
  dotclaude --> dc_skills["skills/\nDomain knowledge packages"]
  dotclaude --> dc_agents["agents/\nSpecialized agent definitions"]
  dotclaude --> dc_commands["commands/\nCustom slash commands"]
  dotclaude --> dc_mcp["mcp-internal/\nGenerated MCP servers"]
  dotclaude --> dc_audit["audit/\nQuality audit system"]

  dc_audit --> dc_backlog["backlog/\nOpen issues"]
  dc_audit --> dc_archive["archive/\nResolved issues"]
  dc_audit --> dc_ledger["LEDGER.md\nFix history"]

  root --> mcp_json[".mcp.json\nMCP server registry"]
Loading

Delete .claude/ to revert everything. CCB never modifies your source code.

Extending CCB

CCB is designed to be customized. Every component can be added, modified, or removed without affecting others.

Add domain knowledge — install a built-in skill or create your own in .claude/skills/:

/blueprint:skill-add rest-api-guide        # install built-in skill
/blueprint:skill-add typescript-strict     # install another

Create specialized agents — define custom agent roles for your team's needs:

/blueprint:agent-create                    # interactive agent builder
/blueprint:agent-scaffold                  # full Anthropic Agent SDK project

Automate workflows with hooks — run shell commands on tool use events:

/blueprint:hook-add                        # add pre/post tool use hooks

Build project-specific tools — generate MCP servers from your stack:

/blueprint:tool-generate                   # create MCP server template
/blueprint:tool-link                       # register in .mcp.json

Share context with other AI agents — export your .claude/ knowledge:

/blueprint:export --target all             # generate AGENTS.md, GEMINI.md, copilot-instructions.md

Design Principles

Principle Description
Legacy First Never overwrites existing files — only adds what's missing
Encapsulation Everything lives inside .claude/ — delete the folder to fully revert
Modular Intelligence Knowledge split into skills, rules, and agents — loaded on demand
Role Spec Protocol Audit commands are generic executors — all behavior defined by agent role spec files
Area Preservation Exports use marker blocks — user content outside markers is never touched

License

MIT

Jeonhui Lee — @Jeonhui

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors