blueprint-claude-md

Generate or update the project's CLAUDE.md file based on blueprint artifacts, PRDs, and project structure.

When to Use This Skill

CLAUDE.md vs Auto Memory

Claude Code has two complementary systems for project context. CLAUDE.md should contain team-shared instructions — not patterns Claude learns on its own.

Auto memory lives at ~/.claude/projects/<project>/memory/ and is managed automatically. Do not duplicate auto memory concerns into CLAUDE.md.

Memory Hierarchy (precedence low → high)

1. User-level rules: ~/.claude/rules/ — personal rules across all projects
2. CLAUDE.md (project): Team-shared project instructions (checked into git)
3. CLAUDE.local.md: Personal project-specific preferences (gitignored)
4. .claude/rules/: Modular, path-specific rules
5. Managed policy: Organization-wide instructions (enterprise, system paths)
6. Auto memory: Claude's own notes (~/.claude/projects/<project>/memory/)

@import Syntax

CLAUDE.md files support importing other markdown files to stay lean:

# Project: MyApp

@docs/architecture.md
@docs/conventions.md
@.claude/rules/testing.md

• Paths are relative to the file containing the import
• Recursive imports supported (max depth 5)
• Imports are not evaluated inside code spans or code blocks
• First-time external imports trigger an approval dialog

Use @import to reference existing documentation rather than duplicating content into CLAUDE.md.

Steps:

1. Check current state:

   • Look for existing CLAUDE.md in project root
   • Look for existing CLAUDE.local.md (personal preferences, gitignored)
   • Read docs/blueprint/manifest.json for configuration
   • Check for ~/.claude/rules/ (user-level rules)
   • Determine claude_md_mode (single, modular, or both)

2. Determine action (use AskUserQuestion):

   {If CLAUDE.md exists:}
   question: "CLAUDE.md already exists. What would you like to do?"
   options:
     - "Update with latest project info" → merge updates
     - "Regenerate completely" → overwrite (backup first)
     - "Add missing sections only" → append new content
     - "Add @imports for existing docs" → replace inline content with imports
     - "Convert to modular rules" → split into .claude/rules/
     - "Create CLAUDE.local.md" → personal preferences (gitignored)
     - "View current structure" → analyze and display
   
   {If CLAUDE.md doesn't exist:}
   question: "No CLAUDE.md found. How would you like to create it?"
   options:
     - "Generate from project analysis" → auto-generate
     - "Generate from PRDs" → use blueprint PRDs
     - "Generate with @imports (lean)" → auto-generate using imports for existing docs
     - "Start with template" → use starter template
     - "Use modular rules instead" → skip CLAUDE.md, use rules/
   

3. Gather project context:

   • Project structure: Detect language, framework, build tools
   • PRDs: Read docs/prds/*.md for requirements
   • Work overview: Current phase and progress
   • Existing rules: Content from .claude/rules/ if present
   • Git history: Recent patterns and conventions
   • Dependencies: Package managers, key libraries

4. Generate CLAUDE.md sections:

   Standard sections (focused on team-shared instructions):

   # Project: {name}
   
   ## Overview
   {Brief project description from PRDs or detection}
   
   ## Tech Stack
   - Language: {detected}
   - Framework: {detected}
   - Build: {detected}
   - Test: {detected}
   
   ## Development Workflow
   
   ### Getting Started
   {Setup commands}
   
   ### Running Tests
   {Test commands}
   
   ### Building
   {Build commands}
   
   ## Architecture
   {Key architectural decisions from PRDs — or use @import:}
   @docs/prds/architecture-prd.md
   
   ## Conventions
   
   ### Code Style
   {Detected or from PRDs}
   
   ### Commit Messages
   {Conventional commits if detected}
   
   ### Testing Requirements
   {From PRDs or rules}
   
   ## See Also
   {If modular rules enabled:}
   - `.claude/rules/` - Detailed rules by domain
   - `docs/prds/` - Product requirements
   

   Sections to omit (auto memory handles these automatically):

   • "Current Focus" — Claude tracks this in auto memory
   • "Key Files" — Claude learns file relationships automatically
   • Debugging tips — Claude records these in auto memory topic files

5. If modular rules mode = "both":

   • Keep CLAUDE.md as high-level overview
   • Reference .claude/rules/ for details:

     ## Detailed Rules
     See `.claude/rules/` for domain-specific guidelines:
     - `development.md` - Development workflow
     - `testing.md` - Testing requirements
     - `frontend/` - Frontend-specific rules
     - `backend/` - Backend-specific rules
     

6. If modular rules mode = "modular":

   • Create minimal CLAUDE.md with @import references
   • Move detailed content to .claude/rules/
   • Example lean CLAUDE.md:

     # Project: {name}
     
     ## Overview
     {One-paragraph description}
     
     @docs/prds/main.md
     
     ## Development
     {Build, test, lint commands}
     
     ## Rules
     See `.claude/rules/` for detailed guidelines.
     

6b. If "Create CLAUDE.local.md" selected:

• Create CLAUDE.local.md in project root for personal preferences
• Add CLAUDE.local.md to .gitignore if not already present
• Template:

  # Personal Preferences
  
  ## My Environment
  - IDE: {detected or ask}
  - Terminal: {detected or ask}
  
  ## My Workflow Preferences
  - {Personal conventions not shared with team}
  

6c. If "Add @imports" selected:

• Scan existing CLAUDE.md for sections with content that exists in other files
• Replace duplicated content with @path/to/source.md imports
• Preserve CLAUDE.md-only content inline
• Show diff of changes before applying

7. Smart update (for existing CLAUDE.md):

   • Parse existing sections
   • Identify outdated content (compare with PRDs, structure)
   • Offer section-by-section updates:

     question: "Found outdated sections. Which would you like to update?"
     options: [list of sections]
     allowMultiSelect: true
     

8. Sync with modular rules:

   • If rules exist in .claude/rules/
   • Detect duplicated content
   • Offer to deduplicate:

     question: "Found duplicate content between CLAUDE.md and rules/. How to resolve?"
     options:
       - "Keep in CLAUDE.md, remove from rules"
       - "Keep in rules, reference from CLAUDE.md"
       - "Keep both (may cause confusion)"
     

9. Update manifest:

   • Record CLAUDE.md generation/update
   • Track which PRDs contributed
   • Update timestamp

10. Update task registry:

    Update the task registry entry in docs/blueprint/manifest.json:

    jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
      '.task_registry["claude-md"].last_completed_at = $now |
       .task_registry["claude-md"].last_result = "success" |
       .task_registry["claude-md"].stats.runs_total = ((.task_registry["claude-md"].stats.runs_total // 0) + 1)' \
      docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json
    

11. Report:

    ✅ CLAUDE.md updated!
    
    {Created | Updated}: CLAUDE.md
    {If created:} CLAUDE.local.md (personal preferences, gitignored)
    
    Sections:
    - Overview ✅
    - Tech Stack ✅
    - Development Workflow ✅
    - Architecture ✅
    - Conventions ✅
    
    @imports used: {count, if any}
    - @docs/prds/architecture.md
    - @.claude/rules/testing.md
    
    Sources used:
    - PRDs: {list}
    - Rules: {list}
    - Project detection: {what was detected}
    
    {If modular mode:}
    Note: Detailed rules are in .claude/rules/
    CLAUDE.md serves as overview and quick reference.
    
    Note: "Current Focus" and "Key Files" are managed by Claude's
    auto memory — no need to maintain these in CLAUDE.md.
    
    Run `/blueprint-status` to see full configuration.
    

CLAUDE.md Best Practices:

• Keep it concise (< 500 lines ideally)
• Focus on team-shared instructions (standards, commands, architecture)
• Use @import to reference existing docs instead of duplicating content
• Use CLAUDE.local.md for personal preferences (auto-gitignored)
• Reference .claude/rules/ for detailed, path-specific rules
• Let auto memory handle "Current Focus", "Key Files", debugging tips
• Update when PRDs change significantly

12. Prompt for next action (use AskUserQuestion):

    question: "CLAUDE.md updated. What would you like to do next?"
    options:
      - label: "Check blueprint status (Recommended)"
        description: "Run /blueprint:status to verify configuration"
      - label: "Manage modular rules"
        description: "Add or edit rules in .claude/rules/"
      - label: "Continue development"
        description: "Run /project:continue to work on next task"
      - label: "I'm done for now"
        description: "Exit - CLAUDE.md is saved"
    

    Based on selection:

    • "Check blueprint status" → Run /blueprint:status
    • "Manage modular rules" → Run /blueprint:rules
    • "Continue development" → Run /project:continue
    • "I'm done" → Exit

Template Sections (customize per project type):