Claude.md Development

CLAUDE.md serves as the project's single source of truth for session behavior and component architecture. This skill ensures consistency between documentation and implementation.

Core principle: CLAUDE.md must remain concise, evergreen, and properly synchronized with .claude/rules/ and component meta-skills.

What CLAUDE.md Contains

Role 1: Health Maintenance (Session-Only)

• Project overview and architecture
• Core principles and philosophy
• Development workflow guidance
• Navigation to rules, skills, and docs

Role 2: Component Factory Reference

• Key meta-skills reference table
• Component-specific guidance links
• Quality standards and Success Criteria
• Portability invariant enforcement

Update Protocol

When to Update CLAUDE.md

Update required when:

• Adding new meta-skills (invocable-development, etc.)
• Changing core architecture (Layer A/Layer B)
• Modifying project structure or navigation
• Adding new documentation directories
• Changing quality standards

No update needed for:

• Individual skill/command content changes
• Minor reference file updates
• Example additions
• Routine maintenance

Content Synchronization

Critical Synchronization Points

CLAUDE.md ↔ .claude/rules/

CLAUDE.md ↔ Meta-Skills

Best Practices

Structure

• Keep it concise: CLAUDE.md should be ~300-500 lines max
• Evergreen content: Avoid transient information
• Single source of truth: Each concept documented once
• Progressive disclosure: High-level in CLAUDE.md, details in references/

Navigation

• Use tables for structured references
• Include both file paths and descriptions
• Mark mandatory references clearly
• Cross-link to docs/ directory for extended content

Quality

• Validate all links actually exist
• Ensure consistency with .claude/rules/
• Keep meta-skill table current
• Sync Success Criteria with quality-standards

Common CLAUDE.md Patterns

Philosophy Table Format

| File          | Layer    | Content                                        |
| ------------- | -------- | ---------------------------------------------- |
| principles.md | **Both** | Dual-layer architecture, Portability Invariant |
| patterns.md   | **Both** | Implementation patterns, Degrees of Freedom    |

Meta-Skill Table Format

| Meta-Skill                | Purpose                  | Transformation                   |
| ------------------------- | ------------------------ | -------------------------------- |
| **invocable-development** | Creating portable skills | Tutorial → Architectural refiner |

Component Guidance Format

## Component-Specific Guidance

For detailed guidance on creating portable components, consult the appropriate meta-skill:

| Component | Meta-Skill            | Output Traits             |
| --------- | --------------------- | ------------------------- |
| Skills    | invocable-development | Portable, self-sufficient |

Anti-Patterns

DON'T: Include Generic Content

❌ "How to write Markdown" ❌ "What is YAML" ❌ "Introduction to Git"

DON'T: Duplicate Content

❌ Repeating rules from .claude/rules/ ❌ Copying meta-skill content into CLAUDE.md ❌ Duplicating philosophy explanations

DON'T: Make It Transient

❌ Including session-specific notes ❌ Temporary workarounds ❌ "TODO" items for future work

Navigation

For hybrid format standards (Markdown + XML), see the hybrid-format rule.

For architectural philosophy, see: docs/philosophy/deep-dives.md

For development workflows, see: docs/workflows/development.md

<critical_constraint> MANDATORY: Keep CLAUDE.md under 500 lines (use progressive disclosure) MANDATORY: Validate all links exist before committing changes MANDATORY: Sync meta-skill table when adding/removing meta-skills MANDATORY: Never include transient or TODO content No exceptions. CLAUDE.md is evergreen documentation, not a scratchpad. </critical_constraint>