Clawpatch + codex-review：AI 代码审查工具链的正确打开方式

<p>Peter Steinberger（GitHub 上的 steipete）是一个在 AI 开发工具领域绕不开的名字。他曾白手起家将 PSPDFKit 做到百万美元 ARR 并成功退出，如今在 OpenAI 负责 Agent 相关研发。他创建的 OpenClaw 项目收获了 37 万+ stars，而 Clawpatch 和 codex-review skill 是他 AI 编程工具链中专注于代码审查这一环的两个代表作。</p><p>传统代码审查有个结构性矛盾：审查者往往不熟悉被审查代码的完整上下文，所以要么流于表面（看看命名、格式），要么只能依赖作者写的 PR 描述来理解意图。AI 时代的解法很直接——让一个能读懂整个代码库的 Agent 来做审查。但不是随便把代码丢给 LLM 让它&quot;看看有没有问题&quot;就行，真正的挑战在于：如何划定审查边界、如何确保证据可追溯、以及发现问题后如何安全地修复。</p><p>Clawpatch 和 codex-review skill 分别从&quot;工具链自动化&quot;和&quot;工作流规范化&quot;两个角度回答了这些问题。</p><p>![cover<img src="/2026/05/20/clawpatch-codex-review-ai-code-review-toolchain/cover.png" class=""></p><h2 id="一、Clawpatch：语义级自动化代码审查"><a href="#一、Clawpatch：语义级自动化代码审查" class="headerlink" title="一、Clawpatch：语义级自动化代码审查"></a>一、Clawpatch：语义级自动化代码审查</h2><p>![01-clawpatch-overview<img src="/2026/05/20/clawpatch-codex-review-ai-code-review-toolchain/01-clawpatch-overview.png" class=""></p><p>Clawpatch（<a href="https://clawpatch.ai/">clawpatch.ai</a>，GitHub：<a href="https://github.com/openclaw/clawpatch">openclaw&#x2F;clawpatch</a>）是一个命令行代码审查工具，MIT 协议开源。它的核心思路是把代码审查从&quot;逐文件扫描&quot;升级为&quot;按语义单元审查&quot;。</p><span id="more"></span><p>传统 linter 或 SAST 工具看到的是一棵文件树，它们逐个文件分析，发现的问题往往是局部的（&quot;这个变量未使用&quot;、&quot;这行代码有 SQL 注入风险&quot;）。Clawpatch 的做法不同：它先通过 <code>clawpatch map</code> 命令把整个仓库映射为语义特征（semantic features）——不只是文件列表，而是包含入口点（entrypoints）、归属文件（owned files）、上下文文件（context files）、关联测试（nearby tests）的完整单元。比如一个 Next.js 的 <code>/api/checkout</code> 路由，它的特征记录会包含路由文件本身、它引用的 Service 层代码、相关的数据库模型、以及对应的测试文件。</p><p>这个映射能力是 Clawpatch 最硬核的部分。它目前能自动识别的项目类型覆盖了主流技术栈：Node.js&#x2F;TypeScript（包括 Next.js、React Router、Nx、Turborepo）、Python（Flask、FastAPI、Django）、Go、Rust&#x2F;Cargo、Java&#x2F;Kotlin（包括 Gradle、Android 语义角色识别）、C#&#x2F;.NET（包括 ASP.NET Core 控制器和 Minimal API）、Ruby&#x2F;Rails、Elixir&#x2F;Phoenix、SwiftPM、C&#x2F;C++（CMake、autotools）、PHP&#x2F;Laravel 等。这意味着你不用手动告诉它&quot;这段代码是干什么的&quot;，它能根据框架约定和代码结构自动推断。</p><p>有了特征映射后，<code>clawpatch review</code> 命令会把这些特征单元逐个送给 AI provider（默认使用本地 Codex CLI，也支持 ACP 兼容 Agent、Grok Build CLI、OpenCode CLI 等）进行审查。每次审查产出的 finding 包含分类（bug、security、performance、docs-gap、test-gap、maintainability）、严重程度（critical&#x2F;high&#x2F;medium&#x2F;low）、置信度（high&#x2F;medium&#x2F;low）和证据（代码片段、文件位置、推理链），持久化存储在 <code>.clawpatch/findings/</code> 目录下。</p><p>发现问题的下一步是修复，而 Clawpatch 在这里的设计相当保守——这正是它区别于&quot;AI 自动改代码&quot;类工具的关键。<code>clawpatch fix --finding &lt;id&gt;</code> 是一条显式命令，它只会修复你明确指定的那一条 finding。修复过程走完整的验证流水线：先检查代码格式（Prettier 等），再跑类型检查（<code>tsc --noEmit</code>），然后 lint（ESLint），最后跑测试。全部通过后，修改落在你的工作目录中等待人工 review——Clawpatch 不会自动 commit、push、创建 PR 或合入代码。这种&quot;AI 动手，人类拍板&quot;的模式确保了安全性，同时保留了自动化的效率收益。</p><p>还有一个值得单独提的功能是 <code>deslopify</code> 模式（<code>clawpatch review --mode deslopify</code>）。&quot;Slop&quot; 在 AI 编程语境中特指那种&quot;能跑但质量堪忧&quot;的代码——变量命名随意、逻辑可以大幅简化、有明显冗余。deslopify 模式专门针对这类可本地验证的代码清理，不作为严肃的安全或逻辑审查，而是作为日常的代码健康检查。</p><h2 id="二、codex-review-skill：Codex-审查的标准化工作流"><a href="#二、codex-review-skill：Codex-审查的标准化工作流" class="headerlink" title="二、codex-review skill：Codex 审查的标准化工作流"></a>二、codex-review skill：Codex 审查的标准化工作流</h2><p>![02-codex-review-skill<img src="/2026/05/20/clawpatch-codex-review-ai-code-review-toolchain/02-codex-review-skill.png" class=""></p><p>如果说 Clawpatch 是一个完整的自动化审查工具链，那 codex-review skill（<a href="https://github.com/steipete/agent-scripts/blob/main/skills/codex-review/SKILL.md">steipete&#x2F;agent-scripts</a>）就更像一个审查流程的 SOP（标准操作流程）。它的形式就是我们在 mattpocock&#x2F;skills 那篇文章中介绍过的 skill 文件——YAML frontmatter + Markdown 指令集，专门为 Codex CLI 的 <code>codex review</code> 命令设计了一套严谨的执行规范。</p><p>这个 skill 的核心价值不在于它能做什么审查（审查本身是 Codex 的能力），而在于它定义了一套防呆的审查纪律。比如它明确规定：</p><ul><li><p><strong>审查输出只作为建议，不能盲信。</strong> 每一条 finding 都必须通过阅读真实代码路径和相邻文件来验证。</p></li><li><p><strong>拒绝不切实际的边缘案例和投机性风险。</strong> 不是说 AI 报了就要改，要判断这个风险在实际场景中是否成立。</p></li><li><p><strong>修复要小、要精准。</strong> 不做大规模重构，除非它明确改善了该类 bug 的根本问题。</p></li><li><p><strong>修复后必须重新跑测试和重新审查，直到没有 actionable finding 为止。</strong> 这个闭环确保修复本身不会引入新问题。</p></li><li><p><strong>不要为了审查而 push 代码。</strong> 审查是本地活动，push 只在用户明确要求时才发生。</p></li></ul><p>skill 还内置了一个 helper 脚本，能自动判断该用哪种审查模式：当前工作区有未提交的修改时用 <code>--uncommitted</code>；有 PR 时自动抓取 <code>gh pr view</code> 获取 base 分支；已经提交到 main 的用 <code>--commit HEAD</code>。这让审查流程几乎零配置——跑一个命令，skill 自己搞清楚该审查什么。</p><p>还有一个很务实的细节：skill 明确建议用 subagent 来跑审查，因为 <code>codex review</code> 通常输出很长且噪音多，直接在主对话里跑会淹没上下文。subagent 只返回三类信息：接受的 actionable finding、拒绝的 finding（带一行理由）、需要重新跑的测试和文件。这保持了主对话的干净和高效。</p><h2 id="三、实战：从零开始用-Clawpatch-审查一个真实项目"><a href="#三、实战：从零开始用-Clawpatch-审查一个真实项目" class="headerlink" title="三、实战：从零开始用 Clawpatch 审查一个真实项目"></a>三、实战：从零开始用 Clawpatch 审查一个真实项目</h2><p>![03-practical-guide<img src="/2026/05/20/clawpatch-codex-review-ai-code-review-toolchain/03-practical-guide.png" class=""></p><p>下面用一个 Next.js 电商项目的真实场景，从头到尾走一遍 Clawpatch 的完整工作流。每一步你都可以在自己的项目里直接复现。</p><h3 id="前置准备"><a href="#前置准备" class="headerlink" title="前置准备"></a>前置准备</h3><p>确保本地装了 Codex CLI（Clawpatch 默认 provider）：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">codex --version</span><br><span class="line"><span class="comment"># 确认能正常输出</span></span><br><span class="line"></span><br><span class="line">npm install -g clawpatch</span><br><span class="line"><span class="comment"># 或 pnpm add -g clawpatch</span></span><br></pre></td></tr></table></figure><p>进入你的项目根目录：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="built_in">cd</span> my-ecommerce-app</span><br></pre></td></tr></table></figure><h3 id="第一步：初始化"><a href="#第一步：初始化" class="headerlink" title="第一步：初始化"></a>第一步：初始化</h3><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">clawpatch init</span><br></pre></td></tr></table></figure><p>这个命令做了什么？它在项目根目录创建了 <code>.clawpatch/</code> 目录，里面有两个文件：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">.clawpatch/</span><br><span class="line"> config.json # 审查配置：上下文文件数上限、并发数、git行为等</span><br><span class="line"> project.json # 自动检测到的项目元信息：包管理器、构建命令、测试命令</span><br></pre></td></tr></table></figure><p>你不需要手动改任何东西就能直接用。当然后续可以按需调整——比如你的测试命令不是默认的 <code>npm test</code>，就去 <code>config.json</code> 里把 <code>commands.test</code> 改成实际命令。</p><h3 id="第二步：构建语义特征映射"><a href="#第二步：构建语义特征映射" class="headerlink" title="第二步：构建语义特征映射"></a>第二步：构建语义特征映射</h3><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">clawpatch map</span><br></pre></td></tr></table></figure><p>输出大概长这样：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">Found 23 features:</span><br><span class="line"> route /api/checkout (3 owned files, 5 context files, 4 tests)</span><br><span class="line"> route /api/products/[id] (2 owned files, 3 context files, 3 tests)</span><br><span class="line"> route /api/orders (4 owned files, 6 context files, 5 tests)</span><br><span class="line"> command cli/seed-db (1 owned file, 0 context files, 0 tests)</span><br><span class="line"> pkg @myapp/payment (6 owned files, 4 context files, 7 tests)</span><br><span class="line"> pkg @myapp/auth (4 owned files, 2 context files, 5 tests)</span><br><span class="line"> ...</span><br></pre></td></tr></table></figure><p>每个特征不是孤立文件，而是一个打包好的审查单元。比如 <code>/api/checkout</code> 这个路由，它的 &quot;owned files&quot; 是 <code>app/api/checkout/route.ts</code> 本身，而 &quot;context files&quot; 包括了它引用的 <code>lib/payment/service.ts</code>、<code>lib/inventory/reserve.ts</code>、<code>types/order.ts</code> 等——这些是 AI 理解这个路由在干什么所需要的上下文。</p><p><strong>关键点</strong>：这个映射不是静态快照。你改代码后要重新 <code>clawpatch map</code> 更新映射，否则 Clawpatch 会基于旧的代码结构做审查。</p><h3 id="第三步：跑第一轮审查"><a href="#第三步：跑第一轮审查" class="headerlink" title="第三步：跑第一轮审查"></a>第三步：跑第一轮审查</h3><p>刚才改了一堆结账流程的代码，现在跑审查：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">clawpatch review --<span class="built_in">limit</span> 5</span><br></pre></td></tr></table></figure><p><code>--limit 5</code> 的意思是只审查 5 个特征单元。这个限制很实用——你不会一次性把 23 个特征全扔给 AI，那样上下文太大，审查质量也差。分批审查，每批聚焦几个特征。</p><p>审查进行中，消耗的主要是时间（每个特征约 10-30 秒，取决于复杂度）和 AI provider 的 token。结束后输出：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">Reviewed 5 features. Found 8 findings:</span><br><span class="line"></span><br><span class="line"> #a1b2c3 [high] bug /api/checkout — 未校验库存不足时的回滚</span><br><span class="line"> #d4e5f6 [medium] security /api/checkout — 退款金额未验证非负</span><br><span class="line"> #g7h8i9 [medium] test-gap @myapp/payment — 缺少部分退款测试</span><br><span class="line"> #j0k1l2 [low] maint /api/orders — 重复的日期格式化逻辑</span><br><span class="line"> ...</span><br></pre></td></tr></table></figure><h3 id="第四步：逐条处理-findings"><a href="#第四步：逐条处理-findings" class="headerlink" title="第四步：逐条处理 findings"></a>第四步：逐条处理 findings</h3><p>拿到 8 条 finding 后，不是一键修复全部——Clawpatch 的设计哲学是你必须逐条决策。</p><p>先看一条严重的：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">clawpatch show --finding a1b2c3</span><br></pre></td></tr></table></figure><p>这会展开这条 finding 的完整信息：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line">Finding #a1b2c3</span><br><span class="line"> Feature: /api/checkout</span><br><span class="line"> Category: bug</span><br><span class="line"> Severity: high</span><br><span class="line"> Confidence: high</span><br><span class="line"> Status: open</span><br><span class="line"></span><br><span class="line"> Evidence:</span><br><span class="line"> app/api/checkout/route.ts:42 — 扣减库存后未在 catch 中回滚</span><br><span class="line"> lib/inventory/reserve.ts:15 — reserve() 没有提供 rollback() 接口</span><br><span class="line"></span><br><span class="line"> Recommendation:</span><br><span class="line"> 在 reserve() 调用外层加 try-catch, catch 中调用新增的 rollback()</span><br></pre></td></tr></table></figure><p>你确认这是真问题，修复它：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">clawpatch fix --finding a1b2c3</span><br></pre></td></tr></table></figure><p>Clawpatch 做三件事：</p><ol><li>调用 AI provider 生成修复代码</li><li>自动跑验证流水线：格式化检查 → 类型检查 → lint → 测试</li><li>如果全部通过，修改落在你的工作目录中</li></ol><p>如果测试挂了（比如 fix 引入了一个回归），Clawpatch 会报出来，修复不会应用到工作目录。你可以调整后再试。</p><p>再看一条可能是误报的：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">clawpatch show --finding g7h8i9</span><br></pre></td></tr></table></figure><p>你判断&quot;部分退款测试已经在另一个 PR 里由同事在写了&quot;，这条先不管。标记掉：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">clawpatch triage --finding g7h8i9 --status false-positive --note <span class="string">&quot;已在 #342 中覆盖&quot;</span></span><br></pre></td></tr></table></figure><p>它从活跃列表中移除了，但记录保留在 <code>.clawpatch/findings/</code> 中，未来可审计。</p><h3 id="第五步：修复后验证"><a href="#第五步：修复后验证" class="headerlink" title="第五步：修复后验证"></a>第五步：修复后验证</h3><p>你修了 3 条 finding，标记了 2 条误报，还剩 3 条暂时不处理。现在验证已修复的：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">clawpatch revalidate --finding a1b2c3</span><br><span class="line">clawpatch revalidate --finding d4e5f6</span><br><span class="line">clawpatch revalidate --finding j0k1l2</span><br></pre></td></tr></table></figure><p>每条 revalidate 会用 AI provider 重新检查这个 finding 对应的代码路径，确认修复有效且没有引入新问题。通过后 finding 状态变为 <code>fixed</code>。</p><h3 id="第六步：生成审查报告"><a href="#第六步：生成审查报告" class="headerlink" title="第六步：生成审查报告"></a>第六步：生成审查报告</h3><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">clawpatch report</span><br></pre></td></tr></table></figure><p>生成一份 Markdown 报告到 <code>.clawpatch/reports/</code> 下，包含：</p><ul><li>本次审查覆盖了哪些特征单元</li><li>发现了多少问题（按严重程度和分类统计）</li><li>哪些已修复、哪些标记为误报、哪些仍在 open</li><li>每条 finding 的摘要</li></ul><p>这份报告可以直接贴到 PR 描述或团队文档中，作为审查记录。</p><h3 id="日常使用节奏"><a href="#日常使用节奏" class="headerlink" title="日常使用节奏"></a>日常使用节奏</h3><p>经过第一次完整流程后，日常使用就很简单了：</p><p><strong>每次提交前：</strong></p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">clawpatch map <span class="comment"># 更新特征映射，秒级完成</span></span><br><span class="line">clawpatch review --<span class="built_in">limit</span> 3 <span class="comment"># 只审最近改动的几个特征</span></span><br><span class="line">clawpatch fix --finding &lt;<span class="built_in">id</span>&gt; <span class="comment"># 修复你认可的问题</span></span><br><span class="line">clawpatch triage --finding &lt;<span class="built_in">id</span>&gt; --status false-positive <span class="comment"># 打标误报</span></span><br></pre></td></tr></table></figure><p><strong>每周一次（代码健康检查）：</strong></p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">clawpatch map</span><br><span class="line">clawpatch review --mode deslopify --<span class="built_in">limit</span> 15</span><br><span class="line"><span class="comment"># 专门清理可本地验证的代码质量问题，不改业务逻辑</span></span><br></pre></td></tr></table></figure><p><strong>PR 创建前（最终检查）：</strong></p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">clawpatch map</span><br><span class="line">clawpatch review --<span class="built_in">limit</span> 10</span><br><span class="line">clawpatch report -o pr-review.md <span class="comment"># 输出报告贴到 PR 里</span></span><br></pre></td></tr></table></figure><h3 id="一个真实的踩坑点"><a href="#一个真实的踩坑点" class="headerlink" title="一个真实的踩坑点"></a>一个真实的踩坑点</h3><p><code>clawpatch map</code> 有时候会因为项目结构变化而产出不同的特征 ID，这会导致之前 triage 过的 finding 找不到对应特征。如果你发现 <code>clawpatch status</code> 里有一些&quot;孤儿 finding&quot;，不用慌——它们是之前审查的产物，特征映射更新后关联断裂了。直接删掉或者用 <code>--force</code> 重新 map 处理即可。这个问题在 Clawpatch 的 issue 列表中有讨论，后续版本会改善特征 ID 的稳定性。</p><h2 id="四、开发流程中的协作分工"><a href="#四、开发流程中的协作分工" class="headerlink" title="四、开发流程中的协作分工"></a>四、开发流程中的协作分工</h2><p>![04-collaboration<img src="/2026/05/20/clawpatch-codex-review-ai-code-review-toolchain/04-collaboration.png" class=""></p><p>Clawpatch 和 codex-review skill 在同一个开发流程中扮演不同的角色，不是二选一的关系。</p><p>Clawpatch 的审查是&quot;结构化深度审查&quot;——基于特征单元，产出带证据链的 finding，可追踪、可修复、可验证。Codex review 则更适合作为&quot;closeout 检查&quot;——在提交前的最后一轮，快速扫一遍全局变更，捕捉 Clawpatch 可能因特征划分边界而遗漏的跨模块问题。</p><p>实操中的配合顺序：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">1. 功能开发完成，工作区有未提交修改</span><br><span class="line">2. clawpatch map → clawpatch review --limit 5 # 语义深度审查</span><br><span class="line">3. clawpatch fix --finding &lt;id&gt; # 逐条修复确认的问题</span><br><span class="line">4. clawpatch triage --finding &lt;id&gt; # 标记误报</span><br><span class="line">5. clawpatch revalidate --finding &lt;id&gt; # 验证修复</span><br><span class="line">6. codex review --uncommitted # closeout 全局检查</span><br><span class="line">7. 如有问题 → 修复 → 重跑测试 → 回到第6步</span><br><span class="line">8. 确认 clean → git commit → git push</span><br></pre></td></tr></table></figure><p>对于 CI&#x2F;CD 集成，Clawpatch 支持在 GitHub Actions 中运行 review 和 report 命令。一个典型的配置是：PR 创建后自动跑一轮 Clawpatch 审查，生成的 findings report 作为 PR comment 贴在下面。这样 reviewer 在人工审查时就能直接看到 AI 已经发现了哪些问题、哪些已经自动修复、哪些需要人工判断。</p><p>Clawpatch 的价值主张是&quot;让 AI 替你审查，但由你决定修不修&quot;；codex-review skill 的价值主张是&quot;让审查有纪律，不盲信、不跳过、不偷懒&quot;。两者结合起来，你就拥有了一套既有广度（覆盖整个仓库的语义单元）又有深度（每条 finding 都有证据链和验证流程）的 AI 代码审查体系。</p><p>如果你已经厌倦了 PR review 中大量的机械性检查（这个 import 没用到、那个边界条件没处理、这里可以提取一个公共函数），把 Clawpatch 装到项目里，再把 codex-review skill 加入你的 Agent 配置，下次 PR 时你会发现自己只需要关注那些真正需要人类判断的问题——架构决策、业务逻辑正确性、用户体验权衡。这才是一个好的 AI 审查工具该做的事情。</p><h2 id="五、FAQ"><a href="#五、FAQ" class="headerlink" title="五、FAQ"></a>五、FAQ</h2><p><strong>Q1：Clawpatch 和 ESLint &#x2F; SonarQube 这类传统静态分析工具有什么本质区别？</strong></p><p>传统工具基于规则匹配（AST 模式、正则、CFG 分析），擅长发现确定性问题——未使用的变量、潜在的空指针、已知的漏洞模式。它们快、稳定、零假阳性可控，但看不到&quot;语义&quot;——一段代码在业务流程中是否合理、边界条件是否完整、错误处理是否和上下游匹配。Clawpatch 的差异在于它把代码放在特征单元（feature context）中审查，AI provider 能理解&quot;这个 if 分支在退款流程中意味着什么&quot;而非仅仅&quot;这个 if 分支没有 else&quot;。两者不互斥：ESLint 做第一道机械检查，Clawpatch 做第二道语义审查。</p><p><strong>Q2：AI 审查的假阳性怎么处理？会不会审查五分钟，排查假阳性半小时？</strong></p><p>这是所有 AI 审查工具的核心矛盾。Clawpatch 的设计从三个层面缓解：第一，每条 finding 标注置信度（confidence），低置信度的可以先跳过；第二，<code>clawpatch triage</code> 命令可以对 finding 做快速分类（false-positive、wont-fix 等），标记后会从活跃列表中移除；第三，codex-review skill 的纪律明确要求&quot;拒绝不切实际的边缘案例&quot;——这本身就是一道人工过滤。如果某个模式反复出现假阳性，你可以在 Clawpatch 的配置中通过自定义规则排除它。</p><p><strong>Q3：Clawpatch 的特征映射（feature map）在非标准项目结构下还能用吗？</strong></p><p>特征映射的默认行为依赖框架约定——Next.js 的 <code>app/</code> 目录、Go 的 <code>go list</code>、Gradle 的项目结构等。如果项目结构完全自定义（比如自己写的构建系统），自动映射会退化到文件级分组，这时候审查质量会打折扣。Clawpatch 的路线图中包含自定义 mapper 接口和 agent-assisted enrichment（让 AI 辅助识别代码语义角色），但目前这两个还在开发中。对于非标准项目，现阶段建议先用 <code>clawpatch map --source agent</code> 尝试让 AI 辅助映射。</p><p><strong>Q4：PR 很大（几十个文件）时，AI 审查会不会因为上下文不够而漏问题？</strong></p><p>会，这是当前所有 AI 审查的硬限制。Clawpatch 的缓解策略是按特征单元分批审查而非一次性塞所有文件，每个特征单元的上下文文件数有上限（默认 <code>maxContextFiles: 24</code>）。codex-review skill 则建议用 subagent 跑 review，减少主对话上下文的消耗。对于超大 PR，最务实的做法是在 CI 中用 <code>--limit</code> 分批审查，每批聚焦少量特征单元，分多次 comment 贴到 PR 下。</p><p><strong>Q5：Clawpatch 能发现业务逻辑级别的漏洞吗？比如&quot;退款金额校验绕过&quot;这种？</strong></p><p>取决于特征映射能提供多少上下文。如果映射把退款路由、Service 层校验逻辑、支付网关交互代码作为一个特征单元打包送给 AI provider，那么 AI 确实有可能发现&quot;这里没有校验已退款累计金额&quot;。但如果校验逻辑分散在多个特征单元中（比如路由在一个单元、校验在另一个、数据访问又在第三个），跨单元的语义关联就可能断裂。这是一个积极演进的方向——Clawpatch 的路线图中有&quot;更深层的框架 mapper&quot;和&quot;Agent 辅助映射&quot;计划，目的就是让特征边界更贴合真实的业务逻辑边界。</p><p><strong>Q6：团队有自己的编码规范和审查重点（比如&quot;所有外部 API 调用必须有超时设置&quot;），能定制审查规则吗？</strong></p><p>Clawpatch 目前通过 <code>config.json</code> 中的 <code>review</code> 配置项和 provider 的 prompt 来控制审查行为，但不支持像 ESLint rules 那样声明式地定义自定义规则。变通方案是在项目的 CLAUDE.md 或 AGENTS.md 中写明团队的编码规范，AI provider 在审查时会读取这些文件作为上下文。自定义审查模板（finding templates）在 Clawpatch 的路线图中，但尚未实现。codex-review skill 更灵活一些——你可以在 skill 文件中追加团队特定的审查关注点。</p><p><strong>Q7：Clawpatch 和 codex-review skill 都用了 AI provider，token 消耗会不会很大？成本怎么控制？</strong></p><p>Clawpatch 的默认行为是按特征单元分批、带 limit 限制，控制了单次审查的上下文体积。<code>review.maxContextFiles</code> 和 <code>review.maxOwnedFiles</code> 配置项让你可以收紧上下文窗口。codex-review skill 建议用 subagent 隔离审查上下文，避免挤占主对话的 token 预算。对于成本敏感的场景，可以指定更便宜的 model（如果 provider 支持），或者用 <code>mock</code> provider 先在本地验证映射和配置的正确性，确认无误后再切换到真实 provider 做正式审查。</p><h2 id="参考资料"><a href="#参考资料" class="headerlink" title="参考资料"></a>参考资料</h2><ul><li>[1] Clawpatch 官网: <a href="https://clawpatch.ai/">https://clawpatch.ai/</a></li><li>[2] Clawpatch GitHub: <a href="https://github.com/openclaw/clawpatch">https://github.com/openclaw/clawpatch</a></li><li>[3] codex-review skill: <a href="https://github.com/steipete/agent-scripts/blob/main/skills/codex-review/SKILL.md">https://github.com/steipete/agent-scripts/blob/main/skills/codex-review/SKILL.md</a></li><li>[4] steipete&#x2F;agent-scripts: <a href="https://github.com/steipete/agent-scripts">https://github.com/steipete/agent-scripts</a></li><li>[5] Peter Steinberger GitHub: <a href="https://github.com/steipete">https://github.com/steipete</a></li></ul>