claudex-loop

Claudex Loop

当前对话负责需求、规划和协调。另一家提供方负责审查计划。任一提供方都可以实现；未负责实现的提供方会在全新会话中检查最终代码。

一次性确定角色

根据运行时环境识别实际宿主，不要依据 PATH、已安装的技能、对模型名称的猜测或代码仓库。两个 CLI 都可能已安装。在 Claude Code 中使用 host=claude，在 Codex 中使用 host=codex。如果无法确定运行时身份，请询问用户正在使用哪个宿主，只问一次。

宿主	需求与计划	计划审查方	默认实现方	最终检查方
Claude Code	当前 Claude 会话	Codex	Claude	全新 Codex 会话
Codex	当前 Codex 会话	Claude	Codex	全新 Claude 会话

遵从 builder=claude|codex。检查方始终是另一家提供方。即使由另一家提供方负责实现，宿主仍然是协调方。要更换规划方，请在另一宿主中开始对话；不要假装 CLI 审查方就是用户的规划对话。

模型选择独立于提供方角色。保留宿主已选定的模型。审查和实现 CLI 调用会沿用各自的配置，除非提供了 reviewer_model、builder_model 或 inspector_model；将这些参数映射为该次调用的 runner --model。同样应用显式指定的 *_effort。Fable 5.1 和 GPT-6 Astra 是合适的显式选择，但并非强制指定的固定模型。宿主 UI 中显示的模型，并不能证明单独的 CLI 会使用该模型。分别报告请求的模型信息和实际观察到的模型信息；如 CLI 默认模型仍未确定，请如实说明。发生故障时，绝不能静默改用其他模型或提供方。

启动 CLI 前，请阅读运行时参考。根据已安装的 SKILL.md 的位置解析 runner 路径，绝不要相对于被审查的项目解析。启动 runner 时使用绝对路径。

如果用户提供了 codex_cli 或 claude_cli，请将所选提供方的可执行文件路径映射到 --cli。宿主应用可能有比 PATH 中的 CLI 更新且可正常工作的二进制文件；请验证路径和版本，但不要静默更改全局安装或配置。

可调参数

参数	默认值	含义
PLAN_FILE / plan	PLAN.md	全程使用的计划路径，包括实现交接
LOG_FILE / log	PLAN-REVIEW-LOG.md	仅追加的记录
rounds / MAX_ROUNDS	5	计划审查的最大完成轮数
builder	宿主	负责实现计划的提供方
research	与任务相称	none、web 或显式选择加入的 deep
mode	full	full 包含侦察／访谈；review 从现有计划开始
inspect	on	仅当用户明确选择退出时才设为 off；并记录此选择
MAX_FIX_ROUNDS	2	报告问题或接手前，有上限的实现修复尝试次数
MAX_INSPECTION_ROUNDS	2	初次检查，以及修复后的一次检查

开始前，回显角色、路径、轮数上限、请求使用的模型及退出检查的选择。保留现有授权范围：请求制定计划并不授权实现；请求制定计划并实现则授权两者。寻求任何剩余确认之前，先完成已获授权的准备工作。

阶段 0 — 侦察

对于现有项目，检查相关代码、依赖项、调用方和共享状态的写入方。阅读现有的 CONTEXT.md / CONTEXT-MAP.md 及相关 ADR。对于全新项目，在适当时调研先例、合理的技术栈和具体故障模式。遵守明确指定的调研深度。深度多 Agent 调研需要明确选择启用，且必须有可用工具；否则采用受支持的定向调研，并说明这一限制。不要要求使用专有的 Workflow 工具，也不要硬编码调研 Agent 的模型。

通过宿主提供的目录以及在可访问时通过其他提供方记录的技能位置，发现相关技能。只记录相关的拟议依赖项。不要假定宿主的 MCP、浏览器、凭据或技能可转移到另一个 CLI。依赖构建能力之前，先确认其必需能力可用。

提供一份假设清单，其中包含来源路径或调研链接。将重要的不确定事项汇总起来，请用户更正。用户已授权的情况下，自行处理常规且可逆的选择；对于需要审批的操作，沉默不代表批准。

阶段 1 — 敲定需求

维护一份简短、可见的决策图。只询问会影响结果且尚未解决的决策。对于每个重要问题，说明建议、其重要性，以及猜错的代价。将相互独立的问题合并询问；有依赖关系的问题则按顺序询问。如果代码能够给出答案，就自行检查。若一长串决策会拖慢用户进度，提供“接受所有剩余建议”选项。

遵守现有术语表的定义；解决有歧义的领域术语。根据需要，使用 CONTEXT-FORMAT.md 维护仅包含术语表的上下文。只有针对难以撤销且不明显的权衡，才使用 ADR-FORMAT.md 记录 ADR。

编写已敲定的 PLAN_FILE，其中包含：

• 目标和可观察的验收标准。
• 具体方案、关键决策、权衡和非目标。
• 有来源依据的已确认假设及剩余风险。
• 各提供方的相关工具链要求（如有）。
• 验证：确切的证明命令及预期结果，以及必要时的手动／视觉检查。应在生成输入的程序的真实输出上证明更改有效，而不只是使用手写样例。替换代码时，使用相同输入运行旧代码和新代码并进行比较。

尽可能从代码库推导证明命令。只有在成功标准仍不明确时才提问。在仅追加的 LOG_FILE 中记录角色、模型请求、范围、授权和轮次限制。将运行诊断信息保存在代码库目录之外。

当 mode=review 时，加载提供的计划；必要时只与用户补充解决重要缺漏，然后直接开始审查；不要重新启动需求访谈。

阶段 2 — 独立审查计划

使用共享运行器的 review 模式，并提供实际的 --host、已解析的 --plan 以及可选的模型/effort。第一轮会创建一个会话。后续轮次使用 --resume <previous-successful-result.json>，并保持相同的 provider/model/effort，同时提供一份由 host 编写、包含处理意见的 --feedback 文件。绝不可使用猜测的 session id、--last 或 build 会话来充当审查者。

每个成功的响应都包含判定结果、有证据支撑的发现、实际覆盖范围和限制。将完整响应和运行器结果路径保存在 LOG_FILE 中。

• **APPROVED：**没有尚未解决的重大缺陷。批准仅适用于确切的计划路径和 SHA256。说明剩余的低优先级建议和限制；没有发现也属有效结果，但不代表已证明计划完全正确。
• **REVISE：**由 host 对每项发现进行裁定。落实合理的计划变更；拒绝缺乏依据的建议并说明理由。若变更替换了某项行为，应在整个计划中搜索被替换的条件，并修改或标记所有仍描述旧行为的段落，包括验收标准。记录处理意见，并将修订后的计划交给同一审查者。没有新证据时，避免重新争论已解决的问题。
• **BLOCKED / 进程失败 / 结果格式错误：**绝不可将其计为批准。说明实际缺失的证据或运行故障。不要盲目重试以消耗剩余轮次，也不要悄悄切换 provider。如果审查 provider 的配额已用尽，则不能改用其他模型：等待配额重置，或让用户选择下述记录未审查状态的路径。

在达到 MAX_ROUNDS 时停止。说明尚未解决的发现及 host 的立场，不要强行制造共识。计划一旦变更，就必须再次审查。开始构建前，对最终计划执行批准检查。如果用户明确选择在未获独立批准的情况下继续，则记录该例外，并使用独立的未审查规范路径；绝不可将其标记为已批准。

阶段 3 — 构建与检查

展示已审查的计划、改进之处和剩余限制。如果尚未授权实施，请先征求最终决定。使用选定的构建者，默认由 host 担任。阅读构建参考。

host 可以直接使用其常规工具实施。若使用其他构建者，则使用共享运行器的 build 模式。无论采用哪种方式，都必须记录构建前的 commit、保留用户无关的工作，并沿用相同的已解析计划和验证约定。

运行约定的证明检查，检查所有变更文件，并通过另一个 provider 的全新 inspect 会话审查结果。提供构建前的 commit 和构建者身份。接受修复后的再次检查也必须使用全新会话。记录发现和处理意见；修复后重新运行受影响的证明检查。

如果协调器接手编写代码，则其已成为构建者。必须由另一个 provider 对其变更进行全新检查；绝不可声称先前的检查覆盖了后续编辑。如果两个 provider 都贡献了代码，应记录各自的作者身份，并让双方分别检查对方的变更；不得声称任何模型独立审查了自己编写的代码。如果检查预算已用尽，则明确报告剩余发现和未经审查的编辑，交由用户决定。

展示最终差异、证明结果、检查覆盖范围、未解决的发现、偏离情况和已用轮次。遵循现有的 commit/push 授权；否则，保留具体差异以供签核。仅仅运行此流程，绝不意味着已获准向外部发布。