syncing-claude-md

# Syncing CLAUDE.md

## Overview

Ensure CLAUDE.md (the primary AI agent instruction file) remains synchronized with the constitution. CLAUDE.md serves a different audience (AI agents) than the constitution (human governance), so synchronization is selective—specific sections map with explicit sync rules.

## When to Use

- Constitution has been amended (any version bump)
- New principle added to constitution
- Principle removed from constitution
- Quality gate thresholds changed
- Technology stack updated
- Governance rules modified
- User explicitly requests CLAUDE.md sync
- After running `humaninloop:authoring-constitution` or `humaninloop:brownfield-constitution`

## When NOT to Use

- **Constitution does not exist yet**: Create constitution first with `humaninloop:authoring-constitution`
- **CLAUDE.md is intentionally project-specific**: Some projects customize CLAUDE.md beyond constitution scope
- **No mapped sections changed**: If amendment only touches rationale or non-mapped sections, sync may not be needed
- **Draft constitution not yet ratified**: Wait until constitution is approved before syncing

## Common Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| Full duplication | CLAUDE.md becomes constitution copy, loses agent-focused format | Use selective sync per mapping table |
| Stale sync | CLAUDE.md lags behind constitution, agents use outdated rules | Sync on every constitution version bump |
| Missing version | No version tracking makes drift undetectable | Always include version footer in CLAUDE.md |
| Partial sync | Some sections synced, others forgotten | Use validation checklist before completing |
| Summary drift | Summarization loses enforcement keywords and thresholds | Preserve MUST/SHOULD/MAY and numeric thresholds |

## Why CLAUDE.md Sync Matters

```
┌─────────────────────────────────────────────────────────────────┐
│                    TWO AUDIENCES                                 │
├────────────────────────────┬──────