Document independent review workflow

2026-09-17 14:03:58 +08:00
parent f2443a4855
commit 9901bca1ec
3 changed files with 101 additions and 8 deletions
@@ -1,11 +1,12 @@
 # Coding Skills

-两个中文工程 skill，用精简的当前决策保持目标一致，并将规划与实施放在不同会话。
+三个中文工程 skill，用精简的当前决策保持目标一致，将规划、实施与独立审查放在不同会话。

 | Skill | 用途 | 产出 |
 | --- | --- | --- |
 | `align-plan` | 调查代码、每轮提问 1–3 个问题、核对假设并收敛范围 | 系统约束、当前决策与用户确认后的可执行计划 |
 | `execute-plan` | 按已确认计划实施、验证、核对范围和 review | 外部实施记录与本地 Git commit |
+| `review-changes` | 对比当前分支与最新远程 master，审查原始目标、行为偏差及旧功能回归 | 外部审查报告，不自动修复 |

 ## 安装

@@ -17,11 +18,11 @@
 npx -y skills add ssh://git@gitea.fjy8018.top:8022/fjy8018/coding-skills.git --skill '*'
 ```

-需要已配置可访问该仓库的 SSH 密钥。两个 skill 也可单独安装，将 `'*'` 替换为 `align-plan` 或 `execute-plan` 即可。安装时由 CLI 选择目标 agent。
+需要已配置可访问该仓库的 SSH 密钥。三个 skill 也可单独安装，将 `'*'` 替换为 `align-plan`、`execute-plan` 或 `review-changes` 即可。安装时由 CLI 选择目标 agent。

 ## 使用

-两个 skill 仅在用户明确调用时启用。Codex 中可使用 `$align-plan`、`$execute-plan` 或通过 skill 选择器调用；普通“规划方案”“执行任务”请求不自动启用。
+三个 skill 仅在用户明确调用时启用。Codex 中可使用 `$align-plan`、`$execute-plan`、`$review-changes` 或通过 skill 选择器调用；普通规划、执行或审查请求不自动启用。

 在项目目录中开始规划，例如：

@@ -58,9 +59,27 @@ Codex 默认根据 `description` 隐式选择 skill；本仓库在每个 skill

 测试从原始目标推导正常、边界、异常及保留行为场景，预期结果独立于实现，确保能发现目标偏离；不为覆盖变更代码而堆用例。

+### 独立审查
+
+建议新开会话，在被审项目中直接提供原始需求，或指定含目标的文档：
+
+```text
+$review-changes 审查当前分支。
+原始目标：修复订单查询的分页重复问题，保留现有接口格式及排序语义。
+报告放到 /绝对路径/工程讨论/2026-09-10-pagination-fix。
+```
+
+也可指定 `plan.md`，但仅定向提取目标、验收和保留行为，不读取实施步骤、修改清单、执行记录、实施总结或既有审查结论。内容混排无法可靠分离时会询问目标摘录；缺少目标不妨碍独立代码检查，但不能宣称目标达成。此 skill 可独立使用，`execute-plan` 不自动调用它；已有上下文不能假称已清除。
+
+默认获取 `origin` 的最新 `master`，也可指定其他远程。固定远程提交、HEAD 和共同祖先，以共同祖先到 HEAD 审查分支增量，另检查 master 后续变化的兼容影响，不把远程新增误判为本分支删除。只审查已提交内容，排除并说明工作区修改，必要验证使用隔离快照。获取失败或基线不明时会报告限制，不静默换用旧缓存或其他分支。
+
+重点比较既有逻辑修改、删除、移动及插入新增行的前后行为、目标依据和旧功能影响，同时检查新实现是否真实接入。审查覆盖候选问题反证、实际依赖契约、逻辑分叉、替换遗留及测试有效性；不以测试数量或通过结果代替充分验证。
+
+报告保存为外部 `review-YYYYMMDD-HHmmss.md`，包含目标达成与偏差、已确认问题、关键验证缺口、基线及实际验证结果，对话给摘要和链接。可复用已有资产定位，位置缺失时询问，不回退代码库。允许获取远程引用和必要验证，不修改被审代码、计划或门禁，不自动修复、提交或推送。
+
 ## 资产约定

-首次未指定资产目录时会询问；之后从项目 `.agent/MEMORY.md` 复用。这个文件只保存必要定位信息，通过 Git 本地 exclude 排除，不修改项目共享 `.gitignore`。已被跟踪时会先报告冲突，不自行取消跟踪。
+规划与实施首次未指定资产目录时会询问；之后从项目 `.agent/MEMORY.md` 复用。这个文件只保存必要定位信息，通过 Git 本地 exclude 排除，不修改项目共享 `.gitignore`。已被跟踪时会先报告冲突，不自行取消跟踪。独立审查只读取已有定位，不维护 MEMORY 或 CONTEXT。

 讨论资产严格使用用户选择的代码库外部目录，可按计划建立一层子目录，不添加项目名或系统名中间层。用户已指定本次计划目录时直接使用：

@@ -71,6 +90,7 @@ Codex 默认根据 `description` 隐式选择 skill；本仓库在每个 skill
    current.md                   当前目标、确认决策、约束与未决问题
    plan.md                   最新自包含计划，原地修订、审阅确认
    execution-日期时间.md         实施与验证记录
+    review-日期时间.md            独立审查报告
 ```

 每个计划目录只维护 plan.md，修订直接覆盖，只保留最新方案，不生成版本副本或历史方案。实质修订清除旧批准依据并标为待确认，用户重新审阅后再执行。对话只给摘要和链接，写入成功不代表批准。current.md 同样只维护当前讨论状态，不累计历史。目录失效或无法写入时会报告，不自行改存代码库。个人绝对路径不写入可分发的 skill。
@@ -81,7 +101,7 @@ Codex 默认根据 `description` 隐式选择 skill；本仓库在每个 skill

 该文件不记录任务清单、实现代码、日志或完整历史。`current.md` 保留本次讨论与未决问题；计划保留本次相关约束的快照，执行记录保存进度和证据。CONTEXT 不存在时从首次确认的长期约束开始建立，不回扫历史计划。执行 agent 的局部实现选择不自动变成系统约束。

-每份生成的 Markdown 资产（包括本地 MEMORY）顶部保留以下 YAML 元数据：
+每份生成的 Markdown 资产（包括本地 MEMORY 和审查报告）顶部保留以下 YAML 元数据：

 ```markdown
 ---
@@ -91,7 +111,7 @@ Codex 默认根据 `description` 隐式选择 skill；本仓库在每个 skill
 ---
 ```

-系统填写项目或系统名称，目标概括对应计划的目标，无法确定时留空。时间对应资产所依据的决策，使用用户当地日期。未确认草稿先记创建日期，正文标明待确认；确认后更新为确认日期。计划重新批准后使用新确认日期；实施记录沿用计划决策日期，执行时间单独记录。纯进度或排版更新不改决策日期。
+系统填写项目或系统名称，目标概括对应计划的目标，无法确定时留空。规划与实施资产的时间对应资产所依据的决策，使用用户当地日期。未确认草稿先记创建日期，正文标明待确认；确认后更新为确认日期。计划重新批准后使用新确认日期；实施记录沿用计划决策日期，执行时间单独记录。纯进度或排版更新不改决策日期。审查报告的时间使用用户当地审查日期，目标对应被审变更的原始目标。

 CONTEXT 的目标填写“保存系统当前业务与技术约束”，时间为最近一次确认系统决策的日期；普通排版更新不修改该日期。

@@ -105,12 +125,14 @@ Markdown 正文使用带语言标记的代码块包裹代码、命令和多行
 npx skills add . --list
 ```

-预期仅发现 `align-plan` 和 `execute-plan`。若已安装 skill-creator，可用其 `scripts/quick_validate.py` 分别检查两个 skill 目录；它是开发期检查工具，不是安装或运行依赖。
+预期发现 `align-plan`、`execute-plan` 和 `review-changes`。若已安装 skill-creator，可用其 `scripts/quick_validate.py` 分别检查三个 skill 目录；它是开发期检查工具，不是安装或运行依赖。各目录的 `agents/openai.yaml` 均应保留显式调用策略。

 行为检查应使用真实 agent 在隔离项目中演练：目录首次询问与复用、错误假设纠正、长对话恢复、目标分阶段、批准前不实现、新会话交接、必要配套文件与范围扩展的区别、过期计划、测试覆盖与重复、已有用户修改及提交隔离。

 系统上下文还需检查：首次无 CONTEXT、下次直接读取、无实施依赖的确认规则直接记录、待实施方案只留计划、冲突澄清、执行失败不改当前约束、验证后替换废弃规则、局部实现细节不写入系统约束。

+独立审查需检查：远程领先不误报删除、未提交内容不混入、获取失败不声称最新、目标缺失不推断完成、混排文档不泄漏实施内容；旧功能回归、删除逻辑、未接入实现和弱断言能进入审查，已有保护、合法兼容分支和无关历史问题不被误报。报告须分离缺陷与验证缺口，不引用实施结果作证明、不修改被审代码。
+
 结构验证只能检查格式和可发现性；静态场景复核只能发现指令缺口。两者都不证明模型实际遵循工作流，实际行为需要另行记录演练证据。不要把文字规则当作宿主级权限隔离。

 ## 参考来源
@@ -125,4 +147,4 @@ npx skills add . --list

 另外参考 [domain-modeling](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md) 在讨论中持续沉淀的机制。上游 CONTEXT 限于术语表、设计决策另存 ADR；本项目按需要将当前业务与技术约束直接保存在外部 CONTEXT，不引入 ADR 框架。

-上游工作流会变化；本仓库的实际规则以两个 `SKILL.md` 为准。
+上游工作流会变化；本仓库的实际规则以三个 `SKILL.md` 为准。
@@ -0,0 +1,69 @@
+---
+name: review-changes
+description: 仅用户指定 review-changes 时启用；对比当前分支与最新远程 master，审查原始目标达成、行为偏差及旧功能回归，输出报告，不自动修复。
+---
+
+# 审查分支变更
+
+完成条件：固定审查基线，检查主要行为变化与回归风险，对候选问题完成反证核查，保存包含目标判断、问题和验证缺口的报告。不能在首次浏览或发现第一个问题后结束，也不为凑数找问题、无新证据反复检查。
+
+仅审查，不修复、不提交、不推送，不修改被审代码、原计划或质量门禁。允许获取远程引用、运行必要验证及写入外部报告；实验或需写入文件的验证在隔离快照中进行，避免影响用户工作区，不执行有实际外部副作用的验证。不要求先运行其他 skill，不自动调用规划或实施流程，不强制多代理编排。
+
+## 原始目标与信息边界
+
+- 用户可直接提供原始需求，或指定含目标的文档。从原始需求、已确认验收、保留行为和不做事项判断应该发生什么；不从实现或同次新增测试反推目标。
+- 需要从 `plan.md` 提取目标时，先仅定位 Markdown 标题，再定向读取目标相关章节或片段，不整份加载。只提取需求、行为契约及必要约束，不读取实施步骤、文件修改清单、执行记录、实施总结或既有审查结论。目标与实施内容混排且无法可靠分离时，请用户提供目标摘录，不为找目标展开整份资料。
+- 可从 `.agent/MEMORY.md` 读取资产定位，按需读取适用的项目规范及 `CONTEXT.md` 中当前有效的业务、技术约束；不扫描历史计划或执行资产。约束与原始需求冲突时报告冲突，不用实施后更新的约束替代原始目标。
+- 目标缺失或冲突时询问，期间可继续独立代码检查；没有可靠目标时标为无法判断，不编造需求、改动原因或达成结论。
+- 推荐用户在新会话调用。若当前上下文已有实施过程或结果，说明无法清除，不能将其作为审查证据或假称独立隔离。
+
+## 固定 Git 范围
+
+- 记录仓库、当前分支、HEAD，以及暂存、未暂存、未跟踪状态。默认只审查固定 HEAD 的已提交内容，列明排除的工作区修改；从提交快照读取代码、配置和测试，避免把工作区内容混入判断。
+- 使用用户指定远程，否则使用 `origin`；不存在或指向不明确时询问，不猜其他远程。获取该远程的最新 `refs/heads/master`，成功后立即固定其提交 ID 与获取时间。例如可用 `git fetch --no-tags <远程> refs/heads/master`，随即以 `git rev-parse FETCH_HEAD` 固定远程提交；后续均使用固定 ID，不依赖会变化的引用。
+- 找出远程提交与 HEAD 的共同祖先，以共同祖先到 HEAD 的 diff（含重命名识别）审查分支增量；另检查共同祖先到远程 master 的后续变化与本次变更的交集、调用契约和兼容影响。不能把远程新增而分支未同步的内容误报为本分支删除。
+- 获取失败、远程无 master、历史不足或共同祖先不唯一/不可确定时，明确受限范围；可继续不依赖该信息的检查，但不得静默改用缓存、其他分支或任意祖先，也不得声称已比较最新基线。不为审查执行 pull、merge 或 rebase。
+- 必要测试使用固定 HEAD 的隔离快照，尤其不能在存在未提交修改的工作区测试后声称 HEAD 已通过。涉及远程后续变化的集成验证也在隔离环境进行；未做集成验证则注明证据限制。结束时核对 HEAD 是否变化，变化后报告仍明确针对原固定提交。
+
+## 行为变化与回归
+
+以变更为中心，沿具体风险扩展到调用方、被调用方、配置、注册、数据和相关测试，不进行无关全仓库审计。
+
+- **既有逻辑优先**：对既有文件中的修改、删除、移动和插入的新增行，比较改动前后行为，分析与目标的关系、必要性、旧行为及错误路径是否保持。不能只看 diff 中的加号行，也不能把纯移动误当成新功能。原因有需求或契约依据才作结论，否则标为待确认。
+- **新增实现**：检查真实入口和调用链是否接入，注册、配置和依赖是否有效，不能用“文件存在”或直接调用新函数的单测代替集成证据。
+- **正确性与维护风险**：按实际变化核查边界、状态迁移、错误传播和资源生命周期；关注同一业务规则的独立实现是否产生偏差、替换后是否留下可达的旧实现或无用配置。先查真实引用、动态注册和兼容用途，不因名字陈旧或一次搜索无引用判定死代码。
+- **规范与依赖**：核实符号、配置和第三方 API 是否存在，按实际解析版本核查契约；本地证据不足时查对应版本的官方文档，不凭记忆或用最新版语义否定旧版合法行为。规范和设计问题须有明确适用规则或具体后果，不报告个人风格偏好。
+- 只将本次引入、加重或变得可达的问题列为本次发现，包括被本次替换遗留的实现；无关历史债务不展开。
+
+## 测试证据与候选问题裁决
+
+- 从原始目标和保留行为选择正常、边界、异常、旧功能回归场景；并发、重试、部分成功、恢复等只在相关时检查，不机械遍历清单或追求覆盖率数字。
+- 阅读测试真实调用与关键断言，判断有意义的实现错误是否会使测试失败。关注复制生产算法计算预期值、只断言 mock 返回值、关键业务语义被替换、仅覆盖成功路径及无依据更新快照。
+- 核查本次是否弱化断言、扩大 skip/exclude、改变测试发现范围或让 CI 忽略失败。声称已有覆盖须指出具体测试和断言；声称通过须有本次实际执行结果，并确认目标测试确实运行。既有实施记录不作为执行证据。
+- 报告候选问题前，核对具体触发条件、真实可达路径、违反的契约、后果及与变更的因果关系，主动检查调用方保护、其他层处理、有意设计和合法例外。静态证据链充分时不强制制造失败；需要复现时在隔离环境做最小反例，不自动修复。
+- 合并同一根因。区分已复现、静态确认、待验证；未证实的怀疑不能进入已确认问题。测试缺口说明具体未保护的行为和已有断言为何不足，不能冒充已发生的运行时缺陷。
+
+## 保存报告与交付
+
+复用用户指定的外部位置或已知资产定位；已有本次计划目录则将报告放在其中，否则用已知资产根目录，不从计划父目录猜测根目录，不扫描目录内的执行结果。位置缺失时询问，同时继续只读调查。位置不可用时报告保存阻碍，不回退代码库、不宣称已保存，也不因写入失败隐去已确认问题。
+
+保存独立的 `review-YYYYMMDD-HHmmss.md`，避免覆盖既有报告，使用用户当地审查时间。顶部沿用元数据，未知字段留空，特殊值加引号：
+
+```yaml
+---
+系统: 系统名称
+时间: YYYY-MM-DD
+目标: 本次审查对应的原始目标
+---
+```
+
+正文保持紧凑，包含：
+
+1. **目标达成与偏差**：按原始行为要求说明已满足、未满足或无法判断及证据，列明越界行为、旧功能影响和目标来源；不评价实施步骤是否照做。
+2. **已确认问题**：按严重程度排序。每条给出类型（行为缺陷、规范违例或重要设计问题）、严重度、证据状态、文件与最小相关行范围、触发条件、依据、后果、证据和最小修正方向。删除内容标注旧侧位置及基线，不能编造 HEAD 行号。
+3. **关键验证缺口**：具体未证明的行为、已有验证不足的原因、待核实条件及建议验证方式，与已确认缺陷分开。
+4. **范围与实际验证**：仓库、远程、获取时间、远程 master/HEAD/共同祖先 ID、排除的工作区内容、远程后续变化影响、实际命令和结果、未验证部分及上下文限制。
+
+使用代码围栏表示命令和多行配置，来源引用注明出处；不粘贴完整日志。无发现时明确“在已审查范围和已执行验证中未发现需要报告的问题”，不等同于目标全部达成或可放心上线。确认报告可读后，对话给出目标判断、重要问题与验证限制的简短摘要及文件绝对路径链接。
+
+修复后的复审聚焦修复 delta、原问题和受影响行为；重新获取并固定基线，若远程或目标变化则核查其影响，不自动沿用旧通过结论，不读取旧报告作为新结论依据。
@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false