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:
- Reviews recent changes to the codebase
- Identifies new patterns, conventions, or important context
- Updates CLAUDE.md to reflect current state
- 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