blueprint-claude-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

根据蓝图工件、PRD、项目结构生成或更新项目的CLAUDE.md文件。

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用于团队说明	使用 `/blueprint:rules` 设置路径特定规则
希望为现有CLAUDE.md添加@import语法	使用 `/blueprint:generate-rules` 从PRD生成规则
需要创建CLAUDE.local.md用于个人偏好设置	直接编辑单个规则文件
将内联内容转换为精简的@import结构	仅需查看当前内存配置

CLAUDE.md vs Auto Memory

CLAUDE.md 与自动内存

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/<project>/memory/

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

Claude Code拥有两个互补的项目上下文系统。CLAUDE.md应包含团队共享说明——而非Claude自行学习到的模式。

属于CLAUDE.md的内容	属于自动内存（由Claude管理）的内容
团队编码标准	调试见解与解决方案
构建/测试/代码检查命令	个人工作流偏好
架构决策	随时间学习到的项目特定模式
强制遵循的约定	文件关联与导航快捷方式
CI/CD工作流	常见错误及修复方法

自动内存存储于

~/.claude/projects/<project>/memory/

，由系统自动管理。请勿将自动内存相关内容重复写入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/<project>/memory/
```
)

用户级规则：
```
~/.claude/rules/
```
—— 所有项目通用的个人规则
CLAUDE.md（项目级）：团队共享的项目说明（已提交至git）
CLAUDE.local.md：项目专属的个人偏好设置（已加入git忽略）
.claude/rules/：模块化、路径特定的规则
管理策略：组织级说明（企业版、系统路径）
自动内存：Claude自身的笔记（
```
~/.claude/projects/<project>/memory/
```
）

@import Syntax

@import 语法

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

markdown

undefined

CLAUDE.md文件支持导入其他Markdown文件以保持精简：

markdown

undefined

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):
```markdown
# 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

If modular rules mode = "both":

Keep CLAUDE.md as high-level overview

Reference

.claude/rules/

for details:

markdown

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

markdown

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

markdown

# 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

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

bash

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

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


- 路径相对于包含导入语句的文件
- 支持递归导入（最大深度5层）
- 代码段或代码块内的导入不会被解析
- 首次导入外部文件会触发确认对话框

使用`@import`引用现有文档，而非将内容复制到CLAUDE.md中。

**步骤**:

1. **检查当前状态**:
   - 查找项目根目录下现有的`CLAUDE.md`文件
   - 查找现有的`CLAUDE.local.md`文件（个人偏好设置，已加入git忽略）
   - 读取`docs/blueprint/manifest.json`获取配置信息
   - 检查`~/.claude/rules/`（用户级规则）
   - 确定`claude_md_mode`（单文件、模块化或两者兼具）

2. **确定操作**（使用AskUserQuestion）:

{若CLAUDE.md已存在:} question: "CLAUDE.md已存在。您希望执行什么操作？" options: - "使用最新项目信息更新" → 合并更新内容 - "完全重新生成" → 覆盖（先备份） - "仅添加缺失章节" → 追加新内容 - "为现有文档添加@import语法" → 用导入语句替换内联内容 - "转换为模块化规则" → 拆分至.claude/rules/ - "创建CLAUDE.local.md" → 个人偏好设置（已加入git忽略） - "查看当前结构" → 分析并展示

{若CLAUDE.md不存在:} question: "未找到CLAUDE.md。您希望如何创建它？" options: - "通过项目分析生成" → 自动生成 - "通过PRD生成" → 使用蓝图PRD - "生成带@import的精简版本" → 自动生成并引用现有文档 - "从模板开始" → 使用起始模板 - "改用模块化规则" → 跳过CLAUDE.md，使用rules/


3. **收集项目上下文**:
- **项目结构**: 检测语言、框架、构建工具
- **PRD**: 读取`docs/prds/*.md`获取需求
- **工作概述**: 当前阶段与进度
- **现有规则**: 若存在则读取`.claude/rules/`中的内容
- **Git历史**: 近期模式与约定
- **依赖**: 包管理器、核心库

4. **生成CLAUDE.md章节**:

**标准章节**（聚焦团队共享说明）:
```markdown
# 项目: {name}

## 概述
{来自PRD或自动检测的项目简要描述}

## 技术栈
- 语言: {检测结果}
- 框架: {检测结果}
- 构建工具: {检测结果}
- 测试工具: {检测结果}

## 开发工作流

### 快速开始
{安装配置命令}

### 运行测试
{测试命令}

### 构建项目
{构建命令}

## 架构
{来自PRD的核心架构决策 —— 或使用@import引用:}
@docs/prds/architecture-prd.md

## 约定规范

### 代码风格
{检测结果或来自PRD}

### 提交信息
{若检测到则使用规范提交格式}

### 测试要求
{来自PRD或规则}

## 参见
{若启用模块化规则:}
- `.claude/rules/` - 分领域的详细规则
- `docs/prds/` - 产品需求文档

需省略的章节（自动内存会自动处理这些内容）:

"当前重点" —— Claude会在自动内存中跟踪此信息
"核心文件" —— Claude会自动学习文件关联关系
调试技巧 —— Claude会将这些记录在自动内存的主题文件中

若模块化规则模式 = "both":

保持CLAUDE.md为高层级概述

引用

.claude/rules/

获取详细内容:

markdown

## 详细规则
请查看`.claude/rules/`获取分领域指南:
- `development.md` - 开发工作流
- `testing.md` - 测试要求
- `frontend/` - 前端专属规则
- `backend/` - 后端专属规则

若模块化规则模式 = "modular":

创建极简CLAUDE.md并包含@import引用
将详细内容迁移至
```
.claude/rules/
```

精简版CLAUDE.md示例:

markdown

# 项目: {name}

## 概述
{一段描述}

@docs/prds/main.md

## 开发
{构建、测试、代码检查命令}

## 规则
请查看`.claude/rules/`获取详细指南。

6b. 若选择"创建CLAUDE.local.md":

在项目根目录创建
```
CLAUDE.local.md
```
用于个人偏好设置
若尚未添加，则将
```
CLAUDE.local.md
```
加入
```
.gitignore
```

模板:

markdown

# 个人偏好设置

## 我的开发环境
- IDE: {检测结果或询问用户}
- 终端: {检测结果或询问用户}

## 我的工作流偏好
- {不与团队共享的个人约定}

6c. 若选择"添加@import":

扫描现有CLAUDE.md，查找内容与其他文件重复的章节
用
```
@path/to/source.md
```
导入语句替换重复内容
保留仅存在于CLAUDE.md中的内联内容
应用更改前展示差异对比

智能更新（针对现有CLAUDE.md）:
- 解析现有章节
- 识别过时内容（与PRD、项目结构对比）
- 提供逐章节更新选项:
```
question: "发现过时章节。您希望更新哪些？"
options: [章节列表]
allowMultiSelect: true
```

与模块化规则同步:

若
```
.claude/rules/
```
中存在规则
检测重复内容

提供去重选项:

question: "发现CLAUDE.md与rules/之间存在重复内容。如何处理？"
options:
  - "保留在CLAUDE.md，从rules/移除"
  - "保留在rules/，从CLAUDE.md引用"
  - "两者都保留（可能造成混淆）"

更新清单:
- 记录CLAUDE.md的生成/更新操作
- 跟踪贡献内容的PRD
- 更新时间戳

更新任务注册表:

更新

docs/blueprint/manifest.json

中的任务注册表条目:

bash

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

生成报告:

✅ CLAUDE.md已更新!

{已创建 | 已更新}: CLAUDE.md
{若创建:} CLAUDE.local.md（个人偏好设置，已加入git忽略）

已处理章节:
- 概述 ✅
- 技术栈 ✅
- 开发工作流 ✅
- 架构 ✅
- 约定规范 ✅

使用的@import数量: {数量（若有）}
- @docs/prds/architecture.md
- @.claude/rules/testing.md

使用的数据源:
- PRD: {列表}
- 规则: {列表}
- 项目检测: {检测内容}

{若启用模块化模式:}
注意: 详细规则位于.claude/rules/
CLAUDE.md作为概述与快速参考。

注意: "当前重点"与"核心文件"由Claude的自动内存管理——无需在CLAUDE.md中维护这些内容。

运行`/blueprint:status`查看完整配置。

CLAUDE.md最佳实践:

保持简洁（理想情况下少于500行）
聚焦团队共享说明（标准、命令、架构）
使用
```
@import
```
引用现有文档，避免内容重复
使用
```
CLAUDE.local.md
```
存储个人偏好设置（自动加入git忽略）
引用
```
.claude/rules/
```
获取详细的路径特定规则
让自动内存处理"当前重点"、"核心文件"、调试技巧
当PRD发生重大变更时进行更新

提示下一步操作（使用AskUserQuestion）:

question: "CLAUDE.md已更新。您接下来希望做什么？"
options:
  - label: "检查蓝图状态（推荐）"
    description: "运行/blueprint:status验证配置"
  - label: "管理模块化规则"
    description: "添加或编辑.claude/rules/中的规则"
  - label: "继续开发"
    description: "运行/project:continue处理下一个任务"
  - label: "暂时完成"
    description: "退出 - CLAUDE.md已保存"

根据选择执行:

"检查蓝图状态" → 运行
```
/blueprint:status
```
"管理模块化规则" → 运行
```
/blueprint:rules
```
"继续开发" → 运行
```
/project:continue
```
"暂时完成" → 退出

模板章节（按项目类型自定义）:

项目类型	核心章节
Python	虚拟环境、pytest、类型提示
Node.js	包管理器、测试运行器、构建
Rust	Cargo、clippy、unsafe使用规则
单体仓库	工作区结构、共享依赖
API	端点、认证、错误处理
前端	组件、状态、样式