Refresh CLAUDE.md

You are refreshing the project's CLAUDE.md file to ensure it stays relevant and useful for future Claude Code sessions.

Purpose

CLAUDE.md serves as persistent context between sessions. When a project evolves, CLAUDE.md should evolve too. This skill:

1. Reviews recent changes to the codebase
2. Identifies new patterns, conventions, or important context
3. Updates CLAUDE.md to reflect current state
4. Removes outdated information

Process

Step 1: Analyze Recent Changes

bash
1# Recent commits
2git log --oneline -20
3
4# Changed files
5git diff --stat HEAD~10..HEAD
6
7# New files
8git diff --name-status HEAD~10..HEAD | grep "^A"

Look for:

• New features or modules
• New dependencies or tools
• Changed conventions or patterns
• New commands or scripts
• Architecture changes

Step 2: Review Current CLAUDE.md

Read the existing CLAUDE.md and identify:

• Outdated information
• Missing new features/tools
• Incorrect commands or paths
• Stale conventions

Step 3: Scan the Codebase

Check for patterns not reflected in CLAUDE.md:

bash
1# Check for new test patterns
2ls -la **/test* **/*test* **/*spec* 2>/dev/null | head -20
3
4# Check for new config files
5ls -la *.config.* .* 2>/dev/null | head -20
6
7# Check package.json/pyproject.toml/etc for new scripts
8cat package.json 2>/dev/null | jq '.scripts' || true

Step 4: Update CLAUDE.md

Make targeted updates:

DO update:

• New commands (dev, test, build, lint)
• New project structure (directories, key files)
• New conventions discovered in code
• Important architectural decisions
• New dependencies that affect how to work with the code

DON'T add:

• Implementation details that change frequently
• Obvious things (e.g., "this is a JavaScript project" for a .js repo)
• Temporary workarounds
• Personal preferences not enforced by tooling

Step 5: Verify Changes

After updating, verify:

• Commands still work
• Paths are correct
• No duplicate sections
• Concise and scannable

Output Format

markdown
1## CLAUDE.md Refresh Summary
2
3### Changes Made
4- Added: [what was added]
5- Updated: [what was updated]
6- Removed: [what was removed]
7
8### Context Discovered
9- [New pattern or convention found]
10- [New tool or command found]
11
12### Recommendations
13- [Suggestions for project improvements]

Guidelines

Keep It Concise

CLAUDE.md should be scannable. Every line should earn its place.

❌ "This project uses React, which is a JavaScript library for building user interfaces..."
✓ "React 18 with TypeScript. See src/components/ for patterns."

Focus on What's Actionable

Include information Claude needs to work effectively:

✓ Commands to run
✓ Key file locations
✓ Conventions to follow
✓ Things to avoid

Avoid Duplication

Don't repeat what's in:

• README.md (user-facing docs)
• Code comments (implementation details)
• Config files (tooling handles it)

Keep It Fresh

Remove information that's:

• No longer accurate
• Covered by tooling (linters, formatters)
• Too detailed for context

Example Updates

Adding a New Command

markdown
1## Commands
2+ npm run e2e        # Run end-to-end tests

Adding a Convention

markdown
1## Conventions
2+ API routes follow REST conventions in `src/api/`
3+ Use `zod` for runtime validation at API boundaries

Removing Outdated Info

markdown
1- ## Legacy
2- The old auth system in `src/auth-old/` is deprecated.

When to Run

• After adding major features
• After significant refactoring
• After adding new tools or dependencies
• Periodically (weekly/monthly) on active projects
• Before onboarding new team members