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

When to Use This Skill

Use this skill when...

Use alternative when...

Need to create/update CLAUDE.md for team instructions

Use

/blueprint:rules

for path-specific rules

Want to add @imports to existing CLAUDE.md

Use

/blueprint:generate-rules

to create rules from PRDs

Need to create CLAUDE.local.md for personal preferences

Editing individual rule files directly

Converting inline content to lean @import structure

Just need to view current memory configuration

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.

Belongs in CLAUDE.md

Belongs in Auto Memory (managed by Claude)

Team coding standards

Debugging insights and workarounds

Build/test/lint commands

Personal workflow preferences

Architecture decisions

Project-specific patterns learned over time

Required conventions

File relationships and navigation shortcuts

CI/CD workflows

Common mistakes and how to fix them

Auto memory lives at

~/.claude/projects//memory/

and is managed automatically. Do not duplicate auto memory concerns into CLAUDE.md.

Memory Hierarchy (precedence low → high)

User-level rules

:

~/.claude/rules/

— personal rules across all projects

CLAUDE.md (project)

Team-shared project instructions (checked into git)

CLAUDE.local.md

Personal project-specific preferences (gitignored)

.claude/rules/

Modular, path-specific rules

Managed policy

Organization-wide instructions (enterprise, system paths)

Auto memory

Claude's own notes ( ~/.claude/projects//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

:

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)

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/

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 Generate CLAUDE.md sections : Standard sections (focused on team-shared instructions):

Project: {name}

Overview

Tech Stack

Language:

Framework:

Build:

Test: {detected}

Development Workflow

Getting Started

Running Tests

Building

Architecture {Key architectural decisions from PRDs — or use @import:} @docs/prds/architecture-prd.md

Conventions

Code Style

Commit Messages

Testing Requirements

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

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:

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 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 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)" Update manifest : Record CLAUDE.md generation/update Track which PRDs contributed Update timestamp 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 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 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): Project Type Key Sections Python Virtual env, pytest, type hints Node.js Package manager, test runner, build Rust Cargo, clippy, unsafe usage rules Monorepo Workspace structure, shared deps API Endpoints, auth, error handling Frontend Components, state, styling