ship-change

交付一次改动

目的是让"收尾"不依赖记性。多数项目的文档腐烂不是因为没人愿意写，而是因为写文档不在流程里。

流程

- [ ] 1. 对范围
- [ ] 2. 摸清现状
- [ ] 3. 定方案（有取舍才需要）
- [ ] 4. 实现
- [ ] 5. 自测
- [ ] 6. 收尾同步
- [ ] 7. 复盘蒸馏

1. 对范围

先看项目根目录的 docs/roadmap.md。不在里面的需求，先补一条再动手——不是走形式，是为了在写代码之前发现"这个其实不该做"。

同时确认边界：这次做什么、明确不做什么。把不做的部分说出来，比默默不做要好，用户会当场纠正你的理解偏差。

2. 摸清现状

动手前先读相关代码。重点是已有的模式：类似的功能现在是怎么写的？有没有可以复用的工具函数？

新代码应该读起来像周围的代码——命名习惯、错误处理方式、注释密度、目录约定都要对齐。写出一段风格突兀的正确代码，也是一种债。

如果本次改动范围内还有轻量初始化留下的 TODO(init) 欠账，停下来问清那一格，补上再继续；与本次改动无关的欠账不要顺手全补。

3. 定方案

只有存在真实取舍时才需要这一步。有的话，把两个方案和各自的代价说给用户听，选定后走 /record-decision 记下来。

没有取舍就直接做，不要为了显得严谨而编造一个方案对比。

4. 实现

范围与验证的口径以 AGENTS.md 的铁律为准，这里不复述一份——两处都写就会漂，改一处忘另一处，agent 读到互相矛盾的两句话。本步只补铁律没说的操作细节：

• 小步走，每一步都保持仓库可运行。
• 用最直接的方式实现，最小改动优先。 新建文件、引入依赖、加抽象层（接口 / 工厂 / 基类 / 配置文件），必须先有一句"现有结构为什么不够"的理由；没有理由就内联、就地改，不要为"以后可能要用"预支复杂度。能一个函数解决的不建模块，能改现有代码的不另起一套。
• 注释只写"为什么"——约束、取舍、来源。不写"这行在做什么"，更不要写"我把这里改成了 X"这种给 reviewer 看的话。
• 不确定的地方停下来问，不要猜一个 API 的行为然后写下去。

5. 自测

跑哪些命令、跑到什么范围，以 AGENTS.md 的验证命令表和铁律为准——那是这个项目验证口径的唯一来源，本步不再复述。

这里只补它管不到的部分：跑完问自己，边界情况处理了吗（空输入、零、负数、超长、并发、网络失败）？失败路径试过吗，还是只跑通了顺利路径？

通过一次就停。 不要反复读同一个文件、重复跑同一命令来"确认"同一结果，也不要为一次小改动额外编写探索性验证脚本。范围在步骤 1 已经对齐，超出的验证意味着范围又漂了。

6. 收尾同步

这一步是这个技能存在的理由。逐条过：

如果这次改动	就更新
加了或改了命令	AGENTS.md 命令表
加了顶层目录	AGENTS.md 目录地图
引入了新的领域概念或口径	docs/glossary.md
改变了分层或数据流	docs/architecture.md
包含有取舍的技术选择	新的 ADR（/record-decision）
完成或改变了 roadmap 条目	docs/roadmap.md 状态
排查超过 20 分钟才解决的问题	docs/troubleshooting.md（已确认事实，直接写）
暴露出上下文里缺了一条违反后果不可逆或不可发现的高风险规则	AGENTS.md 加一条铁律（唯一允许立即进铁律的情形）
暴露出上下文里缺了一句话，但风险没到不可逆/不可发现	docs/learning-inbox.md（待第二次出现再晋升）
本次改动范围内还有轻量初始化留下的 TODO(init) 欠账	现场问清后填入对应文件，范围外的留给 /ship-change 或 /maintain-context

和代码在同一次提交里更新，不要留到"以后统一整理"——那个"以后"不会到来。

7. 复盘蒸馏

收尾同步是把「改了什么」写回文档，这一步是把「学到了什么」写进收件箱——前者更新现状，后者更新理解，两者分开。

任务里出现过四种信号中的任何一种——我一开始理解错了什么 / 用户纠正了我什么 / 我花了超过 20 分钟才搞清什么 / 同一个流程或概念被解释了 2 次以上——先问自己：这件事是不是已经在步骤 6 写进权威文件了？写过了就不要重复入箱；收件箱只装待观察、待第二次出现再晋升的候选（通常是「纠正」和「流程」两类）。「坑」类在步骤 6 已写进 docs/troubleshooting.md，不重复入箱；「澄清」类如果已在步骤 6 更新了 goals.md / glossary.md / architecture.md，也不重复入箱。每种信号对应的类型、去向和条目格式都写在 docs/learning-inbox.md 里，追加时必然要打开它，这里不重复一份。