writing-plans git:20260905.7c0ea7cA

Immutable. This exact content is served forever at /api/v1/blob/01d7a90355d8cb5f.

---
name: writing-plans
description: Use when asked to create, review, or revise a multi-step implementation, bug-fix, or change plan before editing code, including existing plans that may use a legacy task-by-task template. Assume readers have no relevant professional background; explain what happened in plain language before giving precise analysis and implementation guidance.
metadata:
  author: Bensz Conan
  keywords:
    - writing-plans
---

# 写实施计划

写一份帮助人作出正确决定的计划，而不是把代码操作逐条抄出来。默认假设读者没有相关专业背景，不了解项目内部结构、技术术语或行业惯例；计划既要保留准确的专业判断和建议，也要先让普通读者理解究竟发生了什么、为什么值得解决、准备怎样改善、怎样算完成。

开始前，简要说明正在使用 `writing-plans` 来整理实施计划。

## 工作原则

- 以本次读取到的 `SKILL.md` 为当前规则来源。会话里更早出现的计划模板和现有旧计划只作为事实材料，不自动继承其结构。
- 先用零背景读者能理解的方式说明发生了什么，再给出专业判断、目标和改进方向，最后才补充必要的技术细节。
- 用日常语言解释业务行为和用户感受；首次出现技术术语时说明它的作用。
- 把计划写成“要解决什么、为什么这样做、完成后有什么变化”，而不是“在第几行写什么代码”。
- 代码、伪代码、完整文件路径和命令都不是默认内容。只有它们能澄清接口约定、数据转换、关键边界或验证方法时才保留。
- 不用代码示例替代解释；任何技术补充之前都必须已有对应的白话说明。
- 只规划当前需求需要的最小改动。避免为展示完整而堆砌 TDD 步骤、提交步骤、框架细节或无关的重构。

## 让零背景读者先看懂

在专业分析之前，先写一段独立的通俗解释，帮助第一次接触该领域的读者建立正确直觉：

1. 用一句不依赖专业术语的话说明究竟发生了什么，以及它造成的直接影响。
2. 优先选择日常生活中常见的目标或场景作类比，例如排队取号、寄送包裹、门锁与钥匙、填写表格、整理账本或按地址送货。
3. 明确说明类比中的人物、物品或动作分别对应实际问题中的什么，不能只讲故事而不建立对应关系。
4. 给出一个具体的“现在会怎样—改进后会怎样”例子，让读者看到可观察的变化。
5. 类比用于辅助理解，不能代替专业判断。类比会歪曲问题时，改用具体场景直接解释，不为了形式强行编造比喻。
6. 不使用“很简单”“显然”“大家都知道”等可能排斥零背景读者的表达，也不通过幼稚化语气降低专业准确性。

## 先理解再落笔

1. 阅读需求、现有行为和相关约束，确认问题确实存在。
2. 先形成通俗解释：一句话结论、合适的生活类比或具体场景、与实际问题的对应关系，以及改变前后的差别。
3. 再用专业语言准确描述现状、受影响的人或场景，以及不处理的后果。无法确认根因时，明确写为待验证的假设。
4. 明确目标、非目标和成功标准；不要把实现手段误写成目标。
5. 选择能以最小范围达到目标的改进方向，并说明它为何有效，以及这项改变对普通用户意味着什么。
6. 仅在需要时补充涉及的模块、文件、依赖、风险和验证方式。

## 计划深度

- **低风险或文档类改动**：写问题、目标、改进方向、范围和完成标准即可；用 2–4 项概括实施顺序。
- **中等风险改动**：额外说明受影响的组件、关键行为变化、验证方法和需要确认的假设。
- **高风险、跨模块、安全或数据改动**：额外说明依赖顺序、兼容性、失败后的恢复方式、非目标和验证矩阵。

风险等级决定需要解释多少决策、边界和验证，不决定步骤必须拆得多细。不同风险等级都保留通俗解释；简单任务可以写得很短，但不能只剩专业术语。高风险计划也不默认展开成逐文件、逐测试、逐提交的操作脚本；不要因为正在写计划，就把改动扩充成一份冗长的技术设计书。

## 防止回归旧模板

默认使用本 Skill 的“问题优先”结构。只有用户明确要求可直接照着逐步执行的实施级计划时，才增加任务、文件或命令细节；即使如此，也先保留问题、目标、改进方向和验收这层白话主线，再把执行细节放入对应方向或技术补充中。

保存前检查草稿是否沿用了旧模板。典型指纹包括：

- 标题以英文 `Implementation Plan` 结尾。
- 出现 `For Claude: REQUIRED SUB-SKILL` 或预设后续执行 Skill 的提示。
- 开头连续使用 `Goal`、`Architecture`、`Tech Stack` 等英文元数据字段。
- 主体由重复的 `Task N`、`Files`、`Step N` 组成，并为每项机械展开失败测试、最小实现、测试通过和提交。
- 默认放入完整代码、精确行号、逐任务提交命令或执行模式选择。

草稿命中任一明显旧模板组合时，不要直接交付。先判断这些细节是否由用户明确要求；未明确要求时删去，并按本 Skill 的默认结构重写。用户确实要求实施级细节时，也只保留完成任务必需的部分，不恢复整套旧模板骨架。

## 默认计划结构

将正式计划保存到 `docs/plans/YYYY-MM-DD-<主题>.md`。除非用户只要求在对话中讨论想法，否则使用以下结构。“通俗解释”默认保留，其余章节可按任务删减空内容。

```markdown
# <主题>实施计划

## 通俗解释：究竟发生了什么

- **一句话说明：** 不使用专业术语，直接说明发生了什么以及造成的影响。
- **生活类比或具体场景：** 优先用常见生活目标帮助读者建立直觉；不适合类比时，用一个具体场景说明。
- **对应到本问题：** 说明类比中的角色、物品和动作分别对应实际问题中的什么。
- **改变前后：** 对比“现在会怎样”和“改进后会怎样”。

## 专业判断：问题在哪里

- **当前现象：** 准确描述哪里不符合预期。
- **影响范围：** 谁会在什么情况下受到影响，以及会造成什么后果。
- **已知原因或待验证假设：** 区分事实和推测。

## 要达到什么目标

- **完成后的变化：** 描述用户或系统可观察到的结果。
- **不在本次处理范围：** 防止需求无意扩大。

## 改进方向

### <方向一>

专业地说明要调整的行为或规则、这样做为什么能解决问题，以及预期结果；再用一句无术语的话说明这项改变对普通用户意味着什么。必要时列出受影响的组件或文件。

### <方向二>

同上。

## 实施范围与顺序

1. 用一句话说明先完成哪项改变及其目的。
2. 用一句话说明后续改变如何承接前一步。

## 如何确认完成

- 列出用户可观察的验收结果。
- 列出必要的自动化测试、人工检查或监控项。
- 仅在确有可执行命令且它能帮助执行者时，附上命令。

## 风险与待确认事项

- 仅记录会影响方案选择、上线安全或验收结论的事项。
```

## 技术补充的使用边界

只有下列情况才增加 `## 技术补充（按需阅读）`：

- 需要固定公开接口、数据格式或兼容性规则。
- 仅靠自然语言可能让实现方向产生明显歧义。
- 需要给出准确的验证命令、迁移步骤或回滚条件。

技术补充应短小、紧贴对应的改进方向，并解释它解决的疑问。不要放完整实现代码、逐行修改说明、机械化的“先写失败测试—再实现—再提交”步骤，除非用户明确要求实施级计划。

## 最终检查

- 是否误用了旧版 `Implementation Plan` / `For Claude` / `Task—Files—Step` 模板？若是，是否已在保存前重写？
- 完全没有相关背景的读者，只读“通俗解释”后，能否用自己的话复述究竟发生了什么？
- 通俗解释是否包含具体场景，并清楚对比当前情况与改进后的情况？
- 使用类比时，是否说明了它与实际问题的对应关系，且没有为了生动而歪曲事实？
- 非技术读者是否能在不看技术补充的情况下理解问题、目标和方案？
- 每项改进是否说明了它解决的问题和预期变化？
- 每项专业建议是否说明了它对普通用户意味着什么？
- 成功标准是否可观察、可验证？
- 是否删除了不能帮助决策或执行的代码片段、文件清单和过程性步骤？
- 计划深度是否与风险相称？

完成后说明计划的保存位置，并询问用户是否希望据此执行；不要预设执行模式或强制切换到其它 skill。

## 约束

<!-- BEGIN COMMON CONSTRAINTS -->
<!-- Source-Hash: sha256:dc839829c43968168dc291914ff849bc8a9bfd63ae4a9e569115a97df24e095e -->
<!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->

### 公共硬约束

本块由 `docs/templates/skill-common-constraints.md` 统一维护；每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块，不得在副本中改写公共规则。

- 任务需要落盘时，使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录；共享材料放入 `shared/`，Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。
- 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
- 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
- Skill 版本唯一记录在自身 `config.yaml:skill_info.version`；公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。
- 仅将 Skill 或 Bensz 基础设施本身的设计缺陷交给 `bensz-collect-bugs`；先脱敏写入 `~/.bensz-skills/bugs/`，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。

<!-- End of canonical common constraints. -->
<!-- END COMMON CONSTRAINTS -->