CLAUDE.md as a Forcing Function: How Writing a Project Constitution Cleans Up Your Tooling

If you have been using Claude Code for a few months across multiple repos, the cheap, ongoing mistake is to keep
adding rules to CLAUDE.md every time the model does something wrong. The list grows, the file becomes a copy
of a prompt template, and the model treats it like static noise.

A more useful pattern that has worked for our team: write CLAUDE.md as a constitution, not a prompt,
and use the constraint itself as a forcing function for cleaning up the underlying tools.

The mental shift is small but practical. Instead of "Claude keeps running the wrong test command, so add
a paragraph explaining how to run tests", write "the test command for this repo is pnpm test <name>",
and ask yourself: why is the test command even ambiguous? If the only way to explain it is a paragraph,
the tooling is the problem, not the prompt.

Three rules we follow:

1. Hard scope, positive form. A line that says "only edit files inside src/<module>/ and
   tests/<module>/. Stop and ask if a change touches anything else" is more reliable than a list of
   "never touch X" rules. Negative-form rules invite the model to find creative workarounds; positive
   rules give it a default and an escalation path.

2. Short or it is wrong. A long CLAUDE.md is a symptom that the team is not investing in
   package.json scripts, internal CLIs, and clear conventions. We cap the file around 2-3KB of
   bullet points. Anything bigger is a hint that a tool needs to be wrapped in a script with a sane
   surface area, not explained in markdown.

3. Memory and retrieval are not CLAUDE.md jobs. CLAUDE.md is for behavior that should apply
   every run (build commands, lint scope, project layout). Past-decision context, code-archaeology
   notes, and "what did I do last week" questions belong to a separate layer — git, a project
   notebook, or, in our case, a local session retrieval tool. Mixing them in CLAUDE.md makes the
   file grow and pollutes the per-run context window.

We did not start out with these rules. We arrived at them after watching CLAUDE.md files balloon
to 30KB and watching Claude ignore half of what we wrote. The cleanest side effect is that the team
also started writing better internal CLIs. When your constitution forces you to express a workflow
in one bullet, you cannot hide behind prose.

If you are just starting with Claude Code, my suggestion is to begin with a deliberately short
CLAUDE.md, watch what the model gets wrong, and let the file stay small. Long CLAUDE.md files
are a sign that the project itself needs more structure, not that the model needs more instructions.

Shelf, the open-source desktop workspace we are building around Claude Code and Codex, is the
project-level retrieval layer we use to find old sessions by project. The link is at
https://github.com/Harukaon/shelf if you want to compare it to your current workflow.

Tags: claudecode, codex, devtools, workflow, ai