📄 补充 Agent 自主操作边界、指令冲突裁决与人类可读写作规范

[cyfung1031]

Checklist / 检查清单

• Fixes mentioned issues / 修复已提及的问题
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

N/A — 不对应单个 issue；尚无人工复核。Changes tested 指文档验证，不是产品测试，见「验证」。

背景

我们的 agent 文档把「改动要达到什么质量」写得很全，但漏了三件事，而这三件事恰好决定 agent 用起来舒不舒服。

一、文档从没把 agent 写成决策者。 decide 的每一处主语都是别的东西：

git grep -nE 'decide[sd]? by|decides whether' -- AGENTS.md docs/
#   AGENTS.md:53   … is decided by the classification table in …
#   AGENTS.md:142  The root-cause principle decides whether …

proceed 也一样，要么是许可，要么是限制。整套文档是约束语料，从未授予判断权，所以 agent 遇到自己完全能解决的
判断题时会写成「建议」交回来——把活推回给人。本 PR 前两版自己就这样：发现 PR 模板缺 checklist 诚实性提示，
却写成「应由维护者决定，不属于本 PR 范围」。那不是审慎，是把一行可回滚的编辑推给别人。本版直接做掉了。

二、写给人看的东西该怎么写，全套文档一个字都没有。 develop.md 的 Language Conventions 只管用哪种语言。
而 pull-request.md 给的是九级标题骨架 + 七项决策链 + 十行证据表——一张表格。Agent 会把表格填满，
于是产出前三版这份 PR 描述那样的东西：两百行、四个表格、同一件事在五个章节里各说一遍。人读起来很累。

三、几个具体的分歧点，都能在 main 上 grep 复核。material 是决定「要不要写七段 rationale chain、
要不要风险段、能不能算 ready」的门槛词，被引用九次、从未定义，而且 pull-request.md:77 的
“needs only the material parts” 用的还是另一个意思。测试失败的例外在常驻的 AGENTS.md 里只有两条，
owner 的分类表实际有六种处置，其中 Flaky 和 Misclassified integration 两种不在例外里——
「popup.test.ts flaky，修稳定」按常驻文件读要改生产代码，按 owner 读多半是修测试隔离。
路由表是一次性分类，跨边界的重命名做到一半发现该读架构文档时，没有规则叫你回去。
执行期没有冲突裁决规则（DOC-MAINTENANCE.md 那套是给改文档的人用的），agent 只能静默选边。
「人工指令能覆盖什么」也没写——面对「先 as any 顶一下」，手上是三块互不衔接的文本。

本次改动

给 agent 判断权，同时把边界写清楚。AGENTS.md 的 ## Autonomous operation 改成「acting as much as the
bounds on it」，并新增两条：Decide inside the scope you were given 区分三种被混为一谈的情况——不知道就去查
（自己能回答的不算问题）、还不可知就取最省的合理读法并写明假设、无权决定才是升级；难度、歧义、
一般风险不是授权问题。Hand a decision back only with its owner and its blocker named 要求升级时指名谁拥有该决定、
只有他们能提供什么、没回音时你的默认动作；顺带发现的事，任务确实需要就做掉，只是恰好在旁边就记 follow-up，
边界是 scope discipline 而不是你打开了哪些文件。把本可做完的事写成「建议」不是更轻的选项，是更小的交付物。

新增 ## Writing for a human reader：写到读者的下一个决定为止；散文是默认，结构要自己挣来位置；
每件事只说一次；靠取舍变短而不是靠省略——查过的检查、限制、不确定性一个都不能删。
配套把 pull-request.md 的结构说明改成「待考虑项，不是待填表格」，并点明描述比 diff 还长通常已经帮倒忙。

其余是修正已有规则：前言补指令冲突裁决与人工指令的覆盖边界（可豁免 preference，不满足写成禁止的规则；
说明一次，被重申则执行并记为具名的已接受偏离）；路由改成持续的；测试失败例外整体交给 owner 分类表裁决，
链接改指 #cleaning-up-tests-safely；pull-request.md:77 一处 material 改 relevant 消除一词两义。
新增 material 的可操作定义、声明范围与最终 diff 的绑定、不稳定检查结果的报告口径
（绿色重跑不撤销红色运行）、临时性修复必须自我披露、禁止自造 oracle，以及 DOC-MAINTENANCE.md 的
Instruction budget（约束以后往这套文档里加规则，也约束本 PR 自己）。

.github/pull_request_template.md 加了三行不渲染的注释：只有真做了才勾、Code reviewed by human 指人
而不是作者自己的 agent、不适用就留空并写一行 N/A — why。pull-request.md 要求模板保持 lightweight
并保留 Checklist，两条都守住了——去掉全部 HTML 注释后模板输出与改前逐字节相同。它是唯一能触达
不读 AGENTS.md 的外部 agent 的位置。若认为模板一个字符都不该动，删掉这三行即可。

已知限制

这是静态审查。上面每条都能在 main 上 grep 复核，属可验证的文本事实；但「改完之后真实模型行为会变好」
本 PR 不提供证据。我用任务 trace 走查了这些分歧点（flaky 测试、as any 豁免请求、跨边界重命名、
一行修复的 materiality、owner 间冲突、以及本 PR 自己的 deferral 和这份描述本身），trace 用于定位文本缺陷，
不构成验收依据——本 PR 新增的规则之一就是禁止把自造评分当 oracle，所以这里没有分数。

material 的定义放在 AGENTS.md（shared contract），pull-request.md 靠常驻加载继承。
若认为该由 pull-request.md 拥有，位置可以调，但不该两处各写一份。

建议审查重点

1. Decide inside the scope you were given 的三分法是不是你们要的升级门槛。
2. Hand a decision back 与 scope discipline 的边界：现在切在「任务确实需要就做，只是在旁边就记 follow-up」。
3. ## Writing for a human reader 会不会和 pull-request.md 的证据要求打架——写的是「靠取舍变短，
   不靠省略」，查过的检查和限制不许删，请确认这个防线够不够。
4. 测试失败规则改交 owner 分类表后，AGENTS.md 是否仍保住足够强的非可协商部分。
5. PR 模板那三行注释是否接受。

验证

只改 Markdown。pnpm run lint 的 prettier 只覆盖 **/*.{ts,tsx,js,jsx,mjs}，Markdown 不在其内，
所以跑的是 pull-request.md#documentation-only-prs 要求的文档验证。

base 61164f6920e736fd3a03b269fb907e7aa7975432 → head 017872bf2b8c4a33ba6bf4b30861c4f665d9fa55

git diff --numstat        .github/pull_request_template.md  +4/-0
                          AGENTS.md                        +101/-5
                          docs/DOC-MAINTENANCE.md           +10/-0
                          docs/develop.md                    +6/-0
                          docs/pull-request.md              +10/-2
                          5 files changed, 131 insertions(+), 7 deletions(-)

链接完整性   DOC-MAINTENANCE.md 的 one-shot 脚本，HEAD 全部 tracked Markdown → 0 BROKEN
锚点         #cleaning-up-tests-safely / #revision-scope-and-publication-binding /
             #decision-evidence-and-readiness → 各 1 命中
重复标题     ## Autonomous operation、## Writing for a human reader 仅在 AGENTS.md；
             ## Instruction budget 仅在 DOC-MAINTENANCE.md
模板渲染     去掉全部 HTML 注释后与改前逐字节相同，Checklist 三项与顺序未动
政策一致性   绝对语气 grep 命中 6 处，逐条确认为有意的 non-negotiable
术语         'material' 在 pull-request.md 的第二种含义已改为 "the relevant parts"
隐私扫描     clean
行宽         新增行均 ≤120 列

未跑 pnpm test / pnpm run lint / pnpm run build：不触及产品代码、测试、生成文件或翻译，
且本 worktree 无 node_modules，Markdown 也不在这些检查范围内。无 UI 变更。

🤖 Generated with Claude Code

[cyfung1031]

@CodFrm 你 agent 提交的那些还没合并的 PR，建议先把这个 PR 合并掉，然后再基于最新代码重做一下那些 PR。

[CodFrm]

没有使用了，清理掉相关的内容好了，并不是所有人都用这个工具

[CodFrm]

能否收进docs里面的文档，agents.md 和 相关的文档又开始膨胀了

[CodFrm]

能否收进docs里面的文档，agents.md 和 相关的文档又开始膨胀了，或者精简/优化之类，agent pr的时候也要求pr的内容精简准确，不然一大段话也难读

不过我认可你这个pr的价值，我后续的pr可以看看效果，我先合了