Skip to content

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
Step zero

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.

Terminal, Mac, Windows or Linux
$ 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.

What you get

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.

What a phase in PLAN.md looks like
## 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)
Path A

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.

  1. 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.

  2. 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.

  3. 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.

  4. 04

    Run /project-bootstrap

    In Claude Code, type /project-bootstrap and press Enter. Claude reads your Project Plan.md and starts splitting it.

  5. 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.

  6. 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.

Path B

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.

  1. 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.

  2. 02

    Install the skill

    In the project folder, run npx clevotics-claude-bootstrap@latest and press Enter to install it for this project.

  3. 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.

  4. 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.

  5. 05

    Approve the mapping

    Claude shows which existing section moves to which new doc. Nothing is written until you say go.

  6. 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 clevotics

Saved 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.

Why split the file

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.

Measured on one real Clevotics project (about 4 characters per token)
FileWhen it is loadedApprox tokens
CLAUDE.mdEvery session, automatically2,250
PRD.mdOnly for product questions2,950
ARCHITECTURE.mdOnly for backend or data work29,750
DESIGN.mdOnly for UI work11,050
PLAN.mdWhen starting or finishing a phase18,450
All in one CLAUDE.mdEvery session64,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.

For teams

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.

Didn't work?

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.

FAQ

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 demo

More free resources

Try the AI slash commands for ChatGPT, Claude and Gemini, or browse every guide.

Browse all resources

We use analytics cookies. Privacy Policy