sync-claude-md

name	sync-claude-md
description	Sync per-folder CLAUDE.md and AGENTS.md files with context-aware content. Use after structural changes, adding new directories, refactoring, or periodic maintenance to keep folder-level AI instructions current.
license	MIT
metadata	{"author":"samuel","version":"1.0","category":"workflow"}

Sync CLAUDE.md Files

Recursively scan project directories and create or update per-folder CLAUDE.md and AGENTS.md files with auto-detected content including languages, purpose, key files, and test indicators.

When to Use

• After creating new directories or packages
• After a major refactoring that moves files between folders
• After adding a new language or framework to the project
• Periodic maintenance to keep folder context accurate
• When onboarding a new project with many existing directories

Process

Step 1: Run Sync

# Sync all directories (recursive, unlimited depth)
samuel sync

# Preview changes first
samuel sync --dry-run

# Only top-level directories
samuel sync --depth 1

# Overwrite user-customized files
samuel sync --force

Step 2: Review Output

The command reports what happened for each directory:

• Created — New CLAUDE.md + AGENTS.md files generated
• Updated — Existing auto-generated files refreshed with current analysis
• Skipped — User-customized files preserved (no auto-gen marker)

Step 3: Customize as Needed

After syncing, review generated files and add folder-specific instructions:

1. Open any generated CLAUDE.md
2. Add project-specific context below the auto-generated sections
3. The auto-gen marker ensures samuel sync won't overwrite your changes next time — remove it to protect the file from future updates

What Gets Detected

Detection	Examples
Languages	Go, Python, TypeScript, Rust, Java, etc. (by file extension)
Purpose	cmd/ → entry points, internal/ → private packages, tests/ → test files
Key files	main.go, package.json, Dockerfile, Makefile
Tests	*_test.go, test_*.py, *.spec.ts, *.test.js

Update Strategy

Condition	Action
File doesn't exist	Create new file
File has <!-- Auto-generated by Samuel marker	Update (overwrite)
File exists without marker	Skip (user-customized)
--force flag	Always overwrite

Manual Fallback

If the CLI is not available, create per-folder CLAUDE.md files manually:

# folder-name

<!-- Auto-generated by Samuel. Customize with folder-specific instructions. -->
<!-- AI agents load this file when working in this directory. -->

## Purpose

Description of what this folder contains.

## Languages

- Go (10 files)

## Key Files

- `main.go` — Entry point

Post-Sync Verification

After running sync, verify the results:

1. Check that generated content matches folder reality
2. Ensure no sensitive directories received CLAUDE.md files
3. Confirm AGENTS.md mirrors CLAUDE.md in each folder
4. Add custom instructions where auto-detected content is insufficient