2.2 六大基础设施原语 — 构建可靠循环的工程积木

本节导读：掌握 Addy Osmani 定义的六大循环基础设施原语——Automations、Worktrees、Skills、Connectors、Sub-agents、State——理解每个原语在循环中的角色和使用方法。

学习目标

• 理解六大原语各自在循环中的职责
• 掌握每个原语在 Claude Code 和 Codex 中的具体实现
• 学会根据任务需求选择合适的原语组合
• 理解原语之间的协作关系

核心概念

Addy Osmani 在其里程碑式的文章中定义了构建循环所需的六大基础设施原语。这些原语不是理论发明，而是从 Claude Code 和 Codex 等成熟产品中提炼出的共性设计。正如 Osmani 所说："The names are a bit different here and there but the capability is the same thing."（名字各有不同，但能力是完全一样的。）

原语一：Automations（自动化）——循环的心跳

Automations 是让循环成为"真正的循环"而不是"一次性执行"的关键。

在循环中的角色：定时发现和分流。Automations 按照预设的时间节奏自动触发循环，将结果分类为"需要处理"和"自动归档"。

Claude Code 实现：

# /loop：会话内循环
> /loop "检查并修复 CI 失败" --interval 30m

# cron 定时任务
> /cron "每日 Issue 分流" --schedule "0 9 * * *"

# hooks：在 Agent 生命周期特定点触发
> hooks: {"on_session_start": "git pull", "on_file_edit": "npx eslint"}
​

Codex 实现：

# Automations 标签页
# 选择项目 → 设置提示词 → 选择频率 → 选择环境
# 结果进入 Triage Inbox（分流箱）

# /goal：持续运行直到条件满足
> /goal "所有测试通过"
​

实际用途：

• 每日自动审查 GitHub Issues
• 定期检查 CI 失败并尝试自动修复
• 定时运行代码质量检查

原语二：Worktrees（工作树）——并行不混乱

核心问题：同时运行多个 Agent 时，文件冲突是最大的失败原因。"两个 Agent 写同一个文件，就像两个工程师没有先沟通就提交同一行代码"。

解决方案：Git worktree 提供隔离的工作目录——同一个仓库的不同分支，各自的修改互不影响。

# Claude Code: 使用 --worktree 标志
claude --worktree feature/login-fix

# Codex: 自动为每个 thread 创建 worktree

# 手动创建 worktree（理解原理）
git worktree add ../fix-auth auth-fix
cd ../fix-auth
# Agent 在这里工作，不影响主分支
​

原语三：Skills（技能）——项目知识的持久化

核心问题：Agent 每次会话都从零开始，不了解项目约定、历史决策和编码规范。"没有 Skills，循环每轮都从头重新推导你的整个项目"。

解决方案：将项目知识编码为 SKILL.md 文件，Agent 每次运行自动读取。

# Skill 文件结构
.claude/skills/
├── testing.md          # 测试规范
├── deployment.md       # 部署流程
├── code-style.md       # 代码风格约定
└── payment-module.md   # 特定模块知识
​

SKILL.md 示例：

# Payment Module Skill

## 概述
支付模块处理用户支付、退款和订阅管理。

## 关键约定
- 金额使用 Decimal.js，禁止原生浮点数
- 错误码格式：PAYMENT_<TYPE>_<DETAIL>
- 支付超时设为 30 秒，重试采用指数退避

## 文件位置
- 支付逻辑：src/payment/processor.ts
- 支付网关适配：src/payment/gateways/
- 测试：src/payment/__tests__/

## 常见问题模式
- 金额精度丢失 → 使用 .toFixed(2) + Decimal.js
- 并发修改 → 乐观锁版本号检查
- 网络超时 → 指数退避重试（1s → 2s → 4s）
​

重要原则：Skills 的描述要"无聊但精确"。Osmani 说："a tight boring description beats a clever one"（一个紧凑无聊的描述胜过一个聪明的描述）。Agent 根据描述判断是否激活 Skill，模糊的描述会导致误激活。

原语四：Connectors（连接器）——触达真实世界

核心问题："一个只能看到文件系统的循环，只是一个很小的循环"。

解决方案：通过 MCP（Model Context Protocol）连接外部系统——Issue 追踪器、数据库、API、消息平台。

实际效果：

• 没有 Connectors：Agent 说"这里是修复代码"
• 有 Connectors：Agent 自动创建 PR、关联 Linear ticket、CI 通过后发通知到 Slack

原语五：Sub-agents（子代理）——制造者与检查者分离

核心价值：这是循环中"最有用的结构性设计"。编写代码的模型对自己写的代码评分太宽松。需要一个独立的子代理来检查。

Claude Code 实现：

# 子代理配置
.claude/agents/
├── coder.md      # 实现者：专注编码
├── reviewer.md   # 审查者：专注检查
└── tester.md     # 测试者：专注测试验证
​

子代理成本意识：每个子代理都消耗独立的 Token。Osmani 建议"在第二个意见值得付费的地方使用子代理"——不是所有任务都需要 maker-checker 分离。

原语六：State（外部状态）——循环的记忆

核心问题："模型的上下文窗口会遗忘一切。记忆必须在磁盘上，不在上下文中。Agent 会遗忘，仓库不会。"

解决方案：使用外部文件持久化循环状态——Markdown 文件、Linear board、数据库。

# progress.md - 循环状态文件

## 当前状态
- 日期：2026-06-26
- 目标：修复 Payment 模块 Bug
- 总轮次：4
- 已修复：3/5 个 Bug

## 已完成
- [x] 修复金额计算精度（Round 1）
- [x] 修复超时重试逻辑（Round 2）
- [x] 修复并发竞态条件（Round 3）

## 当前问题
- [ ] token 过期处理逻辑（Round 4 尝试失败，需要人工确认）

## 尝试历史
- Round 4: 尝试修改 token 校验逻辑 → 引入新失败 → 回滚
​

环境准备 / 前置知识

• 已完成 2.1 节学习
• 有 Claude Code 或 Codex 的实际使用经验
• 了解 Git worktree 基本概念

分步实战

步骤 1：配置完整的六大原语

# 1. Automations: 设置定时循环
mkdir -p .claude
cat > .claude/automations.json << 'EOF'
{
  "automations": [
    {
      "name": "daily-triage",
      "schedule": "0 9 * * *",
      "prompt": "阅读 GitHub Issues，尝试自动修复简单 Bug",
      "skill": "$triage"
    }
  ]
}
EOF

# 2. Skills: 创建项目知识
mkdir -p .claude/skills
cat > .claude/skills/testing.md << 'EOF'
# Testing Skill
运行测试: npm test
测试框架: Jest
覆盖率要求: > 80%
EOF

# 3. State: 创建进度追踪
cat > progress.md << 'EOF'
# 循环进度
## 状态: idle
## 日期: 2026-06-26
EOF

# 4. Worktrees: 创建隔离环境
git worktree add ../loop-worktree

# 5. Sub-agents: 配置多代理
cat > .claude/agents/reviewer.md << 'EOF'
# 代码审查 Agent
你是一个严格的代码审查者。
检查代码质量、测试覆盖率、安全问题。
不要通过有问题的代码。
EOF
​

步骤 2：运行一个使用全部原语的循环

claude --worktree

# 启动使用完整原语的循环
> /goal "按照 $testing Skill 的规范修复所有失败测试。使用 $reviewer 审查每个修复。进度记录在 progress.md。"
​

常见问题 FAQ

Q1：六个原语是否每次循环都需要全部使用？

A：不需要，而且不应该。Osmani 的建议是渐进式采用。大多数团队从以下最小集合开始：Skills（项目知识）+ 验证器（确定性检查）。确认基本循环可靠后，再逐步加入 Automations、Worktrees、Connectors 和 Sub-agents。

Q2：Skills 和 Connectors 有什么区别？

A：Skills 是"知道什么"，Connectors 是"能做什么"。Skills 编码的是项目知识（约定、规范、历史决策），告诉 Agent "在这个项目中应该怎样做"。Connectors 是外部工具连接（GitHub API、数据库、Slack），赋予 Agent "可以操作外部系统的能力"。两者互补。

Q3：State 文件放在哪里最合适？

A：项目根目录的 Markdown 文件是最简单的选择。更成熟的方案是使用 Linear/Trello 通过 MCP 连接器集成。核心原则是状态必须在 Agent 的上下文窗口之外——文件系统或外部服务，而不是对话历史。

最佳实践与避坑

• 渐进采用：从 Skills 开始，不需要一次配齐六个
• Skills 要精确：无聊但精确的描述 > 聪明但模糊的描述
• Worktree 是必须的：任何涉及代码修改的并行工作都需要隔离
• Sub-agents 要克制：Token 成本高，只在需要独立验证时使用
• State 要简洁：每次循环更新，但保持结构化，避免膨胀

本节小结

本节详解了构成循环工程的六大基础设施原语。Automations 提供定时触发，Worktrees 保证并行隔离，Skills 持久化项目知识，Connectors 连接外部系统，Sub-agents 分离制造与检查，State 提供外部记忆。六个原语共同构成了循环的工程基础。

下一节我们将探讨开放循环与闭合循环的设计选择。

延伸阅读

• Addy Osmani - Loop Engineering
• Addy Osmani - Agent Skills
• 相关章节：2.3 开放循环与闭合循环设计

关键词：Loop Engineering, 六大原语, Automations, Worktrees, Skills, Connectors, Sub-agents, State, Claude Code, Codex, 教程, 架构

难度：进阶

预计阅读：16 分钟