gh-chamherry-claude-code-third-party-plugins-plugins-project-init/commands/project-init.md at master

zhongwei/gh-chamherry-claude-code-third-party-plugins-plugins-project-init

Files

Zhongwei Li 2c73f243fb Initial commit

2025-11-29 18:08:40 +08:00

60 KiB

Raw Permalink Blame History

allowed-tools, description

allowed-tools	description
Read, Write, AskUserQuestion, Bash(date:*), Glob, Grep	智能分析项目并生成 CLAUDE.md 规范文件（完全跨平台）

智能分析现有项目结构和配置文件,自动推断技术栈、架构模式等信息,只对无法确定的信息进行询问,最终生成项目的 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 工具询问用户同意
5. **禁止行为** - [明确禁止的操作]

### Claude Code 工具使用规范

**AI 必须使用的工具**：
- **AskUserQuestion**: 数据不足或需要决策时，必须主动询问用户
- **TodoWrite**: 跟踪多步骤任务的进度，及时更新任务状态
- **Read/Grep/Glob**: 修改前必须先分析现有代码，避免重复定义

**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: "生成包含当前进度总结和剩余待办事项实施方案的文档，便于在新会话中继续"

生成进度总结文档（用户选择选项 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**

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

最佳实践：

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

核心开发实践（强制）

1. 代码修改前的分析（强制）

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

调用链路分析要点

HTTP请求 → 路由 → Controller → Service → Logic → Data → Storage

必须分析：

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

方案设计原则：KISS

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

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

性能要求：

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

代码简洁性：

能用30行解决，绝不写300行
复用现有代码
函数职责单一

数据驱动的方案设计（强制）

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

数据充足性判断：

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

数据不足时的处理：

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

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

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

禁止：

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

方案审批流程（强制）

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

工作流程：

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

方案文档要求：

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

分析检查清单

开始编码前必须完成：

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

2. SOLID原则（强制执行）

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

1. 单一职责原则（SRP - Single Responsibility Principle）

定义：一个类/模块只负责一个功能领域的变化
实践要点：
- 每个包/模块职责单一且清晰
- 工厂负责创建，适配器负责转换，具体实现负责执行
- 避免"上帝类"或"万能函数"
- 一个模块的修改原因只能有一个

2. 开闭原则（OCP - Open-Closed Principle）

定义：对扩展开放，对修改封闭
实践要点：
- 添加新功能通过扩展实现，不修改现有代码
- 使用接口和抽象类定义扩展点
- 新增实现只需创建新文件，无需修改旧代码
- 避免使用大量 switch/if-else 判断类型

3. 里氏替换原则（LSP - Liskov Substitution Principle）

定义：子类必须能够替换父类而不影响程序正确性
实践要点：
- 所有实现同一接口的类必须可互换
- 接口契约必须保持一致
- 不违反接口定义的前置条件和后置条件
- 调用方不应关心具体实现类型

4. 接口隔离原则（ISP - Interface Segregation Principle）

定义：客户端不应该依赖它不需要的接口
实践要点：
- 接口应该小而专注，只包含必要方法
- 避免臃肿的接口定义
- 根据客户端需求定义最小接口
- 大接口应拆分为多个小接口

5. 依赖倒置原则（DIP - Dependency Inversion Principle）

定义：高层模块不应该依赖低层模块，两者都应该依赖抽象
实践要点：
- 依赖接口而不是具体实现
- 通过依赖注入传递依赖
- 抽象层不依赖具体层
- 具体实现可以随时替换

SOLID原则检查清单

设计新功能前必须回答：

SRP：每个模块的职责是否单一明确？
OCP：添加新功能是否需要修改现有代码？
LSP：所有实现是否可以互换使用？
ISP：接口是否臃肿，是否包含不必要的方法？
DIP：是否依赖抽象而不是具体实现？

违反SOLID原则的后果：

代码耦合度高，难以维护
功能扩展需要大量修改现有代码
测试困难，无法进行单元测试
技术债务快速累积

3. 功能版本迭代限制

禁止版本迭代: 对于存量功能，严格禁止版本迭代（v1、v2、v3）

核心原则：

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

4. 任务解析与影响分析

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

文件影响评估

主要修改文件: 直接需要编辑的核心文件
关联影响文件: 可能受影响需同步更新的文件
测试相关文件: 需要更新或新增的测试文件
配置文件: 可能需要调整的配置

依赖关系分析

文件依赖: 识别导入/引用关系
功能依赖: 识别模块间调用关系

重复定义检查

添加任何新定义前，必须先检查：

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

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

5. 前置条件信任原则

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

// ❌ 过度防御：重复验证已验证数据
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 工具询问用户同意
5. **禁止行为** - [明确禁止的操作]
   - 禁止子项目间的紧耦合
   - 禁止绕过 API 直接访问其他子项目的数据库

### Claude Code 工具使用规范

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

**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: "生成包含当前进度总结和剩余待办事项实施方案的文档，便于在新会话中继续"

生成进度总结文档（用户选择选项 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**

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

最佳实践：

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

核心开发实践（强制）

1. 代码修改前的分析（强制）

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

调用链路分析要点（Monorepo）

用户请求 → [子项目1入口] → [子项目1业务逻辑] → [跨项目API调用] → [子项目2] → [数据存储]

必须分析：

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

方案设计原则: KISS

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

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

性能要求:

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

代码简洁性:

能用30行解决，绝不写300行
复用现有代码和共享库
函数职责单一

数据驱动的方案设计（强制）

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

数据充足性判断：

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

数据不足时的处理:

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

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

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

禁止:

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

方案审批流程（强制）

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

工作流程:

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

方案文档要求:

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

分析检查清单

开始编码前必须完成:

已完整追踪调用链路（包括跨项目调用）
已理解所有涉及子项目的职责
已识别所有跨项目数据传递点
已回答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原则的后果：

代码耦合度高，难以维护
功能扩展需要大量修改现有代码
子项目间紧耦合，难以独立开发和部署
测试困难，无法进行单元测试
技术债务快速累积

3. 功能版本迭代限制

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

核心原则:

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

4. 任务解析与影响分析

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

文件影响评估（Monorepo）

主要修改文件: 直接需要编辑的核心文件
关联影响文件: 同一子项目中可能受影响的文件
跨项目影响文件: 其他子项目中可能受影响的文件
共享代码影响: 共享库和工具的影响范围
测试相关文件: 需要更新或新增的测试文件（包括集成测试）
配置文件: 可能需要调整的配置

依赖关系分析（Monorepo）

子项目内依赖: 识别导入/引用关系
跨项目依赖: 识别子项目间的调用关系
共享代码依赖: 识别对共享库的依赖

重复定义检查

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

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

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

5. 前置条件信任原则

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

分层职责:

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

交互规范（强制）

沟通原则

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

主动提问机制（强制）

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

文件创建限制（强制）

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

Monorepo 特定规范

跨项目通信规范

API 调用规范
- 使用明确定义的 API 接口
- API 变更必须遵循版本管理策略
- 禁止直接访问其他子项目的内部实现
共享代码规范
- 共享代码放在独立的包中
- 共享代码必须有完善的文档和测试
- 修改共享代码必须评估对所有依赖方的影响
数据共享规范
- 优先使用 API 传递数据
- 必要时可共享数据库，但需明确所有权
- 禁止直接读写其他子项目的数据表

构建和部署规范

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

最后更新: [日期]


---

## 执行步骤

### 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 调用)

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 批询问

优先级排序:

高优先级: 项目描述、架构模式 (影响模板填充)
中优先级: 数据存储、命名规范 (可能影响规范细节)
低优先级: 测试要求、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.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类型])

**整体架构**:


**子项目详情**:

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

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

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

d. 生成核心技术栈部分（汇总所有子项目）：

### 核心技术栈

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

e. 添加生成时间戳

f. 调整开发规范章节：

保留通用的开发规范
在必要时添加子项目特定的说明

4.3 Monorepo separate 场景（额外步骤）

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

对于每个子项目：

使用单项目模板
填充该子项目的分析数据

添加"父项目引用"章节：

## 父项目

本项目是 [根项目名称] Monorepo 的一部分。

**位置**: `[子项目路径]`
**其他子项目**: [列出其他子项目]

完整项目规范请参考根目录的 CLAUDE.md。

记录要写入的文件路径：[子项目路径]/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

跨平台兼容性说明

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

✅ 跨平台特性

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

🖥️ 系统支持

✅ Windows: 完全支持（包括 CMD 和 PowerShell）
✅ macOS: 完全支持
✅ Linux: 完全支持
✅ WSL: 完全支持

📝 核心改进

智能分析优先：
- 自动检测项目配置文件（package.json, go.mod, pyproject.toml 等）
- 智能推断技术栈、架构模式、代码风格
- 减少用户输入负担，提升体验
数据驱动决策：
- 基于实际项目数据进行推断
- 避免猜测和假设
- 置信度评估确保准确性
按需询问：
- 只对无法确定的信息询问用户
- 提供检测到的值作为推荐选项
- 灵活的分批询问策略
错误处理：
- 文件读写失败时，提供清晰的错误信息
- 权限不足时，建议用户检查目录权限
- 用户输入验证（避免空值）
灵活性：
- 支持空项目（使用传统询问模式）
- 支持已有项目（智能分析模式）
- 允许用户覆盖自动检测的结果
向后兼容：
- 备份机制确保不会丢失现有配置
- 提供清晰的操作提示和确认
遵循 KISS 原则：
- 不进行过度验证
- 不添加不必要的功能
- 专注于核心任务：分析项目 → 收集信息 → 生成文件

🎯 最佳实践

对于新项目（空目录）:

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

对于已有项目:

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

最佳工作流程:

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

60 KiB Raw Permalink Blame History Unescape Escape

内置模板

核心开发实践（强制）

1. 代码修改前的分析（强制）

调用链路分析要点

方案设计原则：KISS

数据驱动的方案设计（强制）

方案审批流程（强制）

分析检查清单

2. SOLID原则（强制执行）

1. 单一职责原则（SRP - Single Responsibility Principle）

2. 开闭原则（OCP - Open-Closed Principle）

3. 里氏替换原则（LSP - Liskov Substitution Principle）

4. 接口隔离原则（ISP - Interface Segregation Principle）

5. 依赖倒置原则（DIP - Dependency Inversion Principle）

SOLID原则检查清单

3. 功能版本迭代限制

4. 任务解析与影响分析

文件影响评估

依赖关系分析

重复定义检查

5. 前置条件信任原则

交互规范（强制）

沟通原则

主动提问机制（强制）

文件创建限制（强制）

核心开发实践（强制）

1. 代码修改前的分析（强制）

调用链路分析要点（Monorepo）

方案设计原则: KISS

数据驱动的方案设计（强制）

方案审批流程（强制）

分析检查清单

2. SOLID原则（强制执行）

1. 单一职责原则（SRP - Single Responsibility Principle）

2. 开闭原则（OCP - Open-Closed Principle）

3. 里氏替换原则（LSP - Liskov Substitution Principle）

4. 接口隔离原则（ISP - Interface Segregation Principle）

5. 依赖倒置原则（DIP - Dependency Inversion Principle）

SOLID原则检查清单

3. 功能版本迭代限制

4. 任务解析与影响分析

文件影响评估（Monorepo）

依赖关系分析（Monorepo）

重复定义检查

5. 前置条件信任原则

交互规范（强制）

沟通原则

主动提问机制（强制）

文件创建限制（强制）

Monorepo 特定规范

跨项目通信规范

构建和部署规范

b. 检测典型目录结构

c. 检测多配置文件（兜底检测）

d. 结果记录

e. 用户确认（confidence = "low" 时）

f. 输出检测结果

2. 项目分析（智能推断）

a. 检测项目类型

b. 分析项目结构

c. 分析代码风格

d. 分析数据存储

e. 检测测试配置

f. 记录推断结果

g. 输出分析结果

2.5 分析子项目（Monorepo 场景）

a. 遍历子项目

b. 汇总子项目分析结果

c. 推断项目间关系

d. 限制子项目数量

e. 输出子项目分析摘要

3. 智能信息收集

询问策略:

询问示例:

分批询问流程:

Monorepo 策略询问（仅 Monorepo 场景）:

4. 生成 CLAUDE.md

4.1 单项目场景

4.2 Monorepo 场景（unified 或 separate）

60 KiB

Raw Permalink Blame History