1.5 第一循环：动手实践你的第一个 Loop — 从设计到验证的完整闭环

本节导读：通过一个完整的实战项目，从循环设计、验证器构建、Skills 编写到结果审查，完整体验 Loop Engineering 的工作流程。

学习目标

• 完成一个端到端的 Loop Engineering 实战项目
• 掌握循环设计文档的编写方法
• 理解 Skills 在循环中的作用和编写技巧
• 学会审查和优化循环的运行结果

核心概念

一个完整的 Loop Engineering 项目包含四个阶段：

环境准备 / 前置知识

• 已完成 1.1-1.4 节
• Claude Code 或 Codex 已安装并配置
• 准备一个真实的代码项目（推荐使用你自己的项目）

分步实战

步骤 1：设计循环文档

在启动循环之前，先写一份循环设计文档——这是循环工程最重要的步骤：

# Loop 设计文档：修复 Payment 模块 Bug

## 目标
修复 src/payment/ 目录下所有已知的 Bug，确保所有测试通过。

## 验证标准（Verifiable Stopping Criteria）
1. `npm test -- --testPathPattern=payment` 全部通过
2. TypeScript 编译零错误：`npx tsc --noEmit`
3. ESLint 零 error：`npx eslint src/payment/`

## 停止条件
- 成功：以上三个验证标准全部满足
- 升级：连续 3 轮无测试改善，或单轮修复引入 2+ 新失败
- 硬限：最多 8 轮

## 循环范围
- 包含：src/payment/ 下的 Bug 修复
- 排除：重构、性能优化、新功能（除非修复 Bug 必须）

## 参考资料
- .claude/skills/payment.md（项目规范）
- docs/payment-architecture.md（架构文档）
- GitHub Issues #123, #145, #167（已知 Bug）
​

步骤 2：编写 Skills 文件

# 创建 Skill 目录
mkdir -p .claude/skills

# 编写 payment Skill
cat > .claude/skills/payment.md << 'EOF'
# Payment 模块开发规范

## 代码规范
- 使用 TypeScript strict 模式
- 所有金额计算使用 Decimal.js，禁止浮点数运算
- 错误码格式：PAYMENT_<TYPE>_<DETAIL>
  - 例如：PAYMENT_VALIDATION_AMOUNT_ZERO
  - 例如：PAYMENT_TIMEOUT_GATEWAY

## 测试要求
- 每个公开方法至少 3 个测试用例
- 必须覆盖边界条件：0 金额、负数金额、极大金额
- Mock 外部依赖（Stripe API、数据库）
- 测试文件位置：src/payment/__tests__/

## 已知问题模式
- 金额四舍五入错误 → 使用 Decimal.js 的 toFixed
- 时区导致日期比较失败 → 统一使用 UTC
- 并发修改导致竞态 → 使用乐观锁
- 超时后重试 → 指数退避，最多 3 次

## 禁止事项
- 不要修改测试来让测试通过——修改实现代码
- 不要删除 TODO 注释，改为修复并移除
- 不要引入新的外部依赖（需人工审批）
EOF
​

步骤 3：启动循环

# 启动 Claude Code
claude

# 使用 /goal 启动循环
> /goal "按照 .claude/skills/payment.md 规范，修复 src/payment/ 下所有 Bug。验证标准：npm test -- --testPathPattern=payment 全通过，tsc --noEmit 零错误，eslint 零 error。最多 8 轮。连续 3 轮无进展则停止。"

# 或者使用 Skill 引用（更简洁）
> /goal "$payment-fix" --max-rounds 8
​

步骤 4：监控循环运行

循环运行时，观察以下关键指标：

## 循环监控清单

每轮检查：
- [ ] Agent 是否在范围内工作（没有偏离到其他模块）
- [ ] 每轮修复是否有实际改善（失败数减少）
- [ ] 是否引入了新的失败（回归）
- [ ] 验证器的判断是否准确

异常信号：
- ⚠️ 连续 2 轮修复同一个 Bug → 可能是思路错误
- ⚠️ 修复引入了更多失败 → 需要人工介入
- ⚠️ Agent 在修改测试文件而非源代码 → Skills 不够明确
​

步骤 5：审查结果

循环完成后，必须人工审查产出的每一处代码变更：

# 查看变更
git diff

# 逐个检查修改的文件
git diff --stat

# 确认测试真的通过了（独立于 Agent 的验证）
npm test -- --testPathPattern=payment

# 运行完整测试套件确认无回归
npm test
​

完整示例：多目标循环设计

当需要循环处理多个目标时，使用编排策略：

"""
multi_goal_loop.py - 多目标循环编排
"""
from enum import Enum
import subprocess

class GoalStatus(Enum):
    PENDING = "pending"
    RUNNING = "running"
    DONE = "done"
    FAILED = "failed"
    SKIPPED = "skipped"

def multi_goal_loop(goals: list[dict]):
    """
    多目标循环编排器
    每个 goal 独立运行，失败不影响其他目标
    """
    results = {}

    for goal in goals:
        print(f"\n{'='*60}")
        print(f"🎯 目标: {goal['name']}")
        print(f"验证: {goal['verifier']}")
        print(f"{'='*60}")

        results[goal['name']] = GoalStatus.RUNNING

        # 启动子循环（实际中调用 Agent API）
        for round_num in range(goal.get('max_rounds', 6)):
            print(f"  Round {round_num + 1}...")

            # 验证
            verify_cmd = goal['verifier']
            result = subprocess.run(
                verify_cmd,
                shell=True,
                capture_output=True, text=True
            )

            if result.returncode == 0:
                results[goal['name']] = GoalStatus.DONE
                print(f"  ✅ 达成!")
                break
        else:
            results[goal['name']] = GoalStatus.FAILED
            print(f"  ❌ 未能达成，需人工介入")

    # 汇总
    print(f"\n{'='*60}")
    print("📊 循环执行汇总")
    for name, status in results.items():
        icon = {
            GoalStatus.DONE: "✅",
            GoalStatus.FAILED: "❌",
            GoalStatus.SKIPPED: "⏭️"
        }.get(status, "❓")
        print(f"  {icon} {name}: {status.value}")
    print(f"{'='*60}")

    return results

# 使用
goals = [
    {
        "name": "修复 Payment 测试",
        "verifier": "npm test -- --testPathPattern=payment",
        "max_rounds": 8
    },
    {
        "name": "修复 Auth 测试",
        "verifier": "npm test -- --testPathPattern=auth",
        "max_rounds": 6
    },
    {
        "name": "TypeScript 编译检查",
        "verifier": "npx tsc --noEmit",
        "max_rounds": 4
    },
]

multi_goal_loop(goals)
​

常见问题 FAQ

Q1：循环修复了 Bug 但我不理解它的修复方式，怎么办？

A：这正是 Addy Osmani 所说的"理解债务"（Comprehension Debt）。解决方案：(1) 让循环在修复时生成详细说明，写入 commit message；(2) 你花时间读一遍修改，不理解的部分直接问 AI 解释；(3) 在 Skills 中要求 Agent 写详细注释。永远不要跳过审查步骤。

Q2：循环一直在同一个 Bug 上反复失败怎么办？

A：这是循环设计需要优化的信号。可能的原因和对策：(1) Skills 中缺少必要的上下文 → 补充项目知识；(2) 验证标准不够具体 → 拆分目标为更小的子目标；(3) Agent 缺少必要的工具权限 → 检查工具配置。连续 3 轮无进展后应该自动停止，让你有机会调整循环设计。

Q3：如何衡量一个循环设计的好坏？

A：三个核心指标：(1) 成功率：循环在最大轮次内达成目标的频率；(2) 效率：平均需要多少轮达成（越少越好）；(3) Token 效率：达成目标消耗的 Token 数量。用这些指标对比不同的循环设计，持续优化。

最佳实践与避坑

• 先写设计文档，再启动循环：5 分钟的设计文档可以节省 1 小时的 Token 浪费
• Skills 是循环的"大脑"：花时间写好 Skills，循环质量会大幅提升
• 审查不可跳过：循环自动化的是执行，不是判断
• 记录循环日志：每轮的目标、尝试、结果都记下来，用于后续优化
• 渐进式自动化：先 Level 1→验证可靠→再 Level 2→最后考虑 Level 3

本节小结

本节通过一个完整的实战项目，带你体验了 Loop Engineering 从设计到验证的全流程。我们编写了循环设计文档、构建了 Skills 知识库、启动了 /goal 循环、并学习了如何监控和审查循环结果。

至此，第一章全部完成。你已经掌握了 Loop Engineering 的基本概念、核心思维模式和第一手实践经验。下一章我们将深入循环的架构设计。

延伸阅读

• Addy Osmani - The Intent Debt
• Addy Osmani - Agent Skills
• 相关章节：2.1 循环的四大阶段详解

关键词：Loop Engineering, 循环设计, Skills 编写, /goal, 验证器, 循环实战, 代码修复循环, 最佳实践, 教程

难度：入门

预计阅读：13 分钟