32 lines
2.1 KiB
Markdown
32 lines
2.1 KiB
Markdown
# Agent Note: 每项实质性变更都必须附带 Agent Note
|
||
|
||
Status: implemented
|
||
|
||
[English](2026-07-19-require-agent-notes-for-non-trivial-changes.md) | 中文
|
||
|
||
## 问题
|
||
|
||
如果只在决策被认为持久、有争议且出人意料时才记录 Agent Note，实质性变更就可能在没有保存决策依据的情况下落地。代码和测试能展示改动内容，却无法稳定保留某种方案胜出的原因、被放弃的备选方案，以及维护者接受的成本。
|
||
|
||
## 决策
|
||
|
||
每项实质性变更都在同一个 PR 中新增或更新至少一份 Agent Note。实质性变更包括行为、架构、跨文件或跨包契约、流程或工具、测试策略、磁盘格式、线协议或配置格式，以及维护者可能合理重审的其他决策。
|
||
|
||
更新已经持有该决策的 Agent Note 即满足规则；仅当没有 Agent Note 持有该决策时才新增记录。完全机械或局部、且不改变行为、契约、结构、流程或决策依据的编辑可豁免。[Agent Notes README](../../README.md#when-to-write-one) 持有这条边界，根目录 `AGENTS.md` 则携带常驻指令。
|
||
|
||
评审负责执行这条语义边界。自动化门禁不尝试把差异分类为平凡或实质性变更，因此这项政策不会增加门禁阶段或运行时间。
|
||
|
||
## 备选方案
|
||
|
||
**只为被判断为持久、有争议且出人意料的决策要求 Agent Note。** 这条门槛过于主观，实质性变更可能被视为显而易见或局部改动，从而丢失 Agent Note 本应保存的决策依据。
|
||
|
||
**每项变更都必须新增 Agent Note。** 当现有 Agent Note 已经持有该决策时，这会产生重复记录，也会让纯机械编辑承担空洞的流程负担。
|
||
|
||
**添加 CI 差异分类门禁。** 机械检查无法可靠判断语义变更是否平凡，额外门禁还会增加运行时间，并引入误报或表面合规。
|
||
|
||
## 影响
|
||
|
||
- 每项实质性变更都会在实现旁保留其决策依据和被放弃的备选方案。
|
||
- 贡献者维护现有的决策持有记录，而不是创建重复记录。
|
||
- 机械编辑仍保持轻量，门禁拓扑和运行时间也保持不变。
|