A project instructions file is read at the start of every session, so every line in it is paid for on every request for as long as the file exists. That single fact decides what belongs in one and what does not. Anything discoverable from the code — the language, the framework, the directory layout — is being restated to a reader who can already see it. What earns its place is the opposite: the test command that needs a flag, the version of Node that breaks the build, the convention a newcomer would guess wrong, the thing that already cost somebody an afternoon. This builder is organised around those categories, estimates what the file costs, and flags the lines that are telling the repository about itself.
Features
Sections prompted by what belongs in them, not by a blank page
A running token estimate — the cost on every request, not once
Flags lines that restate what the code already shows
Flags empty exhortations that change nothing
Warns when the file has grown past the size where it gets skimmed
Notes when there are no headings to prune by
Empty sections are dropped rather than written as blanks
Downloads as CLAUDE.md
How to use the Project Instructions Builder
Name the project
Fill in only the sections you have something non-obvious to say in
Watch the token estimate as it grows
Read the warnings, then download the file
Example
Input
This project is a React app.
Output
Warning: the language and framework are visible from the manifest
The test for a line: could a reader find this out in ten seconds?
Common errors & troubleshooting
The file is flagged as too large. — Move anything only occasionally relevant into a separate document the session can read when it needs it. The instructions file is for what is always true.
A line I wanted is flagged as discoverable. — Ignore the warning if it is genuinely load-bearing. The check is a prompt to ask whether a reader could find it out anyway, not a rule.
Nothing seems to change when I add instructions. — Specific, checkable instructions land far better than general ones. “Use the primitives in components/ui” beats “write clean code”.
Should this be CLAUDE.md or something else? — The content is the same either way. Save it under whichever filename your tooling reads; the structure and the discipline about what goes in it do not change.
Frequently asked questions
What actually belongs in a project instructions file?
Things that cannot be discovered from the code and would otherwise be guessed wrong: the command that needs a flag, the version that breaks the build, the convention that is not visible in any single file, and explicit prohibitions. Everything else is being restated to a reader who can already read it.
How long should it be?
Short enough to still be read. The estimate is shown as you type; past a couple of thousand tokens it is worth asking which lines are genuinely always relevant, because the rest can live in a document that is read on demand.
Why does it flag “write clean code”?
Because it does not change anything. A general exhortation costs tokens on every request and gives no basis for a decision; a specific convention — where logic goes, which primitives to use — does.
Does it matter that this is paid for on every request?
It is the reason the file needs pruning at all. A page of instructions is a small cost once and a meaningful one across thousands of requests, which is why the estimate is shown next to the text rather than hidden.
Can I put secrets or credentials in it?
No — it is read into context on every session and usually committed to the repository. Keep credentials in your environment and refer to them by name if the instructions need to mention them at all.
Related tools
Skill Builder — Write a SKILL.md with the frontmatter checked as you type.
Subagent Builder — Build a subagent definition file with its tools and model set.
Slash Command Builder — Build a custom slash command, with arguments and a tool allow-list.
Context Window Planner — Budget a context window across prompt, tools, history and the reply.
Prompt Cache Planner — Order the blocks of a request so the cacheable prefix is as long as possible.
System Prompt Linter — Find contradictions, dead instructions and unfilled placeholders in a prompt.
More AI & Agents tools
Skill Builder — Write a SKILL.md with the frontmatter checked as you type.
Skill Linter — Paste a SKILL.md and see what stops it being matched to a task.
Subagent Builder — Build a subagent definition file with its tools and model set.
Slash Command Builder — Build a custom slash command, with arguments and a tool allow-list.