Blueprint Mode
Blueprint Mode is an attempt at creating a stable source of truth in the era of vibe coding and agentic AI assistants.
It attempts to solve the problem if maintainability in code repositories with large amounts of AI code while trying to
stay out of the way. The following axioms are what Blueprint Mode is built on:
When code is the spec, AI rewrites your source of truth at will. We need a high level ground truth that is not changed on a whim.
We want to keep humans in control of system design while letting AI deal with the details of the bulk of the code
More time is spent maintaining a code base than writing the first version
The Problem
Code as the source of truth
This is what you typically get from vibe coding platforms like Lovable or Cursor (out of the box). Documentation is usually
in the form of a README file and code comments.
- Lost intent — you can't tell if code reflects a conscious decision or AI just picking something
- Lost memory — AI forgets why you chose PostgreSQL over MongoDB last week
- Lost consistency — different architectural choices each session
- Lost boundaries — difficult to set up constraints and coding practices
Spec driven development and similar approaches
Traditional spec-driven development tries to solve the "code as truth" problem by creating detailed specifications before writing code. But this introduces its own set of problems:
- Premature detail — you are forced to focus on details that is not yet on top of your mind
- High friction — updating specs is tedious, so developers skip it or stop reading them entirely
- Spec drift — specifications become outdated as code evolves, creating a second source of truth that contradicts the first
- Wrong abstraction level — specs either become too detailed (duplicating code in English) or too vague (unhelpful)
- No context for decisions — specs say what but rarely why - this is important to know when they are outdated
How It Works
- Interview — Claude asks about your project, tech choices, and why you made them
- Document — Decisions become ADRs, patterns get captured, boundaries get set
- Develop — AI follows your documented decisions consistently
- Evolve — Update decisions with
/blueprint:decide or /blueprint:supersede
Quick Start
/plugin marketplace add rickardp/blueprint-mode
/plugin install blueprint-mode
Local development
To run a locally checked out version of the plugin (useful during development):
git clone https://github.com/rickardp/blueprint-mode.git
cd blueprint-mode
claude --plugin-dir ./plugins/blueprint-mode
The --plugin-dir flag loads the plugin directly from the specified directory, overriding any installed version with the same name. This allows you to test changes immediately without reinstalling.
You can also use an absolute path:
claude --plugin-dir /path/to/blueprint-mode/plugins/blueprint-mode
Commands
| Command | Purpose |
|---|
/blueprint:setup-repo | Set up new repository with spec structure |
/blueprint:onboard | Add spec structure to existing codebase |
/blueprint:require | Add functional or non-functional requirements |
/blueprint:decide | Record technology/architecture decisions as ADRs |
/blueprint:good-pattern | Capture approved code patterns |
/blueprint:bad-pattern | Document anti-patterns to avoid |
/blueprint:supersede | Replace previous decisions with new ones |
/blueprint:list-adrs | List all ADRs with status and summaries |
/blueprint:status | Show overview of project's Blueprint structure |
/blueprint:validate | Check code against documented patterns and decisions |
/blueprint:help | Explain Blueprint features and available commands |
Onboarding an existing codebase
/blueprint:onboard
Also, the onboarding pushes the limits for what a skill can really do, so on more complex cases it may be worth running the onboarding multiple times (it will fill in gaps if it skipped over some files in the first run).
Setting up a new repo
/blueprint:setup-repo
Note that this functionality is in its early stages.
What Gets Created
rickardp