claudex-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claudex Loop

Claudex Loop

The current conversation owns requirements, planning and coordination. The other provider reviews the plan. Either provider can build; the provider that did not build inspects the final code in a fresh session.
当前对话负责需求、规划和协调。另一 provider 负责审查计划。任一 provider 均可进行构建;未承担构建的 provider 会在全新会话中检查最终代码。

Resolve roles once

一次性确定角色

Identify the actual host from your runtime, not PATH, installed skills, model-name guesses, or the repository. Both CLIs may be installed. Use
host=claude
in Claude Code and
host=codex
in Codex. If the runtime identity is unavailable, ask which host the user is using once.
HostRequirements and planPlan reviewerDefault builderFinal inspector
Claude CodeCurrent Claude sessionCodexClaudeFresh Codex session
CodexCurrent Codex sessionClaudeCodexFresh Claude session
Honor
builder=claude|codex
. The inspector is always the other provider. The host remains coordinator even when the other provider builds. To swap the planner, start the conversation in the other host; do not pretend a CLI reviewer is the user's planning conversation.
Model selection is independent of provider roles. Preserve the host's selected model. Review/build CLI calls inherit their own configuration unless
reviewer_model
,
builder_model
, or
inspector_model
is supplied; map these to the runner's
--model
for that invocation. Apply an explicit
*_effort
similarly. Fable 5.1 and GPT-6 Astra are suitable explicit choices, not mandatory pins. A model in the host UI does not prove which model a separate CLI will use. Report requested and observed model information separately; report an unresolved CLI default honestly. Never silently fall back to another model/provider on a failure.
Read the runtime reference before launching a CLI. Resolve its runner relative to this installed SKILL.md, never relative to the project being reviewed. Use absolute paths when launching it.
If the user supplies
codex_cli
or
claude_cli
, map the selected provider's executable path to
--cli
. A host app can have a newer working binary than the CLI on PATH; verify the path and version without silently changing global installation or configuration.
根据运行时确定实际 host,而不是根据 PATH、已安装的 skills、模型名推测或仓库。两个 CLI 可能都已安装。在 Claude Code 中使用
host=claude
,在 Codex 中使用
host=codex
。如果无法识别运行时身份,则仅询问一次用户正在使用哪个 host。
Host需求与计划计划审查方默认构建方最终检查方
Claude Code当前 Claude 会话CodexClaude全新 Codex 会话
Codex当前 Codex 会话ClaudeCodex全新 Claude 会话
遵循
builder=claude|codex
设置。inspector 始终由另一 provider 担任。即使由另一 provider 构建,host 仍负责协调。要更换计划制定方,应在另一个 host 中启动对话;不要将 CLI reviewer 冒充为用户的规划对话。
模型选择与 provider 角色无关。保留 host 所选的模型。除非提供
reviewer_model
、
builder_model
或
inspector_model
,否则审查和构建 CLI 调用会继承各自的配置;对于相应调用,将这些参数映射到 runner 的
--model
。显式指定的
*_effort
同理处理。Fable 5.1 和 GPT-6 Astra 可作为合适的显式选项,但不是必须固定的模型。host UI 中显示的模型不能证明独立 CLI 会使用哪个模型。分别报告请求的模型信息与实际观测到的模型信息;如果无法确定 CLI 默认模型,应如实说明。失败时绝不静默回退到其他模型或 provider。
启动 CLI 前,务必阅读运行时参考。runner 必须相对于这份已安装的 SKILL.md 定位,绝不能相对于被审查的项目定位。启动 runner 时使用绝对路径。
如果用户提供
codex_cli
或
claude_cli
,将所选 provider 的可执行文件路径映射到
--cli
。host app 使用的可执行文件可能比 PATH 中的 CLI 更新;应验证路径和版本,但不得静默更改全局安装或配置。

Tunables

可调参数

ArgumentDefaultMeaning
PLAN_FILE
/
plan
PLAN.md
Plan path used throughout, including the build handoff
LOG_FILE
/
log
PLAN-REVIEW-LOG.md
Append-only transcript
rounds
/
MAX_ROUNDS
5
Maximum completed plan-review rounds
builder
hostProvider implementing the plan
research
proportionate to task
none
,
web
, or explicit opt-in
deep
mode
full
full
includes recon/interview;
review
starts from an existing plan
inspect
on
off
only when the user explicitly opts out; record it
MAX_FIX_ROUNDS
2
Bounded build-fix attempts before reporting or taking over
MAX_INSPECTION_ROUNDS
2
Initial inspection plus one after fixes
Echo roles, paths, round limits, requested models and inspection opt-out before starting. Preserve existing authorization: a request to plan does not authorize building; a request to plan and implement does. Do authorized preparation before seeking any remaining sign-off.
参数默认值含义
PLAN_FILE
/
plan
PLAN.md
全程使用的计划路径,包括构建交接
LOG_FILE
/
log
PLAN-REVIEW-LOG.md
仅追加的记录
rounds
/
MAX_ROUNDS
5
最多完成的计划审查轮数
builder
host实施计划的 provider
research
与任务相称
none
、
web
,或需要明确启用的
deep
mode
full
full
包含调研/访谈;
review
从现有计划开始
inspect
on
只有用户明确选择退出时才设为
off
,并记录该选择
MAX_FIX_ROUNDS
2
报告问题或接管前,构建与修复尝试次数的上限
MAX_INSPECTION_ROUNDS
2
初次检查一次,修复后再检查一次
开始前,复述角色、路径、轮次上限、请求的模型以及检查退出选择。沿用现有授权范围:仅要求制定计划并不授权构建;同时要求制定计划并实现则授权构建。在寻求任何剩余签核之前,先完成已获授权的准备工作。

Phase 0 — Recon

阶段 0 — 调研

For existing projects, inspect relevant code, dependencies, callers and writers of shared state. Read existing
CONTEXT.md
/
CONTEXT-MAP.md
and relevant ADRs. For greenfield work, research prior art, a reasonable stack and concrete failure modes when useful. Respect an explicit research depth. Deep multi-agent research requires explicit opt-in and an available tool; otherwise use supported targeted research, and report the limitation. Do not require a proprietary Workflow tool or hard-code a research-agent model.
Discover relevant skills through the host's available catalog and the other provider's documented skill locations when accessible. Record only relevant proposed dependencies. Do not assume host MCP, browser, credentials or skills transfer to the other CLI. Verify required build capabilities before relying on them.
Present one assumptions ledger with source paths or research links. Ask for corrections to material uncertainties as a batch. Resolve routine reversible choices yourself when the user has authorized the work; silence is not approval of an action requiring approval.
对于现有项目,检查相关代码、依赖关系、调用方以及共享状态的写入方。阅读现有的
CONTEXT.md
/
CONTEXT-MAP.md
和相关 ADR。对于全新项目,在有帮助时调研现有方案、合理的技术栈和具体的失败模式。遵循明确指定的调研深度。深度多 Agent 调研需要用户明确启用且具备可用工具;否则使用受支持的定向调研,并报告相关限制。不得要求使用专有 Workflow 工具,也不得硬编码某个 research-agent 模型。
通过 host 的可用 skill catalog,以及在可访问时另一 provider 有文档说明的 skill 位置,发现相关 skills。仅记录相关且建议采用的依赖项。不要假定 host 的 MCP、browser、credentials 或 skills 会传递给另一 CLI。在依赖构建能力之前,先验证这些能力是否可用。
提交一份包含来源路径或调研链接的假设清单。将实质性不确定项集中列出,一次性请求更正。当用户已授权工作时,常规且可逆的选择由你自行决定;沉默不构成对需要审批操作的批准。

Phase 1 — Settle requirements

阶段 1 — 确定需求

Maintain a short visible decision map. Ask only about unresolved decisions that change the outcome. For each consequential question, give the recommendation, why it matters, and the cost of guessing wrong. Batch independent questions; ask dependent ones sequentially. If the code can answer, inspect it instead. Offer “accept all remaining recommendations” when a long decision list would slow the user down.
Respect existing glossary definitions; resolve ambiguous domain language. Maintain glossary-only context lazily using CONTEXT-FORMAT.md. Record an ADR only for expensive-to-reverse, non-obvious trade-offs using ADR-FORMAT.md.
Write the resolved
PLAN_FILE
with:
  • Goal and observable acceptance criteria.
  • Concrete approach, key decisions, trade-offs and non-goals.
  • Confirmed assumptions with sources and remaining risks.
  • Relevant toolchain requirements per provider, if any.
  • Verification: exact proof command(s), expected results, and manual/visual checks when needed. Prove the change on the real output of the program that produces its input, not only on hand-written samples. When code is replaced, run the old and new code on the same inputs and compare.
Derive proof commands from the repository when possible. Ask only when what counts as success remains unclear. Start the append-only
LOG_FILE
with roles, model requests, scope, authorization and round limits. Keep run diagnostics outside the checkout.
With
mode=review
, load the supplied plan, fill only material gaps with the user as needed, and proceed directly to review; do not restart a requirements interview.
维护一份简短且对用户可见的决策图。只询问尚未解决且会影响结果的事项。对于每个关键问题,给出建议、该问题的重要性以及猜错的代价。将相互独立的问题集中提出;有依赖关系的问题则依次询问。如果代码能够回答问题,应检查代码而不是提问。当冗长的决策清单会拖慢用户时,提供“接受其余所有建议”的选项。
遵循现有的 glossary 定义;厘清有歧义的领域用语。使用 CONTEXT-FORMAT.md 按需维护仅包含 glossary 内容的上下文。仅针对难以逆转且并不明显的权衡,使用 ADR-FORMAT.md 记录 ADR。
将已确定内容写入
PLAN_FILE
,其中包括:
  • 目标和可观察的验收标准。
  • 具体方案、关键决策、权衡和非目标。
  • 已确认的假设、来源和剩余风险。
  • 各 provider 的相关工具链要求(如有)。
  • 验证:确切的验证命令、预期结果,以及必要的人工/视觉检查。应在生成输入数据的程序的真实输出上验证变更,而不只使用手写样本。替换代码时,应让新旧代码处理相同输入并进行对比。
尽可能从仓库推导验证命令。只有在成功标准仍不明确时才询问用户。在仅追加的
LOG_FILE
开头记录角色、模型请求、范围、授权和轮次上限。将运行诊断信息保存在 checkout 之外。
使用
mode=review
时,加载所提供的计划,仅在必要时与用户确认并补齐实质性缺口,然后直接进入审查;不要重新开始需求访谈。

Phase 2 — Independent plan review

阶段 2 — 独立计划审查

Use the shared runner in
review
mode with the actual
--host
, resolved
--plan
and optional model/effort. First round creates a session. Further rounds use
--resume <previous-successful-result.json>
with the same provider/model/effort and a host-authored
--feedback
file containing dispositions. Never use a guessed session id,
--last
, or a build session as a reviewer.
Each successful response contains a verdict, evidence-backed findings, actual coverage and limitations. Preserve the entire response and runner result path in
LOG_FILE
.
  • APPROVED: no unresolved material defects. Approval is bound to the exact plan path and SHA256. Present remaining low-priority advice and limitations; zero findings is valid and is not proof of exhaustive correctness.
  • REVISE: the host arbitrates each finding. Implement warranted plan changes; reject unsupported suggestions with reasons. When a change replaces a behaviour, search the whole plan for the replaced condition and change or mark every passage that still states the old behaviour, acceptance criteria included. Record dispositions and send the revised plan to the same reviewer. Avoid relitigating resolved points without new evidence.
  • BLOCKED / failed process / malformed result: never count this as approval. Explain the actual missing evidence or operational failure. Do not burn remaining rounds on blind retries or switch providers silently. If the reviewing provider is out of quota, there is no cross-model fallback: wait for the quota to reset, or let the user choose the recorded unreviewed path below.
Stop at
MAX_ROUNDS
. Present unresolved findings and the host's position instead of manufacturing convergence. A changed plan requires another review. Before building, run the approval check on the final plan. If the user explicitly chooses to proceed without independent approval, record that override and use the standalone unreviewed-spec path; never label it approved.
使用共享 runner 的
review
模式,并传入实际的
--host
、解析后的
--plan
以及可选的 model/effort。第一轮创建会话。后续轮次使用
--resume <previous-successful-result.json>
,保持相同的 provider/model/effort,并提供由 host 编写且包含处置结论的
--feedback
文件。绝不能使用猜测的 session ID、
--last
,也不能将 build 会话用作 reviewer。
每个成功响应都包含裁决结果、有证据支持的发现、实际覆盖范围和限制。将完整响应和 runner 结果路径保存在
LOG_FILE
中。
  • APPROVED: 没有尚未解决的实质性缺陷。批准仅对确切的计划路径和 SHA256 有效。展示剩余的低优先级建议和限制;零项发现是有效结果,但不代表已经证明完全正确。
  • REVISE: 由 host 逐项裁决发现。落实有依据的计划变更;拒绝无依据的建议并说明理由。当某项变更替换了一种行为时,在整个计划中搜索被替换的条件,并将所有仍描述旧行为的段落(包括验收标准)修改或明确标记。记录处置结果,并将修订后的计划发送给同一 reviewer。没有新证据时,不要重新争论已解决的事项。
  • BLOCKED / 流程失败 / 结果格式错误: 绝不将其视为批准。说明实际缺失的证据或操作失败。不要将剩余轮次用于盲目重试,也不要静默切换 provider。如果 reviewer provider 的配额耗尽,则不存在跨模型 fallback:等待配额重置,或让用户选择下文记录的未审查路径。
达到
MAX_ROUNDS
时停止。列出未解决的发现和 host 的立场,而不是强行制造一致结论。计划发生变更后,需要再次审查。构建前,对最终计划执行批准检查。如果用户明确选择在未经独立批准的情况下继续,则记录该例外决定,并使用独立的未审查规格路径;绝不将其标记为已批准。

Phase 3 — Build and inspect

阶段 3 — 构建与检查

Present the reviewed plan, improvements and remaining limits. If implementation is not already authorized, ask for that final decision. Use the selected builder, defaulting to the host. Read the build reference.
The host can implement directly with its normal tools. For a different builder, use the shared runner's
build
mode. Either path must capture the pre-build commit, preserve unrelated user work, and carry the same resolved plan and verification contract.
Run the agreed proof checks, inspect all changed files and review the result through the other provider in a fresh
inspect
session. Supply the pre-build commit and builder identity. Reinspection after accepted fixes also uses a fresh session. Log findings and dispositions; rerun affected proof checks after fixes.
If the coordinator takes over coding, it has become a builder. Require a fresh other-provider inspection of its changes; never describe the earlier inspection as covering later edits. If both providers contributed code, record authorship and have each inspect the other's changes; do not claim any model independently reviewed code it authored. If the inspection budget is exhausted, report remaining findings and unreviewed edits explicitly for the user's decision.
Present the final diff, proof results, inspection coverage, unresolved findings, deviations and rounds used. Honor existing commit/push authorization; otherwise leave the concrete diff ready for sign-off. External publication is never implied merely by running the loop.
展示经审查的计划、改进内容和剩余限制。如果尚未获得实现授权,就此征求最终决定。使用选定的 builder,默认采用 host。阅读构建参考。
host 可以直接使用常规工具实施。如果选择不同的 builder,则使用共享 runner 的
build
模式。任一路径都必须记录构建前的 commit,保护与任务无关的用户工作,并沿用同一份已确定计划和验证约定。
执行约定的验证检查,检查所有变更文件,并通过另一 provider 在全新的
inspect
会话中审查结果。提供构建前的 commit 和 builder 身份。接受修复后的复检也使用全新会话。记录发现和处置结果;修复后重新运行受影响的验证检查。
如果 coordinator 接管编码,它就成为 builder。必须由另一 provider 在全新会话中检查其变更;绝不将早期检查描述为覆盖了后续编辑。如果两个 provider 都贡献了代码,应记录代码作者归属,并让它们分别检查对方的变更;不要声称任何模型独立审查了其亲自编写的代码。如果检查预算已耗尽,应明确报告剩余发现和未经检查的编辑,交由用户决定。
展示最终 diff、验证结果、检查覆盖范围、未解决的发现、偏差以及已使用的轮数。遵循已有的 commit/push 授权;否则保留具体 diff,等待签核。仅运行本 loop 绝不代表获得外部发布授权。