claude-md-sync

Keep CLAUDE.md documentation in sync with codebase evolution. Use when user says "sync claude.md", "update claude.md", "check claude.md", or when project structure, tech stack, or architecture has changed and documentation may be outdated.

SKILL.md

---
name: claude-md-sync
description: Keep CLAUDE.md documentation in sync with codebase evolution. Use when user says "sync claude.md", "update claude.md", "check claude.md", or when project structure, tech stack, or architecture has changed and documentation may be outdated.
---

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

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

For JSON output (useful for programmatic processing):

```bash
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:

1. **New directories/features** - Added files in new locations
2. **API changes** - New or modified API routes
3. **Tech stack changes** - New dependencies or tools
4. **Architecture changes** - Structural reorganization
5. **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