2.1 循环的四大阶段：发现、规划、执行、验证 — Loop Engineering 的核心控制流

本节导读：深入解析循环的四个核心阶段（Discover → Plan → Execute → Verify），理解每个阶段的职责、设计原则和常见陷阱，掌握构建可靠循环控制流的方法。

学习目标

• 深入理解循环四阶段（discover → plan → execute → verify）的具体职责
• 掌握每个阶段的设计原则和最佳实践
• 学会识别和避免各阶段的常见陷阱
• 理解循环控制流与 ReAct 模式的关系

核心概念

循环工程的控制流可以用一个简洁的伪代码表示：

state = init_state(goal)

for step in range(MAX_STEPS):
    thought = model.reason(state)        # DISCOVER + PLAN
    action = model.choose_action(state)  # PLAN + EXECUTE
    result = tools.execute(action)       # EXECUTE
    state = update(state, result)       # VERIFY
    state = compact(state)               # 上下文管理

    if verifier.passes(state):           # VERIFY
        return success(state)
    if no_progress(state) or budget.exhausted():
        return escalate_to_human(state)

return escalate_to_human(state)
​

正如 Tosea.ai 的指南所说："Almost everything interesting in loop engineering is a decision about one of these lines."（循环工程中几乎所有有趣的事情，都是对其中某一行代码的决策。）

阶段一：Discover（发现）——"我现在在哪？"

发现阶段的目标是让 Agent 获取对当前状态的准确认知。这是循环的起点，也是最容易出问题的地方——如果 Agent 对现状的认知有偏差，后续所有阶段都会建立在错误基础上。

核心职责：

• 读取项目状态（测试结果、错误日志、Issue 列表）
• 分析当前代码质量和结构
• 识别需要修复或改进的具体问题
• 与之前的循环状态对比（如果有外部持久化状态）

设计原则：

1. 确定性优先：读取的来源应该产生确定性的输出（测试通过/失败、编译成功/错误）
2. 多维度发现：不只看测试，还要看 lint、类型检查、代码覆盖率
3. 增量发现：优先关注自上次循环以来的变化，而非从头扫描

常见陷阱：

• ⚠️ 依赖 Agent 的"感觉"而非实际运行检查
• ⚠️ 忽略了外部变化（他人提交的代码、更新的依赖）
• ⚠️ 过度发现导致 Token 浪费（扫描了不相关的文件）

阶段二：Plan（规划）——"下一步做什么？"

规划阶段是 LLM 发挥核心作用的环节——分析发现的信息，推理出最佳的行动方案。

核心职责：

• 分析发现阶段的输出，确定优先级
• 选择具体的修复策略或任务执行方式
• 预估行动的影响范围
• 考虑历史尝试（避免重复失败路径）

设计原则：

1. 最小变更原则：优先选择改动最小的修复方案
2. 先易后难：先处理确定的修复，再处理不确定的
3. 历史感知：查看外部状态文件，避免重复已失败的尝试
4. 可验证的规划：每个计划步骤应该对应一个可验证的输出

常见陷阱：

• ⚠️ 过度工程化：简单 Bug 搞成了重构（偏离了循环目标）
• ⚠️ 忽略依赖关系：修复 A 引入了 B 的新 Bug
• ⚠️ 没有使用 Skills 中的项目知识（重复推导约定）

阶段三：Execute（执行）——"去做"

执行阶段是 Agent 与真实环境交互的环节——编辑代码、运行命令、创建文件。

核心职责：

• 按照计划执行具体的代码修改或命令
• 确保变更在隔离环境中进行（worktree）
• 记录执行过程中的关键信息
• 处理执行中的意外错误

设计原则：

1. 原子性：每个执行步骤应该是可回滚的
2. 隔离性：使用 worktree 确保不影响主分支
3. 最小权限：Agent 只应该拥有完成任务所需的最小权限
4. 可追踪：所有变更都应通过 Git 记录

常见陷阱：

• ⚠️ 修改测试来通过测试（而非修改实现代码）
• ⚠️ 在主分支上直接修改（应该使用 worktree）
• ⚠️ 一次修改过多文件（难以回滚和审查）

阶段四：Verify（验证）——"做得怎么样？"

验证阶段是循环的决策点——根据验证结果决定循环继续还是停止。

核心职责：

• 运行验证器（测试、lint、类型检查等）
• 与目标对比，评估完成度
• 检测无进展（是否在原地打转）
• 决定循环继续、停止还是升级

设计原则：

1. 确定性验证：验证标准应该可以自动检查，不需要主观判断
2. 多重验证：不止一个验证维度
3. 独立验证：验证器独立于执行者（maker-checker 分离）
4. 清晰的阈值：通过/失败有明确的标准

# 好的验证标准
verifiers = [
    {"name": "测试套件", "command": "npm test", "pass_on": 0},
    {"name": "TypeScript", "command": "npx tsc --noEmit", "pass_on": 0},
    {"name": "ESLint", "command": "npx eslint src/", "pass_on": 0},
    {"name": "覆盖率", "command": "npx jest --coverage", "min": 80},
]

# 差的验证标准（不要这样做）
# "代码看起来不错"  ← 主观判断，不可自动检查
# "尽量提高性能"     ← 无明确阈值
# "改善代码质量"     ← 永远不知道何时停止
​

环境准备 / 前置知识

• 已完成第一章的学习
• 了解基本软件工程概念（测试、版本控制、CI/CD）
• 有 Claude Code 或 Codex 的实际使用经验

分步实战

步骤 1：实现完整的四阶段循环

"""
four_phase_loop.py - 完整的四阶段循环实现
展示 Discover → Plan → Execute → Verify 的完整流程
"""
import subprocess
import json
from dataclasses import dataclass, field
from typing import Optional

@dataclass
class LoopState:
    """循环状态 - 贯穿四个阶段"""
    goal: str
    round: int = 0
    discoveries: list = field(default_factory=list)
    plan: Optional[str] = None
    actions_taken: list = field(default_factory=list)
    verify_results: list = field(default_factory=list)
    status: str = "idle"

class FourPhaseLoop:
    def __init__(self, goal: str, project_path: str):
        self.state = LoopState(goal=goal)
        self.project_path = project_path
        self.max_rounds = 10

    def discover(self):
        """阶段一：发现"""
        print(f"\n🔍 [Discover] 第 {self.state.round + 1} 轮发现...")

        # 1. 运行测试
        test = subprocess.run(
            ["npm", "test", "--", "--json", "--silent"],
            cwd=self.project_path,
            capture_output=True, text=True, timeout=60
        )

        # 2. 运行类型检查
        tsc = subprocess.run(
            ["npx", "tsc", "--noEmit"],
            cwd=self.project_path,
            capture_output=True, text=True, timeout=30
        )

        # 3. 汇总发现
        test_passed = test.returncode == 0
        type_ok = tsc.returncode == 0

        discovery = {
            "tests_passed": test_passed,
            "type_check_passed": type_ok,
            "test_output": test.stdout[-500:] if not test_passed else "All passed",
            "type_errors": tsc.stdout[-300:] if not type_ok else "None"
        }

        self.state.discoveries.append(discovery)
        print(f"  测试: {'✅' if test_passed else '❌'}")
        print(f"  类型: {'✅' if type_ok else '❌'}")
        return discovery

    def plan(self, discovery):
        """阶段二：规划"""
        print(f"\n🧠 [Plan] 基于发现制定计划...")

        if discovery["tests_passed"] and discovery["type_check_passed"]:
            self.state.plan = "所有检查通过，无需操作"
            print("  计划: 无需操作，目标已达成")
            return self.state.plan

        # 简化版规划（实际中由 LLM 完成）
        actions = []
        if not discovery["tests_passed"]:
            actions.append("分析测试失败输出，定位根因")
            actions.append("修复相关代码")
            actions.append("重新运行测试验证")
        if not discovery["type_check_passed"]:
            actions.append("修复类型错误")

        self.state.plan = " → ".join(actions)
        print(f"  计划: {self.state.plan}")
        return self.state.plan

    def execute(self, plan):
        """阶段三：执行（示意，实际由 Agent 完成）"""
        print(f"\n🔧 [Execute] 执行计划...")

        # 实际中这里调用 AI Agent API
        # 示例：subprocess.run(["claude", "-p", plan, "--allowedTools", "write,edit"])
        print("  [Agent 正在分析和执行...]")
        self.state.actions_taken.append({
            "round": self.state.round + 1,
            "plan": plan,
            "status": "executed"
        })

    def verify(self):
        """阶段四：验证"""
        print(f"\n✅ [Verify] 验证结果...")

        # 重新运行所有验证器
        test = subprocess.run(
            ["npm", "test"],
            cwd=self.project_path,
            capture_output=True, text=True, timeout=60
        )
        tsc = subprocess.run(
            ["npx", "tsc", "--noEmit"],
            cwd=self.project_path,
            capture_output=True, text=True, timeout=30
        )

        result = {
            "tests_passed": test.returncode == 0,
            "type_check_passed": tsc.returncode == 0,
            "all_passed": test.returncode == 0 and tsc.returncode == 0
        }

        self.state.verify_results.append(result)
        print(f"  综合: {'✅ 全部通过' if result['all_passed'] else '❌ 未达标'}")
        return result

    def run(self):
        """运行完整循环"""
        self.state.status = "running"
        print(f"\n{'='*50}")
        print(f"🎯 目标: {self.state.goal}")
        print(f"🔄 最大轮次: {self.max_rounds}")
        print(f"{'='*50}")

        for i in range(self.max_rounds):
            self.state.round = i

            discovery = self.discover()
            plan = self.plan(discovery)

            if "无需操作" in plan:
                self.state.status = "success"
                break

            self.execute(plan)
            result = self.verify()

            if result["all_passed"]:
                self.state.status = "success"
                print(f"\n🎉 循环在第 {i+1} 轮达成目标!")
                break

            # 无进展检测
            if i >= 2:
                recent = [v["tests_passed"] for v in self.state.verify_results[-3:]]
                if all(not x for x in recent):
                    self.state.status = "stuck"
                    print(f"\n⚠️ 连续 3 轮无进展，循环停止")
                    break
        else:
            self.state.status = "max_rounds"
            print(f"\n⚠️ 达到最大轮次 {self.max_rounds}")

        return self.state
​

步骤 2：实践不同阶段的优化

# 在 Claude Code 中体验各阶段
claude

# 1. 纯 Discover：只看不做
> 分析当前项目的测试状态和类型检查结果，不要修改任何文件

# 2. Plan + Execute：有计划地执行
> 阅读上一个分析结果，制定修复计划，然后执行修复

# 3. 完整循环：Discover → Plan → Execute → Verify
> /goal "修复所有失败测试和类型错误"
​

常见问题 FAQ

Q1：四个阶段是否一定要严格按顺序执行？

A：绝大多数情况下是的，但允许回退。典型情况：Execute 阶段发现了一个 Plan 阶段没考虑到的依赖关系，需要回退到 Plan 重新规划。关键是每一轮的四个阶段是有序的，但跨轮之间可以基于新的发现调整计划。

Q2：Discover 阶段是否可以缓存之前的发现结果？

A：应该缓存，但要验证是否过时。外部状态文件（如 progress.md）可以记录上次循环的发现，新一轮开始时先读取再验证。这避免了每轮从头发现的开销。但如果有其他人修改了代码或依赖更新了，缓存可能过期——因此 Discover 阶段仍然需要至少一次快速验证。

Q3：Verify 阶段发现了部分通过怎么办？

A：这是最常见的情况。处理方式：(1) 记录哪些验证通过了，哪些没通过；(2) 下一轮的 Discover 聚焦于未通过的部分；(3) 避免修改已经通过的验证相关代码（防止回归)。这就是为什么验证标准应该分维度设置——你不需要所有维度同时通过才开始工作，可以逐个击破。

最佳实践与避坑

• Discover 要高效：只获取必要信息，避免扫描全项目
• Plan 要保守：最小变更优于大胆重构
• Execute 要可追踪：每一步都通过 Git 记录
• Verify 要严格：宁可误报不通过，也不要漏掉问题
• 四阶段是迭代单元：每轮结束应该有明确的结论

本节小结

本节深入解析了循环的四个核心阶段。Discover 提供"我在哪"的准确认知，Plan 决定"下一步做什么"，Execute 与真实环境交互，Verify 判断"做得好不好"。四个阶段构成一个完整的控制流单元，每轮循环重复执行，直到目标达成或触发停止条件。

下一节我们将介绍六大基础设施原语——让循环从理论走向可落地的工程实践。

延伸阅读

• Oracle: The Core Architecture Behind Autonomous AI Systems
• Tosea.ai: Complete Guide 2026
• 相关章节：2.2 六大基础设施原语

关键词：Loop Engineering, 循环四阶段, Discover, Plan, Execute, Verify, ReAct, 验证器, 控制流, Agent Loop, 教程, 架构

难度：进阶

预计阅读：15 分钟