Help us improve
Share bugs, ideas, or general feedback.
From codebase-health
Updates and optimizes project docs like CLAUDE.md, README, and CHANGELOG by inventorying files, analyzing git history, and ensuring AI agent compatibility.
npx claudepluginhub jeffrigby/somepulp-agents --plugin codebase-healthHow this skill is triggered — by the user, by Claude, or both
Slash command
/codebase-health:docs-maintenanceThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Comprehensive methodology for keeping project documentation current, consistent, and optimized for AI coding agents.
Updates, refreshes, optimizes, and cleans up CLAUDE.md by exploring codebase, removing stale content, and restructuring for scannability. Use when docs are out of sync.
Implements two-phase workflow to analyze code changes via git diff and update project documentation. Use before merging branches, after features/bugfixes, or when docs stale.
Updates CLAUDE.md files with non-obvious conventions and gotchas from staged git changes. Activates on user requests like 'update CLAUDE.md' or significant code modifications.
Share bugs, ideas, or general feedback.
Comprehensive methodology for keeping project documentation current, consistent, and optimized for AI coding agents.
CLAUDE.md or .claude/CLAUDE.md - AI agent instructions (highest priority)CLAUDE.local.md - Deprecated. Use ~/.claude/CLAUDE.md or @ imports instead.claude/rules/*.md - Modular rules (may have paths frontmatter for scoping)README.md - Project overviewCHANGELOG.md - Version history/docs/ directory - Extended documentation@path imports in CLAUDE.md that reference additional filesgit log --oneline --since="$(git log -1 --format=%ci -- CLAUDE.md)"
Target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. If over 200 lines:
@path/to/file imports to reference additional files.claude/rules/ directoryCheck for proper use of the CLAUDE.md ecosystem:
/Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux), C:\Program Files\ClaudeCode\CLAUDE.md (Windows). Cannot be excluded.~/.claude/CLAUDE.md - user-level personal preferences (all projects)./CLAUDE.md or ./.claude/CLAUDE.md - project instructions (checked into git).claude/rules/*.md - modular, topic-specific rules (can use paths frontmatter for scoping)@path imports - for referencing additional files without duplicating contentCLAUDE.local.md - deprecated; recommend ~/.claude/CLAUDE.md or @ imports insteadNot every project needs all of these. Include only what's relevant, and only content Claude couldn't figure out by reading the code:
Include: Bash commands Claude can't guess, code style rules differing from defaults, testing instructions, repo etiquette, architectural decisions, dev environment quirks, common gotchas.
Exclude: Anything Claude can figure out by reading code, standard language conventions, detailed API docs (link instead), frequently changing info, long tutorials, file-by-file codebase descriptions, self-evident practices.
npm test" not "You can run tests")IMPORTANT or YOU MUST for critical instructions (use sparingly).claude/rules/ (Claude picks arbitrarily)@path imports or link to docs instead of pastingFollow Keep a Changelog format:
Categories:
Best Practices:
Stale Documentation Signs:
Freshness Commands:
# Last doc update vs last code change
git log -1 --format=%ci -- CLAUDE.md
git log -1 --format=%ci -- "*.ts" "*.js" "*.py"
# Files changed since last CLAUDE.md update
git diff --name-only $(git log -1 --format=%H -- CLAUDE.md)..HEAD
See the reference documents for detailed guidance:
references/claude-md-guide.md - CLAUDE.md optimization patterns and section templatesreferences/changelog-patterns.md - Keep a Changelog format and git extraction techniquesreferences/doc-sync-methodology.md - Git commands, pattern detection, and automation