Iterate 使用指南：先做只读审查，再决定是否让 AI 修复
Iterate 适合需要多轮检查、修复、重新验证和复审的代码任务；普通的一两行修改通常不需要它。它可以在多种编程助手中运行，但也会调用 shell、读写项目文件并使用 Git。第一次建议先做 review-only，熟悉报告后，再在干净的隔离分支里尝试修复。
版本说明（2026-10-25）： GitHub 最新 release 和 npm 安装器已发布 3.9.0；此时 ClawHub 注册 API 仍标记 3.8.2。下面的安装命令会从 GitHub 获取最新 release，因此安装器路径和 ClawHub 当前索引版本可能暂时不同。不要混用两个版本的行为说明。
安装：一条命令会做哪些事
官方安装器支持 Codex、Claude Code、Cursor、GitHub Copilot 等客户端。先确认 Node.js 18+、Python 3.10+、tar 和 GnuPG 可用，再在终端运行：
npx iterate-skill-installer --ai codex
--ai codex 只选择 Codex 目标；安装器仍会把 iterate CLI 安装到 PATH（优先使用 pipx，否则用 pip --user）。默认也会安装 Skill；在交互确认前检查目标客户端和安装位置，避免重复安装。若只想安装 Skill，可加 --no-cli，但之后需要另行安装 CLI 才能执行 onboarding 和确定性检查。
安装器从 GitHub Release 下载归档、SHA256 清单及其签名，验证文件哈希和 GPG 签名。没有 GnuPG 时应先安装并核实签名密钥；不要为了继续而关闭验证。安装失败时保留错误信息，别改用不明镜像。
如果安装了 CLI 并希望在终端使用 Tab 补全，3.9.0 新增了安装命令：
iterate completion zsh --install
它会写入用户的 zsh 补全目录；若目标文件已存在，默认拒绝覆盖，可先读帮助再决定是否使用 --force。这项新命令不属于当时 ClawHub API 标记的 3.8.2 文件。
先初始化项目，再检查配置
进入准备审查的 Git 项目，在终端运行：
cd /path/to/your-project
iterate onboard
iterate doctor
Onboarding 会扫描项目上下文并准备 ITERATE.md 和 iterate.config.yaml。先检查生成的项目地图、禁止修改的区域和 validation.commands。后者会在后续验证中执行，必须确认每条命令确实适用于本项目，再开始修复。iterate doctor 可检查初始化状态和配置；它不代表代码已经通过测试。
第一次任务：只生成审查报告
先选一个你可以人工复核的范围，例如“检查最近改动的输入校验与错误处理”。在支持 Codex Skill 的对话里调用 $iterate，并明确要求只读；其他客户端按各自的 Skill 调用方式输入同一目标。可改写这个练习提示：
只审查这个项目的输入校验和错误处理。使用 review-only 模式，不要修复代码或创建分支。报告每个发现的文件路径、行号、影响和复核方法；最后检查报告内部计数和证据，并给出最终 verdict。
Iterate 的 review-only / dry-run 会跳过修复循环，生成带收敛信息的报告、meta-review 和 approved 或 needs_revision verdict。检查每条路径和行号是否存在，确认建议与代码上下文一致。版本 3.9.0 的说明允许写入一条报告记录到 .iterate_decisions.md，所以它表示“不改代码”，不应被理解为“工作树绝对零写入”；运行前后比较 git status --short。
确认工作方式后再让它修改
若需要实现功能、修 bug 或重构，先提交或保存现有改动，把任务放进干净的隔离 worktree / 分支，再提供具体目标：
使用 defensive 模式，为设置页增加邮箱格式校验。先检查项目约束和现有测试；每次只做小步修改，运行已确认的验证命令。完成后报告改动文件、测试结果、未解决项和分支名称，不要合并或推送。
在适用客户端中调用 $iterate defensive 并附上目标；使用斜杠命令的客户端则按该客户端格式调用 /iterate defensive <目标>。防御式模式先做 pre-check，再最小步修改、逐次 post-check，最后检查项目不变量并进入多轮审查收敛。若项目已完成 onboarding 却没有配置验证命令，guard 会 fail-closed；先在 iterate.config.yaml 配好真实检查项，不要跳过失败继续写代码。
普通 /iterate <目标> 适合“先审查、再分类修复、验证并重复审查直到收敛”的收尾任务。原子问题可自动修；架构类问题按说明需用户批准。合并和推送默认关闭。若项目改动尚未隔离，或目标涉及认证、付款、生产数据等高风险区域，先不要让自动修复模式运行。
怎样验收结果
不要只看“完成”摘要：
- 打开最终报告，查看 finding 的证据路径、行号、严重性和收敛轮次；
0 findings只表示本轮没有新发现，不证明代码没有缺陷。 - 看 meta-review 的 verdict 和证据校验；
needs_revision时先解决报告矛盾或无效证据。 - 在终端检查
git status --short和git diff，确认变更都在预期隔离分支，没有意外文件或敏感信息。 - 自己重跑项目的测试、lint 或构建，确认报告中的验证命令确实执行并通过。AI 的结论不能替代项目 CI 或人工代码审查。
- 阅读被修改的代码后，再决定是否 cherry-pick、合并或推送；不要把“收敛”当作自动发布。
常见卡点
- 第一次调用先出现 onboarding： 按提示检查项目上下文与配置，不是卡死；onboarding 会写文件。
- 防御式模式拒绝开工： 查看
iterate guard pre-check的失败项，常见原因是工作树不干净、验证命令未配置或可执行程序不在 PATH。 - 验证命令报错： 先确认配置与项目脚本一致；不要让 agent 把失败测试改成跳过来制造绿灯。
- 报告引用不可信： 对照真实文件与行号。证据缺失时要求重审，不要把推测写成 bug。
- 任务跑太久： 缩小到一个模块或明确的变化范围，并设置合理轮数；完整项目多维审查可能更慢。
- 命令与客户端不匹配： 安装器负责放置 Skill 和 CLI；斜杠调用形式由宿主客户端决定。Codex 使用自己的 Skill 调用入口，不能直接照抄其他客户端的命令。
适不适合你
| 任务 | 建议 |
|---|---|
| 只想获得有路径和行号的审查报告 | 从 review-only 开始 |
| 想完成一个正常增量任务，并每一步都检查 | 使用 /iterate defensive，先确认干净隔离环境和验证命令 |
| 发布前做多维度审查、修复并复查到收敛 | 使用普通 /iterate，架构修复逐项审批 |
| 只需一处简单编辑，或无法提供可靠的自动验证命令 | 直接让编码助手完成小任务并人工复核 |
如果只需要一个范围明确的审查提示，Matt Pocock 的 code-review Skill 是另一种更窄的参考；Iterate 的区别在于它提供可选择的只读报告、自动修复/复审循环以及防御式增量编码模式。两者都不能替代你自己的测试和批准。
本文按官方文档与发布说明整理；没有将其写成本站实测或独立用户成功案例。