writing-plans

# 写实施计划 写一份帮助人作出正确决定的计划，而不是把代码操作逐条抄出来。读者即使没有编程经验，也应先能回答：现在的问题是什么、为什么值得解决、准备怎样改善、怎样算完成。 开始前，简要说明正在使用 `writing-plans` 来整理实施计划。 ## BenszAPI 任务工作区 本 Skill 产生的中间材料统一写入 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/writing-plans/input|output|log/`。正式计划保存到项目的 `docs/plans/`，不要写入中间目录；只有多 Skill 协作时才创建 `shared/`。 ## 与 bensz-collect-bugs 的协作约定 - 因本 Skill 的设计缺陷导致的问题，先用 `bensz-collect-bugs` 记录到 `~/.bensz-skills/bugs/`；不要直接修改用户本地已安装的 Skill 副本。 - 只有用户明确要求公开上报时，才使用本地 `gh` 上传脱敏后的新记录；不要拉取或克隆整个 bug 仓库。 ## 工作原则 - 以本次读取到的 `SKILL.md` 为当前规则来源。会话里更早出现的计划模板和现有旧计划只作为事实材料，不自动继承其结构。 - 先说问题、影响和目标，再说改进方向，最后才补充必要的技术细节。 - 用日常语言解释业务行为和用户感受；首次出现技术术语时说明它的作用。 - 把计划写成“要解决什么、为什么这样做、完成后有什么变化”，而不是“在第几行写什么代码”。 - 代码、伪代码、完整文件路径和命令都不是默认内容。只有它们能澄清接口约定、数据转换、���键边界或验证方法时才保留。 - 不用代码示例替代解释；任何技术补充之前都必须已有对应的白话说明。 - 只规划当前需求需要的最小改动。避免为展示完整而堆砌 TDD 步骤、提交步骤、框架细节或无关的重构。 ## 先理解再落笔 1. 阅读需求、现有行为和相关约束，确认问题确实存在。 2. 用一两句话描述现状、受影响的人或场景，以及不处理的后果。无法确认根因时，明确写为待验证的假设。 3. 明确目标、非目标和成功标准；不要把实现手段误写成目标。 4. 选择能以最小范围达到目标的改进方向，并说明它为何有效。 5. 仅在需要时补充涉及的模块、文件、依赖、风险和验证方式。 ## 计划深度 - **低风险或文档类改动**：写问题、目标、改进方向、范围和完成标准即可；用 2–4 项概括实施顺序。 - **中等风险改动**：额外说明受影响的组件、关键行为变化、验证方法和需要确认的假设。 - **高风险、跨模块、安全或数据改动**：额外说明依赖顺序、兼容性、失败后的恢复方式、非目标和验证矩阵。 风险等级决定需要解释多少决策、边界和验证，不决定步骤必须拆得多细。高风险计划也不默认展开成逐文件、逐测试、逐提交的操作脚本；不要因为正在写计划，就把改动扩充成一份冗长的技术设计书。 ## 防止回归旧模板 默认使用本 Skill 的“问题优先”结构。只有用户明确要求可直接照着逐步执行的实施级计划时，才增加任务、文件或命令细节；即使如此，也先保留问题、目标、改进方向和验收这层白话主线，再把执行细节放入对应方向或技术补充中。 保存前检查草稿是否沿用了旧模板。典型指纹包括： - 标题以英文 `Implementation Plan` 结尾。 - 出现 `For Claude: REQUIRED SUB-SKILL` 或预设后续执行 Skill ...