SuperAPI AI 工具集

exec-plan-writing

写作与研究

查看项目

更新于 10-15 22:37

技能介绍

用途:执行计划是签入仓库的持久记录,说明某项工作为何以特定方式完成,便于未来的智能体与人类在不翻查提交历史或已关闭 PR 的情况下重建意图。它不同于仓库根目录的 PLAN.md(进行中的工作步骤计划)、docs/design-docs/ 下的设计文档(架构信念与跨领域决策),也不同于提交信息或 PR 描述。

何时撰写:存在非显而易见的设计选择(有被否决的替代方案)、一个 PR 关闭多个 issue、将顺手修复与主变更捆绑、评审者可能问“为什么不直接做 X”、或变更带有影响后续工作排序的明确范围边界时。纯机械性变更(错别字、依赖升级、链接更新、格式化)可跳过。

位置与命名:docs/exec-plans/YYYY-MM-DD-kebab-case-slug.md,日期用 PR 打开日而非合并日;slug 简短、带动作感,便于未来检索。PR 打开时创建,合并后可将 Status 从 In review 更新为 Merged YYYY-MM-DD,不要移动文件目录。

模板结构:标题(与 PR 标题一致,去掉约定式提交前缀)、Status/Closes/Parent 元信息、Goal、Why now、Decisions(每条为选择加理由,含被弃替代方案)、Explicitly out of scope(列出相邻工作并链接 issue)、How to update(可选)、Verification(可复现的持久验证步骤)。不适用的章节应删除而非留空。

限制与检查:文档应比 PLAN.md 短,若更长说明内容从“决策”泄漏到了“实现步骤”。提交前检查命名、Status 与 issue 链接、Decisions 每条是否选择加理由、范围外是否列全、空章节是否删除。仓库首个示例为 docs/exec-plans/2026-05-21-robots-named-ai-bots.md,约 40 行。