Skip to content
IshooThe Ishoo manual

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:

markdown
# 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.
docs/rules/landing.md, from Ishoo's own repository.

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:

toml
[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.rs matches src/tools, not a broader src/.
  • 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:

text
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#

  1. At claim

    The agent names the files it expects to touch. The reply names their areas: “Rules for these files: landing, store”.

  2. On demand

    ishoo_rules with an area or files returns the current pages, and warns about bad addresses and rules past their review date.

  3. In search

    Every rule paragraph is a record ishoo_find can return, ranked higher for the files in play.

  4. Testing, always

    Every project has a built-in testing page on writing tests that catch real regressions. A project's own testing area 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.
markdown
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]
A repealed rule, and a rule marked for review. After its review date a rule still holds; ishoo_rules just says it's due.

Moving from a long CLAUDE.md#

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

  2. One page per area

    Write each area's rules as numbered paragraphs in docs/rules/<area>.md, and add its prefixes to areas.toml.

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

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

Contents