Project memory / Page 43 of 70
This page is one part of The Ishoo manual. The complete manual is a single page, short enough to read in one go: ishoo.app/docs/
Rules
Claude Code skips CLAUDE.md rules most often because they are many, far from the work, and compete with everything else in context. Ishoo keeps rules by area in docs/rules/, and gives an agent only the rules for the files it touches, when it claims. It can't force a model to obey, but it makes rules hard to miss.
A CLAUDE.md starts short and grows. Each surprise adds a line, until it's hundreds of lines about every corner of the project, loaded into every session whether it applies or not. The rule that matters for this change sits beside forty that don't, and the agent weighs them all the same.
Ishoo splits the rules by what they govern. Each area of the code gets one short page. An agent working on the store reads the store's rules; an agent working on the window reads the window's.
A rule page#
One Markdown page per area, made of numbered paragraphs. Each paragraph has a permanent address, the area name and its number:
# Landing
1. **landing.1** Land is one call: commit what's in the worktree (the note is the message), rebase on main, fast-forward main, push, record.
2. **landing.2** No CI run gates a landing. CI runs in the background or at night, never in the agent's way.
3. **landing.3** On a rebase conflict, abort the rebase, name the files and who landed there recently, and let the agent resolve it.Keep each page to about a kilobyte. A rule is a sentence or two saying what to do; the reasons go in a decision, which the rule can cite by its number.
Which files each area covers#
docs/rules/areas.toml maps path prefixes to areas:
[areas.landing]
page = "landing.md"
prefixes = ["src/tools", "src/review.rs"]
[areas.store]
page = "store.md"
prefixes = ["src/store.rs"]
[areas.ui]
page = "ui.md"
prefixes = ["app/", "assets/", "packaging/"]
# Files no rule governs, by choice.
[unmapped]
prefixes = ["LICENSE", ".gitignore"]- The longest matching prefix wins.
src/tools.rsmatchessrc/tools, not a broadersrc/. - Ties share. When two areas match equally long, both apply: one file can carry two sets of rules.
- Ungoverned is written down. Files that no rule covers go under
[unmapped], so “no rules here” is a choice, not an accident.
When a claim names files in no area, or a landing adds one, Ishoo says so in one line:
lib/new.rs is in no rule area, so agents touching it get no rules. Add a prefix to an area, or to [unmapped], in docs/rules/areas.toml.When an agent sees them#
At claim
The agent names the files it expects to touch. The reply names their areas: “Rules for these files: landing, store”.
On demand
ishoo_ruleswith anareaorfilesreturns the current pages, and warns about bad addresses and rules past their review date.In search
Every rule paragraph is a record
ishoo_findcan return, ranked higher for the files in play.Testing, always
Every project has a built-in testing page on writing tests that catch real regressions. A project's own
testingarea replaces it.
Changing a rule#
- Edit the page directly. There's nothing else to update.
- Never renumber or reuse an address. Other files cite
landing.4; it must keep meaning the same thing. Add new rules at the end. - Repeal in place. Replace the text with a pointer, so old citations still lead somewhere.
- Specific beats general. An area's own rule wins over a project-wide one for files in that area.
4. **api.4** Repealed by DEC-09 (2026-10-30); see `api.7`
5. **api.5** Return errors as plain sentences, never codes. [review-by: 2027-03-01]Moving from a long CLAUDE.md#
Sort by files
For each line in CLAUDE.md, ask which files it's about. Lines about the same part of the code form an area.
One page per area
Write each area's rules as numbered paragraphs in
docs/rules/<area>.md, and add its prefixes toareas.toml.Reasons become decisions
Where a rule has a story (“we tried X and it broke Y”), keep the rule to one sentence and record the story as a decision.
Shrink CLAUDE.md
Leave a few lines: use Ishoo, and anything that truly applies to every file. Your agent can do the whole move for you in one issue.