plan-loop

Plan Loop

一个规划循环：它会将提示词转换为足够详细且准确、可交给较低层级模型执行的计划。产物就是计划——plan.md（布局）+ tasks.json（按 PR 规模划分的任务，每项都包含文件、测试、依赖项和原子子任务）。反馈信号分为两部分，类似于仓库中的其他评估循环：一个客观门禁（tools/validate_plan.py——检查架构形状、依赖图无环、拓扑顺序有效以及组件覆盖完整）和一个定性门禁（由单独的首席工程师 Agent 评审对齐程度、拆分方式、可测试性，以及初级工程师能否在不猜测的情况下执行每项任务）。你从第一性原理出发构建计划，对其进行验证和评审，并持续修订，直到评审通过。这是更大规模的提示词 → 计划 → 执行 → 调试流水线中的计划阶段；计划准备好交接后，流程即停止。

适用场景

用于将功能／Bug／重构提示词转换为基于真实仓库的可执行计划——当目标是交接产物，供下游执行者（或较小的模型）逐项实现时。对于按字面执行的实现者而言，计划的质量取决于其中最薄弱的任务，因此该循环优化的是可执行性，而非文案。

默认情况下：以提供的 <repo> 为依据制定计划，并让首席工程师的评审推动修订。如果某项关键决策无法从提示词或仓库中确定，就将其记录为供人工处理的 open_question，而不要猜测。不适用于编写代码（使用下游执行循环），也不适用于研究／实验提案（使用 research-proposal）。

设置

以交互方式确定绑定项。如果存在 loop.run.yaml，加载它，用一行确认各项值，然后跳转到循环。否则：在 Claude Code 中（可使用 AskUserQuestion 工具），为每项绑定推断可能的值并给出建议；在其他宿主环境中，以引用式提示逐项询问。然后写入 loop.run.yaml（格式：examples/run.example.yaml），并在创建其他任何文件之前进行确认。

绑定项	含义	默认值	推断方式
<prompt>	要规划的任务——文件路径或内嵌文本	—	用户的请求
<repo>	计划所针对的项目；读取以了解真实环境和约定（绝不编辑）	.	正在处理的仓库
<plan_file>	人类可读的计划布局（Markdown）	<sandbox_root>/plan.md	—
<tasks_file>	结构化任务，根据 schemas/plan.schema.json 验证	<sandbox_root>/tasks.json	—
<pr_loc>	每项任务的目标代码行数（按 PR 规模；任务可超出此范围）	100-400	—
<sandbox_root>	计划、任务和记录文件的存放位置	./sandbox	—
<budget>	最大优化轮数	5	—

<skill_dir> 是此技能的安装目录；写入 loop.run.yaml 时，请替换为实际路径。 客观门禁会在每个周期运行：

python3 <skill_dir>/tools/validate_plan.py --tasks <tasks_file>

它会打印一个 JSON 对象 {ok, errors, warnings, stats}——只有当 ok 为 true（没有错误）时，计划才会被视为已准备就绪。

循环

复制此检查清单，并逐项勾选。

制定计划（第 0 轮——第一性原理）：

• 摸清情况。 阅读 <prompt> 并检查 <repo>，以确认实际情况：语言、包管理器、 运行时/OS、测试命令，以及可复用的现有模块/惯例。能检查的都检查；不要 臆测可读取的信息。
• 分解。 从第一性原理梳理各个组件——目标；最终状态 / 完成定义；非目标；环境；构建模块；模块之间的接口/契约； 工具；包；数据/资源；复用（现有代码 + 已安装的技能）； 待解决问题。递归拆分任何大到无法整体推理的组件。
• 任务（PR 规模）。 将工作拆分为多个任务，每个任务约为 <pr_loc>，相当于一个 PR。对 每个任务记录：它服务的组件、描述、构建模块/工具/包、要创建或修改的确切 files、用于证明其正确性的 tests、acceptance_criteria，以及 estimated_loc。
• 排序。 填写每个任务的 depends_on，然后计算拓扑 order（每个任务都排在其 依赖项之后）。
• 子任务。 将每个任务拆分为初级开发人员无需进一步决策即可完成的原子子任务—— “创建文件 X”、“定义函数 f(args) -> T”、“将 f 接入 Y”。
• 编写 + 验证。 编写 <plan_file> 和 <tasks_file>，然后运行 tools/validate_plan.py； 在首次评审前修复所有错误，并认真评估所有警告。记录基线台账行。

完善（重复，直到计划通过或达到 <budget>）：

• 评审。 使用提示词、仓库、plan.md、tasks.json、最新的 validate_plan.py 输出，以及此主机上已安装技能的列表，启动首席工程师（启动失败则降级，roles/principal-engineer.md）。它将返回结构化评审 （schemas/critique.schema.json）：结论、评分、问题（阻塞/主要/次要，每项均附修复方案）、 覆盖缺口和建议技能。
• 修订。 修复所有阻塞和主要问题——重新分解、调整规模、重新排序、 添加测试、锁定包版本，并补充具体签名/路径/数据形状，确保初级开发人员不会出错。 重新运行 tools/validate_plan.py。追加一行台账。
• 停止：评审结论为 pass（没有阻塞或主要问题）且验证器无错误——计划即可交付执行。否则继续循环，最多达到 <budget>；如果评分停滞且只剩次要问题，则停止，并将它们记录为待处理备注。

停止时，交付物为 <plan_file> + <tasks_file>（以及供人工处理的任何 open_questions），可由下游执行循环或较低层级模型按 order 逐个执行任务。

计划产物

<tasks_file>（tasks.json）——可由机器执行的计划；完整契约见 schemas/plan.schema.json。 简略结构：

{
  "objective": "...", "end_state": "...", "non_goals": ["..."],
  "environment": {"language": "python", "package_manager": "uv", "test_command": "pytest -q"},
  "components": [{"id": "c1", "name": "config", "description": "load + validate config"}],
  "open_questions": ["which auth provider?"],
  "tasks": [
    {"id": "T1", "title": "config loader", "serves": ["c1"], "description": "...",
     "building_blocks": ["dataclass Config"], "tools": ["pytest"], "packages": ["pyyaml"],
     "files": [{"path": "src/config.py", "action": "create", "what": "Config + load()"}],
     "subtasks": [{"id": "T1.1", "description": "define load(path) -> Config"}],
     "tests": [{"description": "load() parses a valid file", "kind": "unit"}],
     "acceptance_criteria": ["invalid config raises ConfigError"],
     "depends_on": [], "estimated_loc": 180, "suggested_skills": []}
  ],
  "order": ["T1"]
}

<plan_file>（plan.md）——面向人工的布局：目标、最终状态、非目标、环境、 各组件、按 order 排列的任务表（id · 标题 · 服务对象 · depends_on · 预估 LOC）、风险/待解决问题，以及一行指向 tasks.json 的“执行方式”说明。它与 tasks.json 保持一致；tasks.json 是执行器使用的事实来源。

台账

<sandbox_root>/ledger.tsv，以制表符分隔，自由文本中不得使用逗号。表头 iter phase verdict score blocking major change：

iter	phase	verdict	score	blocking	major	change
0	build	-	-	-	-	first-principles decomposition: 6 components, 8 tasks, validator ok
1	critique	revise	72	1	2	PE: T3 bundles 2 PRs; T5 has no real test; nothing covers config loading
2	revise	-	-	-	-	split T3 -> T3a/T3b; added retry test to T5; added T9 config loader; reordered
3	critique	pass	90	0	0	PE: solid; one minor naming nit recorded as an open note

报告评审通过时所在轮次的最终计划（若到达 <budget>，则报告达到的最高评分）。

约束

• 仅制定计划，不要实施。 不得在 <repo> 中编写生产代码、脚手架或文件；输出为 plan.md + tasks.json。实施和调试属于后续循环。
• 每项陈述都必须以真实的仓库／环境为依据。 不要臆造软件包、文件、API 或命令；请对照 <repo> 核实。确实未知的内容应作为 open_question 留给人工处理，而不是猜测——自信地写出错误内容的计划，远不如指出信息缺口的计划。
• 任务应控制在 PR 规模且可独立完成。 每项任务至少关联 1 个组件，并包含测试和验收标准；每个子任务都必须是原子任务。应针对会照字面执行、不会自行补全信息的实施者进行优化。
• 保持评审者独立。 主工程师评审自己未编写的计划（在 Claude Code 中，spawn-or-degrade 可提供真正的隔离）；绝不能让作者自行批准自己的计划。
• 仅在 <sandbox_root> 中编辑（计划、任务、日志）；<repo> 仅作为只读上下文。持续运行循环，直到评审通过或达到 <budget>，期间不要暂停询问是否继续。

角色

roles/principal-engineer.md — 对抗式计划评审者。采用 spawn-or-degrade：在 Claude Code 中使用 Agent/Task 工具启动真正隔离的子 Agent；否则在当前上下文中担任该角色。该角色只读，依据固定标准进行评判，并返回通过 schemas/critique.schema.json 验证的 JSON。向其提供宿主环境已安装的技能列表，以便其建议复用；如果无法获取该列表，则直接跳过 suggested_skills。