CLAUDE.md Sync

Keep CLAUDE.md up-to-date as the codebase evolves. Uses git commit history to efficiently detect changes without scanning the entire codebase.

Workflow

Step 1: Analyze Changes

Run the analysis script to see what changed since last CLAUDE.md update:

python3 .claude/skills/claude-md-sync/scripts/analyze_commits.py .

For JSON output (useful for programmatic processing):

python3 .claude/skills/claude-md-sync/scripts/analyze_commits.py . --json

Step 2: Identify Documentation Gaps

Based on the analysis, check if CLAUDE.md needs updates for:

New directories/features - Added files in new locations
API changes - New or modified API routes
Tech stack changes - New dependencies or tools
Architecture changes - Structural reorganization
Removed functionality - Deleted features that should be removed from docs

Step 3: Suggest Updates

Read current CLAUDE.md and propose specific edits:

Add new sections for significant new features
Update existing sections with new information
Remove outdated information about deleted code
Keep descriptions concise and accurate

Step 4: Apply Changes

After user approval, use Edit tool to update CLAUDE.md with the proposed changes.

What the Script Analyzes

The analyze_commits.py script:

Finds last commit that modified CLAUDE.md
Collects all commits since then
Categorizes file changes by type:
- API Routes, Pages, Components, Contexts
- Utilities, Mastra (AI Layer), Supabase
- Documentation, Configuration, Database

Example Output

# Git Changes Analysis

**Commits analyzed:** 5
**Date range:** 2026-02-01 → 2026-02-05

## Recent Commits
- Add user authentication flow
- Implement Mastra agent scaffolding

## ➕ Files Added (3)
### Mastra (AI Layer)
- `src/mastra/agents/tutor.ts`
- `src/mastra/tools/youtube.ts`

Guidelines

Only suggest updates for significant structural changes
Keep CLAUDE.md concise - it shares context window with conversations
Prefer updating existing sections over adding new ones
Remove stale information about deleted functionality

claude-md-sync