📄 提升 PR 描述规范的可见度，防止代理默认回退到通用模板

[cyfung1031]

Checklist / 检查清单

• Fixes mentioned issues / 已修复或实现
• reviewed by human / 通过人工检查
• Changes tested / 已完成测试

背景

在 #1609 首次提交时，我（代理）未遵循本仓库 docs/pull-request.md 定义的 PR 描述规范，而是使用了通用的 ## Summary / ## Test plan 结构。经用户追问，诚实复盘发现：该规范（AGENTS.md 中的 "Pull Request Description Format" 一节 + docs/pull-request.md）已经存在于我的上下文中——由仓库所有者在 #1601（"明确代理创建 PR 的描述规范"）中于 2026-07-17 添加，就在我创建 #1609 的前一天。我没有资源或信息缺口，只是习惯性地使用了自身工具指令中内置的通用 PR 模板示例，而没有先查阅仓库自己的规范。

对比 AGENTS.md 中另外四条 "Before X, read Y" 提示（写代码前读 develop.md、翻译前读 translation.md、编辑文档前读 DOC-MAINTENANCE.md），PR 描述规范的提示被放在文件末尾、且措辞是被动陈述（"Detailed PR description guidance lives in..."），而非同样醒目的祈使句式，也不与"创建 PR"这一具体动作直接绑定。这种表述方式/位置上的不一致，正是造成本次遗漏的可复现根因——而非规范本身不存在。

本次改动

• AGENTS.md：将 PR 描述规范的提示从文件末尾的独立小节，提升为与其他四条文档提示同级、同样醒目的顶部 "Before X, read Y" 引用块，触发时机明确为"创建/更新 PR 时"。原末尾小节已删除，避免与新增引用块重复陈述同一事实。引用块本身只做指路，不复述 docs/pull-request.md 已有的具体规则或标题示例——权威内容只留一处，减少未来漂移点。
• docs/pull-request.md：
  • 开头新增一句提示：无论使用何种标题，本指南的清单与验证信息要求依然适用——## Summary / ## Test plan 这类标题本身不能豁免这些要求。（初版曾写成"使用通用标题即代表未查阅本指南"，但这是对贡献者流程的推断、无法验证——有人查阅后仍可能选用同义英文标题，也有人可能照抄标题却未真正理解内容；已改为只对可验证的"内容要求"下结论。初版还曾提到该模板"是许多代理工具自身指令中内置的默认示例"，属于无法对照当前分支验证的元评论，已删除。）
  • 补充："其余清单项不适用或未执行时应留空，而非改写文字"——此前该规则只对 "Code reviewed by human" 一项有说明，现推广到整个清单，避免代理为凑格式而勾选不相关项或改写清单文字。（此表述本身也曾有问题：把"不适用"和"未执行"统一为同一个"留空"状态，导致审查者/未来自动化校验无法区分二者——已修正为清单文字不变、未执行留空、不适用则额外在清单下方补一行简短 N/A — <原因> 说明。）
  • 开头段落补回 "preserve its checklist"（保留模板中的 Checklist 小节）这一条此前隐含在示例结构里、但未被明确写出的规则。
• docs/DOC-MAINTENANCE.md：将 docs/pull-request.md 补充进"一次性验证"章节的链接完整性检查清单（此前遗漏）。

已知限制

• 本次改动只能提升该规范在文档中的可见度与触发时机，无法从机制上强制执行——仍然依赖代理在创建 PR 时主动查阅。若未来需要更强的保证，可考虑在 CI 中增加 PR 描述结构的 lint 检查，但这超出本次改动范围。
• docs/DOC-MAINTENANCE.md 的链接完整性检查脚本仍是手工枚举文档列表（本次只是补上遗漏的一项），未来新增文档时仍可能重复此类遗漏；改为自动发现（如 find docs -name '*.md'）是更彻底的修复，但涉及改写一个已在使用的校验脚本，存在误纳入不该检查的文件（如模板文件）的风险，本次未处理。
• docs/pull-request.md 中 "Fixes mentioned issues" 等清单项在某些变更类型下是否适用，仍依赖代理自行判断；已加入"不适用时留空"的通用规则，但未逐项列举适用边界。

建议审查重点

• docs/pull-request.md 新增的"内容要求不因标题而豁免"表述是否足够清晰，是否比初版"标题即信号"的说法更准确、更不容易被误读为标题黑名单。
• AGENTS.md 中新引用块进一步精简后（不再举出具体标题示例），是否仍能让代理准确定位到该做什么。
• 本 PR 描述本身经过多轮基于审查意见的修订（详见下方"验证"）——是否已准确反映当前 diff，而非停留在早期版本的措辞。

关联

• #1609 — 触发本次改动的原始事件（该 PR 首次提交时未遵循 docs/pull-request.md，后经用户指出并已修正描述格式）。
• #1601 — 引入 docs/pull-request.md 及 AGENTS.md 对应小节的原始 PR。

验证

• docs/DOC-MAINTENANCE.md 自带的链接完整性检查脚本（"One-shot verification" 章节的 bash 片段）本地多次执行（每轮改动后），全部链接可解析，无 BROKEN 输出。
• 人工核对 AGENTS.md、docs/DOC-MAINTENANCE.md（所有权表）、docs/README.md（索引）、docs/develop.md（提交/PR 工作流小节）中对 pull-request.md 的引用，确认改动后无重复陈述同一事实、且仅有一处权威提示位置。
• git commit 触发的预提交钩子（lint-staged）因本次改动仅涉及 .md 文件而跳过 JS/TS 相关检查（无相关文件改动）。
• 本 PR 经过三轮独立审查反馈并据此修订：第一轮修正了措辞过度叙述个人经历、未考虑 token 效率的问题；第二轮修正了 "required" 与 docs/pull-request.md 自身 "recommended" 的矛盾表述、标题禁令对具体事件的过拟合、AGENTS.md 与 docs/pull-request.md 之间的重复内容；第三轮修正了 PR 描述本身滞后于最新实现、"标题即信号"这一不可验证的推断、清单不适用项规则缺失的问题；第四轮（本次）修正了第三轮新加的"不适用/未执行留空"规则本身混淆了两种不同审查含义的问题。本 PR 描述本身即按 docs/pull-request.md 规定的结构撰写，并在每轮修订后同步更新，作为本次改动是否达到预期效果的直接验证。

[cyfung1031]

@CodFrm