用途:审查本次工作新增的散文内容(注释、docstring、changelog 条目),判断其是否描述代码当前状态,而非叙述产生该改动的过程。权威依据是 AGENTS.md 的“Writing for Future Readers”章节,本技能是其操作化检查。
主要能力:按范围获取 diff 并只审查新增行(^+)中的注释、docstring 及 changelog/*.md 内容,未改动的散文不在范围内。对每个命中项阅读周边代码,判断句子主语是代码还是改动。
使用方式:参数决定审查范围。staged 使用 git diff --cached -U0;branch(默认)使用 git diff $(git merge-base main HEAD) -U0;<path> 使用 git diff $(git merge-base main HEAD) -U0 -- <path>。branch 与 <path> 基于 merge base,覆盖已提交和未提交的工作。
判定标准:应重写或删除描述代码过去行为、对比新旧行为、论证改动正确或记录已验证、列出被否决的替代方案、仅复述相邻代码已显示内容、或使用任务中途才懂的简写的句子。仅当缺失理由会让未来读者困惑时保留理由,并优先陈述约束而非叙述发现过程。不要仅凭“previously”“instead of”“no longer”“used to”等词做模式匹配,应判断句子主语。
Changelog 例外:changelog 条目和 PR 描述是面向用户的发布说明,对比新旧用户可见行为属于其中;但开发过程细节(被否决方案、评审往返、验证叙述、从内部视角描述的重构)不属于。
修复:按情况选择最省成本的落点——未提交直接编辑;已提交未推送单提交用 git commit --amend --no-edit;多提交编辑后提交再用 /squash-commits;提交信息措辞用 git commit --amend -m 或 /squash-commits;已推送无 PR 用 --force-with-lease 强推;changelog 文件随时正常编辑提交;PR 描述用 gh pr edit <pr_number> --body;PR 已在评审中则追加提交,不重写已推送历史。
报告:逐条列出违规的 file:line、原文及修改结果;若散文干净需明确说明,调用方依赖知道检查已运行。
限制:仅审查新增行,未改动散文不在范围;交互式 rebase 不可用。