dev-docs

name dev-docs description 开发文档自动化生成和维护工具。在完成需求开发后自动生成需求文档(PRD)和API接口文档，在代码更新后自动维护CHANGELOG和API CHANGELOG。触发时机：用户说"生成文档"、"写文档"、"更新文档"，或提到PRD、API文档、changelog、需求文档时自动触发。 开发文档自动化工具 多平台支持 : 本文件可作为 Cursor IDE 的 Skill ( ~/.cursor/skills/ ) 或 Claude Code 的 Skill ( ~/.claude/skills/ ) 使用。 本技能帮助在开发过程中自动生成和维护项目文档，确保文档与代码保持同步。 核心工作流 流程 1：新功能开发完成 → 生成文档 当完成一个新功能的开发后，执行以下步骤： 分析代码变更 识别新增/修改的文件 提取新增的 API 接口 识别数据模型变更 生成需求文档 → docs/requirements/REQ-{feature_name}.md 更新 API 文档 → docs/api/API.md 更新 CHANGELOG → docs/CHANGELOG.md 更新 API CHANGELOG → docs/api/API_CHANGELOG.md 流程 2：代码更新 → 更新文档 当对现有功能进行修改后： 识别变更类型 (Added/Changed/Fixed/Removed) 更新对应的需求文档 更新 API 文档 （如有接口变更） 追加 CHANGELOG 条目 文档模板 需求文档模板 (PRD) 文件位置： docs/requirements/REQ-{feature_name}.md # {功能名称} - 需求文档 ## 文档信息 | 属性 | 值 | |------|-----| | 文档编号 | REQ-{编号} | | 版本 | v1.0 | | 创建日期 | {YYYY-MM-DD} | | 最后更新 | {YYYY-MM-DD} | | 作者 | {作者} | | 状态 | 草稿/评审中/已批准/已实现 | --- ## 1. 功能概述 ### 1.1 简要描述 {一句话描述该功能的核心目的} ### 1.2 关键词 {功能相关的关键术语} --- ## 2. 背景和目标 ### 2.1 背景 {为什么需要这个功能？解决什么问题？} ### 2.2 目标 - 目标 1：{具体可衡量的目标} - 目标 2：{具体可衡量的目标} ### 2.3 非目标 {明确声明此功能不做什么} --- ## 3. 功能需求 ### 3.1 用户故事 | 编号 | 角色 | 需求 | 价值 | |------|------|------|------| | US-01 | 作为{角色} | 我希望{功能} | 以便{价值} | ### 3.2 功能清单 | 编号 | 功能名称 | 优先级 | 描述 | |------|----------|--------|------| | F-01 | {功能名} | P0/P1/P2 | {详细描述} | ### 3.3 业务规则 - BR-01：{业务规则描述} --- ## 4. 非功能需求 ### 4.1 性能要求 - 响应时间：{具体指标} - 吞吐量：{具体指标} ### 4.2 安全要求 - {安全相关要求} ### 4.3 兼容性 - {浏览器/系统兼容性要求} --- ## 5. UI/交互设计 ### 5.1 页面布局 {描述或引用设计稿} ### 5.2 交互流程 {用户操作的步骤流程} ### 5.3 状态说明 | 状态 | 显示效果 | 触发条件 | |------|----------|----------| | {状态名} | {效果} | {条件} | --- ## 6. 数据模型 ### 6.1 新增/修改的数据表 {使用 Mermaid ER 图或表格描述} ### 6.2 数据字段说明 | 字段名 | 类型 | 必填 | 描述 | |--------|------|------|------| | {字段} | {类型} | 是/否 | {说明} | --- ## 7. 验收标准 ### 7.1 功能验收 - [ ] AC-01：{验收条件} - [ ] AC-02：{验收条件} ### 7.2 测试用例 | 用例编号 | 描述 | 预期结果 | |----------|------|----------| | TC-01 | {测试步骤} | {预期结果} | --- ## 8. 时间节点 | 里程碑 | 计划日期 | 实际日期 | 状态 | |--------|----------|----------|------| | 需求评审 | {日期} | {日期} | {状态} | | 开发完成 | {日期} | {日期} | {状态} | | 测试完成 | {日期} | {日期} | {状态} | | 上线发布 | {日期} | {日期} | {状态} | --- ## 附录 ### A. 相关文档 - [ API 文档 ]( ../api/API.md ) - [ 架构文档 ]( ../architecture.md ) ### B. 变更历史 | 版本 | 日期 | 作者 | 变更说明 | |------|------|------|----------| | v1.0 | {日期} | {作者} | 初始版本 | API 文档模板 文件位置： docs/api/API.md # {项目名称} API 接口文档 ## 文档信息 | 属性 | 值 | |------|-----| | 版本 | v{版本号} | | 最后更新 | {YYYY-MM-DD} | | 基础URL | {API基础路径} | --- ## 1. 概述 ### 1.1 简介 {API 的用途和范围} ### 1.2 基础信息 - **协议** : HTTPS - **数据格式** : JSON - **字符编码** : UTF-8 --- ## 2. 认证方式 ### 2.1 认证类型 {JWT / API Key / OAuth 等} ### 2.2 认证方式 Authorization: Bearer {token} ### 2.3 获取 Token {获取认证 Token 的方式} --- ## 3. 接口列表 ### 3.1 {模块名称} #### {接口名称} | 属性 | 值 | |------|-----| | 路径 | `{HTTP方法} {路径}` | | 认证 | 是/否/可选 | | 描述 | {接口功能描述} | **请求参数** | 参数名 | 位置 | 类型 | 必填 | 描述 | |--------|------|------|------|------| | {参数} | path/query/body | {类型} | 是/否 | {描述} | **请求示例** ```json { "field": "value" } 响应参数 参数名 类型 描述 {参数} {类型} {描述} 响应示例 { "code" : 0 , "message" : "success" , "data" : { } } 4. 数据模型 4.1 {模型名称} 字段名 类型 必填 描述 {字段} {类型} 是/否 {描述} 5. 错误码说明 错误码 HTTP状态码 描述 解决方案 0 200 成功 - 10001 400 参数错误 检查请求参数 10002 401 未授权 检查认证信息 10003 403 禁止访问 检查权限 10004 404 资源不存在 检查请求路径 10005 500 服务器错误 联系管理员 6. 调用示例 6.1 cURL curl -X POST "{base_url}/api/endpoint" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{"key": "value"}' 6.2 Python import requests response = requests.post( "{base_url}/api/endpoint" , headers={ "Authorization" : f"Bearer {token} " }, json={ "key" : "value" } ) print (response.json()) 6.3 JavaScript const response = await fetch ( "{base_url}/api/endpoint" , { method : "POST" , headers : { "Authorization" : `Bearer ${token} ` , "Content-Type" : "application/json" }, body : JSON . stringify ({ key : "value" }) }); const data = await response. json (); --- ### CHANGELOG 模板 文件位置：`docs/CHANGELOG.md` 遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 格式： ```markdown # Changelog 本文件记录项目的所有重要变更。 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 ## [Unreleased] ### Added - {新增的功能} ### Changed - {修改的功能} ### Fixed - {修复的问题} ### Removed - {移除的功能} --- ## [1.0.0] - {YYYY-MM-DD} ### Added - 初始版本发布 - {功能1} - {功能2} --- [Unreleased]: {repo_url}/compare/v1.0.0...HEAD [1.0.0]: {repo_url}/releases/tag/v1.0.0 API CHANGELOG 模板 文件位置： docs/api/API_CHANGELOG.md # API Changelog 本文件记录 API 接口的所有变更。 ## [Unreleased] ### 新增接口 - `{METHOD} {path}` - {描述} ### 接口变更 - `{METHOD} {path}` - {变更说明} ### 废弃接口 - `{METHOD} {path}` - 将在 v{版本} 移除，请使用 {替代接口} ### 移除接口 - `{METHOD} {path}` - {原因} ---