基于 CLAUDE_TEMPLATE.md 模板快速初始化项目 CLAUDE.md 规范文件,通过交互式问答生成定制化开发规范

version
1.0.0
GitHub stars
50

Install

/plugin install project-init@claude-code-third-party-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ChamHerry/claude-code-third-party-plugins.

Contents

Discovered from source

Commands 1

智能分析现有项目结构和配置文件,自动推断技术栈、架构模式等信息,只对无法确定的信息进行询问,最终生成项目的 CLAUDE.md 开发规范文件。

核心特性:

  • 🔍 智能分析: 自动检测项目类型、语言、框架
  • 💡 按需询问: 只对无法推断的信息询问用户
  • 🎯 数据优先: 优先使用项目实际数据,避免猜测
  • 🌐 跨平台: 完全兼容 Windows / macOS / Linux

内置模板

以下是用于生成 CLAUDE.md 的内置模板:

# CLAUDE.md 模板

> 用于在新项目中快速建立开发规范和最佳实践。使用时请填充 `[占位符]` 部分。

---

## 项目概述

**[项目名称]** - [项目一句话描述]

### 核心技术栈
- **框架**: [框架名称和版本]
- **数据存储**: [数据库/缓存技术]
- **开发语言**: [语言和版本]
- **代码风格**: [命名规范]

### 项目架构

[绘制项目架构图] 例如: API层 → Service层 → Logic层 → Data层 → Storage


**关键模块**:
- **[模块1]**: [路径] - [说明]
- **[模块2]**: [路径] - [说明]

---

## 测试规范
- 测试覆盖率 > 80%
- 使用 Mock 模拟外部依赖
- Mock 数据存放在 `test/data/` 目录
- 测试文件存放在 `test/` 目录

---

## 架构规则(强制)

### 层职责定义
- **[Layer 1]**: ✅ [应该做的] / ❌ [不应该做的]
- **[Layer 2]**: ✅ [应该做的] / ❌ [不应该做的]

### 开发规则
1. **命名规范** - [统一命名规范]
2. **依赖管理** - [依赖引入规则]
3. **错误处理** - [统一错误处理机制]
4. **版本控制** -
   - Git 提交必须使用 AskUserQuestion 工具询问用户同意
   - 提交消息必须包含:
     - 问题描述(What)
     - 根本原因(Why)
     - 修复内容(How)
     - 技术细节(Details)
     - 影响范围(Impact)
   - **严格禁止**包含以下内容:
     - `🤖 Generated with [Claude Code](https://claude.com/claude-code)`
     - `Co-Authored-By: Claude <noreply@anthropic.com>`
     - 其他任何 AI 工具的标识或署名
5. **禁止行为** - [明确禁止的操作]

### Claude Code 工具使用规范

**AI 必须使用的工具**:
- **AskUserQuestion**: 数据不足或需要决策时,必须主动询问用户
- **TodoWrite**: 跟踪多步骤任务的进度,及时更新任务状态
- **Read/Grep/Glob**: 修改前必须先分析现有代码,避免重复定义
- **Plan**: 设计实施方案时,必须使用 Plan 工具进行规划和架构设计

### Skills 技能使用规范(强制)

Skills 是可扩展的专业能力模块,**必须**根据场景强制使用对应技能。

#### 强制使用场景映射表

> **使用说明**: 根据项目实际可用的 Skills 填充下表。通过 `<available_skills>` 列表获取当前环境可用技能。

| 触发场景 | 关键词识别 | 必须使用的技能 |
|---------|-----------|--------------|
| [场景1] | [关键词1、关键词2、...] | `[skill-name-1]` |
| [场景2] | [关键词1、关键词2、...] | `[skill-name-2]` |
| [场景3] | [关键词1、关键词2、...] | `[skill-name-3]` |

**常见场景类型参考**:
- 架构设计类:系统架构、技术选型、组件设计
- 可视化类:架构图、流程图、时序图、关系图
- 文档处理类:Word、PPT、PDF、Excel
- 前端设计类:UI设计、界面原型、组件设计

#### 强制触发规则

**以下场景必须调用对应技能,禁止跳过**:

1. **[场景类型1]**(触发 `[skill-name]`)
   - [具体触发条件1]
   - [具体触发条件2]
   - 用户提及"[关键词]"

2. **[场景类型2]**(触发 `[skill-name]`)
   - [具体触发条件1]
   - [具体触发条件2]

#### 技能调用检查清单

在完成任务前,必须检查:
- [ ] 是否识别到上述强制触发场景?
- [ ] 是否已调用对应的必需技能?
- [ ] 如未调用,是否有合理理由?(需向用户说明)

#### 禁止行为

- ❌ **禁止**在强制场景下不调用对应技能
- ❌ **禁止**用文字描述替代可视化输出(有可视化技能时)
- ❌ **禁止**跳过专业技能直接输出低质量结果

#### 技能调用语法

使用 Skill 工具,参数 skill 设置为技能名称:

  • [根据 <available_skills> 列表填充]

#### 动态技能发现流程

1. **识别任务类型**:分析用户需求,判断是否需要专业技能支持
2. **查看可用技能**:通过系统提供的 `<available_skills>` 列表确认当前可用的技能
3. **匹配场景映射**:根据上表的场景映射,确定必须调用的技能
4. **调用技能**:使用 `Skill` 工具调用对应技能

**Token 管理规范(强制)**:

在开始每个 todo 任务前,必须评估剩余 token 是否足够完成该任务:

1. **评估标准**:
   - 当前剩余 token < 30000:存在风险
   - 当前剩余 token < 20000:高风险
   - 当前剩余 token < 10000:极高风险

2. **风险处理流程**:

   **如果存在风险**,必须使用 AskUserQuestion 工具询问用户:

   ```yaml
   question: "⚠️ Token 预警:当前剩余 [X] tokens,即将开始「[Todo任务名称]」可能存在 token 不足风险。您希望如何处理?"
   header: "Token 管理"
   multiSelect: false
   options:
     - label: "继续执行当前任务"
       description: "继续完成当前任务,可能需要在新会话中继续未完成的工作"
     - label: "生成进度总结文档"
       description: "生成包含当前进度总结和剩余待办事项实施方案的文档,便于在新会话中继续"
  1. 生成进度总结文档(用户选择选项 2 时):

    创建文档:docs/progress/YYYY-MM-DD-HH-MM-[任务名称]-进度总结.md

    文档必须包含:

    # [任务名称] - 进度总结与实施方案
    
    **创建时间**: YYYY-MM-DD HH:MM
    **当前状态**: 进行中
    **完成度**: X/Y 个任务
    
    ---
    
    ## 一、已完成任务
    
    ### 1.1 任务清单
    - [x] 任务 1 - 完成情况描述
    - [x] 任务 2 - 完成情况描述
    - [x] 任务 3 - 完成情况描述
    
    ### 1.2 关键成果
    - **成果 1**: 具体内容和路径
    - **成果 2**: 具体内容和路径
    - **成果 3**: 具体内容和路径
    
    ### 1.3 已修改文件
    

    path/to/file1.ext - 修改内容描述 path/to/file2.ext - 修改内容描述

    
    ---
    
    ## 二、剩余待办任务
    
    ### 2.1 待办清单
    - [ ] 任务 4 - 详细描述
    - [ ] 任务 5 - 详细描述
    - [ ] 任务 6 - 详细描述
    
    ### 2.2 实施方案
    
    #### 任务 4: [任务名称]
    **目标**: [具体目标]
    **步骤**:
    1. [详细步骤 1]
    2. [详细步骤 2]
    3. [详细步骤 3]
    
    **需要修改的文件**:
    - `path/to/file1.ext` - [修改说明]
    - `path/to/file2.ext` - [修改说明]
    
    **注意事项**:
    - [注意点 1]
    - [注意点 2]
    
    #### 任务 5: [任务名称]
    ... (同上格式)
    
    ---
    
    ## 三、技术背景和上下文
    
    ### 3.1 项目架构
    [关键架构信息]
    
    ### 3.2 技术栈
    [使用的技术栈]
    
    ### 3.3 重要约束
    - [约束 1]
    - [约束 2]
    
    ### 3.4 已知问题
    - [问题 1 及解决方案]
    - [问题 2 及解决方案]
    
    ---
    
    ## 四、继续工作指南
    
    ### 4.1 快速启动
    在新会话中执行以下步骤:
    1. 阅读本文档了解当前进度
    2. 使用 TodoWrite 工具恢复任务列表
    3. 从「任务 4」开始继续执行
    
    ### 4.2 验证检查清单
    开始前请确认:
    - [ ] 已理解所有已完成任务的内容
    - [ ] 已查看所有修改过的文件
    - [ ] 已理解剩余任务的实施方案
    - [ ] 已了解技术背景和约束
    
    ---
    
    **🤖 Generated with Claude Code**
    
  2. 文档生成后:

    • 输出文档路径
    • 提示用户在新会话中使用 @文档路径 继续工作
    • 优雅结束当前会话

最佳实践:

  • 定期评估 token 使用情况
  • 在大型任务开始前进行评估
  • 预留至少 15000 tokens 的安全边际
  • 及时保存进度,避免工作丢失

AI 工作流程与质量门(强制)

工作流程总览

需求输入
   ↓
A. 立项/澄清(Gate 0)
   ↓  KISS + YAGNI + AskUserQuestion
   ↓
B. 方案设计(Gate 1)
   ↓  SoC/LoD/组合优于继承 + DIP/ISP
   ↓
C. 编码前置(Gate 2)
   ↓  DRY + 分层职责 + 前置条件信任
   ↓
D. 编码实现
   ↓  SOLID + 幂等/限流/熔断 + 可观测性
   ↓
E. 测试与验收(Gate 3)
   ↓  单测+契约 + Mock + 覆盖率
   ↓
开发完成 ✅
(发布与运维不在此范围)

A. 立项/澄清阶段(Gate 0)

目标: 明确需求边界,拒绝过度设计

使用原则:

  • KISS + YAGNI → 先砍需求,确认功能必要性
  • AskUserQuestion → 明确边界与约束

输出:

  • 需求边界清晰
  • 最小方案草图
  • 走审批流程

质量门 Gate 0:问题澄清

  • 已使用 AskUserQuestion 收敛需求与约束
  • KISS 四问已回答(特别是"真的需要这个功能吗?")
  • 需求边界明确,无歧义

B. 方案设计阶段(Gate 1)

目标: 设计可扩展、可维护的方案

使用原则:

  • SoC/LoD/组合优于继承 → 明确分层边界,减少耦合
  • DIP/ISP → 稳住扩展点,依赖抽象

输出:

  • 方案文档(docs/todo/YYYY-MM-DD-HH-MM-功能名称-方案.md)
  • 必须包含:
    • 完整调用链路分析
    • KISS 四问的回答
    • 性能影响评估
    • 风险分析和缓解措施

质量门 Gate 1:方案评审

  • 方案文档已提交
  • 调用链路分析完整
  • KISS 四问已回答
  • 性能影响已评估
  • 风险与缓解措施明确
  • 已获得用户审批

C. 编码前置阶段(Gate 2)

目标: 确保代码质量,避免重复实现

使用原则:

  • DRY → 全局检索避免重复(使用 grep)
  • SRP/SoC → 划清分层职责
  • 前置条件信任原则 → 避免重复验证

输出:

  • 代码重复检查报告
  • 分层职责明确
  • 前置条件明确

质量门 Gate 2:实现前检查

  • 已使用 grep 全局检索,无重复定义
  • 分层边界清晰,职责明确
  • 前置条件信任原则已应用
  • 接口契约明确

D. 编码实现阶段

目标: 高质量代码实现

使用原则:

  • SOLID → 作为底座(SRP/OCP/LSP/ISP/DIP)
  • 幂等/限流/熔断 → 进到关键路径
  • 日志/指标/Trace → 埋点就位

输出:

  • 高质量代码
  • 可观测性埋点
  • 健壮性保障(幂等/限流/熔断)

关键检查:

  • SOLID 原则已遵循
  • 关键路径已添加幂等/限流/熔断
  • 日志/指标/Trace 埋点完整

E. 测试与验收阶段(Gate 3)

目标: 确保代码质量和功能正确性

使用原则:

  • 测试金字塔 → 单测+契约优先
  • Mock → 隔离外部依赖

输出:

  • 测试报告(docs/test/YYYY-MM-DD-HH-MM-功能名称-测试报告.md)
  • 测试覆盖率报告

质量门 Gate 3:测试门

  • 单元测试覆盖率 ≥ 80%(或项目自定义值)
  • 集成测试已通过
  • 必要的契约测试已完成
  • Mock 数据已准备(test/data/)
  • 测试报告已生成

核心开发实践(强制)

1. 代码修改前的分析(强制)

所有代码修改前,必须先完成深度分析,理解项目架构后再设计方案。

调用链路分析要点
HTTP请求 → 路由 → Controller → Service → Logic → Data → Storage

必须分析:

  • 入口点: 请求从哪个API端点或界面进入
  • 数据流转: 数据在各层之间如何传递和转换
  • 依赖关系: 各组件之间的依赖
  • 错误传播: 错误如何在调用链中传播
  • 缓存策略: 缓存的读写时机
  • 事务边界: 数据一致性保证点
方案设计原则:KISS

设计前必须回答4个问题:

  1. "这是真问题还是臆想的?" - 拒绝过度设计
  2. "有更简单的方法吗?" - 永远寻找最简方案
  3. "会破坏什么吗?" - 向后兼容是铁律
  4. "真的需要这个功能吗?" - 确认功能必要性

性能要求:

  • 最小化数据库/缓存操作次数
  • 优先使用批量操作
  • 合理使用并发和异步
  • 避免不必要的数据复制

代码简洁性:

  • 能用30行解决,绝不写300行
  • 复用现有代码
  • 函数职责单一
数据驱动的方案设计(强制)

所有方案必须有充足的数据支撑:

数据充足性判断:

  • ✅ 是否完整理解现有代码实现逻辑?
  • ✅ 是否掌握性能瓶颈数据?
  • ✅ 是否了解用户实际使用场景?
  • ✅ 是否分析业界最佳实践?
  • ✅ 是否评估不同方案优劣?

数据不足时的处理:

⚠️ 我没有足够的信心设计最佳方案

需要以下数据:
1. [具体需要的数据1]
2. [具体需要的数据2]
...

请提供这些数据或告诉我如何获取。

禁止:

  • ❌ 基于猜测或假设进行方案设计
  • ❌ 数据不足时强行给出方案
  • ❌ 使用"可能"、"也许"等不确定词汇描述关键决策
方案审批流程(强制)

在实施任何代码修改前,必须先获得用户审批:

工作流程:

  1. 分析阶段:AI 使用只读工具(Read/Grep/Glob)深度分析代码
  2. 方案设计:制定详细的实施方案(见下方"方案文档要求")
  3. 展示方案:向用户清晰展示方案,等待批准
  4. 执行修改:获得批准后才开始实际修改代码

方案文档要求:

  1. 提交方案设计文档,包含:

    • 完整调用链路分析
    • 问题诊断和根因分析
    • 支撑数据和分析(必须包含)
    • 方案设计(架构图、时序图、代码片段)
    • KISS原则4问题的回答
    • 性能影响评估
    • 风险分析和缓解措施
    • 文档保存: 保存到 docs/todo/YYYY-MM-DD-HH-MM-功能名称-方案.md
  2. 等待用户确认 - 批准后方可开始实施

  3. 实施 - 严格按照批准方案执行

分析检查清单

开始编码前必须完成:

  • 已完整追踪调用链路
  • 已理解所有涉及层的职责
  • 已识别所有数据转换点
  • 已回答KISS原则4个问题
  • 已收集充足数据支撑方案
  • 已制定详细实施方案
  • 已获得用户审批确认

2. 设计与代码层原则

2.1 SOLID原则(强制)
单一职责原则(SRP)
  • 一个类/模块只负责一个功能领域的变化
  • 每个包/模块职责单一且清晰,一个修改原因只能有一个
  • 避免"上帝类"或"万能函数"
开闭原则(OCP)
  • 对扩展开放,对修改封闭
  • 添加新功能通过扩展实现,不修改现有代码
  • 使用接口和抽象类定义扩展点
里氏替换原则(LSP)
  • 子类必须能够替换父类而不影响程序正确性
  • 所有实现同一接口的类必须可互换
  • 接口契约必须保持一致
接口隔离原则(ISP)
  • 客户端不应该依赖它不需要的接口
  • 接口应该小而专注,只包含必要方法
  • 大接口应拆分为多个小接口
依赖倒置原则(DIP)
  • 高层模块不应该依赖低层模块,两者都应该依赖抽象
  • 依赖接口而不是具体实现,通过依赖注入传递依赖
  • 具体实现可以随时替换
2.2 DRY(Don't Repeat Yourself)
  • 原则: 避免重复实现,优先复用现有代码
  • 实践: 添加任何新定义前,必须先用 grep -r "functionName\|className" 检查是否已存在
  • 目标: 每个知识点在系统中只有唯一、明确的表达
2.3 SoC(Separation of Concerns)
  • 原则: 关注点分离,不同关注点分离到不同模块
  • 实践: 与层职责定义和调用链分析一致,明确各层边界
  • 目标: 业务逻辑、数据访问、UI展示、基础设施各司其职
2.4 LoD(Law of Demeter / 最少知道原则)
  • 原则: 一个对象应当对其他对象有尽可能少的了解
  • 实践: 减少跨层/跨域耦合,只与直接朋友通信
  • 规则: 只调用以下方法:
    • 对象自身的方法
    • 方法参数的方法
    • 方法内创建对象的方法
    • 对象直接持有的组件的方法
2.5 组合优于继承
  • 原则: 优先使用对象组合而不是类继承来实现代码复用
  • 实践: 配合 OCP/LSP,把变更点外提为组合件
  • 优点: 更灵活、更易测试、避免继承层次过深
2.6 YAGNI(You Aren't Gonna Need It)
  • 原则: 只实现当前需要的功能,不为未来可能的需求预先设计
  • 实践: 与 KISS 搭配,拒绝"也许将来会用到"的功能
  • 目标: 减少不必要的复杂性和维护成本

3. 架构与健壮性原则

3.1 Clean/Hexagonal/Ports & Adapters 架构
  • 原则: 接口抽象 + 适配器模式,把外部依赖隔离进边界层
  • 实践:
    • 核心业务逻辑不依赖外部框架、数据库、UI
    • 通过端口(接口)定义核心与外部的交互契约
    • 通过适配器实现具体的外部集成(数据库、API、消息队列)
  • 目标: 与 DIP/ISP 强一致,实现核心业务的可测试性和可替换性
3.2 12-Factor App(服务化应用实践)
  • 配置外置: 配置通过环境变量注入,不硬编码在代码中
  • 无状态进程: 进程无状态,会话状态存储在外部(Redis等)
  • 日志标准输出: 日志输出到 stdout/stderr,由日志收集系统统一处理
  • 一次性进程: 进程可以快速启动和优雅关闭
  • 依赖隔离: 显式声明依赖,不依赖系统全局包
  • 端口绑定: 服务通过端口暴露,自包含运行
3.3 幂等性 & 去重
  • 原则: 写接口、任务重试、事件消费的第一性原则
  • 实践:
    • API设计: POST/PUT 使用幂等键(idempotency-key)
    • 消息消费: 使用消息ID去重,确保至少一次处理
    • 数据库操作: 使用唯一索引防止重复插入
  • 目标: 保证系统在重试、网络抖动情况下的数据一致性
3.4 限流/熔断/重试/退避(服务健壮性四件套)
  • 限流:

    • 保护系统不被突发流量压垮
    • 实现: 令牌桶、漏桶、滑动窗口
    • 默认: 100 RPS/实例(可根据项目调整)
  • 熔断:

    • 快速失败,防止级联故障
    • 触发条件: 20%错误率或连续N次失败(可根据项目调整)
    • 状态: 关闭 → 打开 → 半开 → 关闭
  • 重试:

    • 应对临时性故障
    • 策略: 指数退避(1s, 2s, 4s),最多3次
    • 注意: 必须配合幂等性设计
  • 退避:

    • 避免雪崩效应
    • 策略: 固定退避、指数退避、带抖动的指数退避

4. 功能版本迭代限制

禁止版本迭代: 对于存量功能,严格禁止版本迭代(v1、v2、v3)

核心原则:

  • 就地更新: 所有改进必须直接修改现有代码
  • 用户主导: 只有用户明确要求才能创建新版本
  • 单一实现: 每个功能只能有一个实现版本
  • 向后兼容: 必须保持向后兼容
  • 清理废弃: 必须版本迭代时同时清理旧代码

5. 任务解析与影响分析

任务前置分析原则: 执行任何任务前,必须先进行全面分析

文件影响评估
  • 主要修改文件: 直接需要编辑的核心文件
  • 关联影响文件: 可能受影响需同步更新的文件
  • 测试相关文件: 需要更新或新增的测试文件
  • 配置文件: 可能需要调整的配置
依赖关系分析
  • 文件依赖: 识别导入/引用关系
  • 功能依赖: 识别模块间调用关系
重复定义检查

添加任何新定义前,必须先检查:

# 检查函数/类/接口定义
grep -r "functionName\|className" --include="*.[ext]"

原则: 避免重复实现,优先复用现有代码


6. 前置条件信任原则

避免重复验证: 信任调用链的前置条件

// ❌ 过度防御:重复验证已验证数据
function process(data) {
    if (!data) return  // 前层已验证
    if (!data.field) return  // 前层已验证
    // ...
}

// ✅ 信任前置条件
function process(data) {
    // 前置条件: 调用方已验证
    const value = data.field
    // 业务逻辑...
}

分层职责:

  • 入口层: 负责验证和防护
  • 业务层: 信任前置条件,专注业务
  • 数据层: 处理持久化,不做业务验证

交互规范(强制)

沟通原则

  • 中文响应: 所有响应使用中文
  • 详细说明: 提供清晰的操作步骤和说明
  • 操作确认: 重要操作前进行确认
  • 透明度: 如实汇报进度、问题和风险

主动提问机制(强制)

  • 数据不足时提问: 缺乏必要信息时,必须使用 AskUserQuestion 工具询问用户
  • 明确性优先: 遇到模糊需求时,通过提问明确用户意图
  • 必须提问的场景:
    • 技术方案有多种实现路径需权衡时
    • 需要删除或修改重要功能/数据时
    • 配置参数会显著影响系统行为时
    • 不确定用户具体需求时
    • 设计决策可能影响架构或性能时
    • 存在向后兼容性风险时
  • 提问质量要求:
    • 问题应具体、聚焦
    • 提供2-4个清晰选项
    • 每个选项附带详细说明
    • 说明各选项的影响和优缺点
  • 等待确认: 提问后必须等待用户回答

文件创建限制(强制)

  • 禁止主动创建文档: 不主动创建文档文件(*.md)或README,除非用户明确要求
  • 优先编辑: 优先编辑现有文件而非创建新文件
  • 必要性原则: 只创建绝对必要的文件
  • 用户确认: 创建新文件前必须征得用户同意

最后更新: [日期]


```monorepo-template
# CLAUDE.md 模板 (Monorepo)

> Monorepo 项目的统一开发规范和最佳实践。包含多个子项目的协作规范。

---

## 项目概述

**[项目名称]** - [项目一句话描述]

### 项目类型

**Monorepo** ([Monorepo类型]: 前后端分离 / 多服务架构 / Workspace 管理等)

### 项目架构(Monorepo)

**整体架构**:

Monorepo 根目录 ├── [子项目1路径] - [子项目1名称] ([技术栈]) ├── [子项目2路径] - [子项目2名称] ([技术栈]) └── [子项目N路径] - [子项目N名称] ([技术栈])


**子项目详情**:

#### [子项目1名称] (`[子项目1路径]`)
- **技术栈**: [框架] + [语言]
- **职责**: [项目职责描述]
- **主要目录**:
  - `src/` - 源代码
  - `test/` - 测试文件
  - [其他关键目录]
- **数据存储**: [数据库/缓存技术]
- **架构模式**: [架构模式]

#### [子项目2名称] (`[子项目2路径]`)
- **技术栈**: [框架] + [语言]
- **职责**: [项目职责描述]
- **主要目录**:
  - `src/` - 源代码
  - `test/` - 测试文件
  - [其他关键目录]
- **数据存储**: [数据库/缓存技术]
- **架构模式**: [架构模式]

**项目间关系**:
- [子项目1] → [子项目2]: [关系描述,如 API 调用]
- [子项目2] → [数据存储]: [关系描述]

### 核心技术栈

**整体技术栈**:
- **语言**: [所有使用的语言,去重]
- **框架**: [所有使用的框架,去重]
- **数据存储**: [所有数据存储技术,去重]
- **代码风格**: [统一的命名规范,或注明差异]

---

## 测试规范
- 各子项目测试覆盖率 > 80%
- 使用 Mock 模拟外部依赖和跨项目依赖
- Mock 数据存放在各子项目的 `test/data/` 目录
- 测试文件存放在各子项目的 `test/` 目录
- 集成测试放在根目录 `integration-tests/` 目录

---

## 架构规则(强制)

### Monorepo 管理规则

1. **子项目独立性**
   - ✅ 每个子项目应该能独立构建和测试
   - ✅ 子项目间的依赖应该明确声明
   - ❌ 禁止直接引用其他子项目的内部实现
   - ❌ 禁止循环依赖

2. **共享代码管理**
   - ✅ 共享工具库放在 `packages/` 或 `libs/` 目录
   - ✅ 共享类型定义统一管理
   - ❌ 禁止复制粘贴代码到多个子项目

3. **版本控制策略**
   - ✅ 使用统一的版本管理工具(如 Lerna、pnpm workspaces)
   - ✅ 子项目版本同步或独立管理(根据实际情况)

### 层职责定义

**[子项目1名称]**:
- **[Layer 1]**: ✅ [应该做的] / ❌ [不应该做的]
- **[Layer 2]**: ✅ [应该做的] / ❌ [不应该做的]

**[子项目2名称]**:
- **[Layer 1]**: ✅ [应该做的] / ❌ [不应该做的]
- **[Layer 2]**: ✅ [应该做的] / ❌ [不应该做的]

### 开发规则
1. **命名规范** - [统一命名规范,或注明各子项目差异]
2. **依赖管理** - 使用 workspace 特性管理子项目间依赖
3. **错误处理** - [统一错误处理机制]
4. **版本控制** -
   - Git 提交必须使用 AskUserQuestion 工具询问用户同意
   - 提交消息必须包含:
     - 问题描述(What)
     - 根本原因(Why)
     - 修复内容(How)
     - 技术细节(Details)
     - 影响范围(Impact)
   - **严格禁止**包含以下内容:
     - `🤖 Generated with [Claude Code](https://claude.com/claude-code)`
     - `Co-Authored-By: Claude <noreply@anthropic.com>`
     - 其他任何 AI 工具的标识或署名
5. **禁止行为** - [明确禁止的操作]
   - 禁止子项目间的紧耦合
   - 禁止绕过 API 直接访问其他子项目的数据库

### Claude Code 工具使用规范

**AI 必须使用的工具**:
- **AskUserQuestion**: 数据不足或需要决策时,必须主动询问用户
- **TodoWrite**: 跟踪多步骤任务的进度,及时更新任务状态
- **Read/Grep/Glob**: 修改前必须先分析现有代码,避免重复定义
- **Plan**: 设计实施方案时,必须使用 Plan 工具进行规划和架构设计
- **跨项目影响分析**: 修改子项目代码时,必须分析对其他子项目的影响

### Skills 技能使用规范(强制)

Skills 是可扩展的专业能力模块,**必须**根据场景强制使用对应技能。

#### 强制使用场景映射表

> **使用说明**: 根据项目实际可用的 Skills 填充下表。通过 `<available_skills>` 列表获取当前环境可用技能。

| 触发场景 | 关键词识别 | 必须使用的技能 |
|---------|-----------|--------------|
| [场景1] | [关键词1、关键词2、...] | `[skill-name-1]` |
| [场景2] | [关键词1、关键词2、...] | `[skill-name-2]` |
| [场景3] | [关键词1、关键词2、...] | `[skill-name-3]` |

**常见场景类型参考**:
- 架构设计类:系统架构、技术选型、组件设计
- 可视化类:架构图、流程图、时序图、关系图
- 文档处理类:Word、PPT、PDF、Excel
- 前端设计类:UI设计、界面原型、组件设计

#### 强制触发规则

**以下场景必须调用对应技能,禁止跳过**:

1. **[场景类型1]**(触发 `[skill-name]`)
   - [具体触发条件1]
   - [具体触发条件2]
   - 用户提及"[关键词]"

2. **[场景类型2]**(触发 `[skill-name]`)
   - [具体触发条件1]
   - [具体触发条件2]

#### 技能调用检查清单

在完成任务前,必须检查:
- [ ] 是否识别到上述强制触发场景?
- [ ] 是否已调用对应的必需技能?
- [ ] 如未调用,是否有合理理由?(需向用户说明)

#### 禁止行为

- ❌ **禁止**在强制场景下不调用对应技能
- ❌ **禁止**用文字描述替代可视化输出(有可视化技能时)
- ❌ **禁止**跳过专业技能直接输出低质量结果

#### 技能调用语法

使用 Skill 工具,参数 skill 设置为技能名称:

  • [根据 <available_skills> 列表填充]

#### 动态技能发现流程

1. **识别任务类型**:分析用户需求,判断是否需要专业技能支持
2. **查看可用技能**:通过系统提供的 `<available_skills>` 列表确认当前可用的技能
3. **匹配场景映射**:根据上表的场景映射,确定必须调用的技能
4. **调用技能**:使用 `Skill` 工具调用对应技能

**Token 管理规范(强制)**:

在开始每个 todo 任务前,必须评估剩余 token 是否足够完成该任务:

1. **评估标准**:
   - 当前剩余 token < 30000:存在风险
   - 当前剩余 token < 20000:高风险
   - 当前剩余 token < 10000:极高风险

2. **风险处理流程**:

   **如果存在风险**,必须使用 AskUserQuestion 工具询问用户:

   ```yaml
   question: "⚠️ Token 预警:当前剩余 [X] tokens,即将开始「[Todo任务名称]」可能存在 token 不足风险。您希望如何处理?"
   header: "Token 管理"
   multiSelect: false
   options:
     - label: "继续执行当前任务"
       description: "继续完成当前任务,可能需要在新会话中继续未完成的工作"
     - label: "生成进度总结文档"
       description: "生成包含当前进度总结和剩余待办事项实施方案的文档,便于在新会话中继续"
  1. 生成进度总结文档(用户选择选项 2 时):

    创建文档:docs/progress/YYYY-MM-DD-HH-MM-[任务名称]-进度总结.md

    文档必须包含:

    # [任务名称] - 进度总结与实施方案
    
    **创建时间**: YYYY-MM-DD HH:MM
    **当前状态**: 进行中
    **完成度**: X/Y 个任务
    **项目类型**: Monorepo
    
    ---
    
    ## 一、已完成任务
    
    ### 1.1 任务清单
    - [x] 任务 1 - 完成情况描述
    - [x] 任务 2 - 完成情况描述
    - [x] 任务 3 - 完成情况描述
    
    ### 1.2 关键成果
    - **成果 1**: 具体内容和路径
    - **成果 2**: 具体内容和路径
    - **成果 3**: 具体内容和路径
    
    ### 1.3 已修改文件(Monorepo)
    

    [子项目1]/path/to/file1.ext - 修改内容描述 [子项目2]/path/to/file2.ext - 修改内容描述 共享库/path/to/shared.ext - 修改内容描述

    
    ### 1.4 跨项目影响
    - **[子项目1]**: 影响描述
    - **[子项目2]**: 影响描述
    - **共享代码**: 影响范围
    
    ---
    
    ## 二、剩余待办任务
    
    ### 2.1 待办清单
    - [ ] 任务 4 - 详细描述(涉及子项目:[列表])
    - [ ] 任务 5 - 详细描述(涉及子项目:[列表])
    - [ ] 任务 6 - 详细描述(涉及子项目:[列表])
    
    ### 2.2 实施方案
    
    #### 任务 4: [任务名称]
    **目标**: [具体目标]
    **涉及子项目**: [子项目列表]
    
    **步骤**:
    1. [详细步骤 1]
    2. [详细步骤 2]
    3. [详细步骤 3]
    
    **需要修改的文件**:
    - `[子项目1]/path/to/file1.ext` - [修改说明]
    - `[子项目2]/path/to/file2.ext` - [修改说明]
    - `共享库/path/to/shared.ext` - [修改说明]
    
    **跨项目影响**:
    - [子项目1]: [影响说明]
    - [子项目2]: [影响说明]
    
    **注意事项**:
    - [注意点 1]
    - [注意点 2]
    
    #### 任务 5: [任务名称]
    ... (同上格式)
    
    ---
    
    ## 三、技术背景和上下文
    
    ### 3.1 Monorepo 架构
    

    [展示 monorepo 结构和子项目关系]

    
    ### 3.2 子项目信息
    - **[子项目1]**: [技术栈] - [职责]
    - **[子项目2]**: [技术栈] - [职责]
    
    ### 3.3 重要约束
    - [约束 1]
    - [约束 2]
    - [Monorepo 特定约束]
    
    ### 3.4 已知问题
    - [问题 1 及解决方案]
    - [问题 2 及解决方案]
    
    ---
    
    ## 四、继续工作指南
    
    ### 4.1 快速启动
    在新会话中执行以下步骤:
    1. 阅读本文档了解当前进度
    2. 使用 TodoWrite 工具恢复任务列表
    3. 从「任务 4」开始继续执行
    4. 注意跨项目影响分析
    
    ### 4.2 验证检查清单
    开始前请确认:
    - [ ] 已理解所有已完成任务的内容
    - [ ] 已查看所有修改过的文件(包括所有子项目)
    - [ ] 已理解剩余任务的实施方案
    - [ ] 已了解 Monorepo 架构和子项目关系
    - [ ] 已了解跨项目影响范围
    
    ---
    
    **🤖 Generated with Claude Code**
    
  2. 文档生成后:

    • 输出文档路径
    • 提示用户在新会话中使用 @文档路径 继续工作
    • 优雅结束当前会话

最佳实践:

  • 定期评估 token 使用情况
  • 在大型任务开始前进行评估
  • Monorepo 项目由于涉及多个子项目,通常需要更多 tokens
  • 预留至少 20000 tokens 的安全边际
  • 及时保存进度,避免工作丢失

AI 工作流程与质量门(强制)

工作流程总览

需求输入
   ↓
A. 立项/澄清(Gate 0)
   ↓  KISS + YAGNI + AskUserQuestion
   ↓
B. 方案设计(Gate 1)
   ↓  SoC/LoD/组合优于继承 + DIP/ISP
   ↓
C. 编码前置(Gate 2)
   ↓  DRY + 分层职责 + 前置条件信任
   ↓
D. 编码实现
   ↓  SOLID + 幂等/限流/熔断 + 可观测性
   ↓
E. 测试与验收(Gate 3)
   ↓  单测+契约 + Mock + 覆盖率
   ↓
开发完成 ✅
(发布与运维不在此范围)

A. 立项/澄清阶段(Gate 0)

目标: 明确需求边界,拒绝过度设计

使用原则:

  • KISS + YAGNI → 先砍需求,确认功能必要性
  • AskUserQuestion → 明确边界与约束

输出:

  • 需求边界清晰
  • 最小方案草图
  • 走审批流程

质量门 Gate 0:问题澄清

  • 已使用 AskUserQuestion 收敛需求与约束
  • KISS 四问已回答(特别是"真的需要这个功能吗?")
  • 需求边界明确,无歧义

B. 方案设计阶段(Gate 1)

目标: 设计可扩展、可维护的方案

使用原则:

  • SoC/LoD/组合优于继承 → 明确分层边界,减少耦合
  • DIP/ISP → 稳住扩展点,依赖抽象

输出:

  • 方案文档(docs/todo/YYYY-MM-DD-HH-MM-功能名称-方案.md)
  • 必须包含:
    • 完整调用链路分析(包括跨项目调用)
    • KISS 四问的回答
    • 性能影响评估
    • 跨项目影响分析
    • 风险分析和缓解措施

质量门 Gate 1:方案评审

  • 方案文档已提交
  • 调用链路分析完整
  • KISS 四问已回答
  • 性能影响已评估
  • 跨项目影响已分析
  • 风险与缓解措施明确
  • 已获得用户审批

C. 编码前置阶段(Gate 2)

目标: 确保代码质量,避免重复实现

使用原则:

  • DRY → 全局检索避免重复(使用 grep,覆盖所有子项目)
  • SRP/SoC → 划清分层职责
  • 前置条件信任原则 → 避免重复验证

输出:

  • 代码重复检查报告(覆盖所有子项目)
  • 分层职责明确
  • 前置条件明确

质量门 Gate 2:实现前检查

  • 已使用 grep 全局检索所有子项目,无重复定义
  • 分层边界清晰,职责明确
  • 前置条件信任原则已应用
  • 接口契约明确

D. 编码实现阶段

目标: 高质量代码实现

使用原则:

  • SOLID → 作为底座(SRP/OCP/LSP/ISP/DIP)
  • 幂等/限流/熔断 → 进到关键路径
  • 日志/指标/Trace → 埋点就位

输出:

  • 高质量代码
  • 可观测性埋点
  • 健壮性保障(幂等/限流/熔断)

关键检查:

  • SOLID 原则已遵循
  • 关键路径已添加幂等/限流/熔断
  • 日志/指标/Trace 埋点完整

E. 测试与验收阶段(Gate 3)

目标: 确保代码质量和功能正确性

使用原则:

  • 测试金字塔 → 单测+契约优先
  • Mock → 隔离外部依赖

输出:

  • 测试报告(docs/test/YYYY-MM-DD-HH-MM-功能名称-测试报告.md)
  • 测试覆盖率报告(各子项目)

质量门 Gate 3:测试门

  • 单元测试覆盖率 ≥ 80%(或项目自定义值)
  • 集成测试已通过(包括跨项目集成测试)
  • 必要的契约测试已完成
  • Mock 数据已准备(test/data/)
  • 测试报告已生成

核心开发实践(强制)

1. 代码修改前的分析(强制)

所有代码修改前,必须先完成深度分析,理解 Monorepo 架构后再设计方案。

调用链路分析要点(Monorepo)
用户请求 → [子项目1入口] → [子项目1业务逻辑] → [跨项目API调用] → [子项目2] → [数据存储]

必须分析:

  • 入口点: 请求从哪个子项目的哪个端点进入
  • 跨项目调用: 数据如何在子项目间流转
  • 依赖关系: 各子项目之间的依赖
  • 错误传播: 错误如何跨项目传播
  • 数据一致性: 跨项目的事务和一致性保证
方案设计原则: KISS

设计前必须回答4个问题:

  1. "这是真问题还是臆想的?" - 拒绝过度设计
  2. "有更简单的方法吗?" - 永远寻找最简方案
  3. "会破坏什么吗?" - 向后兼容是铁律,考虑对所有子项目的影响
  4. "真的需要这个功能吗?" - 确认功能必要性

性能要求:

  • 最小化跨项目通信次数
  • 优先使用批量操作
  • 合理使用缓存减少跨项目调用
  • 避免不必要的数据复制

代码简洁性:

  • 能用30行解决,绝不写300行
  • 复用现有代码和共享库
  • 函数职责单一
数据驱动的方案设计(强制)

所有方案必须有充足的数据支撑:

数据充足性判断:

  • ✅ 是否完整理解现有代码实现逻辑?
  • ✅ 是否掌握各子项目之间的调用关系?
  • ✅ 是否了解跨项目的性能瓶颈?
  • ✅ 是否分析业界 Monorepo 最佳实践?
  • ✅ 是否评估不同方案优劣?

数据不足时的处理:

⚠️ 我没有足够的信心设计最佳方案

需要以下数据:
1. [具体需要的数据1]
2. [具体需要的数据2]
...

请提供这些数据或告诉我如何获取。

禁止:

  • ❌ 基于猜测或假设进行方案设计
  • ❌ 数据不足时强行给出方案
  • ❌ 使用"可能"、"也许"等不确定词汇描述关键决策
  • ❌ 忽视跨项目影响
方案审批流程(强制)

在实施任何代码修改前,必须先获得用户审批:

工作流程:

  1. 分析阶段: AI 使用只读工具(Read/Grep/Glob)深度分析所有相关子项目的代码
  2. 方案设计: 制定详细的实施方案,包括跨项目影响分析
  3. 展示方案: 向用户清晰展示方案,等待批准
  4. 执行修改: 获得批准后才开始实际修改代码

方案文档要求:

  1. 提交方案设计文档,包含:

    • 完整调用链路分析(包括跨项目调用)
    • 问题诊断和根因分析
    • 支撑数据和分析(必须包含)
    • 方案设计(架构图、时序图、代码片段)
    • KISS原则4问题的回答
    • 性能影响评估(特别是跨项目通信)
    • 跨项目影响分析(列出所有受影响的子项目)
    • 风险分析和缓解措施
    • 文档保存: 保存到 docs/todo/YYYY-MM-DD-HH-MM-功能名称-方案.md
  2. 等待用户确认 - 批准后方可开始实施

  3. 实施 - 严格按照批准方案执行

分析检查清单

开始编码前必须完成:

  • 已完整追踪调用链路(包括跨项目调用)
  • 已理解所有涉及子项目的职责
  • 已识别所有跨项目数据传递点
  • 已回答KISS原则4个问题
  • 已收集充足数据支撑方案
  • 已分析对所有子项目的影响
  • 已制定详细实施方案
  • 已获得用户审批确认

2. SOLID原则(强制执行)

所有架构设计和代码实现必须遵循SOLID原则:

Monorepo 特别注意:

  • 在 Monorepo 中,SOLID 原则不仅适用于单个子项目内部,也适用于子项目之间的关系
  • 子项目间的接口设计同样需要遵循 SOLID 原则
1. 单一职责原则(SRP - Single Responsibility Principle)
  • 定义:一个类/模块只负责一个功能领域的变化
  • 实践要点:
    • 每个包/模块职责单一且清晰
    • 工厂负责创建,适配器负责转换,具体实现负责执行
    • 避免"上帝类"或"万能函数"
    • 一个模块的修改原因只能有一个
  • Monorepo 应用:
    • 每个子项目应该有明确且单一的职责
    • 避免子项目职责过于复杂或模糊
2. 开闭原则(OCP - Open-Closed Principle)
  • 定义:对扩展开放,对修改封闭
  • 实践要点:
    • 添加新功能通过扩展实现,不修改现有代码
    • 使用接口和抽象类定义扩展点
    • 新增实现只需创建新文件,无需修改旧代码
    • 避免使用大量 switch/if-else 判断类型
  • Monorepo 应用:
    • 添加新子项目不应该需要修改现有子项目
    • 子项目间的 API 应该稳定,通过版本控制实现兼容
3. 里氏替换原则(LSP - Liskov Substitution Principle)
  • 定义:子类必须能够替换父类而不影响程序正确性
  • 实践要点:
    • 所有实现同一接口的类必须可互换
    • 接口契约必须保持一致
    • 不违反接口定义的前置条件和后置条件
    • 调用方不应关心具体实现类型
  • Monorepo 应用:
    • 如果多个子项目实现相同的接口,它们应该可以互相替换
    • 共享接口的契约必须严格遵守
4. 接口隔离原则(ISP - Interface Segregation Principle)
  • 定义:客户端不应该依赖它不需要的接口
  • 实践要点:
    • 接口应该小而专注,只包含必要方法
    • 避免臃肿的接口定义
    • 根据客户端需求定义最小接口
    • 大接口应拆分为多个小接口
  • Monorepo 应用:
    • 子项目之间的 API 应该精简,只暴露必要的接口
    • 避免一个子项目暴露过多不相关的功能
5. 依赖倒置原则(DIP - Dependency Inversion Principle)
  • 定义:高层模块不应该依赖低层模块,两者都应该依赖抽象
  • 实践要点:
    • 依赖接口而不是具体实现
    • 通过依赖注入传递依赖
    • 抽象层不依赖具体层
    • 具体实现可以随时替换
  • Monorepo 应用:
    • 子项目之间应该通过定义良好的接口通信
    • 避免直接依赖其他子项目的具体实现
    • 使用共享接口定义实现解耦
SOLID原则检查清单

设计新功能前必须回答:

  • SRP:每个模块的职责是否单一明确?(包括子项目级别)
  • OCP:添加新功能是否需要修改现有代码?(包括其他子项目)
  • LSP:所有实现是否可以互换使用?(包括跨子项目)
  • ISP:接口是否臃肿,是否包含不必要的方法?(包括跨项目 API)
  • DIP:是否依赖抽象而不是具体实现?(包括子项目间依赖)

违反SOLID原则的后果:

  • 代码耦合度高,难以维护
  • 功能扩展需要大量修改现有代码
  • 子项目间紧耦合,难以独立开发和部署
  • 测试困难,无法进行单元测试
  • 技术债务快速累积
2.2 DRY(Don't Repeat Yourself)
  • 原则: 避免重复实现,优先复用现有代码和共享库
  • 实践: 添加任何新定义前,必须先用 grep -r "functionName\|className" 检查所有子项目
  • 目标: 每个知识点在系统中只有唯一、明确的表达
2.3 SoC(Separation of Concerns)
  • 原则: 关注点分离,不同关注点分离到不同模块
  • 实践: 与层职责定义和调用链分析一致,明确各层边界
  • 目标: 业务逻辑、数据访问、UI展示、基础设施各司其职
  • Monorepo 应用: 每个子项目应有明确的关注点
2.4 LoD(Law of Demeter / 最少知道原则)
  • 原则: 一个对象应当对其他对象有尽可能少的了解
  • 实践: 减少跨层/跨域/跨项目耦合,只与直接朋友通信
  • 规则: 只调用以下方法:
    • 对象自身的方法
    • 方法参数的方法
    • 方法内创建对象的方法
    • 对象直接持有的组件的方法
2.5 组合优于继承
  • 原则: 优先使用对象组合而不是类继承来实现代码复用
  • 实践: 配合 OCP/LSP,把变更点外提为组合件
  • 优点: 更灵活、更易测试、避免继承层次过深
2.6 YAGNI(You Aren't Gonna Need It)
  • 原则: 只实现当前需要的功能,不为未来可能的需求预先设计
  • 实践: 与 KISS 搭配,拒绝"也许将来会用到"的功能
  • 目标: 减少不必要的复杂性和维护成本

3. 架构与健壮性原则

3.1 Clean/Hexagonal/Ports & Adapters 架构
  • 原则: 接口抽象 + 适配器模式,把外部依赖隔离进边界层
  • 实践:
    • 核心业务逻辑不依赖外部框架、数据库、UI
    • 通过端口(接口)定义核心与外部的交互契约
    • 通过适配器实现具体的外部集成(数据库、API、消息队列)
  • 目标: 与 DIP/ISP 强一致,实现核心业务的可测试性和可替换性
3.2 12-Factor App(服务化应用实践)
  • 配置外置: 配置通过环境变量注入,不硬编码在代码中
  • 无状态进程: 进程无状态,会话状态存储在外部(Redis等)
  • 日志标准输出: 日志输出到 stdout/stderr,由日志收集系统统一处理
  • 一次性进程: 进程可以快速启动和优雅关闭
  • 依赖隔离: 显式声明依赖,不依赖系统全局包
  • 端口绑定: 服务通过端口暴露,自包含运行
3.3 幂等性 & 去重
  • 原则: 写接口、任务重试、事件消费的第一性原则
  • 实践:
    • API设计: POST/PUT 使用幂等键(idempotency-key)
    • 消息消费: 使用消息ID去重,确保至少一次处理
    • 数据库操作: 使用唯一索引防止重复插入
  • 目标: 保证系统在重试、网络抖动情况下的数据一致性
3.4 限流/熔断/重试/退避(服务健壮性四件套)
  • 限流:

    • 保护系统不被突发流量压垮
    • 实现: 令牌桶、漏桶、滑动窗口
    • 默认: 100 RPS/实例(可根据项目调整)
  • 熔断:

    • 快速失败,防止级联故障
    • 触发条件: 20%错误率或连续N次失败(可根据项目调整)
    • 状态: 关闭 → 打开 → 半开 → 关闭
  • 重试:

    • 应对临时性故障
    • 策略: 指数退避(1s, 2s, 4s),最多3次
    • 注意: 必须配合幂等性设计
  • 退避:

    • 避免雪崩效应
    • 策略: 固定退避、指数退避、带抖动的指数退避

4. 功能版本迭代限制

禁止版本迭代: 对于存量功能,严格禁止版本迭代(v1、v2、v3)

核心原则:

  • 就地更新: 所有改进必须直接修改现有代码
  • 用户主导: 只有用户明确要求才能创建新版本
  • 单一实现: 每个功能只能有一个实现版本
  • 向后兼容: 必须保持向后兼容,考虑所有依赖该功能的子项目
  • 清理废弃: 必须版本迭代时同时清理旧代码

4. 任务解析与影响分析

任务前置分析原则: 执行任何任务前,必须先进行全面分析

文件影响评估(Monorepo)
  • 主要修改文件: 直接需要编辑的核心文件
  • 关联影响文件: 同一子项目中可能受影响的文件
  • 跨项目影响文件: 其他子项目中可能受影响的文件
  • 共享代码影响: 共享库和工具的影响范围
  • 测试相关文件: 需要更新或新增的测试文件(包括集成测试)
  • 配置文件: 可能需要调整的配置
依赖关系分析(Monorepo)
  • 子项目内依赖: 识别导入/引用关系
  • 跨项目依赖: 识别子项目间的调用关系
  • 共享代码依赖: 识别对共享库的依赖
重复定义检查

添加任何新定义前,必须先检查所有子项目:

# 检查所有子项目中的函数/类/接口定义
grep -r "functionName\|className" --include="*.[ext]" [所有子项目路径]

原则: 避免重复实现,优先复用现有代码和共享库

5. 前置条件信任原则

避免重复验证: 信任调用链的前置条件

分层职责:

  • 入口层: 负责验证和防护(通常在面向用户的子项目)
  • 业务层: 信任前置条件,专注业务
  • 数据层: 处理持久化,不做业务验证
  • 跨项目调用: 调用其他子项目的 API 时,信任其已完成验证

交互规范(强制)

沟通原则

  • 中文响应: 所有响应使用中文
  • 详细说明: 提供清晰的操作步骤和说明
  • 操作确认: 重要操作前进行确认
  • 透明度: 如实汇报进度、问题和风险
  • 跨项目影响说明: 修改代码时明确说明对其他子项目的影响

主动提问机制(强制)

  • 数据不足时提问: 缺乏必要信息时,必须使用 AskUserQuestion 工具询问用户
  • 明确性优先: 遇到模糊需求时,通过提问明确用户意图
  • 必须提问的场景:
    • 技术方案有多种实现路径需权衡时
    • 需要删除或修改重要功能/数据时
    • 修改可能影响多个子项目时
    • 配置参数会显著影响系统行为时
    • 不确定用户具体需求时
    • 设计决策可能影响架构或性能时
    • 存在跨项目向后兼容性风险时
  • 提问质量要求:
    • 问题应具体、聚焦
    • 提供2-4个清晰选项
    • 每个选项附带详细说明
    • 说明各选项的影响和优缺点(包括对各子项目的影响)
  • 等待确认: 提问后必须等待用户回答

文件创建限制(强制)

  • 禁止主动创建文档: 不主动创建文档文件(*.md)或README,除非用户明确要求
  • 优先编辑: 优先编辑现有文件而非创建新文件
  • 必要性原则: 只创建绝对必要的文件
  • 用户确认: 创建新文件前必须征得用户同意

Monorepo 特定规范

跨项目通信规范

  1. API 调用规范

    • 使用明确定义的 API 接口
    • API 变更必须遵循版本管理策略
    • 禁止直接访问其他子项目的内部实现
  2. 共享代码规范

    • 共享代码放在独立的包中
    • 共享代码必须有完善的文档和测试
    • 修改共享代码必须评估对所有依赖方的影响
  3. 数据共享规范

    • 优先使用 API 传递数据
    • 必要时可共享数据库,但需明确所有权
    • 禁止直接读写其他子项目的数据表

构建和部署规范

  1. 独立构建: 每个子项目应该能独立构建
  2. 依赖顺序: 明确子项目的构建依赖顺序
  3. 并行构建: 利用 workspace 工具进行并行构建
  4. 增量构建: 只构建有变更的子项目

最后更新: [日期]


---

## 执行步骤

### 1. 前置检查

a. 检查当前目录是否已存在 CLAUDE.md 文件
   - 使用 Read 工具尝试读取 ./CLAUDE.md
   - 如果文件存在,使用 AskUserQuestion 询问用户是否要覆盖:
     - 选项 1: "备份后覆盖"(推荐) - 将现有文件备份为 CLAUDE.md.backup-{timestamp}
     - 选项 2: "直接覆盖" - 直接覆盖现有文件
     - 选项 3: "取消操作" - 退出命令
   - 如果用户选择取消,立即终止执行并输出提示信息

### 1.5 检测 Monorepo 结构

**目标**: 智能检测项目是否为 Monorepo(包含多个子项目)

#### a. 检测显式 Monorepo 配置

使用 Read 工具检查是否有 Monorepo 配置:

```bash
# 1. 检测 Node.js workspaces
Read package.json → 检查 workspaces 字段
  - 如果存在 workspaces 数组 → isMonorepo = true, confidence = "high", type = "workspaces"

# 2. 检测 Lerna
Read lerna.json → 是否存在
  - 如果存在 → isMonorepo = true, confidence = "high", type = "lerna"

# 3. 检测 Turborepo
Read turbo.json → 是否存在
  - 如果存在 → isMonorepo = true, confidence = "high", type = "turborepo"

# 4. 检测 pnpm workspaces
Read pnpm-workspace.yaml → 是否存在
  - 如果存在 → isMonorepo = true, confidence = "high", type = "pnpm-workspaces"
b. 检测典型目录结构

如果没有检测到显式配置,使用 Glob 检测常见目录组合:

# 检测前后端分离
Glob: frontend
Glob: backend
  - 如果同时存在 → 检查是否有独立配置文件
    - frontend/package.json 或 frontend/其他配置 存在
    - backend/go.mod 或 backend/其他配置 存在
    - 如果是 → isMonorepo = true, confidence = "medium", type = "frontend-backend"

# 检测 client-server 结构
Glob: client
Glob: server
  - 同上逻辑

# 检测 web-api 结构
Glob: web
Glob: api
  - 同上逻辑

# 检测 Node.js packages/apps 结构
Glob: packages/*/package.json
Glob: apps/*/package.json
  - 如果找到多个(≥2个)子项目 → isMonorepo = true, confidence = "medium", type = "multi-packages"

# 检测 Go 多应用结构
Glob: cmd/*
  - 如果 cmd 目录下有多个子目录(≥2个)
  - 且根目录有 go.mod
  - → isMonorepo = true, confidence = "medium", type = "go-multi-app"

# 检测 Python/其他多服务结构
Glob: services/*/
  - 如果 services 目录下有多个子目录(≥2个)
  - 且子目录包含配置文件
  - → isMonorepo = true, confidence = "medium", type = "multi-services"
c. 检测多配置文件(兜底检测)

如果以上都未检测到,搜索所有配置文件:

# 搜索所有主要配置文件
Glob: **/package.json
Glob: **/go.mod
Glob: **/pyproject.toml
Glob: **/pom.xml
Glob: **/Cargo.toml

# 统计配置文件数量和位置
如果在不同的一级子目录中找到多个配置文件(≥2个):
  - isMonorepo = true
  - confidence = "low"  # 需要用户确认
  - type = "multi-project"
d. 结果记录

创建 Monorepo 检测结果数据结构:

MonorepoDetection = {
  isMonorepo: true/false,
  confidence: "high" | "medium" | "low" | null,
  type: "workspaces" | "lerna" | "turborepo" | "pnpm-workspaces" |
        "frontend-backend" | "multi-packages" | "go-multi-app" |
        "multi-services" | "multi-project" | null,
  subProjectPaths: [
    "frontend/",
    "backend/",
    // ... 其他子项目路径
  ]
}
e. 用户确认(confidence = "low" 时)

如果置信度为 "low",使用 AskUserQuestion 确认:

使用 AskUserQuestion:
  question: "检测到项目中有多个配置文件,这是一个包含多个子项目的 Monorepo 吗?"
  header: "Monorepo 确认"
  multiSelect: false
  options:
    - label: "是,这是一个 Monorepo"
      description: "项目包含多个独立的子项目(如前端+后端)"
    - label: "否,这是单个项目"
      description: "按照单项目模式分析"
f. 输出检测结果

输出检测摘要:

🔍 项目结构检测完成!

📦 项目类型: [Monorepo / 单项目]
🔧 检测方式: [检测到的配置类型]
📂 子项目: [子项目数量] 个
  - [子项目1路径]
  - [子项目2路径]
  ...

2. 项目分析(智能推断)

核心原则: 数据驱动,避免猜测。通过分析项目文件自动推断信息,减少用户输入负担。

a. 检测项目类型

使用 Read 工具检查项目配置文件:

Node.js/TypeScript 项目检测:

检测文件: package.json
提取信息:
  - 项目名称: name 字段
  - 项目描述: description 字段
  - 语言: 检查 devDependencies 中是否有 typescript
  - 框架: 从 dependencies 推断
    - "next" → Next.js
    - "react" → React
    - "vue" → Vue
    - "express" → Express
    - "nestjs" → NestJS
  - 测试框架: 从 devDependencies 推断 (jest, vitest, mocha 等)
  - 代码风格: 检查 eslintConfig, prettier 配置

Go 项目检测:

检测文件: go.mod
提取信息:
  - 项目名称: module 声明
  - 语言版本: go 版本行
  - 框架: 从 require 推断
    - "gin-gonic/gin" → Gin
    - "labstack/echo" → Echo
    - "gofiber/fiber" → Fiber

检测文件: go.sum (确认依赖)

Python 项目检测:

检测文件: pyproject.toml (优先) 或 requirements.txt 或 setup.py
提取信息:
  - 项目名称: [project].name 或从目录名推断
  - 语言版本: requires-python 字段
  - 框架: 从依赖推断
    - "fastapi" → FastAPI
    - "django" → Django
    - "flask" → Flask
  - 测试框架: pytest, unittest 等

Java 项目检测:

检测文件: pom.xml 或 build.gradle
提取信息:
  - 项目名称: artifactId 或 name
  - 语言版本: Java version
  - 框架: 从依赖推断
    - "spring-boot" → Spring Boot
    - "micronaut" → Micronaut
    - "quarkus" → Quarkus
b. 分析项目结构

使用 Glob 工具列举项目目录,推断架构模式:

# 检测顶层目录
检测路径:
  - src/, lib/, pkg/ (源代码目录)
  - test/, tests/, __tests__/ (测试目录)
  - docs/ (文档目录)

架构模式推断:
  - 存在 src/controllers, src/services, src/models → 分层架构(MVC)
  - 存在 src/api, src/service, src/logic, src/data → 分层架构(四层)
  - 存在 packages/, services/, apps/ → 微服务架构
  - 存在 functions/, lambda/ → Serverless
  - 否则 → 单体应用
c. 分析代码风格

使用 Read 工具读取几个代码文件样本:

# 读取 2-3 个代码文件
# 分析变量命名模式

命名规范检测:
  - 检测变量/函数名中的模式
  - camelCase: 首字母小写 (userName, getUserData)
  - PascalCase: 首字母大写 (UserName, GetUserData)
  - snake_case: 下划线连接 (user_name, get_user_data)

Lint 配置检测:
  - .eslintrc.* (JavaScript/TypeScript)
  - .golangci.yml (Go)
  - .flake8, pyproject.toml (Python)
  - checkstyle.xml (Java)
d. 分析数据存储

使用 Grep 工具搜索数据库相关导入和配置:

# 搜索数据库导入语句
关键词:
  - "mysql", "pg", "postgres" → PostgreSQL/MySQL
  - "mongodb", "mongo" → MongoDB
  - "redis" → Redis
  - "elasticsearch", "es" → Elasticsearch

# 搜索配置文件
检查:
  - docker-compose.yml (服务定义)
  - .env.example (环境变量示例)
  - config/ 目录下的配置文件
e. 检测测试配置
检测测试目录:
  - test/, tests/, __tests__/ 是否存在
  - 测试文件数量和覆盖情况

检测测试配置:
  - jest.config.js, vitest.config.ts (JS/TS)
  - go.mod 中的测试依赖
  - pytest.ini, tox.ini (Python)
  - pom.xml 中的测试配置 (Java)

推断测试要求:
  - 存在完善测试配置 + 多个测试文件 → 建议 >80%
  - 存在基础测试 → 建议 >60%
  - 无测试 → 不强制要求
f. 记录推断结果

创建推断结果数据结构,记录每项信息的值和置信度:

分析结果 = {
  projectName: {
    value: "从配置文件读取的名称",
    source: "package.json",
    confidence: "high"  // high: 确定 | medium: 较确定 | low: 需确认 | none: 未检测到
  },
  projectDescription: {
    value: "从配置文件读取的描述",
    source: "package.json",
    confidence: "medium"  // 描述可能不准确,建议用户确认
  },
  language: {
    value: "TypeScript 5.0+",
    source: "package.json devDependencies",
    confidence: "high"
  },
  framework: {
    value: "Next.js",
    source: "package.json dependencies",
    confidence: "high"
  },
  storage: {
    value: ["PostgreSQL", "Redis"],
    source: "grep 搜索和 docker-compose.yml",
    confidence: "medium"
  },
  architecture: {
    value: "分层架构",
    source: "目录结构分析",
    confidence: "medium"
  },
  namingStyle: {
    value: "驼峰命名(camelCase)",
    source: "代码文件分析",
    confidence: "high"
  },
  testCoverage: {
    value: ">80%",
    source: "测试配置和文件检测",
    confidence: "medium"
  },
  gitApproval: {
    value: null,  // 这个需要用户决策
    source: null,
    confidence: "none"
  }
}
g. 输出分析结果

输出分析摘要供用户查看:

🔍 项目分析完成!

📊 自动检测结果:
✅ 项目类型: TypeScript 项目 (来源: package.json)
✅ 项目名称: my-app (来源: package.json)
✅ 开发语言: TypeScript 5.0+ (来源: package.json)
✅ 主要框架: Next.js (来源: dependencies)
✅ 数据存储: PostgreSQL, Redis (来源: docker-compose.yml)
✅ 架构模式: 分层架构 (来源: 目录结构)
✅ 命名规范: 驼峰命名 (来源: 代码分析)
⚠️  测试要求: 建议 >80% (来源: 测试配置)

❓ 需要您确认的信息:
- 项目描述 (自动检测可能不准确)
- Git 提交流程 (需要您的决策)

2.5 分析子项目(Monorepo 场景)

仅在步骤 1.5 检测到 Monorepo 时执行此步骤

a. 遍历子项目

对 MonorepoDetection.subProjectPaths 中的每个子项目路径执行分析:

对于每个子项目路径 (例如 "frontend/", "backend/"):
  1. 进入子项目目录上下文(相对路径)

  2. 检测项目类型(重复步骤 2.a 的逻辑,但在子目录中)
     - 读取 [子项目路径]/package.json
     - 读取 [子项目路径]/go.mod
     - 读取 [子项目路径]/pyproject.toml
     - 读取 [子项目路径]/pom.xml
     - ... 其他配置文件

  3. 提取项目信息(重复步骤 2.a 的逻辑)
     - 项目名称
     - 项目描述
     - 语言和框架
     - 测试框架
     - 代码风格

  4. 分析项目结构(重复步骤 2.b 的逻辑)
     - 使用 Glob 列举子项目的子目录
     - 推断子项目的架构模式

  5. 分析代码风格(重复步骤 2.c 的逻辑)
     - 读取子项目中的代码文件样本

  6. 分析数据存储(重复步骤 2.d 的逻辑)
     - 搜索数据库相关导入
     - 检查子项目的配置文件

  7. 检测测试配置(重复步骤 2.e 的逻辑)
     - 检测子项目的测试目录
     - 检测子项目的测试配置
b. 汇总子项目分析结果

创建子项目分析结果数据结构:

SubProjectsAnalysis = [
  {
    path: "frontend/",
    projectName: {
      value: "Web Frontend",
      source: "frontend/package.json",
      confidence: "high"
    },
    projectDescription: {
      value: "用户界面应用",
      source: "frontend/package.json",
      confidence: "medium"
    },
    language: {
      value: "TypeScript 5.0+",
      source: "frontend/package.json",
      confidence: "high"
    },
    framework: {
      value: "Next.js 14",
      source: "frontend/package.json dependencies",
      confidence: "high"
    },
    architecture: {
      value: "组件化架构",
      source: "目录结构分析",
      confidence: "medium"
    },
    namingStyle: {
      value: "驼峰命名 (camelCase)",
      source: "代码分析",
      confidence: "high"
    },
    storage: {
      value: null,
      source: null,
      confidence: "none"  // 前端通常不直接访问数据库
    },
    testCoverage: {
      value: ">80%",
      source: "测试配置",
      confidence: "medium"
    }
  },
  {
    path: "backend/",
    projectName: {
      value: "API Server",
      source: "backend/go.mod",
      confidence: "high"
    },
    projectDescription: {
      value: "RESTful API 服务",
      source: "推断",
      confidence: "low"
    },
    language: {
      value: "Go 1.21+",
      source: "backend/go.mod",
      confidence: "high"
    },
    framework: {
      value: "Gin",
      source: "backend/go.mod require",
      confidence: "high"
    },
    architecture: {
      value: "分层架构",
      source: "目录结构分析",
      confidence: "medium"
    },
    namingStyle: {
      value: "驼峰命名 (camelCase)",
      source: "代码分析",
      confidence: "high"
    },
    storage: {
      value: ["PostgreSQL", "Redis"],
      source: "grep 搜索和配置文件",
      confidence: "medium"
    },
    testCoverage: {
      value: ">80%",
      source: "测试配置",
      confidence: "medium"
    }
  }
  // ... 其他子项目
]
c. 推断项目间关系

基于子项目类型和配置,推断项目间的关系:

ProjectRelations = [
  {
    from: "frontend/",
    to: "backend/",
    relation: "API 调用",
    confidence: "high",  // 基于前端是 web 应用,后端是 API 服务
    description: "前端通过 HTTP API 调用后端服务"
  }
  // 可以根据配置文件中的 API 地址等信息进一步确认
]
d. 限制子项目数量

为了保证性能和可维护性:

如果检测到的子项目数量 > 10:
  使用 AskUserQuestion 让用户选择:
    question: "检测到 [数量] 个子项目,数量较多。您希望如何处理?"
    header: "子项目数量"
    multiSelect: false
    options:
      - label: "分析前 10 个子项目"
        description: "只分析最重要的 10 个子项目"
      - label: "让我手动选择"
        description: "展示所有子项目,让我选择要分析的"
      - label: "全部分析(不推荐)"
        description: "可能需要较长时间"
e. 输出子项目分析摘要
📦 Monorepo 子项目分析完成!

共检测到 [数量] 个子项目:

📂 frontend/ - Web Frontend
  ✅ 语言: TypeScript 5.0+
  ✅ 框架: Next.js 14
  ✅ 架构: 组件化架构

📂 backend/ - API Server
  ✅ 语言: Go 1.21+
  ✅ 框架: Gin
  ✅ 架构: 分层架构
  ✅ 数据: PostgreSQL, Redis

🔗 项目关系:
  frontend/ → backend/ (API 调用)

2.6 检测可用 Skills

目标: 检测当前环境中可用的 Skills,用于生成适配的 CLAUDE.md

a. 获取可用 Skills 列表

从系统提供的 <available_skills> 标签中提取当前可用的技能列表:

AvailableSkills = [
  {
    name: "skill-name",           // 技能名称
    description: "技能描述",       // 技能功能描述
    location: "user/plugin"       // 技能来源
  }
  // ... 其他技能
]
b. 分类 Skills

根据技能描述将其分类:

SkillCategories = {
  design: [],        // 设计类技能(canvas-design, frontend-design 等)
  document: [],      // 文档处理类技能(xlsx, docx, pptx, pdf 等)
  data: [],          // 数据分析类技能
  visualization: [], // 可视化类技能
  other: []          // 其他技能
}

分类规则:

  • 包含 "design"、"visual"、"UI"、"界面" → design
  • 包含 "xlsx"、"docx"、"pptx"、"pdf"、"document"、"文档" → document
  • 包含 "data"、"分析"、"analysis" → data
  • 包含 "chart"、"图表"、"可视化" → visualization
  • 其他 → other
c. 记录 Skills 检测结果
SkillsDetection = {
  available: true/false,          // 是否有可用技能
  count: N,                       // 可用技能数量
  skills: AvailableSkills,        // 完整技能列表
  categories: SkillCategories,    // 分类后的技能
  forTemplate: [                  // 用于模板生成的技能信息
    {
      category: "设计阶段",
      skills: ["canvas-design - 创建视觉设计", "frontend-design - 前端界面开发"]
    },
    {
      category: "文档处理",
      skills: ["xlsx - 电子表格处理", "docx - 文档编辑", "pdf - PDF处理"]
    }
  ]
}
d. 输出检测结果
🔧 Skills 检测完成!

📊 检测结果:
✅ 可用技能数量: [数量] 个

📋 技能分类:
  🎨 设计类: [数量] 个
  📄 文档类: [数量] 个
  📊 数据类: [数量] 个
  📈 可视化: [数量] 个
  🔧 其他: [数量] 个

💡 这些技能将被写入 CLAUDE.md 的 Skills 使用规范中

3. 智能信息收集

根据项目分析结果,只对置信度低或无法推断的信息进行询问。

询问策略:

A. confidence = "high" 的信息:

  • ✅ 直接使用,不询问
  • 在最终确认时展示给用户

B. confidence = "medium" 的信息:

  • ⚠️ 作为推荐选项,但仍询问用户确认
  • 在选项中标注 "(已检测)"

C. confidence = "low" 或 "none" 的信息:

  • ❌ 必须询问用户
  • 提供常见选项供选择
询问示例:

场景 1: 项目名称 confidence="high"

不询问,直接使用检测到的值

场景 2: 项目描述 confidence="medium"

使用 AskUserQuestion:
  question: "请确认项目描述:"
  header: "项目描述"
  multiSelect: false
  options:
    - label: "使用检测到的描述 (已检测)"
      description: "Web application for user management"
    - label: "Web 应用后端服务"
      description: "提供 RESTful API 的后端服务"
    - Other: 自定义描述

场景 3: 数据存储 confidence="medium"

使用 AskUserQuestion:
  question: "请确认项目使用的数据存储技术(可多选):"
  header: "数据存储"
  multiSelect: true
  options:
    - label: "PostgreSQL (已检测)"
      description: "关系型数据库"
    - label: "Redis (已检测)"
      description: "缓存系统"
    - label: "MySQL"
      description: "关系型数据库"
    - Other: 其他存储技术

场景 4: Git 提交流程 confidence="none"

使用 AskUserQuestion:
  question: "Git 提交是否需要审批确认?"
  header: "提交规范"
  multiSelect: false
  options:
    - label: "需要(使用 AskUserQuestion)"
      description: "提交前必须询问用户确认"
    - label: "不需要"
      description: "允许直接提交"
分批询问流程:

根据实际需要询问的问题数量,灵活分批:

如果需要询问 0-2 个问题: 一次性询问 如果需要询问 3-5 个问题: 分 2 批询问 如果需要询问 6+ 个问题: 分 3-4 批询问

优先级排序:

  1. 高优先级: 项目描述、架构模式 (影响模板填充)
  2. 中优先级: 数据存储、命名规范 (可能影响规范细节)
  3. 低优先级: 测试要求、Git 提交规范 (配置项)
Monorepo 策略询问(仅 Monorepo 场景):

仅在步骤 1.5 检测到 Monorepo 时执行

在完成常规信息收集后,询问用户如何生成 CLAUDE.md:

使用 AskUserQuestion:
  question: "检测到这是一个 Monorepo 项目,包含 [数量] 个子项目。您希望如何生成 CLAUDE.md?"
  header: "Monorepo 策略"
  multiSelect: false
  options:
    - label: "只在根目录生成统一的 CLAUDE.md(推荐)"
      description: "生成一个包含所有子项目信息的统一规范文件,便于整体管理"
    - label: "为每个子项目生成独立的 CLAUDE.md"
      description: "在根目录和每个子项目目录都生成独立的 CLAUDE.md,便于各自开发"
    - label: "仅为根目录生成,忽略子项目"
      description: "按照单项目模式生成,不体现子项目信息"

记录用户选择:

  • 选项 1 → userStrategy = "unified"
  • 选项 2 → userStrategy = "separate"
  • 选项 3 → userStrategy = "ignore"

4. 生成 CLAUDE.md

根据分析结果和用户确认的信息,执行以下步骤:

判断项目类型:

  • 如果是单项目 或 userStrategy = "ignore" → 使用单项目模板
  • 如果是 Monorepo 且 userStrategy = "unified" → 使用Monorepo 统一模板
  • 如果是 Monorepo 且 userStrategy = "separate" → 使用Monorepo 统一模板 + 子项目模板
4.0 Skills 适配(所有场景)

在填充模板前,根据步骤 2.6 检测到的 Skills 生成动态的 Skills 使用规范:

a. 如果 SkillsDetection.available = true(有可用技能):

生成具体的 Skills 使用规范内容:

### Skills 技能使用规范(强制)

Skills 是可扩展的专业能力模块,**必须**根据场景强制使用对应技能。

#### 强制使用场景映射表

| 触发场景 | 关键词识别 | 必须使用的技能 |
|---------|-----------|--------------|
{根据 SkillsDetection.forTemplate 动态生成场景映射}
{遍历每个技能,生成对应的触发场景行}

**场景映射生成规则**:
- 架构设计类技能 → 触发场景: 架构设计 | 关键词: 架构、设计方案、技术选型、系统设计
- 可视化类技能 → 触发场景: 可视化图表 | 关键词: 架构图、流程图、时序图、画图
- 文档处理类技能(docx) → 触发场景: 正式文档 | 关键词: Word文档、正式报告
- 文档处理类技能(pptx) → 触发场景: 演示汇报 | 关键词: PPT、演示文稿
- 文档处理类技能(xlsx) → 触发场景: 数据分析 | 关键词: 对比表格、Excel
- 文档处理类技能(pdf) → 触发场景: PDF处理 | 关键词: PDF导出、PDF生成
- 前端设计类技能 → 触发场景: UI/界面设计 | 关键词: 界面设计、UI原型

#### 强制触发规则

**以下场景必须调用对应技能,禁止跳过**:

{根据检测到的技能分类,动态生成触发规则}

1. **[场景类型]**(触发 `[skill-name]`)
   - [根据技能描述生成具体触发条件]
   - 用户提及"[关键词]"

#### 技能调用检查清单

在完成任务前,必须检查:
- [ ] 是否识别到上述强制触发场景?
- [ ] 是否已调用对应的必需技能?
- [ ] 如未调用,是否有合理理由?(需向用户说明)

#### 禁止行为

- ❌ **禁止**在强制场景下不调用对应技能
- ❌ **禁止**用文字描述替代可视化输出(有可视化技能时)
- ❌ **禁止**跳过专业技能直接输出低质量结果

#### 技能调用语法

使用 Skill 工具,参数 skill 设置为技能名称: {遍历所有可用技能,列出技能名称}

  • [skill-name-1]
  • [skill-name-2] ...

#### 动态技能发现流程

1. **识别任务类型**:分析用户需求,判断是否需要专业技能支持
2. **查看可用技能**:通过系统提供的 `<available_skills>` 列表确认当前可用的技能
3. **匹配场景映射**:根据上表的场景映射,确定必须调用的技能
4. **调用技能**:使用 `Skill` 工具调用对应技能

b. 如果 SkillsDetection.available = false(无可用技能):

生成简化的 Skills 使用规范:

### Skills 技能使用规范(强制)

Skills 是可扩展的专业能力模块,**必须**根据场景强制使用对应技能。

**当前状态**:当前环境未检测到可用的 Skills。

如需使用 Skills 功能,请通过以下方式添加:
1. 在 `.claude/skills/` 目录下添加自定义技能
2. 安装支持 Skills 的插件

#### 动态技能发现流程

1. **查看可用技能**:通过系统提供的 `<available_skills>` 列表确认当前可用的技能
2. **匹配场景映射**:根据技能类型确定触发场景
3. **调用技能**:使用 `Skill` 工具调用对应技能

**Skills 使用原则**:
- **强制调用**: 识别到匹配场景时,必须调用对应技能
- **禁止跳过**: 不得在强制场景下跳过技能调用

c. 用生成的 Skills 使用规范内容替换模板中的 ### Skills 技能使用规范(强制) 整个章节

4.1 单项目场景

a. 从"内置模板"部分提取单项目模板内容(template 和 之间的内容)

b. 创建变量映射表并进行字符串替换:

  • [项目名称] → 分析结果中的项目名称(或用户输入)
  • [项目一句话描述] → 分析结果中的项目描述(或用户输入)
  • [框架名称和版本] → 分析结果中的框架(或用户选择)
  • [数据库/缓存技术] → 分析结果中的数据存储(多个则用逗号连接)
  • [语言和版本] → 分析结果中的开发语言(或用户选择)
  • [命名规范] → 分析结果中的代码风格(或用户选择)

c. 添加生成时间戳:

  • 使用 Bash date 命令获取当前日期
  • 替换模板最后的 [日期] 为实际日期(格式:YYYY-MM-DD)

d. 根据分析结果和用户配置,调整对应章节:

  • 如果测试覆盖率选择"不强制要求",修改"测试规范"章节,删除覆盖率要求
  • 如果 Git 提交选择"不需要"审批,修改"版本控制"规则,移除 AskUserQuestion 要求
4.2 Monorepo 场景(unified 或 separate)

a. 从"内置模板"部分提取Monorepo 模板内容(monorepo-template 和 之间的内容)

b. 创建根项目变量映射并替换:

  • [项目名称] → 根项目名称
  • [项目一句话描述] → 根项目描述
  • [Monorepo类型] → 检测到的类型(如 "前后端分离"、"多服务架构"等)
  • [子项目数量] → SubProjectsAnalysis 的长度

c. 生成子项目信息部分:

### 项目架构(Monorepo)

**项目类型**: Monorepo ([Monorepo类型])

**整体架构**:

Monorepo 根目录 ├── [子项目1路径] - [子项目1名称] ([技术栈]) ├── [子项目2路径] - [子项目2名称] ([技术栈]) └── [子项目N路径] - [子项目N名称] ([技术栈])


**子项目详情**:

#### [子项目1名称] (`[子项目1路径]`)
- **技术栈**: [框架] + [语言]
- **职责**: [从描述推断或用户提供]
- **主要目录**: [从分析结果提取]
- **数据存储**: [如果有]
- **架构模式**: [分析结果]

#### [子项目2名称] (`[子项目2路径]`)
...

**项目间关系**:
[根据 ProjectRelations 生成]
- [子项目1] → [子项目2]: [关系描述]

d. 生成核心技术栈部分(汇总所有子项目):

### 核心技术栈

**整体技术栈**:
- **语言**: [去重后的所有语言]
- **框架**: [去重后的所有框架]
- **数据存储**: [去重后的所有数据存储]
- **代码风格**: [统一或列举差异]

e. 添加生成时间戳

f. 调整开发规范章节:

  • 保留通用的开发规范
  • 在必要时添加子项目特定的说明
4.3 Monorepo separate 场景(额外步骤)

如果 userStrategy = "separate",为每个子项目生成独立的 CLAUDE.md:

对于每个子项目:

  1. 使用单项目模板
  2. 填充该子项目的分析数据
  3. 添加"父项目引用"章节:
    ## 父项目
    
    本项目是 [根项目名称] Monorepo 的一部分。
    
    **位置**: `[子项目路径]`
    **其他子项目**: [列出其他子项目]
    
    完整项目规范请参考根目录的 CLAUDE.md。
    
  4. 记录要写入的文件路径:[子项目路径]/CLAUDE.md

5. 文件写入

5.1 备份现有文件(如需要)

a. 如果用户在步骤 1 中选择了"备份后覆盖":

  • 使用 Bash date 命令生成时间戳(格式:YYYYMMDDHHmmss)
  • 使用 Read 工具读取现有的 CLAUDE.md
  • 使用 Write 工具将内容写入 CLAUDE.md.backup-{timestamp}
  • 输出备份成功信息
5.2 写入根目录 CLAUDE.md

b. 使用 Write 工具将生成的内容写入 ./CLAUDE.md 文件

5.3 写入子项目 CLAUDE.md(仅 separate 场景)

如果 userStrategy = "separate":

  • 对每个子项目路径
  • 使用 Write 工具将子项目的 CLAUDE.md 写入 [子项目路径]/CLAUDE.md
  • 输出每个文件的写入成功信息

6. 确认完成

输出成功信息,展示完整的配置信息:

6.1 单项目场景
✅ 项目规范文件生成成功!

📄 文件位置: ./CLAUDE.md
📅 生成时间: {当前时间}

📊 项目配置摘要:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 项目名称: {项目名称}
✅ 项目描述: {项目描述}
✅ 开发语言: {语言和版本}
✅ 主要框架: {框架}
✅ 数据存储: {数据存储技术}
✅ 架构模式: {架构模式}
✅ 命名规范: {命名规范}
✅ 测试要求: {测试覆盖率}
✅ Git 提交: {是否需要审批}

🎯 自动检测项数: {检测成功的项数}/{总项数}

💡 下一步操作:
1. 查看生成的 CLAUDE.md 文件
2. 根据项目实际情况调整细节
3. 提交到版本控制系统

🤖 Generated with Claude Code
6.2 Monorepo 场景(unified)
✅ Monorepo 项目规范文件生成成功!

📄 文件位置: ./CLAUDE.md
📅 生成时间: {当前时间}

📦 Monorepo 信息:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏗️  项目类型: Monorepo ({Monorepo类型})
📂 子项目数: {子项目数量}

📊 子项目摘要:
{对每个子项目}
  📂 {子项目路径} - {子项目名称}
     ✅ 语言: {语言}
     ✅ 框架: {框架}
     ✅ 架构: {架构模式}

🔗 项目关系:
  {项目间关系列表}

🎯 自动检测项数: {检测成功的项数}/{总项数}

💡 下一步操作:
1. 查看生成的 CLAUDE.md 文件
2. 根据各子项目实际情况调整细节
3. 提交到版本控制系统

🤖 Generated with Claude Code
6.3 Monorepo 场景(separate)
✅ Monorepo 项目规范文件生成成功!

📄 生成的文件:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📄 ./CLAUDE.md (根目录统一规范)
  📄 {子项目1路径}/CLAUDE.md
  📄 {子项目2路径}/CLAUDE.md
  ...

📅 生成时间: {当前时间}

📦 Monorepo 信息:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏗️  项目类型: Monorepo ({Monorepo类型})
📂 子项目数: {子项目数量}

📊 子项目摘要:
{对每个子项目}
  📂 {子项目路径} - {子项目名称}
     ✅ 语言: {语言}
     ✅ 框架: {框架}
     ✅ 架构: {架构模式}
     ✅ 独立规范: {子项目路径}/CLAUDE.md

🎯 自动检测项数: {检测成功的项数}/{总项数}

💡 下一步操作:
1. 查看根目录的 CLAUDE.md(整体规范)
2. 查看各子项目的 CLAUDE.md(特定规范)
3. 根据实际情况调整细节
4. 提交到版本控制系统

🤖 Generated with Claude Code

跨平台兼容性说明

此命令已优化为完全跨平台兼容:

✅ 跨平台特性

  1. 内置模板 - 不需要读取外部文件,避免路径问题
  2. Claude Code 工具 - 仅使用跨平台的内置工具
    • Read/Write: 文件读写
    • Glob: 文件查找(跨平台模式匹配)
    • Grep: 内容搜索(跨平台正则表达式)
    • AskUserQuestion: 用户交互
    • Bash date: 时间戳生成(Windows/Mac/Linux 均支持)
  3. 最小依赖 - 仅依赖标准工具,无需额外安装
  4. 相对路径 - 使用 ./CLAUDE.md 相对路径,适配所有系统

🖥️ 系统支持

  • ✅ Windows: 完全支持(包括 CMD 和 PowerShell)
  • ✅ macOS: 完全支持
  • ✅ Linux: 完全支持
  • ✅ WSL: 完全支持

📝 核心改进

  1. 智能分析优先:

    • 自动检测项目配置文件(package.json, go.mod, pyproject.toml 等)
    • 智能推断技术栈、架构模式、代码风格
    • 减少用户输入负担,提升体验
  2. 数据驱动决策:

    • 基于实际项目数据进行推断
    • 避免猜测和假设
    • 置信度评估确保准确性
  3. 按需询问:

    • 只对无法确定的信息询问用户
    • 提供检测到的值作为推荐选项
    • 灵活的分批询问策略
  4. 错误处理:

    • 文件读写失败时,提供清晰的错误信息
    • 权限不足时,建议用户检查目录权限
    • 用户输入验证(避免空值)
  5. 灵活性:

    • 支持空项目(使用传统询问模式)
    • 支持已有项目(智能分析模式)
    • 允许用户覆盖自动检测的结果
  6. 向后兼容:

    • 备份机制确保不会丢失现有配置
    • 提供清晰的操作提示和确认
  7. 遵循 KISS 原则:

    • 不进行过度验证
    • 不添加不必要的功能
    • 专注于核心任务:分析项目 → 收集信息 → 生成文件

🎯 最佳实践

对于新项目(空目录):

  • 命令会检测到没有配置文件
  • 自动切换到询问模式
  • 引导用户完成所有配置

对于已有项目:

  • 命令会自动分析项目文件
  • 提取尽可能多的信息
  • 只对不确定的信息进行询问
  • 展示分析结果供用户确认

最佳工作流程:

  1. 在项目根目录运行命令
  2. 查看自动分析结果
  3. 确认或修改推断的信息
  4. 生成规范文件
  5. 根据实际需求微调细节

Sponsors

Details

Marketplace
ChamHerry/claude-code-third-party-plugins
Source
plugins/project-init
Author
Wang Xuecheng
Category
Productivity

More from ChamHerry/claude-code-third-party-plugins

All 2