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

# Recent commits
git log --oneline -20

# Changed files
git diff --stat HEAD~10..HEAD

# New files
git 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:

# Check for new test patterns
ls -la **/test* **/*test* **/*spec* 2>/dev/null | head -20

# Check for new config files
ls -la *.config.* .* 2>/dev/null | head -20

# Check package.json/pyproject.toml/etc for new scripts
cat 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

## CLAUDE.md Refresh Summary

### Changes Made
- Added: [what was added]
- Updated: [what was updated]
- Removed: [what was removed]

### Context Discovered
- [New pattern or convention found]
- [New tool or command found]

### Recommendations
- [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

## Commands
+ npm run e2e        # Run end-to-end tests

Adding a Convention

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

Removing Outdated Info

- ## Legacy
- 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