Aller au contenu

Rules hygiene

Use this when editing or creating any agent rule / instruction file (.cursor/rules/**/*.mdc, .cursor/skills/**/*.md, CLAUDE.md).

These are loaded into Claude's context window on every relevant request. Every line is a token tax. Apply the checks below before saving.

Budget

  • Hard cap: 200 lines per file. Anthropic-confirmed threshold for instruction adherence; past that, models silently drop rules.
  • Soft target: ≤ 120 lines for topical rules, ≤ 100 for always-loaded files (root CLAUDE.md, sub-app claude-*.mdc).
  • Total subfolder budget: ≤ 800 lines across topical rules — past that, signal/noise drops.

Long rule? Either split it, or move detail into a code comment / PR description and link.

Five-rule checklist

  1. Lead with the why. A reader skimming a bullet should learn the reason, not the mechanism. "Use bg-card for white surfaces — bg-background is cream #f9f5f1" beats "Always use bg-card instead of bg-background". One short sentence.
  2. Don't restate root. If claude-root.mdc already says it (strict typing, no console.log, no relative imports, comments-DRY, …), don't echo it in the sub-app. Link instead: [Root rule X](https://github.com/brickssas/monorepo/blob/develop/.cursor/skills/claude-root.mdc).
  3. One canonical home per fact. New cross-cutting pattern → root or sub-app claude-*.mdc. New topical pattern → the right .mdc. No third copy. Use [link](https://github.com/brickssas/monorepo/blob/develop/.cursor/skills/rules-hygiene/other.mdc) from the secondary location.
  4. ❌ lists only for traps the positive rule can't express. Skip the negative mirror of a "Hard rule" you just wrote — restating it as ❌ Don't do the opposite of X doubles the token cost for zero new info. Keep ❌ for non-obvious foot-guns ("❌ form.setValue to swap a discriminated-union variant — silently doesn't propagate").
  5. Stale fast. Any cited path / version / helper / module name must exist today. If you can't verify in 30 seconds (Read / Grep / package.json), don't cite it.

Self-checks before saving

  • wc -l <file> ≤ 200? If not, find the longest section and cut.
  • Grep for the new bullet's substance across .cursor/rules/ — already exists elsewhere? Link to it instead of duplicating.
  • Every cited path / symbol exists? Read or Glob each one. Versions match package.json?
  • Could this be a code comment instead? If it explains what code does (mechanism), it belongs in the code, not the rule.
  • True/false testable? "Short and concise" is not a rule; "≤ 200 lines" is. Each rule should be either followed or not, with no judgment call.

When to run the full audit

Before merging a PR that touches rule files, run /rules-hygiene (or /rules-hygiene <scope> for a subfolder) — it sweeps for length, duplication, and stale claims across the whole tree.