claude-code-hygiene

name

claude-code-hygiene

description

Audit and enforce 7 Claude Code best practices that most users get wrong. Checks for CLAUDE.md quality, session hygiene, feedback loops, worktree usage, permission config, prompt specificity, and parallel session opportunities. Use when: starting a new project, onboarding to Claude Code, asked to 'check my setup', 'optimize Claude Code', 'claude code best practices', 'hygiene check', 'am I using Claude Code right', or 'audit my workflow'. Proactively suggest when a project has no CLAUDE.md, when context is filling up, or when the user is doing multiple sequential tasks that could be parallelized.

Claude Code Hygiene

Audit the user's Claude Code setup against 7 high-impact practices. Run checks, report a score, and offer to fix each issue.

Audit checklist

1. CLAUDE.md exists and is useful

• Check project root for CLAUDE.md
• If missing: offer to create one with stack, rules, and test commands
• If exists: verify it has (a) stack/framework, (b) code style rules, (c) test/lint commands
• Score: 0 = missing, 1 = exists but thin, 2 = complete

2. Feedback loop configured

• Check if CLAUDE.md contains test/lint commands (npm test, bun test, pytest, cargo test, etc.)
• Check for "run tests and fix failures before finishing" instruction
• If missing: append feedback loop section to CLAUDE.md
• Score: 0 = no commands, 1 = commands but no "fix before finishing", 2 = complete

3. Prompt specificity (advisory)

• Print: every prompt needs WHAT is broken, WHERE it is, what DONE looks like
• Test: "could Claude do this in one pass without a follow-up question?"

4. Session hygiene (advisory)

• Print: /clear between every distinct task
• If context is high, warn and suggest /clear now

5. Worktree safety

• Check current branch via git branch --show-current
• If on main/master: warn, suggest claude -w branch-name for risky changes
• Score: 0 = on main with uncommitted changes, 1 = on main clean, 2 = feature branch

6. Permission setup

• Check ~/.claude/settings.json and .claude/settings.json for allowedTools
• If unconfigured: suggest --permission-mode auto or scoped allowedTools
• Score: 0 = default, 1 = some tools allowed, 2 = auto or comprehensive

7. Parallel sessions (advisory)

• Print: independent tasks can run as claude -w branch --background

Output format

CLAUDE CODE HYGIENE REPORT
==========================
1. CLAUDE.md          [PASS/WARN/FAIL]  details
2. Feedback loop      [PASS/WARN/FAIL]  details
3. Prompt specificity [INFO]            pattern reminder
4. Session hygiene    [INFO]            pattern reminder
5. Worktree safety    [PASS/WARN/FAIL]  details
6. Permissions        [PASS/WARN/FAIL]  details
7. Parallel sessions  [INFO]            pattern reminder

Score: X/8
Fixes available: [list auto-fixable items]

After reporting, offer to fix each FAIL/WARN automatically.

Auto-fixes

• Missing CLAUDE.md: Detect stack from package.json/Cargo.toml/pyproject.toml/go.mod, detect test command, generate CLAUDE.md
• Missing feedback loop: Append test/lint section to existing CLAUDE.md
• No permissions: Add common allowedTools to .claude/settings.json

Detailed reference

See references/detailed-practices.md for full explanations with examples of each practice.