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

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

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

---

## 内置模板

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

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

3. **生成进度总结文档**（用户选择选项 2 时）：

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

   文档必须包含：
   ```markdown
   # [任务名称] - 进度总结与实施方案

   **创建时间**: 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**
   ```

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

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

---

## 核心开发实践（强制）

### 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. 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. 任务解析与影响分析

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

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

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

#### 重复定义检查

添加任何新定义前，必须先检查：
```bash
# 检查函数/类/接口定义
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: "生成包含当前进度总结和剩余待办事项实施方案的文档，便于在新会话中继续"
   ```

3. **生成进度总结文档**（用户选择选项 2 时）：

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

   文档必须包含：
   ```markdown
   # [任务名称] - 进度总结与实施方案

   **创建时间**: 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**
   ```

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

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

---

## 核心开发实践（强制）

### 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原则的后果**：
- 代码耦合度高，难以维护
- 功能扩展需要大量修改现有代码
- 子项目间紧耦合，难以独立开发和部署
- 测试困难，无法进行单元测试
- 技术债务快速累积

### 3. 功能版本迭代限制

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

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

### 4. 任务解析与影响分析

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

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

#### 依赖关系分析（Monorepo）
- **子项目内依赖**: 识别导入/引用关系
- **跨项目依赖**: 识别子项目间的调用关系
- **共享代码依赖**: 识别对共享库的依赖

#### 重复定义检查

添加任何新定义前，必须先检查所有子项目：
```bash
# 检查所有子项目中的函数/类/接口定义
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 检测常见目录组合：

```bash
# 检测前后端分离
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. 检测多配置文件（兜底检测）

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

```bash
# 搜索所有主要配置文件
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 检测结果数据结构：

```javascript
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 确认：

```yaml
使用 AskUserQuestion:
  question: "检测到项目中有多个配置文件，这是一个包含多个子项目的 Monorepo 吗？"
  header: "Monorepo 确认"
  multiSelect: false
  options:
    - label: "是，这是一个 Monorepo"
      description: "项目包含多个独立的子项目（如前端+后端）"
    - label: "否，这是单个项目"
      description: "按照单项目模式分析"
```

#### f. 输出检测结果

输出检测摘要：

```
🔍 项目结构检测完成！

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

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

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

#### a. 检测项目类型

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

**Node.js/TypeScript 项目检测**:
```bash
检测文件: 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 项目检测**:
```bash
检测文件: go.mod
提取信息:
  - 项目名称: module 声明
  - 语言版本: go 版本行
  - 框架: 从 require 推断
    - "gin-gonic/gin" → Gin
    - "labstack/echo" → Echo
    - "gofiber/fiber" → Fiber

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

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

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

#### b. 分析项目结构

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

```bash
# 检测顶层目录
检测路径:
  - 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 工具读取几个代码文件样本：

```bash
# 读取 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 工具搜索数据库相关导入和配置：

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

# 搜索配置文件
检查:
  - docker-compose.yml (服务定义)
  - .env.example (环境变量示例)
  - config/ 目录下的配置文件
```

#### e. 检测测试配置

```bash
检测测试目录:
  - test/, tests/, __tests__/ 是否存在
  - 测试文件数量和覆盖情况

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

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

#### f. 记录推断结果

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

```javascript
分析结果 = {
  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 中的每个子项目路径执行分析：

```bash
对于每个子项目路径 (例如 "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. 汇总子项目分析结果

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

```javascript
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. 推断项目间关系

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

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

#### d. 限制子项目数量

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

```bash
如果检测到的子项目数量 > 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"**
```yaml
使用 AskUserQuestion:
  question: "请确认项目描述："
  header: "项目描述"
  multiSelect: false
  options:
    - label: "使用检测到的描述 (已检测)"
      description: "Web application for user management"
    - label: "Web 应用后端服务"
      description: "提供 RESTful API 的后端服务"
    - Other: 自定义描述
```

**场景 3: 数据存储 confidence="medium"**
```yaml
使用 AskUserQuestion:
  question: "请确认项目使用的数据存储技术（可多选）："
  header: "数据存储"
  multiSelect: true
  options:
    - label: "PostgreSQL (已检测)"
      description: "关系型数据库"
    - label: "Redis (已检测)"
      description: "缓存系统"
    - label: "MySQL"
      description: "关系型数据库"
    - Other: 其他存储技术
```

**场景 4: Git 提交流程 confidence="none"**
```yaml
使用 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：

```yaml
使用 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. 生成子项目信息部分：

```markdown
### 项目架构（Monorepo）

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

**整体架构**:
```
Monorepo 根目录
├── [子项目1路径] - [子项目1名称] ([技术栈])
├── [子项目2路径] - [子项目2名称] ([技术栈])
└── [子项目N路径] - [子项目N名称] ([技术栈])
```

**子项目详情**:

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

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

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

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

```markdown
### 核心技术栈

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

e. 添加生成时间戳

f. 调整开发规范章节：
   - 保留通用的开发规范
   - 在必要时添加子项目特定的说明

#### 4.3 Monorepo separate 场景（额外步骤）

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

对于每个子项目：
  1. 使用单项目模板
  2. 填充该子项目的分析数据
  3. 添加"父项目引用"章节：
     ```markdown
     ## 父项目

     本项目是 [根项目名称] 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. 根据实际需求微调细节