Claude Code commands `sync-claude-md`

Setup a global Claude Code slash command that diffs your unstaged changes and untracked files and auto-updates `CLAUDE.md`.

How global slash commands work

Claude Code looks for custom commands in ~/.claude/commands/. Each .md file becomes a /command-name you can invoke from any project.

Step 1 — Create the global commands directory

mkdir -p ~/.claude/commands

Step 2 — Create the command file

cat > ~/.claude/commands/sync-claude-md.md << 'EOF'
# Sync CLAUDE.md from unstaged changes

You are a senior engineer maintaining a living CLAUDE.md for this project.
Your job is to analyze what has changed in the working tree and surgically update CLAUDE.md to reflect those changes — without rewriting sections that are still accurate.

## Phase 1 — Capture the diff

Run the following commands and carefully read every line of output:

```bash
git diff
```

```bash
git diff --stat
```

```bash
git status --short
```

Also read any new untracked files that are relevant to project structure:

```bash
git ls-files --others --exclude-standard
```

## Phase 2 — Read current CLAUDE.md

Read the existing CLAUDE.md in full so you know what is already documented and what needs updating.

## Phase 3 — Analyze the diff

For every changed file, determine:

- Was a new dependency added or removed? (\*.csproj changes)
- Was the architecture changed? (new folder, new project, new layer)
- Were commands changed? (Program.cs, launchSettings.json, Makefile, tasks.json)
- Were new environment variables or config keys introduced? (appsettings\*.json)
- Was the database schema or migration strategy changed? (DbContext, Migrations/)
- Were new API routes or controllers added? (Controllers/)
- Were code conventions changed? (.editorconfig, .globalconfig, Directory.Build.props)
- Were tests added that reveal new patterns? (_Tests_/)
- Was anything removed that CLAUDE.md still documents?

## Phase 4 — Update CLAUDE.md surgically

Rules:

- ONLY edit sections that are directly affected by the diff
- Do NOT rewrite or reformat sections that are still accurate
- If a new section is needed, add it — do not skip it
- If a section is now outdated, update it with the accurate information
- If something was deleted from the codebase, remove it from CLAUDE.md
- Preserve the existing structure and tone
- Every command you write must be one you verified actually exists in this repo

After saving CLAUDE.md, print a concise changelog of exactly what you changed and why, in this format:

**CLAUDE.md Update Summary**

- [Section name]: [what changed and why]
- [Section name]: [what changed and why]
EOF

Step 3 — Verify it’s available

ls ~/.claude/commands/
# should show: sync-claude-md.md

Step 4 — Use it from any project

Open Claude Code in your project terminal and run:

/sync-claude-md

Claude will immediately run the three git commands, read the diff, compare against your current CLAUDE.md, and surgically update only the affected sections.

Optional — Add a faster alias for the diff-only audit

If you also want a lightweight read-only version that reports what’s stale without editing, add a second command:

cat > ~/.claude/commands/audit-claude-md.md << 'EOF'
# Audit CLAUDE.md against unstaged changes

Run these commands and read the output fully:

```bash
git diff
git diff --stat
git status --short
git ls-files --others --exclude-standard
```

Then read the current CLAUDE.md in full.

Compare the diff against CLAUDE.md and produce a gap report in this format:

**CLAUDE.md Gap Report**

| Section       | Status      | Issue                                                            |
| ------------- | ----------- | ---------------------------------------------------------------- |
| Tech Stack    | ⚠️ Stale    | Package X was removed in csproj but still listed                  |
| Commands      | ✅ Accurate | No changes                                                        |
| Configuration | ⚠️ Missing  | New key `Feature:FlagName` added in appsettings.Development.json  |

After the table, list your recommended edits in priority order.
Do NOT modify any files — this is a read-only audit.
EOF

Then use it as:

/audit-claude-md

Final directory structure

~/.claude/
└── commands/
├── sync-claude-md.md ← edits CLAUDE.md automatically
└── audit-claude-md.md ← read-only gap report

Both commands are global and will work in any project that has a CLAUDE.md and a git repo — including your ASP.NET Core project and any future ones.