refresh-claude

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

Step 1: Analyze Recent Changes

```bash

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

```bash

# 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

```markdown

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]

```

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

Adding a New Command

```markdown

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

```

Adding a Convention

```markdown

+ API routes follow REST conventions in src/api/

+ Use zod for runtime validation at API boundaries

```

Removing Outdated Info

```markdown

• ## Legacy
• The old auth system in src/auth-old/ is deprecated.

```

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