📄 澄清 Agent 文档职责边界、任务路由与 Copilot 审查 finding gate

[cyfung1031]

Checklist / 检查清单

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

N/A — 本 PR 不对应已提及的 issue；当前没有人工审查记录；这是纯 Markdown 文档变更，没有运行产品代码测试。

Description / 描述

背景

本 PR 基于对仓库当前 main 与一份外部审查包中 Agent 文档修订稿的逐文件对比。审查包声明的源提交为 a4bc9b681734717b8c9171f5224f581411ed273c；当前 main 基线仍为该 SHA，因此本次对比不存在“审查稿基于旧 main”的基线漂移。

仓库现有 docs/DOC-MAINTENANCE.md 已明确文档职责：AGENTS.md 负责 repo-wide engineering principles + architecture quick-map，.github/copilot-instructions.md 只保留 Copilot-specific differences，CLAUDE.md 仅导入 AGENTS.md。本 PR 在此基础上进一步收敛职责，并经过多轮 drawback review，重点避免 finding false negative、推测性 review、平行政策漂移和无谓 context 膨胀。

本次改动

AGENTS.md

• 将开头收紧为 repo-wide contract，并明确只拥有工程原则与 architecture quick-map；具体 mechanics 继续由 routed docs 持有。
• 明确 CLAUDE.md 只负责导入，Copilot 文件只能增加 Copilot-specific behavior，不能复制 shared policy / architecture。
• 把任务路由提升为显式的 Route the task before acting 门槛。
• 在中央路由表补充 architecture-sensitive 工作：修改 process/message/service/persistence boundary 或新增 subsystem 时，必须读取 docs/architecture.md 与相关 docs/references/architecture-*.md deep-dive，避免架构规则只出现在后文而没有进入主路由。
• 对跨多个任务类型的工作，改为“在执行对应部分之前读取适用 owner”，而不是一开始把所有可能相关文档全部前置加载，降低 context 膨胀。
• 明确 repo-wide principles 是默认 contract；如果原则自身链接到 owning doc 中的窄、显式例外，该例外属于同一 contract，而不是“下游文档静默覆盖上游原则”。
• 把 Architecture 明确定位为 orientation map，而不是 implementation manual。
• 保留 Completion checksum，但将其改成 handoff checklist：主要引用 owning docs 来核对 evidence、verification、architecture 和 documentation facts，而不是在 AGENTS.md 重新复制这些 mechanics。

.github/copilot-instructions.md

• 将文件定位收敛为 Copilot-specific delta only，共享工程原则/架构事实继续指向 AGENTS.md 与其 routed docs。
• 保留“中文 code review”和“每次独立审查当前完整 diff”的要求，并明确 review 结论必须基于 current repository state + actual diff，而不是 PR 描述/commit message。
• 调整 Finding gate，避免初版硬性要求“必须由当前 PR introduced”造成 false negative，同时防止 review 扩张成泛化代码审计：
  • PR review 聚焦当前 diff 引入或新变得 reachable 的 defect；
  • pre-existing defect 只有在沿 affected path 追踪时直接发现，且具有 material correctness / security / data-loss / reliability 或同等级实际影响时才报告；必须明确标记 pre-existing；
  • Concrete trigger 扩展为 Concrete trigger or proof path，允许 race、lifecycle、resource leak、security-boundary 等更适合静态证明的问题通过 demonstrable code path / invariant violation 支撑；
  • PR-introduced finding 定位到最小有用 changed location；pre-existing defect 如果真正位置不在 diff 中，必须放在 review summary，而不是硬挂到无关 changed line；
  • distinct / actionable / concrete impact 等门槛继续过滤纯风格、纯猜测和同根因重复 finding。
• 收紧未验证假设的处理：如果 repository-specific assumption 无法从 owning docs/code 验证，不得作为 finding 提交；若对 reviewer 仍有价值，只能在 review summary 中作为明确的问题/未验证假设提出，并指出需要哪个 canonical source 才能确认。
• 删除 Copilot fallback 中复制的 ScriptCat 架构/技术栈摘要。linked instructions 不可用时，只允许基于当前 diff/files 可直接验证的事实工作，并显式说明无法加载哪个 canonical source。

CLAUDE.md

• 未修改。它在 main 上已经是单行 @AGENTS.md，与审查包修订稿一致。

与审查包的取舍

• 提交了审查包中的两份正式 Agent 文档修订：AGENTS.md 与 .github/copilot-instructions.md。
• 没有提交审查包附带的 clarity report；它是审查过程产物，不是仓库当前文档职责表中的 canonical Agent 入口。
• 当前分支不是对 zip 的机械复制；在原修订方向上又针对实际维护/审查风险做了收敛：
  • 放宽但限定 finding gate，避免漏掉高影响既有缺陷，同时避免泛化审计；
  • 允许静态可证明的问题使用 proof path，而非强求不适合的运行时复现；
  • out-of-diff 的既有缺陷放 review summary，不伪造 inline 定位；
  • 未验证 repository-specific assumption 不得进入 finding；
  • 将 completion checksum 改为 owner-reference checklist，减少未来 policy drift；
  • 将 architecture-sensitive 工作显式纳入主路由；
  • 将跨任务 owner 阅读改为按任务阶段加载，减少不必要 context 消耗。
• 没有修改任何产品代码、测试、配置或用户文档。

影响

这次变更不会改变 ScriptCat 产品运行行为。预期影响仅在 AI coding/review agents：

• 更明确地知道哪个文档拥有哪类规则，包括 architecture-sensitive 工作；
• 减少 Copilot-specific 文件中的重复架构事实；
• review findings 更强调因果关系、证明路径、具体影响和诚实定位；
• material pre-existing defect 不会仅因为“不是 PR 引入”而被强制压掉，但普通既有债务不会借 PR review 扩张；
• 未验证假设不会再被包装成 finding；
• completion 声明更多依赖 owning docs 的真实验证要求，而不是另一份摘要政策。

已知限制 / 取舍

• 删除 fallback 架构摘要后，无法加载 AGENTS.md 的受限 Copilot surface 会失去一部分 degraded-mode 架构能力；这是有意选择“避免 stale duplicated facts”优先于“离线保留简化架构摘要”。
• Finding gate 允许报告 material pre-existing defect 后，review 输出可能比严格只看 regression 的模式略多；通过 affected-path + material-impact + pre-existing 标签限制范围。
• 当前执行环境无法通过本地 git clone 访问 github.com（DNS 解析失败），因此没有运行 docs/DOC-MAINTENANCE.md 中要求的完整本地 git-aware one-shot fact/link scan。
• 通过 GitHub API 核对了 main 基线、canonical docs、最终分支内容和最终 diff，但这不等价于对仓库所有 tracked Markdown 执行完整相对链接扫描。
• 未运行 pnpm 测试/lint：本 PR 只修改 Markdown，且产品代码没有变化。

验证

已完成：

• 确认仓库默认分支为 main，当前基线仍为 a4bc9b681734717b8c9171f5224f581411ed273c。
• 确认审查包报告声明的 source commit 与该 main 基线一致。
• 读取并对照 docs/DOC-MAINTENANCE.md、docs/pull-request.md、docs/develop.md 和 PR template 的职责/提交要求。
• 确认最终分支相对 main 仅修改 2 个文件：AGENTS.md、.github/copilot-instructions.md；CLAUDE.md 未变化。
• 多轮 drawback review 已实际反映到文档：finding false-negative、static proof、policy duplication、context loading、pre-existing scope、out-of-diff location、unverified assumption、architecture routing。
• 最终分支重新压为 1 个文档提交，提交信息为 📄 澄清 Agent 文档职责与审查门槛，符合仓库 gitmoji 提交规范。
• 最终 compare 状态：分支相对 main ahead 1、behind 0，仅上述两个 Markdown 文件发生变化。

未完成：

• 未运行完整本地 git ls-files / git grep / relative-link one-shot verification，原因是当前执行环境无法 clone GitHub 仓库。
• 未进行人工 code review。
• 未运行产品测试；本 PR 没有产品代码变更。

建议审查重点

1. architecture-sensitive 路由是否准确覆盖 process/message/service/persistence boundary 与 subsystem 变更，同时没有把普通实现改动误升级成架构任务。
2. pre-existing finding 的 material-impact + affected-path 限制是否足够清楚，既不会漏掉高影响缺陷，也不会让 review 变成泛化代码审计。
3. trigger or proof path 是否覆盖 race/lifecycle/security 等静态可证明问题，同时仍能过滤纯猜测 finding。
4. 未验证 repository-specific assumption 强制移出 finding、改放 review summary/question 的规则是否符合团队期望。
5. 删除 fallback 架构摘要后，在 Copilot 无法加载 AGENTS.md 的环境里，准确性与 degraded-mode 能力之间的取舍是否符合团队期望。
6. 请在可正常 checkout 的环境里补跑 docs/DOC-MAINTENANCE.md 的完整 git-aware fact/policy/link 检查，再决定是否合并。

Screenshots / 截图

N/A — 纯文档变更，无 UI 变化。

[cyfung1031]

已根据对初版方案的 drawback review 更新本 PR，当前分支不是对审查包的机械复制，而是在保留“文档职责收敛”目标的同时修正几个可能造成实际副作用的点。

主要调整：

• 避免 finding false negative：不再把“必须由当前 PR introduced”作为绝对门槛。PR review 仍优先关注当前 diff 引入/新变得 reachable 的问题，但如果在受影响路径中发现严重的既有缺陷，可以报告，必须明确标记为 pre-existing，避免误导成 regression。
• 允许静态 proof path：将 Concrete trigger 放宽为 Concrete trigger or proof path。race、lifecycle violation、resource leak、security-boundary error 等不适合强行要求运行时复现的问题，可以通过可证明的 code path / invariant violation 支撑；仍然不能用纯猜测代替证据。
• 减少 Completion checksum 的重复政策：checksum 现在明确只是 handoff checklist，具体 reproduction/test/manual verification/文档事实检查继续由 linked owning docs 定义，避免 AGENTS.md 日后成为第二份会漂移的 mechanics 副本。
• 明确原则与例外的关系：repo-wide principles 是默认 contract；原则自身显式链接到 owning doc 的窄例外时，该例外属于同一 contract。未链接、无关的下游文字不能静默覆盖原则。
• 降低 context 膨胀：跨多个路由项的任务改为“执行对应部分前读取 applicable owner”，不要求一开始预加载所有未来可能相关文档。

仍然保留一个有意的取舍：Copilot 无法加载 AGENTS.md 时，不再维护一份 fallback 架构摘要。这样 degraded-mode 能力会弱一些，但可以避免一份无法保证同步的平行架构事实源。PR 描述已明确记录这个限制。

我也重新整理了分支历史：当前相对 main 仍然只有 1 个提交、2 个 Markdown 文件，commit 为 📄 澄清 Agent 文档职责与审查门槛。PR 描述已同步更新，包含上述取舍和仍未完成的本地 full git-aware doc/link scan，不声称已经完成未实际执行的验证。

[cyfung1031]

本轮 drawback 收敛

继续按当前最终 diff 做了一轮反向检查，这次只修改了 .github/copilot-instructions.md；AGENTS.md 上一轮已经把 owner/exception/completion checksum 的边界收敛清楚，本轮没有再扩大它的政策面。

这次处理了 3 个剩余风险：

1. serious pre-existing defect 过于主观

   • 现在不再只写“serious”。
   • 只有在沿当前 PR 的 affected path 实际追踪时直接发现，并且具有 material correctness / security / data-loss / reliability 或同等级别的实际影响，才允许作为 pre-existing finding 报告。
   • 其他既有问题继续保持 PR review scope，不把一次 review 扩张成泛化代码审计。

2. pre-existing defect 可能不在 GitHub diff 上，无法诚实挂 inline comment

   • PR 引入的问题仍定位到 smallest useful changed location。
   • 既有问题如果对应位置确实出现在 diff 中，可以定位到该 affected location。
   • 如果真正的问题位置完全在 diff 外，明确要求放进 review summary，而不是为了满足“必须定位”而硬挂到一个无关 changed line 上。

3. “grounded in current files and diff” 与检查 unchanged affected paths 存在语义张力

   • 现在改成 findings 必须 grounded in the current repository state and the actual diff。
   • 这样既继续禁止拿 PR description / commit message 当结论依据，也允许 unchanged 但受影响的实现成为证据来源。

保留上一轮已经确定的设计：静态可证明的 race/lifecycle/resource-leak/security-boundary 问题仍可使用 trigger or proof path，不强求不合适的运行时复现；linked canonical instructions 不可用时也仍选择显式降级，而不是在 Copilot 文件里维护一份可能漂移的架构副本。

最终分支已重新整理并核对：相对 main ahead 1 / behind 0，只有 1 个提交，仍只修改 AGENTS.md 与 .github/copilot-instructions.md 两个 Markdown 文件。当前剩余主要风险已经从规则设计转为验证层面：完整本地 git-aware 文档 fact/link/policy scan 仍需要在可正常 checkout 的环境中补跑。

[cyfung1031]

最后一轮 drawback 收敛

继续按当前最终规则做了一轮反向检查，这次只处理剩余的两个规则歧义，并同步修正 PR 描述；没有再扩大其他政策面。

本轮实际修改：

1. 把 architecture-sensitive 工作纳入中央路由表

   • 之前 AGENTS.md 后面的 Architecture 章节已经要求“改变 boundary / 新增 subsystem 前读 docs/architecture.md”，但 Route the task before acting 主路由表没有对应入口，存在内部不一致。
   • 现在新增路由：修改 process/message/service/persistence boundary 或新增 subsystem 时，读取 docs/architecture.md，并继续读取相关 docs/references/architecture-*.md deep-dive。
   • 这样 architecture 规则不再依赖 agent 先读到后文才能发现，同时仍然只在真正 architecture-sensitive 的工作触发，不要求普通实现改动无条件加载整套架构文档。

2. 未验证 repository-specific assumption 不再允许作为 finding

   • 上一版最后仍允许“mark it as unverified or omit the finding”，这和前面的 finding gate（concrete trigger/proof path + concrete impact）存在轻微冲突，也可能重新引入推测性 review。
   • 现在明确：如果支撑 finding 所需的仓库特定假设无法从 owning docs/code 验证，不得提交为 finding。
   • 如果这个不确定性对 reviewer 仍然有价值，只能放在 review summary，明确写成 question / unverified assumption，并指出需要哪个 canonical source 才能确认。

3. PR 描述已同步到真实最终规则

   • 补充 material pre-existing finding 的 affected-path + impact 限制；
   • 补充 out-of-diff pre-existing defect 应放 review summary，而不是伪造 inline 定位；
   • 补充未验证假设不得进入 finding；
   • 补充 architecture-sensitive 主路由。

分支历史再次整理为单一提交。当前相对 main：ahead 1 / behind 0，1 个提交，仅修改 AGENTS.md 与 .github/copilot-instructions.md 两个 Markdown 文件；提交信息仍为 📄 澄清 Agent 文档职责与审查门槛。

仍然没有改变的限制：当前环境无法正常 clone GitHub，因此 docs/DOC-MAINTENANCE.md 要求的完整本地 git-aware fact/link/policy scan 仍未执行。这个限制继续保留在 PR 描述中，不把 API 级核对描述成完整本地验证。

到这一版，继续对规则文字做微调的收益已经很低；后续更值得关注的是 human review 和在可正常 checkout 的环境中补跑完整文档验证，而不是继续增加更多 Agent policy。

[cyfung1031]

human checked

[cyfung1031]

合并决策审查：优点、缺点与剩余风险

我按当前 head 70fcc142be837f83b35eff5c32b119b1adf5e83e 的实际 diff、仓库当前文档规则、PR discussion、正式 review 记录和 CI 状态重新核对了一遍。下面把“支持合并”和“反对/暂缓合并”的理由都列出来，避免只重复 PR 描述里的自述。

事实核对

项目	当前事实	对合并判断的意义
变更范围	相对 main 的 a4bc9b681734717b8c9171f5224f581411ed273c：ahead 1 / behind 0，只改 AGENTS.md 和 .github/copilot-instructions.md，共 1 个提交	范围很小，没有产品代码、配置、测试或 UI 变更，运行时回归面低
可合并性	GitHub 当前报告 mergeable: true	没有机械性 merge 冲突；这不代表语义上应该合并
CI	test workflow 全部完成并成功：Lint、2 个 Vitest shard、4 个 E2E shard、聚合测试均通过；License Compliance 也为 success	说明该提交没有触发现有自动化测试/构建回归
CI 能否覆盖本 PR 的核心风险	不能完全覆盖。 pnpm lint:ci 只检查 TS/JS Prettier、typecheck、i18n、issue template 和 ESLint；现有 workflow 没有执行 DOC-MAINTENANCE.md 的全仓 Markdown relative-link / anchor / policy-consistency / final-tree fact scan	“CI 全绿”不能替代本仓库自己要求的 documentation-only 验证
文档专用验证	PR 已明确承认：没有执行完整本地 git ls-files / git grep / relative-link one-shot scan	这是当前最明确的验证缺口，不应被 CI 通过掩盖
正式人工 review	当前 GitHub API 中 0 个 submitted reviews、0 个 review threads。discussion 中有作者自己的 human checked 普通评论	可以说明有人声称做过人工检查，但不能把它等同于一个可审计的独立 GitHub approval/review 记录
PR checklist	Code reviewed by human 已勾选，但 PR 描述同一段仍写着“当前没有人工审查记录”；后续只有作者的 human checked 评论	表述存在轻微不一致，reviewer 不应仅依赖 checkbox 判断审查充分性

支持合并的理由

优点	具体收益	我的判断
文档职责边界更清楚	AGENTS.md 明确只拥有 repo-wide engineering principles + architecture quick-map；具体 mechanics 继续路由到 owner docs；Copilot 文件明确只保留 Copilot-specific delta	明显正向。 能降低同一规则在多个文件重复维护造成的 drift
Architecture 路由前置	process/message/service/persistence boundary 或新增 subsystem 被加入中央 routing table，而不再只埋在后面的 Architecture 章节	正向。 对 agent 来说更不容易漏掉架构 owner docs
Completion checksum 改成引用 owner 的 handoff checklist	不再复制测试、验证、文档事实检查的具体 mechanics，而是指回 owning docs	正向。 比维护第二套“摘要规则”更不容易长期漂移
Finding 的因果和证据门槛更严格	要求说明 relation to change、trigger/proof path、concrete impact、location、distinct、actionable	正向。 有助于减少纯猜测、重复 finding、错误归因和为了 inline 而硬挂无关行
对 pre-existing defect 的处理比绝对禁止更合理	允许在 affected path 中报告 material 的既有 correctness/security/data-loss/reliability 问题，同时强制标 pre-existing	总体正向。 比“不是本 PR 引入就绝不报告”更不容易漏掉高影响问题
未验证仓库假设不能伪装成 finding	repository-specific assumption 无法从 canonical docs/code 验证时，只能作为 question/unverified assumption 放 summary	明显正向。 可以降低 hallucinated finding
当前 diff 本身没有发现产品行为缺陷	两个文件都是 Agent/Copilot 指令 Markdown，没有运行时代码路径改变	如果只按产品回归风险判断，没有发现阻止合并的 runtime blocker

反对或暂缓合并的理由

缺点 / 风险	证据与影响	严重度
本仓库自己要求的 documentation-only 验证尚未完成	docs/pull-request.md 明确要求 Markdown-only PR 做 final-tree fact check、relative-link/actual-anchor、cross-document policy consistency、privacy/sanitization；DOC-MAINTENANCE.md 还要求对 tracked Markdown 做 git-aware 检查。PR 自己也承认完整 scan 未跑，而 CI 不补这个缺口	高：建议合并前补齐
删除 fallback 架构摘要会真实降低部分 Copilot surface 的 degraded-mode 能力	GitHub 当前官方 support matrix 显示：GitHub.com Copilot code review 支持 .github/copilot-instructions.md + AGENTS.md，但 VS Code 的 Copilot code review 只列出 repository-wide .github/copilot-instructions.md，没有列出 AGENTS.md agent instructions。因此这不是纯理论风险：在不直接提供 AGENTS.md 的 review surface，上下文确实会更少。参见 https://docs.github.com/en/copilot/reference/custom-instructions-support	中到高：需要维护者明确接受这个产品取舍
Finding gate 可能把 review 从“规范审查”进一步收窄成“可证明 defect 审查”	现在要求 finding 有 concrete user/developer impact，并明确以 defect 为中心。这会提高 precision，但模型可能因此不再报告某些“违反仓库工程政策、测试纪律或架构约束，但短期影响难以证明”的问题	中：不是必然 bug，但必须确认这就是团队想要的 review 语义
material pre-existing defect 仍存在判断主观性	correctness/security/data-loss/reliability 例子已经比 serious 清楚很多，但“comparably significant impact”和“affected path”仍需要模型判断；允许 pre-existing finding 也会比严格 regression-only review 有更高 scope-creep 风险	中：已有限制，但无法完全消除
Copilot instruction 复杂度增加	.github/copilot-instructions.md 从约 30 行增到约 52 行，并加入 6 条 finding gate。GitHub 自己建议 custom instructions 尽量使用短、self-contained statements；规则越多，模型稳定遵循每一条的把握通常越难。参见 https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions	低到中：需要真实 review 样例验证，而不是只审文字
缺少行为级验证	当前验证主要证明“文档文字看起来一致”；没有看到用几个代表性 PR/diff 对新 finding gate 做 A/B 或 smoke review，例如：普通 regression、静态 race、pre-existing security issue、纯 style/policy violation、无法验证的 repository assumption	中：这次改的是 review agent 行为，行为样例比产品 E2E 更贴题
正式独立 human review 证据不足	当前没有 submitted review/approval；human checked 是 PR 作者的普通 discussion comment	中：对于会影响未来所有 Agent/Copilot review 的 repo-wide policy，最好至少有一位独立 reviewer 明确看过

关于 Copilot fallback 的关键取舍

Surface	GitHub 官方当前列出的支持	本 PR 合并后的影响
GitHub.com Copilot code review	repository-wide instructions + path-specific instructions + AGENTS.md agent instructions	风险较低；AGENTS.md 本身可作为输入
VS Code Copilot code review	repository-wide .github/copilot-instructions.md	删除原来的最小架构 fallback 后，无法假定 review 一定获得 AGENTS.md 的 repo-specific 架构信息；当前新 fallback 会选择主动降级、少做结构性 finding
Copilot cloud agent	支持 repository-wide + path-specific + Agent instructions	与 GitHub.com 类似，owner-routing 设计更容易发挥作用

所以“删除 fallback 摘要”本身不是错误，而是一个真实的能力交换：减少 stale duplicated architecture facts，换取部分 surface 在 canonical instructions 不可用时更弱的 review 能力。 是否值得，应由维护者明确决定，而不是把它当成没有成本的清理。

我的合并建议

决策	建议
现在直接 merge？	默认不建议。 我没有发现产品运行时 blocker，但当前还缺仓库规则明确要求的 documentation-only full verification，而且这次修改的是未来 Agent/Copilot 的 repo-wide review contract，影响面明显大于普通 Markdown 文案
什么条件下我会支持 merge？	至少：① 在可正常 checkout 的环境跑完 DOC-MAINTENANCE.md 要求的 final-tree fact/policy/link 检查，并记录结果；② 有一位独立 reviewer 对这两个文件给出明确 review/approval；③ 维护者明确接受“VS Code 等不保证提供 AGENTS.md 的 surface 会降级”这个取舍；④ 明确确认 finding gate 就是要排除没有 concrete impact 的 style/纯推测/部分 policy-only finding
是否需要继续无限修改文字？	不需要。 目前文字层面的主要矛盾已经基本收敛；下一步价值更高的是补验证和做代表性 Copilot review 行为样例，而不是继续增加更多 policy 文本
如果维护者愿意主动接受剩余风险呢？	在明确接受上述 degraded-mode 和 finding-scope 取舍、并认为完整 doc scan 可作为后续工作时，技术上可以 merge；但这应被记录为“有意识地接受验证缺口/能力取舍”，而不是描述成“已经完全验证、没有剩余风险”

结论：这个 PR 的方向总体是正面的，我没有看到应当因为产品代码正确性而拒绝它的理由；但当前证据不足以支持“无条件直接合并”。最合理的状态是：方向支持 + 合并前补验证/独立审查 + 明确接受 Copilot surface 的降级取舍。