blueprint-claude-md

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

Branch-specific detail lives in references/, split by the path that needs it — an invocation opens only the file for the branch it takes.

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.

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

Execution

Execute this CLAUDE.md workflow:

Step 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)

Step 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/

Step 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

Step 4: Generate CLAUDE.md sections

Build the sections from references/template-sections.md: the standard skeleton, tailored with the per-project-type additions. Leave out what auto memory handles (see "CLAUDE.md vs Auto Memory" above).

Step 5: Apply the modular rules mode

If modular rules mode is both or modular, follow the matching section of references/modular-rules-split.md. Mode single skips this step.

Step 6: Apply a selected option

• "Create CLAUDE.local.md" → references/template-sections.md § CLAUDE.local.md template
• "Add @imports for existing docs" → references/smart-update.md § Add @imports

Step 7: Smart update (existing CLAUDE.md)

When CLAUDE.md already exists, follow references/smart-update.md § Smart update.

Step 8: Sync with modular rules

When .claude/rules/ has rules, follow references/modular-rules-split.md § Sync with modular rules.

Step 9: Update manifest and task registry

Record the run in docs/blueprint/manifest.json per references/manifest-and-registry.md.

Step 10: 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.

Step 11: 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