shield_lock
金大哥
← 返回 Skill 列表
extension
分类: AI Agent 能力无需 API Key

syncing-claude-md

当用户说“sync CLAUDE.md”、“update agent instructions”、“propagate constitution changes”、“CLAUDE.md sync”或“constitution alignment”时，必须调用此技能。如果用户提到“agent instructions”的更新，也应该调用此技能。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

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                                 │
├────────────────────────────┬────────────────────────────────────┤
│       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:

| Constitution Section | CLAUDE.md Section | Sync Rule | |---------------------|-------------------|-----------| | Core Principles | Principles Summary | MUST list all principles with enforcement keywords | | Technology Stack | Technical Stack | MUST match exactly (table format) | | Quality Gates | Quality Gates | MUST match exactly (table format) | | Governance | Development Workflow | MUST include versioning rules and commit conventions | | Project Structure | Project Structure | MUST match if present in constitution | | Layer Import Rules | Architecture | MUST replicate dependency rules |

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

| Section | Source | Sync Rule | Notes | |---------|--------|-----------|-------| | Project Overview | Manual | N/A | Brief description of project purpose | | Principles | Constitution Core Principles | List with enforcement | Omit rationale, keep keywords | | Technical Stack | Constitution Technology Stack | Exact match | Copy table directly | | Quality Gates | Constitution Quality Gates | Exact match | Copy table directly | | Development Workflow | Constitution Governance | List with enforcement | Include commit conventions | | Version Footer | Constitution version | Exact match | Format: Version X.Y.Z | Last synced: YYYY-MM-DD |

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:

| File | Purpose | When to Use | |------|---------|-------------| | references/SECTION-TEMPLATES.md | Templates for each CLAUDE.md section | When creating or restructuring CLAUDE.md | | references/SYNC-PATTERNS.md | Detailed sync patterns, validation checklists, edge cases | When resolving complex sync scenarios |

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