| name | agile-design-doc |
| description | 生成面向敏捷开发团队的精炼设计文档。MVP导向，避免过度设计。使用场景：(1) 需要为新功能或系统模块生成设计文档 (2) 需要明确功能边界和交互流程 (3) 需要提供实现思路和关键方法 (4) 需要阐述技术难点和解决方案。该skill会先分析项目技术栈和现有组件，然后生成精炼、重点突出的设计文档。 |
敏捷设计文档生成
核心原则
1. MVP导向，避免过度设计
- 敏捷开发以快速迭代为目标，不需要考虑所有边界情况
- 专注于核心功能，次要功能可以后续迭代
- 不要为了"完整性"而添加不必要的功能
2. 基于现有技术栈
- 必须先读取项目配置文件（pyproject.toml、package.json等）了解技术栈
- 复用现有组件，避免重复造轮子
- 设计方案必须与当前技术栈兼容
3. 清晰阐述设计意图
- 明确本次设计解决的问题或提供的功能
- 使用mermaid时序图展示交互流程
- 针对每个功能点给出实现思路和关键方法
- 复杂逻辑使用mermaid实现流程
- 提供示例代码说明关键实现
4. 精炼文档，面向技术人员
- 读者是开发者和了解业务的产品人员
- 避免冗长的背景介绍和废话
- 先了解现有组件，避免重复设计
工作流程
第一步：前置分析
在生成设计文档之前，必须先完成以下分析：
1.1 了解项目背景
询问用户或分析项目：
- 项目背景？现在是什么系统，要做什么功能/模块？
1.2 识别技术栈
必须读取的配置文件：
- Python项目：pyproject.toml, requirements.txt, setup.py
- Node.js项目：package.json, yarn.lock, pnpm-lock.yaml
- Java项目：pom.xml, build.gradle
- Go项目：go.mod, go.sum
- 其他：根据项目类型识别
分析内容：
- 主要框架和库
- 数据库和存储
- 消息队列和中间件
- 部署和运维工具
1.3 了解现有组件
通过以下方式了解现有组件：
1. 询问用户：有哪些现有组件可以复用？
2. 读取项目结构：分析src/、lib/、components/等目录
3. 查看文档：README.md、docs/等
记录可复用的组件：
- 基础服务类
- 工具函数
- 中间件
- 数据模型
第二步：设计文档生成
按照以下结构生成设计文档：
2.1 设计目标（1-2段）
明确说明：
- 本次设计要解决什么问题
- 提供什么功能
2.2 功能列表（简洁列表）
简要列出本次设计的功能点：
- 功能1：一句话描述
- 功能2：一句话描述
- 功能3：一句话描述
不要展开详细说明，保持简洁
2.3 交互流程（Mermaid时序图）
为每个主要功能绘制时序图：
```mermaid
sequenceDiagram
participant User
participant API
participant Service
participant DB
User->>API: 请求
API->>Service: 调用
Service->>DB: 查询
DB-->>Service: 返回
Service-->>API: 结果
API-->>User: 响应
时序图目的：
#### 2.4 实现方案（核心部分）
针对每个功能点，按以下结构描述：
**功能点名称**
*实现思路*（2-3句话）
- 说明采用的技术方案
- 为什么选择这个方案
- 与现有组件的集成方式
*关键方法*（代码示例）
```python
# 示例：用户认证
def authenticate_user(token: str) -> User:
"""验证用户token并返回用户信息"""
# 1. 验证token格式
# 2. 从缓存或数据库查询
# 3. 返回用户信息
pass
技术难点（如有）
2.5 数据模型（如需要）
仅列出新增或修改的数据模型：
- User: {id, name, email}
- Order: {id, userId, amount, status}
使用简洁的表格或JSON格式
2.6 接口定义（如需要）
仅列出新增或修改的API：
POST /api/users
- 请求：{name, email}
- 响应：{id, name, email, createdAt}
保持简洁，不要展开所有字段
第三步：质量检查
生成文档后，进行以下检查：
3.1 精炼度检查
3.2 重点突出检查
3.3 技术准确性检查
3.4 MVP导向检查
常见问题处理
Q1: 用户没有提供足够信息
优先级顺序：
1. 读取项目文件（pyproject.toml、package.json等）
2. 分析项目结构
3. 询问用户具体问题
4. 基于常见模式做合理假设（并在文档中说明）
Q2: 不确定是否需要某个功能
原则：
- 如果是核心功能，必须包含
- 如果是辅助功能，可以后续迭代
- 如果不确定，询问用户
- 在文档中明确标注"可选"或"后续迭代"
Q3: 技术栈不熟悉
处理方式：
1. 读取项目配置文件了解技术栈
2. 搜索相关文档和最佳实践
3. 参考项目现有代码的实现方式
4. 在文档中说明技术选型的理由
参考资源
