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