claude-md-maintenancelisted

# CLAUDE.md Maintenance ## The Self-Healing Pattern When Claude makes the same mistake twice, it should update CLAUDE.md to prevent a third occurrence. This is "self-healing" — the system learns from its errors. The cycle: 1. Claude makes mistake X 2. User corrects Claude 3. Claude makes mistake X again 4. Claude (or user) adds a rule to CLAUDE.md: "Don't do X. Do Y instead." 5. Mistake X doesn't happen again This is why the Gotchas section exists. It grows organically from real problems encountered during development. ## The 200-Line Target CLAUDE.md should stay under 200 lines of actual content. This is the official Claude Code guidance and matches `worclaude doctor`'s WARN threshold (150 lines / 30,000 chars) and ERROR threshold (200 lines). It is a target, not a hard limit, but exceeding it significantly means CLAUDE.md is trying to do too much. Claude reads CLAUDE.md at the start of every session and after every /compact. Long CLAUDE.md files waste context on every single interaction. ## What Belongs in CLAUDE.md YES: - Project identity (name, one-line description) - Key file pointers (PROGRESS.md, SPEC.md) - Tech stack and build/test/run commands - Session protocol (start/during/end) - Critical rules (5-10 maximum) - Gotchas (grows, but prune regularly) - Skills pointer (list of available skills) NO: - Detailed coding standards (put in a skill) - Architecture documentation (put in a skill or docs/) - API documentation (put in docs/) - Full workflow description