13. Curing AI Amnesia (CLAUDE.md and Rules)
Show notes
In Episode 13 of Beyond Prompting, author Sho Shimoda breaks down how to configure persistent repository instructions using CLAUDE.md and rule files. Rather than treating CLAUDE.md as a generic style guide or dumping ground for historical bugs, this episode focuses on treating instruction files as a concise briefing for a capable colleague. We cover:
- The 200-Line Rule: Why CLAUDE.md should be kept concise (under ~200 lines) by focusing strictly on non-derivable facts, build environments, and explicit boundaries—leaving out generic advice and formatting rules the model can see for itself.
- Concatenative Inheritance: How instruction files concatenate rather than override across four scopes: managed enterprise policy, user-level ~/.claude/CLAUDE.md, project ./CLAUDE.md, and uncommitted ./CLAUDE.local.md.
- Scoped Rules (.claude/rules/): How to split large instruction sets into modular files inside .claude/rules/ using paths: frontmatter globs so that topic-specific rules (like frontend React conventions) only load when matching files are opened.
- Deterministic Tools vs. Reasoning Context: Why mechanical syntax and formatting rules belong in deterministic linters and git hooks, reserving CLAUDE.md for architectural context and edge-case rationale that static analysis cannot check.
- Preventing Instruction Sediment: Using CLI commands like /init, /memory, and /doctor to audit, prune, and maintain instruction files like code.
(Note for listeners: This episode covers Chapter 13 of Sho Shimoda's book RUNNING CLAUDE: The Operator’s Guide to Chat, Cowork and Claude Code, available on Amazon as the successor book to Master Claude: Chat, Cowork and Code).