writing-plans
GitHub将已接受的愿景与需求转化为接手者可实施、可验收的详细计划,明确目标、依赖、状态契约及验证方式。适用于跨组件或复杂依赖场景,帮助消除歧义并指导后续开发执行。
Trigger Scenarios
Install
npx skills add zts212653/clowder-ai --skill writing-plans -g -y
SKILL.md
Frontmatter
{
"name": "writing-plans",
"triggers": [
"写计划",
"implementation plan",
"拆分步骤"
],
"description": "把已接受的愿景与需求转成接手者可实施、可验收的计划。 Use when: 跨组件、状态对象、依赖或实施顺序需要先理清,且没有足够的现成计划。 Not for: 路径已明确的简单改动、已有可执行计划、尚未接受的愿景决策。 Output: 目标与范围、关键契约\/依赖、可执行工作单元和验证方式。\n",
"tips_exempt": "Renewed 2026-10-30: accepted planning guidance now states resource, waiting and false-block costs against the real loss a safeguard prevents; this remains internal planning guidance with no new end-user entry or action."
}
Writing Plans
计划让实际接手者能够按原始愿景实施与验收。历史上既有把模板写得很细却偏离目标,也有遗漏状态边界、留给 reviewer 逐轮补课的问题;计划应消除这些歧义。
先判断输入是否已经是可实施的约定。愿望过宽、结果不可承诺或关键取舍未定时,先澄清真正影响方案的问题,不用模板替用户制造一个目标。已有清楚约定则直接沿用。按原问题到交付的判断方法核对拆分后的工作是否仍兑现同一个使用结果;实现步骤齐全不能代替这项判断。
必须做到
- 回读已接受的原始需求、feature/spec 与相关决定,写清本计划的目标、覆盖范围、验收要求和来源。计划分步不等于缩减愿景或把未完成包装成已完成。
- 关键依赖、契约和改动位置足够明确,让接手者知道从哪里开始、哪些决定已定、什么仍需查证;无需重复抄写已有真相源全文。
- 每个工作单元有可观察的结果与适用验证。涉及行为/回归风险按
tdd;现有精准检查可以提供 RED,纯文档/机械改动走对应检查。 - 写清这个方案让谁多付出什么、换来什么:新增的常驻进程与内存、拦截和前置、人要等的时间、可能误拦的正常工作,对照它防住的真实损失。说不出一层防住了哪个真问题,就不加这一层。来源:F314 汉弗莱喵案,密钥防线方案只问漏没漏、没算代价,上线后每只猫每个 MCP 各挂一个代理进程(10-27 整层撤除);You 10-29 批注认可(
[thread-id]#private-source-id)。 - 关键未决问题可见:技术问题由猫在职责内解决,真正的价值取舍附 Decision Packet;已接受范围内的可逆细节不重复询问 operator。
- 计划需要跨 session/跨猫消费时,保存在可追溯载体并持久化。通常使用
feature-specs/YYYY-MM-DD-<topic>.md;Git 载体按当前工作现场与仓库风险规则选择,不为写计划专门切回 main。
模板与例子是可选参考。可以照用、改造或换成更清楚的表达;不要求按固定分钟粒度拆动作,不要求预写完整实现,也不按模型资格决定谁可以不用模板。路径已经明确或已有详细计划时直接继续执行。
Stateful Object Gate:状态契约必须清楚
涉及有生命周期的对象时,识别本次新增或改变的状态及消费路径,包括复用现有 API 后新增的轮询、发送闸门或到达判定。必须讲清:
- 谁拥有生命周期,哪些事件改变状态,恢复/删除/list 等旁路如何与之保持一致;
- 哪些不变量必须成立,怎样观察或验证;
- 适用的 crash、并发、恢复和误用边界,以及对应预期。
已有契约直接引用,只补本次 delta。能由纯投影表达的状态不另存一份。转移表、编号不变量、图与测试矩阵都是可选表达,契约是否完整可验证才是判断依据。
来源:F229 PR #2202 多轮补状态边界,以及消费侧状态漏普查的教训。可参考 (internal reference removed)。
可选参考:从终态拆工作
- 用一句话定义要达到的结果,核对验收要求和范围。
- 找出真正影响实现的接口、状态和依赖;需要探索的问题用明确问题与可验证结论组织 Spike。
- 按可实施、可验证的工作单元拆分。每步的产物要服务终态,避免把将来必重写的临时实现冒充交付。
- 为接手者容易误解的边界给一个例子或局部代码;不为模板补全普通实现。
可选计划骨架
# <目标> 实施计划
来源:<原始需求 / feature / accepted decision>
目标与范围:<本计划兑现什么,哪些要求属于已接受的其他范围>
验收:<可验证要求,或准确引用已有 AC>
关键契约与依赖:<已定约束、相关状态/接口、先后关系>
代价:<让谁多付出什么(常驻进程/内存/人的等待/可能误拦),换来什么>
未决问题:<技术 / 价值,以及解决路径>
## 工作单元:<可观察结果>
改动位置:<已核实的文件 / 模块>
行为与边界:<具体预期;需要时附图、表或局部代码>
验证:<当前仓真实命令 / 用户路径与预期结果>
F191/F303 的适用声明仍按 Design Gate 契约提供:Architecture cell / Map delta / Why,命中 consumer/authority 边界时补对应 evidence。普通增量写 Map delta: none,不因计划模板而重画架构图。
Formatting Command Contract
计划写到格式化步骤时,先从当前仓库的 package.json、CI 或现有脚本确认可执行命令及适用范围;不要凭跨仓库习惯猜 formatter。计划中必须写出已确认的完整命令和预期结果,禁止只写“run formatting”或“格式化”。
- 全仓自动修复:
pnpm check:fix - 仅格式化本次文件:
pnpm biome format --write <files> - 终态验证:
pnpm check
若仓库真相源提供不同命令,以真相源为准,并在计划中标明来源。以上仅在计划确实需要该检查时选用,不构成每份计划的全仓检查要求。
常见误区
| 误区 | 正确做法 |
|---|---|
| 每步都很细,愿景里的关键路径却没进计划 | 回读原始需求并核对覆盖 |
| “复用 API”就忽略新消费侧状态 | 检查本次状态对象与生命周期 delta |
| 计划必须含完整代码、每步 2–5 分钟 | 写到足以实施与验证,细节用于消除真实歧义 |
| 小改也先回 main 写新计划 | 使用已有现场与计划,按仓库规则决定载体 |
| 为了通过模板抄全 spec、加无关步骤 | 准确引用已有契约,留下本次真正需要的内容 |
下一步
在已接受的愿景范围内继续实施;需要隔离时用 worktree,需要行为保护时用 tdd。尚缺价值决策则回对应讨论/Design Gate,计划本身不触发整条固定流程。
Version History
-
42017e0
Current 2026-11-02 14:25
新增格式化命令契约规范,要求引用仓库真实命令而非通用描述;细化代价分析要求,强调评估常驻资源与人工成本;补充常见误区对照表。
-
4b5dc96
2026-10-18 21:55
新增格式化命令契约规范,要求依据仓库真相源确认可执行命令;补充常见误区对照表;细化从终态拆分工作的可选参考步骤。
-
5968c19
2026-09-22 04:44
从简单拆分升级为强调状态契约、格式命令确认及避免常见误区的详细规范,增加对生命周期对象和验证细节的要求。
- 56d7c29 2026-08-17 04:25
- f30e20c 2026-08-05 06:07
- 4167cb0 2026-07-05 14:53


