Agent skill
agile-design-doc
生成面向敏捷开发团队的精炼设计文档。MVP导向,避免过度设计。使用场景:(1) 需要为新功能或系统模块生成设计文档 (2) 需要明确功能边界和交互流程 (3) 需要提供实现思路和关键方法 (4) 需要阐述技术难点和解决方案。该skill会先分析项目技术栈和现有组件,然后生成精炼、重点突出的设计文档。
Install this agent skill to your Project
npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/ariesyb/agile-design-doc
SKILL.md
敏捷设计文档生成
核心原则
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. 在文档中说明技术选型的理由
参考资源
- 设计文档模板 - 标准设计文档模板
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
perigon-backend
Perigon ASP.NET Core + EF Core + Aspire conventions
perigon-agent
Pointers for Copilot/agents to apply Perigon conventions
perigon-angular
Angular 21+ standalone/Material/signal conventions for Perigon WebApp
fastapi-mastery
Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.
context7-efficient
Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.
browser-use
Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.
Didn't find tool you were looking for?