2035 lines
60 KiB
Markdown
2035 lines
60 KiB
Markdown
---
|
||
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. 根据实际需求微调细节
|