libpag 仓库技能自检指南：基于 /cr 会话复盘诊断代码审查技能缺陷的完整流程

本文面向在 libpag 仓库中维护 .codebuddy 代码审查技能体系的开发者与 AI Agent，系统讲解如何通过复盘一次完整的 /cr 会话，定位并修复审查技能文件（checklist、判断矩阵、流程指令）自身的缺陷。读完本文，你将掌握"误报、判断错误、流程偏差、其他改进"四类信号的识别方法，以及从会话证据到技能文件编辑落地的完整工作流。

诊断的起点：理解 /cr 技能体系的结构

在 libpag 仓库中，代码审查能力以 .codebuddy/skills/cr/ 技能目录的形式存在，入口文件是 SKILL.md。该技能通过参数路由到不同的审查流程：$ARGUMENTS 为 diag 时进入诊断流程（即本文主题对应的 diagnosis.md）；为 PR 编号或包含 /pull/ 的 URL 时进入 PR 审查（pr-review.md）；在 main/master 分支或环境不支持多 Agent 时进入单 Agent 本地审查（local-review.md）；其余情况进入多 Agent 对抗式审查（teams-review.md），并固定以 FIX_MODE=low_medium 运行——低、中风险问题自动修复，高风险问题（如 API 变更、架构影响）留待用户确认。

诊断流程面向的是这些支撑审查运行的参考文件，主要包括：

文件	职责
code-checklist.md	代码审查检查单：按 A（正确性/安全/结构完整性）→ B（重构与优化）→ C（约定与文档）三级优先级组织
doc-checklist.md	文档审查检查单：同样分 A（准确性）/ B（清晰度与结构）/ C（格式与风格）三级
judgment-matrix.md	判断矩阵：定义风险分级、是否值得修复的判定原则与豁免规则
checklist-evolution.md	检查单演化流程：规定新增条目必须满足的七条约束与三步落地流程
teams-review.md	多 Agent 团队审查：协调者 + reviewer–verifier 对抗式管线的六阶段流程
local-review.md、pr-review.md、bot-review.md	单 Agent 本地审查、PR worktree 审查、CI/CD 机器人审查三种模式

诊断流程的使命，就是保证这套审查体系本身"指得准、查得全、判得稳"。

定位与边界：诊断什么、不诊断什么

诊断的首要原则是目标聚焦：分析最近一次 /cr 会话，找出技能文件自身的缺陷——检查单的覆盖缺口（checklist gaps）、指令的歧义表述（ambiguous instructions）、缺失的排除规则（missing exclusion rules）等。其唯一目的是让技能更准确、更可靠，而不是重新审查项目代码。

这意味着诊断全程只基于会话上下文工作（work entirely from the session context）。只有当你需要确认某条规则的精确措辞、以便提出修改建议时，才允许去读对应的技能文件原文——除此之外，不应扩大检索范围。这条边界同时界定了证据的效力：会话中发生的交互事实才是有效证据，技能文件只作为待修改的目标对象出现。

前置条件：没有 /cr 会话就停止

流程有且仅有一个硬性前置条件：如果当前会话中不存在任何一次 /cr 会话记录，则直接告知用户并停止，不进入分析阶段。这是一个典型的"无输入即退出"守卫，避免在缺乏复盘素材的情况下凭空臆造技能缺陷。

分析：从头到尾扫描整个会话

当确认存在可复盘的 /cr 会话后，进入核心分析阶段。要求是扫描会话的全程（scan the entire session from start to finish），从第一条用户消息到系统通知逐一检查，绝不能在找到第一个问题后就停止——必须穷尽式地核对每一条用户消息和系统通知，防止遗漏。

证据信号：什么最能暴露技能缺陷

会话中以下几类现象是技能缺陷的高价值证据：

• 用户回滚自动修复（rollbacks of auto-fixes）：AI 自动修了某个问题，但用户撤销了修复，说明该问题可能是误报，或修复方式本身不对；
• 用户不得不给出的人工纠正或覆盖（manual corrections or overrides）：技能指令没有覆盖到某个场景，用户被迫亲自干预；
• AI 偏离既定步骤（steps the AI deviated from）：流程要求被跳过、重排或执行错误；
• 用户介入解除卡死（user interventions to unblock a stalled flow）：例如用户主动发问"为什么停下来了？"，或手动提示 AI 继续——这往往指向流程中缺少明确的继续/完成信号。

每一条发现都必须落实到改哪个技能文件、具体改什么（state which skill file to change and what the change should be），即"发现 → 定位文件 → 给出可执行修改"三段式输出。

误报（False positives）

误报指被报告或自动修复、但被用户拒绝、回滚或纠正的问题。这类发现的价值在于反向校准检查单：对每一条误报，要回答"它错在哪里"，并据此判断应该新增、修订哪条检查单项、排除规则或判断矩阵规则，才能让同类问题不再被错误上报。

需要说明的是，检查单体系本身已内置了降低误报的机制，理解它们有助于定位误报根因：

• code-checklist.md 末尾设有排除列表，明确列出 7 类不应上报的问题，例如"格式化工具范围内的纯风格偏好""基于假设的未来需求而非当前代码的建议""对稳定且无正确性问题的代码提出的'更好替代方案'"等；
• judgment-matrix.md 进一步列出反模式清单（Do NOT Fix），包括投机性优化（speculative optimizations）、以教学为目的故意冗长的文档示例被"简化"、以及伪装成 bug 修复的行为变更——这些模式频繁产生误报，除非有确凿证据证明是真实 bug，否则应跳过。

当一次会话中出现误报时，诊断要判断：是检查单项太宽、排除规则缺失，还是判断矩阵的反模式条目没被遵循？据此定位到具体文件。

判断错误（Judgment errors）

判断错误指用户对风险等级或"是否值得修复"的裁决不认同的情况，典型表现包括：用户回滚了一次自动修复，或明确覆盖了一次跳过决定。对每一条，诊断需要记录"会话当时给出的判定 vs 本应有的判定"（what the session assigned vs what it should have been），并据此修订 judgment-matrix.md。

判断矩阵的现行规则是诊断时对照的基准，其中关键定义包括：

• 风险等级按问题逐条评估，而非按类型一刀切——同一类别（如重命名）因影响范围不同可以是低风险或高风险：低风险指只存在一种合理修复方式（空指针检查、修正过时注释、删除死代码等）；中风险指有多种修复方案但不涉及设计决策或外部契约（抽取共享逻辑、合并散落常量、完成未竟的重构）；高风险指涉及设计决策或外部契约（公共 API 变更、测试基线变更、架构重构、引入新依赖、改变持久化格式等）；
• FIX_MODE 与风险等级的处置矩阵：full 模式全部自动修复；low_medium 模式低、中风险自动修复、高风险需确认；low 模式仅低风险自动修复。且无论哪种模式，会改变测试基线（截图对比、golden 文件）的问题一律留给用户确认；
• 是否值得修复的四条决策原则：必须修复（影响运行正确性/安全）、清晰时修复（方案无歧义且不引入新风险）、不一致时修复（违反项目规则或与周边代码既有模式冲突）、永远跳过（纯风格偏好、基于假设的未来需求、对稳定代码的替代式重写）；
• 特例规则：测试覆盖缺口和回归风险只标记不修复，报告给用户知晓；非 bug 修复性质的公共 API 签名变更一律视为高风险。

流程偏差（Flow deviations）

流程偏差指 AI 跳过、重排或错误执行的步骤。对每一条，要指明"哪份文件中的哪一步被违反了，以及如何澄清该指令"。

流程基准分布在各个审查模式文件中，诊断时应逐一核对：

• teams-review.md 定义 Scope → Review → Filter → Fix/Validate → Confirm → Report 六阶段流程，并有多条硬性约束：协调者不得直接修改文件；reviewer 报告必须以原样引用方式逐条转发给 verifier，不得改写、合并或加注释；verifier 默认持对抗立场（adversarial）质疑每条 issue；所有 reviewer 均报告零问题时才可跳过验证；修复必须逐条提交（one commit per fix）且只能改协调者指派文件；验证失败时只能在 fixer 提交中二分定位并回滚，绝不回滚与本轮修复无关的提交；
• local-review.md 定义单 Agent 流程：按 $ARGUMENTS 确定 diff 范围（空参数在 main/master 上只查未提交改动、在特性分支上查 merge-base 至工作树的完整 diff；commit hash 用 git rev-parse --verify 校验；commit range 校验两端点；文件路径先验证存在性），再进入审查、过滤、报告与修复；
• pr-review.md 强调 worktree 模式：必须把 PR 分支拉到本地 worktree 审查，行号从新文件（diff 右侧）实际读取而非从 hunk 偏移推导，提交行级评论必须用 gh api + heredoc，禁用 gh pr comment 等非行级命令；
• bot-review.md 描述 CI/CD 单趟管线：不修复、不批准、不合并，只以行级评论上报问题，并定义了 0/1/2 三个退出码（0=无问题通过，1=发现问题已上报，2=设置或上报失败）。

诊断流程偏差时，重点核对会话中每个动作是否与上述基准一致，例如协调者是否亲自执行了本应派发给 fixer 的修改、verifier 是否在收到全部报告前就给出了终审结论、fixer 是否在一条提交里合并了多个问题等。

其他改进（Other improvements）

此类别收录会话中观察到的、能指向具体技能文件修改的其他任何现象——例如冗余步骤、缺失的护栏（missing guardrails）、措辞不清（unclear wording）。约束是：只有当修改具体且可执行时才纳入（only include if the change is specific and actionable）。泛泛的"流程体验不佳"式观察不属于有效发现，必须能落到"改哪份文件的哪个位置、改成什么"。

一个典型的可纳入项是 teams-review 中"缺失报告检测"机制：如果某 reviewer 的系统通知显示已完成、但协调者未收到其 SendMessage 报告，必须立即跟进索要报告，不能假定报告已丢失（Agent 可能因轮次耗尽而未发出）——这类护栏的存在正是"其他改进"类发现沉淀的结果。

应用：通过多选提交可执行的编辑

分析完成后进入应用阶段（Apply）：凡是能给出具体文件编辑的发现，全部通过多选方式呈现给用户。每个选项的标签是一行对编辑的概括说明（one-line summary of the edit）；用户勾选的编辑被采纳，未勾选的编辑被丢弃；最终应用所有选中的编辑。

这一设计保证了诊断的产出始终是用户裁决过、可追溯的技能文件变更，而非 AI 单方面的改写。结合 checklist-evolution.md 可以看清后续落地的规则——新增检查单项必须同时满足七条约束：用一句断言式短语描述期望状态而非提问；通用性强、不绑定具体变量或函数；原子化（一个条目只关心一个可检查点）；不与现有条目重叠；归入最贴切的现有类别；每个类别保持在 3–8 条；宁少勿滥、优先更宽泛的条目。随后同样经多选确认、按类别与优先级规则插入对应检查单文件。

诊断闭环：从会话缺陷到技能进化

纵观整个流程，诊断并非孤立的一次性动作，而是技能体系自举进化的关键一环：

1. 会话执行：/cr 按路由进入对应审查流程，产出确认问题清单；
2. 技能自检：/cr diag 复盘该会话，从误报、判断错误、流程偏差与改进项四个维度挖掘技能文件缺陷；
3. 检查单演化：确认问题中若存在未被现有检查单覆盖的复现模式，走 checklist-evolution.md 的三步流程（草拟候选条目 → 用户多选确认 → 按规则插入）沉淀为新的检查单项；teams-review 与 pr-review 的收尾阶段均内置了这一步骤；
4. 判断矩阵校准：用户对风险判定不认同的个案回流为 judgment-matrix.md 的修订依据，使后续会话的自动修复阈值更贴合真实意图。

由此，诊断流程保证了 libpag 仓库这套代码审查技能在反复使用中不断收敛误报、补齐盲区、澄清歧义，最终实现"审查技能本身可被审查、可被改进"的自维护闭环。维护者只需在每次会话后运行一次 diag 路由，即可把一次普通代码审查同时转化为一次技能质量的增量升级。