# 决策与复盘

保存长期理由，从会话证据提出最小环境改进。

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

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

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

> Code is the materialized view of all the decisions made
>
> — Matt Pocock, [source](https://x.com/mattpocockuk/status/2107560148243812772), 2026-10-06

## ADR 保存仍需要解释的决定

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

Figure: ADR 的背景、选择、理由与状态 ([s12-adr-fields](/art/s12-adr-fields.zh.svg))

- **背景与选择** 当时遇到什么限制，选了什么方案？
- **理由与后果** 放弃什么，接受什么成本？
- **状态** 当前有效、待决定，还是被哪份记录替代？

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

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

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

Figure: 基于证据提出并验证最小改进 ([d12-retro-flow](/diagrams/d12-retro-flow.zh.svg))

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

## 术语表也需要主动使用

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

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

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

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

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

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

> **本站推论**
> 本站建议：一次只调整一个有证据的障碍，再用相似任务观察。把“少绕路”落实为能定位当前资料，而不是凭会话变短就判断效果。

## 完成标准

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

若改进涉及长期规则，回到 [规范与检查](/zh/standards-and-checks) 选择执行位置。

## 速查

- **ADR** 留下长期背景、选择、理由、后果与状态。
- **复盘** 证据 → 最小改进 → 验证方式 → 人确认。
- **术语表** 记录含义，并主动检查实际文稿。

## 来源

- Matt Pocock，[代码与决策](https://x.com/mattpocockuk/status/2107560148243812772)，2026-10-06。
- Matt Pocock，[retro 提示词](https://x.com/mattpocockuk/status/2105951409887949107)，2026-10-02；仅解读。
- Matt Pocock，[撤回语气实验](https://x.com/mattpocockuk/status/2085681281795232026)，2026-08-07；仅解读。
- ADR 字段、开发记录和答案由本站编写；[版权说明](/zh/about-and-copyright)。

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

本页说明图内嵌的 CSS 片段改编自 Archify（https://github.com/tt-a1i/archify），MIT 许可，完整许可如下。

### 完整许可：Archify (tt-a1i/archify)

```text
MIT License

Copyright (c) 2026 tt-a1i (Archify)
Copyright (c) 2025 Cocoon AI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```