blueprint-claude-md

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

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代方案……
需要为团队说明创建或更新 CLAUDE.md	使用 /blueprint:rules 制定特定路径的规则
想要向现有 CLAUDE.md 添加 @imports	使用 /blueprint:generate-rules 根据 PRD 创建规则
需要为个人偏好创建 CLAUDE.local.md	直接编辑单个规则文件
将内联内容转换为精简的 @import 结构	只需查看当前记忆配置

CLAUDE.md 与自动记忆

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

适合放在 CLAUDE.md 中	适合放在自动记忆中（由 Claude 管理）
团队编码标准	调试经验和变通方法
构建／测试／lint 命令	个人工作流偏好
架构决策	随时间学到的项目特定模式
必须遵循的约定	文件关系和导航快捷方式
CI/CD 工作流	常见错误及其修复方法

自动记忆位于 ~/.claude/projects/<project>/memory/，并由系统自动管理。不要将自动记忆相关内容重复写入 CLAUDE.md。

记忆层级（优先级从低到高）

1. 用户级规则：~/.claude/rules/ — 适用于所有项目的个人规则
2. CLAUDE.md（项目级）：团队共享的项目说明（提交到 git）
3. CLAUDE.local.md：个人项目偏好（已加入 gitignore）
4. .claude/rules/：模块化的特定路径规则
5. 托管策略：组织级说明（企业、系统路径）
6. 自动记忆：Claude 自己的笔记（~/.claude/projects/<project>/memory/）

@import 语法

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

# Project: MyApp

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

• 路径相对于包含该导入语句的文件
• 支持递归导入（最大深度为 5）
• 不会在代码行片段或代码块中解析导入语句
• 首次导入外部文件时会触发批准对话框

使用 @import 引用现有文档，而不是将内容重复写入 CLAUDE.md。

步骤：

1. 检查当前状态：

   • 查找项目根目录中是否存在 CLAUDE.md
   • 查找是否存在 CLAUDE.local.md（个人偏好，已加入 gitignore）
   • 读取 docs/blueprint/manifest.json，了解配置
   • 检查是否存在 ~/.claude/rules/（用户级规则）
   • 确定 claude_md_mode（single、modular 或 both）

2. 确定操作（使用 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. 收集项目上下文：

   • 项目结构：检测语言、框架和构建工具
   • PRD：读取 docs/prds/*.md 中的需求
   • 工作概览：当前阶段和进度
   • 现有规则：读取 .claude/rules/ 中的内容（如果存在）
   • Git 历史：近期模式和约定
   • 依赖项：包管理器和关键库

4. 生成 CLAUDE.md 章节：

   标准章节（侧重团队共享的说明）：

   # 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
   

   应省略的章节（自动记忆会自动处理这些内容）：

   • “当前重点”——Claude 会在自动记忆中跟踪此内容
   • “关键文件”——Claude 会自动了解文件之间的关系
   • 调试技巧——Claude 会将这些记录在自动记忆主题文件中

5. 如果模块化规则模式 = "both"：

   • 将 CLAUDE.md 保持为高层概览
   • 详细规则参见 .claude/rules/：

     ## 详细规则
     领域专属指南请参见 `.claude/rules/`：
     - `development.md` - 开发工作流
     - `testing.md` - 测试要求
     - `frontend/` - 前端专属规则
     - `backend/` - 后端专属规则
     

6. 如果 modular rules mode = "modular"：

   • 创建包含 @import 引用的精简版 CLAUDE.md
   • 将详细内容移至 .claude/rules/
   • 精简版 CLAUDE.md 示例：

     # 项目：{name}
     
     ## 概述
     {一段式描述}
     
     @docs/prds/main.md
     
     ## 开发
     {构建、测试、lint 命令}
     
     ## 规则
     详细指南请参阅 `.claude/rules/`。
     

6b. 如果选择了 "Create CLAUDE.local.md"：

• 在项目根目录创建 CLAUDE.local.md，用于存放个人偏好
• 如果 .gitignore 中尚未包含 CLAUDE.local.md，则将其添加进去
• 模板：

  # 个人偏好
  
  ## 我的环境
  - IDE：{检测到的信息或询问}
  - 终端：{检测到的信息或询问}
  
  ## 我的工作流偏好
  - {不与团队共享的个人约定}
  

6c. 如果选择了 "Add @imports"：

• 扫描现有 CLAUDE.md，查找内容已存在于其他文件中的部分
• 将重复内容替换为 @path/to/source.md 引用
• 将仅存在于 CLAUDE.md 中的内容保留为内联内容
• 应用更改前显示差异

7. 智能更新（针对现有 CLAUDE.md）：

   • 解析现有部分
   • 识别过时内容（与 PRD、项目结构进行比较）
   • 提供逐部分更新选项：

     question: "发现过时部分。要更新哪些部分？"
     options: [部分列表]
     allowMultiSelect: true
     

8. 与模块化规则同步：

   • 如果 .claude/rules/ 中存在规则
   • 检测重复内容
   • 提供去重选项：

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

9. 更新清单：

   • 记录 CLAUDE.md 的生成/更新
   • 跟踪贡献内容的 PRD
   • 更新时间戳

10. 更新任务注册表：

    更新 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. 报告：

    ✅ CLAUDE.md 已更新！
    
    {已创建 | 已更新}：CLAUDE.md
    {如果已创建：} CLAUDE.local.md（个人偏好，已加入 git 忽略）
    
    部分：
    - 概述 ✅
    - 技术栈 ✅
    - 开发工作流 ✅
    - 架构 ✅
    - 约定 ✅
    
    使用的 @imports：{数量，如有}
    - @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 发生重大变化时及时更新

12. 提示下一步操作（使用 AskUserQuestion）：

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

    根据选择：

    • “检查 blueprint 状态” → 运行 /blueprint:status
    • “管理模块化规则” → 运行 /blueprint:rules
    • “继续开发” → 运行 /project:continue
    • “暂时到此为止” → 退出

模板章节（根据项目类型自定义）：

项目类型	关键章节
Python	虚拟环境、pytest、类型提示
Node.js	包管理器、测试运行器、构建
Rust	Cargo、clippy、unsafe 用法规则
Monorepo	工作区结构、共享依赖
API	端点、身份验证、错误处理
前端	组件、状态、样式