| name | code-change-plan |
| description | 代码变更规划助手 - 分析需求、设计方案、评估影响,输出可执行的变更计划 |
Code Change Plan
将需求转换为可执行的代码变更方案。
原则: 先分析 → 再设计 → 产出方案 → 等待审批
核心流程
1. 理解需求
- 业务目标是什么?
- 要实现哪些功能?
- 如何验收?
2. 分析现状
- 当前如何实现的?
- 与目标的差距在哪?
3. 设计方案
- 如何实现目标?
- 为什么这样设计?
- 会影响哪些地方?
4. 制定计划
- 改哪些文件?
- 如何验证?
- 有什么风险?
5. 输出方案
- 文件:.code/change-plans/<需求描述>-YYYYMMDD-HHMMSS.md
- 状态:等待审批
输出报告(简洁版 - 4 章)
报告包含 4 个核心部分:
| 部分 | 内容 | 为什么需要 |
|---|
| 1️⃣ 要做什么 | 需求、验收标准、待决策问题 | 确保理解正确 |
| 2️⃣ 怎么做 | 技术方案、关键决策、流程对比 | 明确实现思路 |
| 3️⃣ 改哪些 | 文件清单(白名单)、影响范围 | 控制变更范围 |
| 4️⃣ 如何验证 | 验证步骤、风险与回滚 | 质量保证 |
报告语义化
输出文件名示例:
.code/change-plans/新增用户登录功能-20260704-143052.md
.code/change-plans/优化数据库查询性能-20260704-150230.md
.code/change-plans/修复订单计算错误-20260704-161520.md
控制台输出示例:
✓ 代码变更方案已生成
【需求】新增用户登录功能
【方案】添加 AuthService + JWT 认证
【影响】6 个文件(新增 3,修改 3)
【风险】中等
【状态】等待审批
文件:.code/change-plans/新增用户登录功能-20260704-143052.md
请审核方案后执行。
调用方式
/code-change-plan
需求:实现用户登录功能
- 支持用户名密码登录
- 返回 JWT token
执行规则
生成方案时遵守以下规则:
- 只分析不改代码 - 生成方案文档,不修改业务代码
- 使用简洁模板 - 使用 4 章结构(assets/change-plan-template.md)
- 初始状态 - 审批状态必须为
WAITING_FOR_APPROVAL
- 文件清单是白名单 - 明确列出允许修改的文件
- 验证步骤可执行 - 提供具体的验证命令
- 风险评估 - 明确标注高/中/低风险项
- 提供回滚方案 - 给出具体的回滚步骤
- 使用直观格式 - Emoji + Checkbox + 代码块
- 避免过度设计 - 不使用复杂的 ID 体系和追踪矩阵
- 人类友好 - 用人话描述,避免技术黑话
工具
- 写入工具:
scripts/write_utf8.py(确保 UTF-8 编码)
- 验证工具:
scripts/validate_change_plan.py(检查方案完整性)
详细文档
assets/change-plan-template.md - 简洁方案模板
references/workflow-detail.md - 详细工作流程
references/report-structure.md - 报告结构说明
references/quality-checklist.md - 质量检查清单