refresh-claude

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