企业官网建设流程全解析

Repomix 项目中的 Codex 迭代式代码审查闭环：codex-review-loop 工作流完全指南

【免费下载链接】repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix

导读

本指南围绕 Repomix 仓库中的命令文档 .agents/commands/code/codex-review-loop.md 展开，系统讲解如何用 OpenAI Codex 作为评审 Agent，对当前分支相对main的改动执行"审查—分流—修复—验证—复审"五步闭环（最多 3 轮迭代）。读完本文，你将掌握该工作流每一步的落地细节（Triage 的 Fix/Skip 分类、最小化修复原则、npm run lint与npm run test的真实校验内容、只复审新改行的边界控制），并能对照仓库内 6 个专业 Reviewer Agent 定义，把同样的闭环方法论迁移到自己的项目里。

一、工作流全景：一个可重复的 5 步闭环

codex-review-loop命令定义的是一条针对"当前分支相对main的改动"的迭代式审查与修复流程，核心是一个最多执行 3 次的循环：

1. Review（审查）—— 派生出 Codex Reviewer Agent；
2. Triage（分流）—— 开发者亲自过滤 Agent 的发现，只保留自己也认为值得注意的项，并逐一归类为Fix（明确缺陷，必须修复）或Skip（风格、吹毛求疵、范围蔓延）；
3. Fix（修复）—— 只修复标为 "Fix" 的项，且保持修改最小；
4. Verify（验证）—— 执行npm run lint与npm run test，修复回归并使所有检查通过后再继续；
5. Re-review（复审）—— 只针对新改动的代码行重新审查，不再重复提出已被跳过的项。

循环终止条件二选一：没有剩余的 "Fix" 项，或达到 3 次迭代上限。最终打印一份总结，说明"修复了什么、跳过了什么"。

这条流程的本质是"让 Agent 穷尽报告、让人来做最终裁决"——它刻意把"发现问题"与"决定改什么"两个职责分离，避免 AI 自行大改代码导致不可控的范围蔓延，同时用main作为基线确保审查范围始终聚焦在本次分支改动上。

二、Review 阶段：派生 Codex Reviewer Agent

第一步是让 Codex 以"评审者"身份介入。命令原文是Spawn codex reviewer agent——即在 Codex CLI 中派生一个专门负责审查的 Agent 会话，输入当前分支相对main的 diff，让它产出审查报告。

该命令本身采用单 Agent 模式（一条 codex-review-loop 命令对应一个 Codex Reviewer）。与之对照的是仓库中的姊妹命令 review-loop.md：后者同时派生6 个专业 Reviewer Agent 并行审查，覆盖代码质量、安全、性能、测试覆盖、规范、整体架构六个角度，对应 .agents/agents/ 下的 6 份定义文件：

如果想让 codex-review-loop 走"单 Agent 但多视角"的路线，可以直接复用 reviewer-code-quality.md 的评审框架作为 Codex Reviewer 的提示词底子。该文件中确立的两条关键约定值得沿用：

• 不预过滤（Do not pre-filter）：Agent 必须报告每一个有具体证据的发现，并标注严重级别（Critical / High / Medium / Low）与置信度（High / Medium / Low）。理由写得很直白——"你压下的发现会永久丢失，而编排者拒绝一条发现只浪费一行"。低置信度的发现也要报告，只是附上"它依赖什么假设"。
• 输出结构化：每条发现包含 Location（文件与行/函数）、Confidence、Issue、Risk、Suggestion，按严重级别分组（Critical 优先）。codex-review-loop 的 Triage 步骤正是消费这种结构化输出，所以 Agent 报告越规范，人工分流越省力。

此外，reviewer-holistic.md 还定义了"premortem 分析"技巧——假设变更已上线并引发事故，倒推 1～3 个具体失败故事，评估严重度、可能性、检测难度与爆炸半径（blast radius）。这可以作为单 Agent 审查的补充视角，让 Codex 不止盯着 diff 里的每一行，也评估整次改动对系统的整体影响。

三、Triage 阶段：开发者是过滤器

命令明确要求："Review agent findings and keep only what you also deem noteworthy"——Agent 的结论不能直接照单全收，开发者必须亲自复核，只留下自己也认为值得注意的项。这是整个闭环防止"AI 过度干预"的关键闸门。

分流操作分三步：

1. 筛选：剔除低置信度、低严重度的发现，除非你能对照代码亲自确认其真实性。Agent 的置信度标注（High / Medium / Low）在这里就是排序依据。
2. 分类：把幸存项归入两类——
   • Fix：明确的缺陷，必须修复；
   • Skip：风格问题、吹毛求疵、范围蔓延（scope creep）。
3. 公示：在动手改任何代码之前，先展示一张简要的分类表格（项、级别、Fix/Skip 决策）。

"先公示再动手"这条约束的价值在于：它强制你在修改前把决策显式化，避免边改边夹带私货；同时为最终的"修复/跳过总结"留下了可回溯的记录。Skip 并不是无理由丢弃——复审阶段（第 5 步）明确规定"不得重新提出已跳过的项"，这保证了 3 轮迭代的收敛性，防止同一批风格争论在每轮循环里反复消耗预算。

四、Fix 阶段：只修 Fix 项，保持最小化

第三阶段的铁律是"Fix only the 'Fix' items. Keep changes minimal."——只动被标记为必须修复的项，其余一律不碰。

在 Repomix 的工程语境下，"最小化修改"有一套具体约束可依循，全部记录在 .agents/rules/base.md：

• 编码规范：遵循 Biome（biome.json）强制的代码标准；每个文件保持单一职责，约 250 行是值得审视内聚性的信号而非强制拆分线。
• 依赖注入模式：新依赖一律通过deps对象参数注入以便测试，测试中用测试替身（test double）mock 依赖，仅在无法注入时才用vi.mock()。修复代码时若不遵守这一模式，后续npm run test很可能在现有测试模式下暴露问题。
• 提交信息：遵循 Conventional Commits 规范type(scope): Description，如feat(cli): Add new --no-progress flag。修复若涉及提交，scope 应对应受影响区域（cli、core、website、security 等）。

由于 Fix 集合来自人工分流，本身数量有限，配合"最小化"原则，每轮迭代对代码库的扰动被控制在可审计范围内——这正是该工作流与"让 AI 直接大改"的本质区别。

五、Verify 阶段：lint 与 test 的真实内涵

第 4 步要求用npm run lint和npm run test验证，出现回归就继续修复并重复本步，直到全部通过才进入下一轮复审。理解这两条命令的真实构成，才能预判验证会覆盖什么、不会覆盖什么。查看根目录 package.json：

• npm run lint（package.json）实际是四条子命令的串联：
  • lint-biome：biome check --write（package.json）——代码风格与静态检查；
  • lint-oxlint：oxlint --fix（package.json）——lint 与自动修复；
  • lint-ts：tsc --noEmit（package.json）——TypeScript 全量类型检查，这是运行时正确性最硬的防线；
  • lint-secretlint：secretlint "**/*"（package.json）——扫描密钥泄露，与 reviewer-security.md 中"Secret Exposure (CWE-798, CWE-532)"的审查焦点呼应。
• npm run test：vitest（package.json），即 Vitest 测试运行器；仓库测试规模庞大，tests/目录完整镜像src/结构，覆盖 CLI 动作、配置加载、文件收集、Git 处理、指标计算、输出样式、安全扫描、tree-sitter 解析等模块。

另外 .agents/rules/base.md 特别提醒两个"验证盲区"：

• 根目录npm run lint不对 website 客户端做类型检查；改动website/client时必须在website/client目录内用npm run docs:build验证；
• 配置 JSON Schema（website/client/src/public/schemas/）是npm run website-generate-schema生成的，CI 在合并到main后会重新生成，绝不能手工编辑。

也就是说，Verify 步骤的"通过"标准在不同改动区域有不同的完整形态：改src/就靠lint + test，改网站文档还需追加 docs 构建验证。在实战中，这提醒我们要把验证命令当作"按改动面裁剪"的组合，而不是一成不变的两条命令。

六、Re-review 阶段与循环收敛

第 5 步规定：只重新审查新改动的行，不要重新提出已跳过的项（"Re-review only the newly changed lines. Do not re-raise skipped items"）。

这条规则同时约束了两个维度：

• 范围上：复审对象从"整个分支 diff"收窄为"上一轮修复引入的新改动行"，避免对未改动代码做重复劳动，也防止 Agent 在新一轮里重提旧问题；
• 决策上：Skip 决策在本循环内是终局性的，保证 3 轮迭代必然收敛。

循环出口：

• 某轮 Triage 后没有剩余 Fix 项 → 立即停止；
• 达到 3 次迭代上限 → 强制停止；
• 无论哪种出口，最后都要打印总结：修复了什么、跳过了什么。这份总结既是本轮工作的审计记录，也可以直接写入 PR 描述，让维护者看到"AI 建议了什么、人决定修了什么、为什么跳过其余项"。

七、实战落地清单

把codex-review-loop的 5 步闭环套用到 Repomix（或任何 Node.js 项目）的开发流程中，建议按以下清单执行：

1. 准备基线：确保本地main已同步，确认git diff main范围即本轮审查对象。
2. Review：启动 Codex，派生 reviewer agent，输入git diff main，要求输出带 Severity + Confidence 的结构化报告；单 Agent 模式下可参考 reviewer-code-quality.md 组织评审视角，如涉及整体架构风险，叠加 reviewer-holistic.md 的 premortem 视角。
3. Triage：逐条核对，只保留你也能在代码里确认的发现；输出 Fix/Skip 表格后再动手。拿不准的项，宁可标 Low 置信度保留，也不要随手丢弃——正如 Reviewer Agent 定义所言，压下的发现就永久丢失了。
4. Fix：只修 Fix 项；遵循 .agents/rules/base.md 的编码规范、单一职责与 deps 依赖注入约定，保持改动最小、可审阅。
5. Verify：npm run lint（biome + oxlint + tsc + secretlint）+npm run test（vitest）；若改动涉及website/client，额外在该目录执行npm run docs:build。任何回归都必须修复后重新验证，直到全绿。
6. Re-review 与收尾：只复审新改行，不重提 Skip 项；无 Fix 项或达到 3 轮即停，输出"修复了什么、跳过了什么"的总结，作为 PR 说明的一部分。

八、方法论迁移：与 review-loop 的取舍

对比 codex-review-loop.md 与 review-loop.md 可以发现，两者共享完全相同的骨架——Triage（Fix/Skip 分类 + 先表格后动手）、最小化修复、npm run lint+npm run test验证闭环、只复审新改行、3 次迭代上限与总结输出。唯一的差异在第一步：

• review-loop：并行派生 6 个专业 Reviewer，各管一个维度，报告自动带 severity + confidence，且 Agent 不做预过滤；
• codex-review-loop：只派生 1 个 Codex Reviewer，依赖 Codex 自身能力完成多维度审查，编排成本更低、token 开销更小。

选择建议：分支改动横跨安全、性能、测试、文档等多个维度时，review-loop的多 Agent 并行能带来更强的覆盖保证；改动面小而集中、或希望控制 LLM 调用成本时，codex-review-loop的单 Agent 模式更轻量。两条命令的可移植性都很强——因为它们依赖的"分级报告 → 人工分流 → 最小修复 → 命令验证 → 定点复审"模式与具体项目解耦，只要项目提供lint与test脚本即可迁移。

结语

codex-review-loop 表面上只是一条 5 步循环命令，但它体现了 Agent 辅助开发中一个重要设计原则：AI 负责穷尽式发现问题，人负责做出修改决策，两者各司其职，并用"最小化修改 + 定点复审 + 迭代上限"把 AI 的介入范围牢牢锁住。结合 .agents/agents/ 下 6 份 Reviewer Agent 定义、.agents/rules/base.md 的工程规范与 package.json 中的验证脚本，这套方法论在 Repomix 仓库中已经具备完整的可落地土壤——你也完全可以将同样的闭环原样迁移到自己的项目，让每次分支合并前的代码质量审查都变得可重复、可审计、可收敛。

【免费下载链接】repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix