决策与复盘

代码留下了，为什么又争论同一个选择？

新会话看到缓存实现，却不知道为何只缓存五分钟。它按自己的猜测改成一天， 旧问题再次出现。代码能显示结果，却未必能显示当时的限制和取舍。

另一些浪费不在代码里：查错资料、读过期说明、手动重复验证。 本页要保存长期理由，并从真实会话提出一项可以验证的环境改进。

Code is the materialized view of all the decisions made

— Matt Pocock2026-10-06

ADR 保存仍需要解释的决定

用 ADR 记录背景、选择、理由、后果与状态。临时执行步骤另管； 决定过时时注明由哪份新记录替代，让下一位读者能辨别历史依据与当前约定。

以上字段由本站编写。ADR 不要求照搬某个人的提交习惯， 仍按团队的评审和变更流程保存。已确定的长期理由与当前任务进度要分开更新。

复盘先找证据，再提最小改进

/retro 的关注点是实际会话和评审反馈：哪里找资料慢、依赖了过期文件， 哪里缺工具或检查。成功交付也可能绕过许多弯路，不能只复盘失败。

每项建议串起观察证据、最小改进和验证方式。由人确认后再落地， 避免 agent 自己增加规则。优先修导航与确定性检查，再考虑是否需要更多文字说明。

术语表也需要主动使用

同一个业务词可能在团队中指不同对象。术语表写明含义、易混叫法和关联， 再主动按它检查工单与报告。只加一句「用词统一」，读者无法观察是否真的统一。

Matt 曾撤回一次被动语气指令的实验；不能据此推断所有写作要求无效。 更可检验的做法是找出实际混淆，指定要检查的词，再对比修改前后的理解。

练习：从一段记录产出两个东西

动手练习

给缓存留下理由，给导航提出改进

• 本站虚构记录：会话先读旧接口说明；测试两次失败后才找到新说明。
• 已确认决定：状态最多容忍五分钟延迟，因此缓存五分钟；代价是更多请求。
• 任务：写一条五字段 ADR，再提一项复盘建议与验证方式。

参考思路

ADR 写清延迟限制、五分钟缓存、理由、请求成本及有效状态。复盘建议为：人工确认后，把状态接口入口指向新说明，并标记旧文档已替代；让新会话查一次，观察是否直接找到当前接口。

完成标准

ADR 能解释为何接受某项代价，且状态与替代关系明确。复盘建议能指向会话证据， 包含最小改动、确认人和验证动作；尚未批准的建议保持为建议，不自动变成新规则。

若改进涉及长期规则，回到 规范与检查 选择执行位置。

速查

来源

• Matt Pocock，代码与决策，2026-10-06。
• Matt Pocock，retro 提示词，2026-10-02；仅解读。
• Matt Pocock，撤回语气实验，2026-08-07；仅解读。
• ADR 字段、开发记录和答案由本站编写；版权说明。

非官方、非商业的学习整理，与 Matt Pocock 无隶属或背书关系。所引作品版权归原作者；MIT 复用内容另附版权与许可声明。