update-claude-md

---

name: update-claude-md description: Create or update CLAUDE.md with best practices - brevity, universal applicability, progressive disclosure

Update my CLAUDE.md based on: $ARGUMENTS

Current CLAUDE.md: @CLAUDE.md

---

Make targeted updates based on my request. Only explore codebase if essential info is missing.

If my request conflicts with best practices below, still make the update but note the tradeoff.

Best Practices (CLAUDE.md is the highest-leverage config point):

Structure - Cover these if creating/missing critical sections:

• WHAT: Tech stack, project structure, key entry points (critical for monorepos)
• WHY: Project purpose, component relationships, domain terminology
• HOW: Build/test/run commands, verification steps

Length (LLMs follow ~150 instructions reliably; system uses ~50):

• Simple: 30-60 lines | Standard: 60-150 | Complex: 150-300 max

Progressive Disclosure - For complex projects, create separate docs and reference them:

Copydocs/testing.md, docs/architecture.md, docs/conventions.md

Then in CLAUDE.md: "See docs/testing.md for test patterns"

Prefer pointers over copies - Use file:line references instead of pasting code snippets (avoids staleness).

Do: Universal instructions | Imperative language | Verified commands | Reference (don't copy) README

Don't:

• Style rules → use linters, formatters, or Claude Code hooks instead
• Task-specific instructions → gets ignored if not relevant to current task
• File/function enumeration → describe patterns instead
• Auto-generated boilerplate

Bad: Always use camelCase. Document with JSDoc. Good: npm test # Required before PR

Verify: <300 lines, no style rules, universal instructions, commands tested.