Data-Wise CLAUDE.md Lifecycle
End-to-end management of CLAUDE.md files: scaffold from project-type templates, sync with project state (audit + fix + optimize), and edit sections interactively. Targets both project-local CLAUDE.md and global ~/.claude/CLAUDE.md.
When to Use
- User asks to create a CLAUDE.md from scratch (new project, missing file)
- User asks to sync / update / audit / fix / optimize an existing CLAUDE.md
- User asks to edit a specific section with preview and validation
- File is over the 150-line budget and needs trimming via pointer architecture
- Version/count drift detected between CLAUDE.md and project sources (
plugin.json,DESCRIPTION, etc.)
When NOT to Use
| Situation | Use Instead |
|---|---|
Applying suggestions from /insights report to global CLAUDE.md |
insights-apply skill |
| Classifying which doc types a feature needs | doc-classifier skill |
| Generating release notes / CHANGELOG | changelog-automation skill |
The boundary with insights-apply: that skill is the rule-applier for one specific source (the /insights report → global CLAUDE.md). This skill is the editor for the full lifecycle (init/sync/edit) of any CLAUDE.md. They share the underlying sync pipeline (utils/claude_md_sync.py) but enter it from different intents.
Three Phases
Phase 1: Init (scaffold)
Create a new CLAUDE.md from a project-type template (lean, < 150 lines, pointer architecture).
| Step | Action |
|---|---|
| 1 | Detect project type: plugin (.claude-plugin/plugin.json), teaching (_quarto.yml + course.yml), r-package (DESCRIPTION) |
| 2 | Scan metadata: version, counts (commands/skills/agents), test count, repo URL, git branch |
| 3 | Populate lean template with discovered values |
| 4 | Show preview with line count vs budget |
| 5 | Create file after confirmation; run post-creation audit |
Flags: --type, --force (overwrite), --dry-run, --global (target ~/.claude/CLAUDE.md)
Refusal: if file exists and --force not set, redirect to sync.
Phase 2: Sync (update + audit + fix + optimize)
Four-phase pipeline against an existing CLAUDE.md.
| Phase | What | Trigger |
|---|---|---|
| Detect | Project type, version source | always |
| Update Metrics | Version, counts, tests, docs% | always |
| Audit | 5 checks + anti-pattern + budget | always |
| Fix | Auto-fix fixable issues | --fix |
| Optimize | Enforce budget, move bloat to detail files | --optimize |
Anti-patterns blocked (refuse to add to CLAUDE.md):
| Pattern | Redirect To |
|---|---|
Release notes (### v\d+) |
docs/VERSION-HISTORY.md |
Diffstats (Files Changed) |
delete |
| "What Shipped" / "Merged PR" | docs/VERSION-HISTORY.md |
"Status: Complete" / Released ✅ |
docs/VERSION-HISTORY.md |
Phase details (### Phase N) |
detail file |
Budget resolution order: .claude-plugin/config.json → package.json claudeMd.budget → default 150. Never store in plugin.json (strict schema rejects it).
Sections: --section status|commands|testing|all (default all).
Phase 3: Edit (interactive section editing)
Open one or more sections in an external editor with TODO hints, validate after.
| Step | Action |
|---|---|
| 1 | Parse sections (H2 headers + horizontal rules) |
| 2 | Display section table with line ranges |
| 3 | User picks section (or all) |
| 4 | Insert <!-- TODO: ... --> hints (unless --no-hints) |
| 5 | Open in editor (default ia, also code / sublime / cursor) |
| 6 | Wait for user to say "done" |
| 7 | Re-read, strip TODO comments |
| 8 | Run post-edit audit (unless --no-validate) |
| 9 | Show diff preview before applying |
iA Writer integration (default): open via AppleScript
osascript -e 'tell application "iA Writer"
activate
open POSIX file "/path/to/CLAUDE.md"
end tell'
Pointer Architecture
The 150-line budget is enforced by pointing out of CLAUDE.md rather than inlining detail:
## References
-> Release history: [VERSION-HISTORY.md](docs/VERSION-HISTORY.md)
-> Architecture: [ARCHITECTURE.md](docs/ARCHITECTURE.md)
-> Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
-> Command reference: [COMMANDS.md](docs/COMMANDS.md)
Claude Code follows markdown links naturally — keep CLAUDE.md as an index, not an encyclopedia.
Global vs Project Targeting
All three phases accept --global / -g:
if "--global" in args or "-g" in args:
target = Path.home() / ".claude" / "CLAUDE.md"
else:
target = Path.cwd() / "CLAUDE.md"
Use global for cross-project rules (workflow, git, safety); use project-local for project-specific commands and structure.
Underlying Utilities
| Utility | Role |
|---|---|
utils/claude_md_detector.py |
Project type detection |
utils/claude_md_template_populator.py |
Lean template variable substitution |
utils/claude_md_sync.py |
4-phase sync pipeline (also called by insights-apply) |
utils/claude_md_optimizer.py |
Budget enforcement + bloat detection |
templates/claude-md/*.md |
Lean templates per project type |
Decision Flow
User intent ─┐
├─► file missing? → Init (Phase 1)
├─► drift / audit needed?→ Sync (Phase 2)
├─► specific section? → Edit (Phase 3)
└─► /insights source? → use `insights-apply` skill
Error Recovery
| Error | Recovery |
|---|---|
| CLAUDE.md not found (sync/edit) | Suggest Init |
| Project type unknown (init) | Offer generic template or --type <name> |
| Over budget after edit/sync | Offer --optimize or manual edit |
| Section not found (edit) | Show available sections + fuzzy suggestion |
| Editor not installed (edit) | List available editors, prompt to pick |
| Anti-pattern submitted | Block, redirect to detail file |
See Also
insights-apply— apply/insightsreport suggestions to global CLAUDE.md (specific source)doc-classifier— decide what doc types a feature needs (sibling inskills/docs/)changelog-automation— release notes / CHANGELOG generation (sibling)/craft:check— invokes sync internally as part of pre-commit validation