codex-review-workflow

star 0

Use for structured code review / document review workflows (代码审查/文档审查) with one-problem-one-file tracking, filename-driven state transitions, duplicate detection and issue reopening for any-status items, and acceptance-criteria validation.

alone-wolf By alone-wolf schedule Updated 3/1/2026
play_arrow Run Skill in Manus View GitHub

name: codex-review-workflow description: Use for structured code review / document review workflows (代码审查/文档审查) with one-problem-one-file tracking, filename-driven state transitions, duplicate detection and issue reopening for any-status items, and acceptance-criteria validation. metadata: version: "2.2" language: zh-CN scope: - 项目代码审查 - 文档审查 - 架构优化 - 重构 - 安全整改 - 性能优化

Codex Review Workflow

一、行为总原则

你在参与项目开发时，必须遵循“结构化记录 -> 用户确认 -> 执行修改 -> 基于验收标准验证 -> 状态更新 -> 归档管理”的闭环机制。

在未获得用户明确确认前，不得擅自修改代码或文档。

所有问题必须形成可追踪记录。

所有修改必须通过验收标准验证。

当前约定 <repo_root>/docs_issue/ 不使用子目录；重复检查与编号扫描仅针对该目录第一层文件。

二、问题发现与分析阶段

当对项目代码或文档进行 Review 时：

  1. 先确认本轮 Review 范围（模块、目录、文档集、目标变更）。
  2. 若 <repo_root>/docs_issue/ 不存在，必须先创建该目录。
  3. 按“代码分析维度”和“文档分析维度”逐项检查并记录证据。
  4. 创建新问题前，必须在 <repo_root>/docs_issue/ 第一层文件中做重复检查（先看文件名摘要，再看文件内容）。
  5. 若已存在同一问题（任意状态），不得新建文件；应更新原文件并按需要调整状态。
  6. 只有确认是新问题时，才可新建问题文件。
  7. 一个问题必须且只能对应 <repo_root>/docs_issue/ 中一个文件。
  8. 新建问题文件时，必须基于模板 skills/codex_review_workflow/assets/problem-file-template.md 生成初始内容。

代码分析至少覆盖以下维度：

  1. 功能正确性（逻辑、边界条件、异常路径）。
  2. 安全性（鉴权、输入校验、敏感数据处理、依赖风险）。
  3. 性能与资源（时间复杂度、IO/网络、内存、并发争用）。
  4. 可维护性（可读性、重复代码、模块边界、可测试性）。
  5. 配置与发布风险（环境差异、默认值、回滚可行性）。

文档分析至少覆盖以下维度：

  1. 准确性（与当前代码行为、接口、版本一致）。
  2. 完整性（前置条件、步骤、异常处理、限制条件齐全）。
  3. 一致性（术语、命名、路径、示例参数前后一致）。
  4. 可执行性（步骤可复现，命令可运行，预期结果可验证）。
  5. 可维护性（结构清晰、可定位、更新成本可控）。

每个问题文档必须包含以下固定结构：

  1. 问题 ID
  2. 当前状态（必须与文件名中的 status 一致）
  3. 最后更新时间（格式：YYYY-MM-DD HH:MM ±HH:MM）
  4. 问题标题
  5. 问题摘要（应与文件名中的摘要一致）
  6. 问题描述：清晰说明问题的现象与表现。
  7. 严重程度：可选值 Critical / High / Medium / Low。
  8. 影响对象（受影响模块/接口/文档/用户范围）。
  9. 问题原因：对问题产生原因的技术分析。
  10. 核心证据路径（用于去重判定）。
  11. 待确认差异（仅在“同一问题”判定不明确时填写）。
  12. 造成问题的证据：包含代码路径、日志、行为描述、配置位置等客观证据。
  13. 影响：说明对功能、性能、安全、维护成本的影响。
  14. 建议解决方案：描述技术方向或实施步骤。
  15. 验收标准：必须使用可验证表达式编写。
  16. 评论：预留一行，由用户填写处理意见。
  17. 状态变更记录

模板位置：

  • skills/codex_review_workflow/assets/problem-file-template.md

“独立问题”拆分规则（用于判断是否应拆成多个问题文件）：

  1. 用户可见行为不同，必须拆分。
  2. 根因不同，必须拆分。
  3. 修复路径不同（涉及不同模块或不同负责人），必须拆分。
  4. 验收标准不能共用，必须拆分。
  5. 同一问题在多处重复出现，可合并为一个问题文件，但必须列出全部证据位置。

判定优先级：

  1. 先应用“独立问题”拆分规则。
  2. 仅当不满足“必须拆分”条件时，才应用“同一问题”判定标准。

“同一问题”判定标准（用于去重）：

  1. 以下三项中至少两项一致，视为同一问题：根因、影响对象、核心证据路径。
  2. 若已有任意状态的问题文件且当前现象与其描述一致，优先复用原文件并更新状态，不得新建。
  3. 若无法判断是否同一问题，先在原最相近文件中追加“待确认差异”，并等待用户确认后再决定是否拆分新文件。

生成问题文件后，你必须停止执行并等待用户响应。

三、文件命名即状态机（强制）

所有问题文件必须放在 <repo_root>/docs_issue/，并使用以下命名格式：

<status>__<issue_id>__<summary>.md

字段规则：

  1. status：只能使用以下值之一：waiting_user、approved、in_progress、verifying、resolved、deferred、rejected、archived。
  2. issue_id：必须使用 QYYYYMMDD-序号，例如 Q20260301-01。
  3. summary：问题浓缩描述，必须简短明确，长度 6 到 24 个字符（按 Unicode 字符数计，不按字节计）。
  4. summary：仅允许中文、英文、数字、短横线 -，禁止空格与其他特殊符号。

issue_id 分配规则（强制）：

  1. 先扫描 <repo_root>/docs_issue/ 第一层现有文件，提取同日期 YYYYMMDD 的最大序号。
  2. 新建问题必须使用“最大序号 + 1”作为新序号，序号至少两位，不足左侧补 0；超过 99 时按实际位数扩展（例如 100、101）。
  3. 若并发或冲突导致同名，必须重新扫描后再分配，不得手动跳号或复用已存在 ID。
  4. 若扫描到历史文件名异常而无法可靠解析序号，必须暂停并等待用户确认后再继续，不得自行猜测序号。

命名示例：

waiting_user__Q20260301-01__接口鉴权头缺失.md

强制执行规则：

  1. Codex 在处理任一问题前，必须先从文件名读取当前状态。
  2. 状态变更时，必须通过重命名文件更新状态，不允许只改正文不改文件名。
  3. 新建问题文件时，status 必须设为 waiting_user。
  4. 除非用户明确要求，issue_id 与 summary 不得在流转中变更。
  5. 若 summary 需修订，必须保持 6 到 24 个字符并同步更新正文“问题摘要”字段。

命名校验失败处理：

  1. 文件名中的 status 是唯一真值来源。
  2. 若发现文件名不符合命名格式或文件名状态与正文“当前状态”不一致，必须先修正文件名，并将正文“当前状态”对齐到文件名后再继续执行流程。
  3. 修正动作必须写入“状态变更记录”并更新“最后更新时间”。
  4. 若文件名严重损坏且无法解析出合法 status，必须暂停并等待用户确认后再继续，不得自行推断状态。

四、用户确认阶段

用户会在问题文档的“评论”字段填写处理意见，例如：

  • 同意修复
  • 修改方案
  • 暂不处理
  • 拒绝

用户明确告知可以继续后，你才可进入执行阶段。

若用户未给出额外指令，默认按照建议方案执行。

五、执行阶段

进入执行阶段后，你必须：

  1. 读取对应问题文档。
  2. 解析“建议解决方案”与“评论”。
  3. 制定修改计划（涉及文件、改动策略、风险点、验证命令）。
  4. 执行代码或文档修改。

修改必须保持最小影响原则，避免引入新的问题。

若执行中发现问题信息不足或与现状不符，必须先回写问题文档（补充证据/调整方案），再继续执行。

六、强制质量验证阶段

修改完成后，必须执行一次独立的质量检查。

该步骤为强制步骤，不得跳过。

执行流程：

  1. 逐条读取问题文档中的“验收标准”。
  2. 为每条标准绑定至少一个验证动作（命令、测试、静态检查、人工可复现步骤）。
  3. 确认全部满足后方可标记为已解决。
  4. 若任一标准未满足，必须继续修正直至通过。

验证动作选择顺序（按优先级）：

  1. 项目已有自动化命令（CI、测试脚本、lint、build）。
  2. 针对问题场景的最小复现验证（含输入、步骤、预期输出）。
  3. 静态检查或人工验证（仅当自动化不可用时）。

文档-only 场景规则：

  1. 若问题仅涉及文档且不包含代码、配置或脚本变更，可对构建、单元测试、性能等不适用项直接标记为 N/A。
  2. 所有 N/A 项必须在“验证记录”中写明原因与替代检查动作（例如：文档步骤复现、示例命令核对、链接可用性检查）。

当仓库缺少自动化测试时，必须在问题文档中明确记录：

  1. 为什么无法自动化验证。
  2. 采用了哪些替代验证动作。
  3. 剩余风险是什么。

验证内容包括但不限于：

  • 构建是否成功
  • 是否产生新的警告
  • 单元测试是否通过
  • 是否覆盖问题场景
  • 是否满足性能指标
  • 是否未引入副作用

只有全部验收标准通过，才允许进入状态更新阶段。

七、验收标准编写规则

当你生成问题文档时，必须保证验收标准符合以下原则：

  1. 可验证：必须可以通过客观方式判断是否达成。
  2. 可测量或可检查：优先使用可测试、可编译、可扫描、可运行验证的表达方式。
  3. 有明确完成边界：必须可以判断“完成”或“未完成”。
  4. 与解决方案分离：解决方案描述做什么；验收标准描述完成后应满足什么状态。
  5. 尽量支持自动化：优先使用可由 CI、测试、静态分析工具验证的标准。

禁止使用模糊表达，例如“更加清晰”“明显提升”等。

八、状态更新阶段

通过验收后，必须更新状态。

状态更新规则：

  1. 先确认目标状态是否合法。
  2. 通过重命名问题文件更新 status 字段（状态机规则以“第三节 文件命名即状态机”为唯一准则）。
  3. 同步更新文档正文字段：当前状态 与 最后更新时间。
  4. 在文档正文追加状态变更记录（时间、原因、操作者、关联提交）。
  5. 保持 issue_id 与 summary 稳定，不得随意改动。

文档维护规则：

  1. 只要问题文档任一正文字段发生变更（包括补充证据、调整方案、更新评论、记录验证结果），都必须同步更新“最后更新时间”。

时间字段规则：

  1. 最后更新时间 与 状态变更记录 中的时间，必须统一使用 YYYY-MM-DD HH:MM ±HH:MM。

状态更新示例：

in_progress__Q20260301-01__接口鉴权头缺失.md
-> verifying__Q20260301-01__接口鉴权头缺失.md
-> resolved__Q20260301-01__接口鉴权头缺失.md

九、Deferred 机制

若问题被标记为“暂不解决但保留记录”：

  1. 将问题文件重命名为 deferred 状态。
  2. 在原问题文档内补充延期原因、延期时间、下次复审时间（可写 TBD）。
  3. 后续若问题重新进入处理，必须从现有 deferred 文件恢复流转，不得新建重复问题文件。

十、Archived 机制

当问题进入 archived 状态时：

  1. 仅通过文件重命名将 status 更新为 archived。
  2. 文件必须保留在 <repo_root>/docs_issue/，不得移动到其他目录。
  3. 归档后若需重新处理，必须复用原文件并改回 waiting_user，不得新建重复问题文件。

十一、状态流转模型

  • waiting_user
  • approved
  • in_progress
  • verifying
  • resolved
  • deferred
  • rejected
  • archived

状态流转条件：

  1. waiting_user -> approved：用户在评论中明确“同意修复”或给出可执行修改方案。
  2. waiting_user -> rejected：用户明确拒绝处理。
  3. waiting_user -> deferred：用户明确“暂不处理”。
  4. approved -> in_progress：开始实际修改。
  5. approved -> deferred：执行前用户改为“暂不处理”。
  6. approved -> rejected：执行前用户改为“拒绝处理”。
  7. in_progress -> verifying：修改完成，进入验收验证。
  8. in_progress -> deferred：执行中因外部约束需延期，且用户确认暂缓。
  9. in_progress -> rejected：执行中用户明确终止处理。
  10. verifying -> resolved：全部验收标准通过。
  11. verifying -> in_progress：任一验收标准失败，需要继续修正。
  12. verifying -> deferred：验证阶段因外部约束需延期，且用户确认暂缓。
  13. deferred -> waiting_user：问题被重新提起，等待新的用户确认。
  14. resolved -> waiting_user：已解决问题被重新提起，恢复待确认状态并继续在原文件流转。
  15. rejected -> waiting_user：已拒绝问题被重新提起，恢复待确认状态并继续在原文件流转。
  16. resolved/rejected/deferred -> archived：记录归档完成。
  17. archived -> waiting_user：归档问题被重新提起，恢复待确认状态并继续在原文件流转。

复开重命名示例：

  1. resolved__Q20260301-01__接口鉴权头缺失.md -> waiting_user__Q20260301-01__接口鉴权头缺失.md
  2. rejected__Q20260301-02__文档示例参数过期.md -> waiting_user__Q20260301-02__文档示例参数过期.md
  3. archived__Q20260301-03__重试机制边界未覆盖.md -> waiting_user__Q20260301-03__重试机制边界未覆盖.md

十二、核心约束

  1. 不得跳过用户确认。
  2. 不得跳过验收验证。
  3. 所有修改必须可追溯到问题文件。
  4. 每个问题只能对应 <repo_root>/docs_issue/ 中的一个文件。
  5. 提出新问题前必须做重复检查，已存在问题不得重复建档。
  6. 状态流转与命名更新必须遵循第三节“文件命名即状态机（强制）”。
  7. 文件名中的问题摘要必须遵守长度限制（6 到 24 个 Unicode 字符）。
  8. 延期与归档流转遵循第九、十节，且不得复制到其他聚合清单文件。
  9. 新建问题文件必须使用标准模板并保留“状态变更记录”区块。
  10. issue_id 必须按规则自动分配并确保唯一，不得手工指定已存在 ID。

Skill 目标

  • 所有问题有记录
  • 所有修改有依据
  • 所有修复可验证
  • 所有延期可追踪
  • 整个过程具备审计能力
Install via CLI
npx skills add https://github.com/alone-wolf/codex-review-workflow --skill codex-review-workflow
Repository Details
star Stars 0
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
alone-wolf
alone-wolf Explore all skills →