Skip to content

Sync CLAUDE.md Files

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

Trigger Description
New directories After creating new packages or modules
Refactoring After moving files between folders
New language/framework After adding a new tech to the project
Periodic maintenance Keep folder context accurate over time
Project onboarding Bootstrap AI instructions for many existing directories

Overview

The samuel sync command walks your project tree and generates context-aware CLAUDE.md (and matching AGENTS.md) files for each directory. It detects:

  • Languages by file extension (Go, Python, TypeScript, Rust, Java, etc.)
  • Purpose by folder name (cmd/ = entry points, internal/ = private packages, tests/ = test files)
  • Key files like main.go, package.json, Dockerfile, Makefile
  • Test files by naming patterns (*_test.go, test_*.py, *.spec.ts)

Usage

Basic Sync

# Sync all directories recursively
samuel sync

# Preview changes without writing
samuel sync --dry-run

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

# Force overwrite user-customized files
samuel sync --force

CLI Flags

Flag Short Default Description
--depth -d -1 Max recursion depth (-1 = unlimited)
--force -f false Overwrite user-customized files
--dry-run false Preview changes without writing files

Update Strategy

The sync command respects user customizations:

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

Protecting Custom Content

Remove the <!-- Auto-generated by Samuel marker from a CLAUDE.md file to prevent future syncs from overwriting your customizations.

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)

Skipped Directories

The following directories are automatically excluded:

  • Hidden directories (.git, .claude, .venv, etc.)
  • Dependency directories (node_modules, vendor, __pycache__)
  • Build output (build, dist, target, .next, .nuxt)
  • Cache directories (coverage, .cache)

Example Generated Content

For a Go package directory, the generated CLAUDE.md might look like:

# internal/core

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

## Purpose

Internal/private implementation packages.

## Languages

- Go (12 files)

## Key Files

- `config.go` — Configuration management
- `registry.go` — Component registry

## Testing

This directory contains test files.

Workflow Integration

With samuel init

When initializing a project, samuel init automatically calls sync with --depth 1 to create CLAUDE.md files for top-level directories.

With AI Agents

Load the sync skill when AI suggests running it:

@.claude/skills/sync-claude-md/SKILL.md

Post-Sync Verification

After running sync:

  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

See Also