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

Why CLAUDE.md Sync Matters

┌─────────────────────────────────────────────────────────────────┐
│                    TWO AUDIENCES                                 │
├────────────────────────────┬────────────────────────────────────┤
│       CONSTITUTION         │           CLAUDE.MD                │
├────────────────────────────┼────────────────────────────────────┤
│ Audience: Humans           │ Audience: AI Agents                │
│ Purpose: Governance        │ Purpose: Runtime Instructions      │
│ Format: Detailed           │ Format: Actionable                 │
│ Contains: Rationale        │ Contains: Rules + Commands         │
│ Updated: Deliberately      │ Updated: Must track constitution   │
└────────────────────────────┴────────────────────────────────────┘

If CLAUDE.md diverges from the constitution, AI agents operate with outdated or incorrect guidance, undermining governance.

Consequences of Drift:

• Agents may use deprecated technology choices
• Quality gates may be bypassed due to outdated thresholds
• Principles may be violated because agents are unaware of new rules
• Commit conventions may be inconsistent
• Code review may miss violations that the constitution now prohibits

Benefits of Synchronization:

• Agents always operate with current governance rules
• Quality gates are consistently enforced
• New principles are immediately actionable
• Version tracking provides audit trail
• Human and AI guidance remain aligned

Mandatory Sync Mapping

The following sections MUST be synchronized:

Sync Rules

Two primary sync rules govern how content transfers:

Rule 1: MUST List All With Enforcement

Principles are summarized but preserve enforcement keywords, metrics, and thresholds. Rationale is omitted because CLAUDE.md focuses on actionable rules, not justification.

What to preserve:

• RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT)
• Numeric thresholds (coverage ≥80%, complexity ≤10)
• Enforcement mechanisms (CI blocks, code review required)
• Quality gate commands (pytest --cov-fail-under=80)

What to omit:

• Rationale sections (why the rule exists)
• Historical context
• Detailed examples (unless critical for understanding)

Rule 2: MUST Match Exactly

Tables are copied directly with no summarization. This applies to:

• Technology Stack tables
• Quality Gates tables
• Layer Import Rules
• Project Structure (if present)

Why exact match: These sections contain precise configuration that agents must follow exactly. Summarization risks losing critical details like specific tool versions or threshold values.

See references/SECTION-TEMPLATES.md for detailed templates and examples for each sync rule.

Synchronization Process

The sync process follows six steps:

Step 1: Read Both Files

Load the constitution and CLAUDE.md. Verify both files exist and are readable. If CLAUDE.md does not exist, create it from the section templates.

Step 2: Extract Mapped Sections

For each row in the Mandatory Sync Mapping table, locate the corresponding sections in both files. Note any missing sections.

Step 3: Identify Gaps

Create a gap report documenting drift between files:

## Sync Gap Report

**Constitution Version**: 2.1.0
**CLAUDE.md Version**: 2.0.0

### Gaps Found

| Section | Constitution | CLAUDE.md | Gap Type |
|---------|--------------|-----------|----------|
| Quality Gates | coverage ≥80% | coverage ≥70% | Value mismatch |
| Principles | 7 principles | 6 principles | Missing content |
| Version | 2.1.0 | 2.0.0 | Version drift |

### Recommended Actions
1. Update CLAUDE.md Quality Gates: 70% → 80%
2. Add Principle VII to Principles Summary
3. Update version footer to 2.1.0

Step 4: Generate Updates

Prepare specific changes needed. For each gap, draft the exact text change required. Preview changes before applying.

Step 5: Apply Updates

Update CLAUDE.md with synchronized content. Apply changes section by section, preserving any CLAUDE.md-specific content not in the mapping.

Step 6: Validate Alignment

Run the Quick Validation checklist. All items must pass before considering sync complete.

See references/SYNC-PATTERNS.md for detailed process steps, validation checklists, and conflict resolution.

CLAUDE.md Structure

CLAUDE.md includes these sections for proper sync:

Required Sections

Optional Sections

These sections may exist in CLAUDE.md but are not synchronized from the constitution:

• Project Structure: Include if constitution defines directory structure
• Architecture: Include if constitution defines layer rules or import restrictions
• IDE Setup: Project-specific, not from constitution
• Local Development: Project-specific, not from constitution
• Troubleshooting: Project-specific, not from constitution

Optional sections are preserved during sync—they are not deleted or modified.

See references/SECTION-TEMPLATES.md for the complete structure template.

Sync Triggers

CLAUDE.md synchronization MUST occur when:

1. Constitution amended: Any version bump requires sync check
2. New principle added: MUST appear in Principles Summary
3. Principle removed: MUST be removed from Principles Summary
4. Quality gate changed: MUST update Quality Gates table
5. Tech stack changed: MUST update Technical Stack table
6. Governance changed: MUST update Development Workflow

Conflict Resolution

When CLAUDE.md contains content that conflicts with the constitution:

Scenario 1: CLAUDE.md Has Extra Content

CLAUDE.md may contain project-specific sections not in the constitution (e.g., IDE setup, local development tips). These sections are allowed and should be preserved during sync.

Action: Keep extra sections. Only update mapped sections.

Scenario 2: CLAUDE.md Has Different Values

A mapped section in CLAUDE.md contains different values than the constitution (e.g., different coverage threshold).

Action: Constitution is authoritative. Overwrite CLAUDE.md with constitution values.

Scenario 3: Constitution Section Missing

A mapped section exists in CLAUDE.md but not in the constitution.

Action: Flag for review. Either add section to constitution or remove from CLAUDE.md.

Scenario 4: Version Mismatch

CLAUDE.md version does not match constitution version.

Action: Always align versions. CLAUDE.md version MUST match constitution version after sync. If constitution is v2.1.0, CLAUDE.md footer must show v2.1.0.

Quick Validation

Before completing synchronization, verify:

• All Core Principles listed with enforcement keywords preserved
• Technology Stack table matches exactly (no omissions)
• Quality Gates table matches exactly (thresholds identical)
• Version numbers match (constitution = CLAUDE.md)
• No contradictions between files
• Extra CLAUDE.md sections preserved (not deleted)

See references/SYNC-PATTERNS.md for the complete validation checklist.

Commit Convention

When syncing, use this commit format:

docs: sync CLAUDE.md with constitution vX.Y.Z

- Updated Principles Summary (added Principle VII)
- Updated Quality Gates (coverage 70% -> 80%)
- Version aligned to X.Y.Z

Referenced Files

This skill includes detailed reference documentation:

Related Skills

• For constitution authoring: OPTIONAL: Use humaninloop:authoring-constitution before syncing (greenfield)
• For brownfield projects: OPTIONAL: Use humaninloop:brownfield-constitution before syncing
• For validation: OPTIONAL: Use humaninloop:validation-constitution to verify constitution quality

Converted and distributed by TomeVault — claim your Tome and manage your conversions.