Require Agent Notes for non-trivial changes

2026-07-19 23:28:30 +08:00
parent 4b7765c774
commit b1b57a0ac5
6 changed files with 73 additions and 5 deletions
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-19-require-agent-notes-for-non-trivial-changes.md: f2645832ebcdd0b81cbff5415c7eb6f60b6fa8cf
+2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md: 659aa7cad0823fa0082be1827f8c083037376a4c
@@ -0,0 +1,31 @@
+# Agent Note: Require an Agent Note for every non-trivial change
+
+Status: implemented
+
+English | [中文](2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md)
+
+## Problem
+
+A selective threshold based on whether a decision seems durable, contested, and surprising lets substantial changes land without preserving their rationale. Code and tests show what changed, but they cannot consistently preserve why an approach won, which alternatives lost, or what costs maintainers accepted.
+
+## Decision
+
+Every non-trivial change adds or updates at least one Agent Note in the same PR. Non-trivial changes include behavior, architecture, cross-file or cross-package contracts, process or tooling, testing strategy, on-disk, wire, or configuration formats, and other decisions a maintainer may reasonably revisit.
+
+Updating the note that already owns a decision satisfies the rule; a new note is required only when no note owns it. Purely mechanical or local edits with no behavioral, contractual, structural, process, or rationale change are exempt. The [Agent Notes README](../../README.md#when-to-write-one) owns this boundary, while root `AGENTS.md` carries the standing order.
+
+Review enforces the semantic boundary. No automated gate attempts to classify a diff as trivial or non-trivial, so this policy adds no gate stage or runtime.
+
+## Alternatives considered
+
+**Require notes only for decisions judged durable, contested, and surprising.** The threshold is subjective enough that a substantial change can be treated as obvious or local, losing the rationale Agent Notes exist to preserve.
+
+**Require a new note for every change.** This duplicates an existing note when it already owns the decision and adds empty ceremony to purely mechanical edits.
+
+**Add a CI diff-classification gate.** A mechanical check cannot reliably determine whether a semantic change is trivial, while another gate adds runtime and invites false positives or superficial compliance.
+
+## Consequences
+
+- Every substantial change preserves its rationale and rejected alternatives beside the implementation.
+- Contributors maintain an existing owning note instead of creating duplicate records.
+- Mechanical edits remain lightweight, and the gate topology and runtime remain unchanged.
@@ -0,0 +1,31 @@
+# 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 差异分类门禁。** 机械检查无法可靠判断语义变更是否平凡，额外门禁还会增加运行时间，并引入误报或表面合规。
+
+## 影响
+
+- 每项实质性变更都会在实现旁保留其决策依据和被放弃的备选方案。
+- 贡献者维护现有的决策持有记录，而不是创建重复记录。
+- 机械编辑仍保持轻量，门禁拓扑和运行时间也保持不变。