Split your CLAUDE.md into a phased plan
clevotics-claude-bootstrap is a free Claude Code skill that turns one project plan or one overloaded CLAUDE.md into focused docs and a phase-by-phase PLAN.md, so Claude reads only what each task needs.
- Command
- 1
- Focused docs
- 5
- Mac and Windows
- Free
Install it in one command
You need Node.js 18 or newer and Claude Code. Open a terminal in your project folder and run the command below. It asks where to install the skill: press Enter for this project, or choose 2 for every project on your machine.
$ npx clevotics-claude-bootstrap@latest
Where should the project-bootstrap skill be installed?
1) This project only (/your/project)
2) Global, all projects (~/.claude)
Choose 1 or 2 [1]:This project (recommended)
Writes .claude/skills/project-bootstrap/ into the repo. Commit it and everyone who clones the repo gets the skill.
Global
Writes the skill to ~/.claude/skills/ on macOS and Linux, or %USERPROFILE%\.claude\skills on Windows, for every project you open.
Skip the question
Add the scope at the end: npx clevotics-claude-bootstrap@latest project or npx clevotics-claude-bootstrap@latest global.
Five docs, one job each
Every fact lives in exactly one doc and the others link to it. CLAUDE.md stays small because it only routes and states the rules.
The router
CLAUDE.md
Short on purpose. Hard rules, commands, and a "read when needed" table that tells Claude which doc to open for which task.
Loaded: Every session
Product
docs/PRD.md
What you are building and for whom: users, features, out of scope and the terms the UI must use. No technology.
Loaded: Product questions
Technology
docs/ARCHITECTURE.md
Stack, repo layout, data model, modules, API contract, security rules, performance budgets and a dated decisions log.
Loaded: Backend and data work
Interface
docs/DESIGN.md
Design tokens, components and their loading, empty and error states, layout and copy rules. Created only when the project has a UI.
Loaded: UI work
The work
docs/PLAN.md
Small numbered phases, each with a goal, tasks, testable exit criteria and a status: TODO, IN PROGRESS, PARKED or DONE.
Loaded: Starting or finishing a phase
Your original plan is kept
The source Project Plan.md moves into docs/ unchanged, as the record of where the project started.
## B2 - Bookings API
**Goal:** staff can create and cancel bookings
**Depends on:** B1
**Tasks**
- [ ] bookings table, migration and indexes
- [ ] POST /bookings, DELETE /bookings/{id}
**Exit criteria**
- double booking the same slot returns 409
- GET /bookings returns 50 rows under 300 ms
**Result:** (filled in when DONE)Starting a new project
Use this when the repo has nothing but your plan. CLAUDE.md is written last, once the docs it routes to exist.
- 01
Start with only your plan
Create the project folder and put a single Project Plan.md in it. Write it in your own words: what the product does, who uses it, the features and any rules you already know.
- 02
Install the skill
Open a terminal in that folder, run npx clevotics-claude-bootstrap@latest and press Enter to install it for this project.
- 03
Restart Claude Code
Close Claude Code if it is already open, then start it again in the same folder. Skills load at startup, so a session that was open during the install will not see it.
- 04
Run /project-bootstrap
In Claude Code, type /project-bootstrap and press Enter. Claude reads your Project Plan.md and starts splitting it.
- 05
Answer the open questions
Claude asks about decisions your plan leaves open, such as stack, auth or hosting, at most four at a time with a recommended option first.
- 06
Build phase by phase
Review the new docs, then say "start phase 1". Claude builds one phase, tests it against its exit criteria and marks it DONE in PLAN.md.
Applying it to an existing project
Use this when the project already has a CLAUDE.md, docs or code. The rule is restructure, never lose anything.
- 01
Commit your current work
Start from a clean git state so you can compare every doc change and undo anything you do not like.
- 02
Install the skill
In the project folder, run npx clevotics-claude-bootstrap@latest and press Enter to install it for this project.
- 03
Restart Claude Code
Close Claude Code if it is already open, then start it again in the project folder. Skills load at startup, so a session that was open during the install will not see it.
- 04
Run /project-bootstrap
In Claude Code, type /project-bootstrap and press Enter. Claude detects the existing project and reads your CLAUDE.md, every doc, your package files and recent git history.
- 05
Approve the mapping
Claude shows which existing section moves to which new doc. Nothing is written until you say go.
- 06
Review and clean up
Your old file is saved as docs/CLAUDE.md.bak, built work appears as DONE phases and every old heading is accounted for. Delete the backup once you are happy.
$ npx clevotics-claude-bootstrap@latest
✓ Skill installed. Your CLAUDE.md is about to get a lot lighter.
$ brew coffee --for clevoticsSaved you some tokens? Buy me a coffee
The bootstrap is free and stays free. A coffee in any amount you choose, in US dollars, pays for the next skill.
Claude reads only what the task needs
Claude Code loads CLAUDE.md into every session. When product notes, stack details, rules and to-do lists all live in that one file, every task pays for all of it and the important rules get buried.
After the split, a UI fix loads CLAUDE.md and DESIGN.md. A database change loads CLAUDE.md and ARCHITECTURE.md. Less noise means rules are followed more reliably.
PLAN.md changes how the work happens too. Instead of "build the app", Claude finishes one small phase, proves it against the exit criteria and marks it DONE before the next one starts.
| File | When it is loaded | Approx tokens |
|---|---|---|
| CLAUDE.md | Every session, automatically | 2,250 |
| PRD.md | Only for product questions | 2,950 |
| ARCHITECTURE.md | Only for backend or data work | 29,750 |
| DESIGN.md | Only for UI work | 11,050 |
| PLAN.md | When starting or finishing a phase | 18,450 |
| All in one CLAUDE.md | Every session | 64,450 |
A task that needs every doc still reads every doc. On a small project with a short CLAUDE.md the token saving is minor, and the gain is structure and the phased plan.
Built for teams as well as solo developers
Clear ownership
Each doc has one owner: product managers own the PRD, architects own ARCHITECTURE.md, designers own DESIGN.md and tech leads own PLAN.md.
Reviewed like code
The docs live in the repo, so a changed rule or decision goes through the same pull request review as any code change.
Same rules for every developer
Installed per project, the skill and the docs are committed, so every developer's Claude Code follows the same rules on every machine.
Faster onboarding
A new developer reads PLAN.md and knows what is done, what is in progress and what comes next, without asking anyone.
Common fixes
/project-bootstrap is not recognised
Restart Claude Code in the project folder. Then check that .claude/skills/project-bootstrap/SKILL.md exists in the project, or in your home folder for a global install. Folders starting with a dot are hidden in Finder and Explorer by default.
npx says command not found
Install Node.js 18 or newer from nodejs.org, then open a new terminal and check with node -v.
Windows PowerShell blocks npx
PowerShell can block npx.ps1 under the default execution policy. Run the same command in Command Prompt, or use npx.cmd in place of npx.
It installed in the wrong place
Run it again and pass the scope directly: add project to install in the current folder or global to install for all projects.
An old version keeps running
Keep @latest at the end of the package name. Without it, npx can reuse a copy it cached earlier.
About the Claude Code bootstrap
What is clevotics-claude-bootstrap?
clevotics-claude-bootstrap is a free npm installer for a Claude Code skill that turns one project plan, or one overloaded CLAUDE.md, into a structured doc set: a short CLAUDE.md, PRD.md, ARCHITECTURE.md, DESIGN.md and a PLAN.md split into small numbered phases with testable exit criteria.
Does clevotics-claude-bootstrap change my code?
No. The project-bootstrap skill only creates and reorganises markdown docs. On an existing project it shows its plan first, waits for approval and saves the old CLAUDE.md as docs/CLAUDE.md.bak before rewriting it.
Does splitting CLAUDE.md into multiple files save tokens?
Yes, when the project docs are large. Claude Code loads CLAUDE.md into every session but reads the other docs only when a task needs them. On one real project this cut the instructions loaded at startup from about 64,500 tokens to about 2,250. On small projects the saving is minor and the main gain is structure.
Can I use the bootstrap skill on a project that already has a CLAUDE.md?
Yes. The project-bootstrap skill has an existing project mode. It reads the current CLAUDE.md, docs and git history, moves each section to the doc that owns it, marks already built work as DONE phases and lists where every old heading now lives.
Does clevotics-claude-bootstrap work on Windows?
Yes. The installer is written in Node.js and runs the same way on Windows, macOS and Linux. It needs Node.js 18 or newer and Claude Code.
Should I install the skill per project or globally?
Install it per project when working in a team, so the skill is committed to the repo and every developer gets it. Install it globally when you want the skill available in every project on your own machine.
Want a team that builds this way?
Clevotics ships custom software and AI automation phase by phase, with every phase tested against its exit criteria before the next one starts.
Book a free demoMore free resources
Try the AI slash commands for ChatGPT, Claude and Gemini, or browse every guide.
Browse all resources