第9课. 代码之外的自动化 — Agent Operable System

实用技巧 — 知道这些就能指挥AI

光让智能体处理代码还不够。要把构建、部署、监控也交给智能体，整个系统必须是智能体能读懂的结构。不需要理解Docker内部。智能体全部处理。

对智能体说：“给服务器添加/health端点。用JSON返回DB连接状态、错误率、运行时间。”

这一句话给了智能体读取系统状态的眼睛。有/health智能体就能机械地确认"服务器活着吗？“没有的话就是蒙眼做手术的医生。

对智能体说：“用docker-compose.yml配置这个项目。必须包含应用服务器和DB。docker compose up就全部启动。”

不需要知道Docker是什么。知道它是"把应用装进箱子让哪里都能一样运行的工具"就够了。从安装到配置智能体全部处理。

对智能体说：“设置部署失败时自动回滚。/health失败就回退到之前的版本。”

智能体必然会犯错。犯错必须能撤回。这一句话就是安全网。

三句话。给服务器装上眼睛，声明系统，铺上安全网。其余的智能体来做。

快速体验

用Claude Code打开第1课的应用（或任何项目）：

“给服务器添加/health端点。用JSON返回DB连接状态、错误率、运行时间。所有现有Hurl测试必须通过。”

智能体添加代码后：

“做一个Hurl测试验证/health返回200。也加上检查JSON响应中有db、status、uptime字段。”

这就是可观测性的开始。智能体可以机械地读取系统状态了。

为什么要这样指挥

引言：超越代码库

第8课把代码做成了智能体能读写的结构。用filefunc拆分文件，用tsma确保测试，用whyso追踪变更历史。

但光代码agent-operable就够了吗？

修改了代码之后要构建。构建之后要部署。部署之后要监控。出故障要回滚。这些过程中哪怕有一个需要人手动操作，智能体的自主范围就到"代码编辑"为止了。

回想氛围编程者的现实。“添加功能"代码就出来了。然后呢？在终端输入构建命令，进AWS控制台部署，用眼睛扫日志，出问题再说"回滚”。

这整个手动过程应该连成一条流水线。智能体改代码、跑测试、构建、部署、监控——人只按审批按钮。

这就是Agent Operable System。

从代码库到系统

代码库是系统的一部分。系统是代码+基础设施+部署流水线+监控+运营流程的总和。

功能请求
→ SSOT编辑（yongol）
→ 代码生成（yongol generate）
→ 测试通过（Hurl + go test）
→ 构建（Docker）
→ 部署（CI/CD）
→ 监控（健康检查+日志）
→ 完成

这条链中如果任何一环对智能体不透明，之后全部变成人的事。一个断裂的环节就能瓦解整个自动化。

Agent Operable System的4个条件

系统要能由智能体运营，必须满足四个条件。

条件1. 可观测性 — 所有状态可以机械观测

智能体没有眼睛。看不到屏幕。读不了仪表盘。智能体要知道系统状态，那个状态必须以文本输出。

# 人的观测
登录AWS控制台 → CloudWatch仪表盘 → 用眼睛看图表
→ "哦，CPU高了" → 判断

# 智能体的观测
$ curl -s localhost:8080/health | jq .
{
  "status": "ok",
  "db": "connected",
  "uptime": "3h42m",
  "error_rate_5m": 0.02
}
→ error_rate > 0.05? → 报警

可观测性的核心：不是人看到的，而是机器能解析的。

没有可观测性的系统中，智能体就是蒙眼做手术的医生。

条件2. 声明式 — 所有行为声明式定义

让智能体"部署"时它做什么？

不是声明式系统的话：智能体猜"通常是这样做的吧？“SSH到服务器，git pull，重启进程…然后漏了什么。

声明式系统的话：一切写在文件里。

# docker-compose.yml — 服务运行什么
services:
  app:
    build: .
    ports: ["8080:8080"]
    environment:
      DATABASE_URL: ${DATABASE_URL}

# Makefile — 什么命令做什么
deploy:
    docker compose up -d
    curl -sf localhost:8080/health || (docker compose logs && exit 1)

# .github/workflows/deploy.yml — 什么时候自动执行
on:
  push:
    branches: [main]
jobs:
  deploy:
    steps:
      - run: make build
      - run: make deploy

声明式系统中智能体要做的很明确：

1. 读文件（docker-compose.yml、Makefile、workflow）
2. 按文件上写的执行
3. 确认结果

没有猜测。文件是真理。

第4课学的yongol的SSOT原则在这里同样适用。正如在代码中分离了决策和实现，在系统中也分离"要做什么”（声明）和"怎么做”（执行）。

Docker是把应用装进箱子、在哪里都能一样运行的工具。就像搬家时把东西装进纸箱，把应用和需要的一切放进一个箱子。搬箱子就行在哪儿都一样跑。Terraform是用代码文件管理服务器的工具。

不需要理解Docker和Terraform的内部。“把应用装进箱子"这一句就够了。其余的智能体来。不要去学docker-compose.yml文件的语法。让智能体做它自己会创建。你只确认结果——“应用启动了吗？/health返回200吗？”

条件3. 可逆 — 所有变更可验证且可回退

智能体部署了但服务挂了。这种情况需要两样东西：

1. 能知道哪里错了（可验证）
2. 能回退到之前的状态（可逆）

# 不可逆的部署（恐怖）
直接往服务器上传文件覆盖。
→ 出问题 → 之前的版本在哪？ → 不记得了 → 恐慌

# 可逆的部署（安心）
git revert HEAD && make deploy
→ 出问题 → 回滚到上一个提交 → 1分钟内恢复

第3课学的Git的核心在这里重现。代码的回退由Git负责。基础设施的回退由Terraform负责。DB的回退由迁移的down文件负责。

不可逆的变更不能交给智能体。 智能体会犯错——而且必然会犯——犯了必须能撤回。

条件4. Human-in-the-loop — 审批门控是显式的

四个条件中最重要的就是这个。

智能体判断、人审批的结构。不是"人指示、智能体执行"而是"智能体提议、人审批”。方向相反。

# 原来：人指示
"修这个Bug" → 智能体修改代码 → 人确认结果

# Agent Operable：智能体提议
智能体："error_rate超过了5%。
  原因：最近部署遗漏了DB连接池配置。
  修改方案：把docker-compose.yml的DB_MAX_CONNECTIONS从20改到50。
  回滚计划：失败时自动回滚到之前的镜像。"
人："批准"

核心是审批门控是显式的，不能自动跳过。

可逆的任务可以自动执行。难以逆转或影响大的任务必须经过审批。事先声明这个边界就是Human-in-the-loop设计。

智能体的瓶颈不是智能是上下文

第8课filefunc消除了代码的上下文污染。这个原理扩展到整个系统。

结构化代码让同一个智能体能处理10倍宽的范围。

不仅是代码。结构化系统的所有层，智能体的探索范围就急剧扩大：

代码   → 用filefunc结构化
配置   → 用docker-compose.yml、Makefile声明式定义
规范   → 用yongol SSOT交叉验证
基础设施 → 用Terraform state持久化
监控   → 用/health+结构化日志做到机器可读

智能体的瓶颈不是智能。给智能体结构化信息比用更聪明的模型有效10倍。第8课用filefunc结构化了代码，第9课结构化整个系统。

80/20 — 人真正要操心的

Agent Operable System完成后，从规范到代码的80-90%自动生成。你要操心的只有剩下的10-20%。

那10-20%是什么？业务规则（定价策略、工作流）、领域逻辑（法律/政策计算）、外部API对接之类的。只需用filefunc结构化这些并用tsma确保测试。

这就是非SWE能维护100+端点的结构。

决策由人做。实现和验证由机器做。人只需决定"要做什么"。“怎么做"由规范定义、智能体执行。

完整流水线：“添加功能"一句话到部署

在配备了Agent Operable System的项目中说"添加订单历史查询功能”：

1. SSOT编辑
   智能体：在features.yaml中添加ListOrders
   智能体：在OpenAPI中定义GET /orders
   智能体：在DDL中定义orders表
   智能体：在SSaC中声明服务流程
   智能体：在Hurl中编写测试场景

2. 一致性验证
   智能体：yongol validate → 0 errors

3. 代码生成
   智能体：yongol generate → Go处理器、sqlc查询、React组件

4. 测试通过
   智能体：go test → PASS
   智能体：Hurl测试 → PASS

5. 构建
   智能体：docker build → 成功

6. 部署（审批门控）
   智能体："所有验证通过。请求staging部署审批。"
   人："批准"
   智能体：staging部署 → /health确认 → 正常

7. 生产部署（审批门控）
   智能体："staging上30分钟无错误。请求production部署审批。"
   人："批准"
   智能体：production部署 → /health确认 → 正常

8. 完成
   智能体："ListOrders功能部署完毕。
   监控中。异常时自动回滚。"

人做的事：“添加订单历史查询功能” + “批准"两次。 智能体做的事：其余全部。

这就是氛围编程规模化的完成形态。

从遗留系统到Agent Operable System

“我们的项目已经做好了怎么转换？”

不需要一次全换。可以分步走。

第1步 — 确保可观测性（1天）

• 添加/health端点
• 日志改为结构化JSON
• 基本监控设置

第2步 — 转换为声明式系统（2-3天）

• 用Docker Compose定义服务配置
• 用Makefile整合构建/部署/测试命令
• 构建CI/CD流水线

第3步 — 确保可逆性（1-2天）

• 引入DB迁移系统
• 文档化并自动化回滚流程
• 部署时健康检查+自动回滚

第4步 — 定义审批门控（1天）

• 整理可自动执行的任务列表
• 整理需要审批的任务列表
• 在CI/CD中添加审批步骤

每步都是独立的。只做第1步智能体就能掌握系统状态。做到第2步智能体就能执行部署。做到第3步就能撤回错误。做到第4步就能安全地自主运营。

愿景 — 氛围编程规模化的终点

从第1课开始的"说了就做"走到哪里了。

第1课：
  "做个待办应用" → 代码出来了 → 3个功能还行，5个就崩了

第9课：
  "添加功能" + "批准"
  → 代码生成 → 测试通过 → 构建 → 部署 → 监控
  → 整个流水线由智能体主导

非SWE能维护、部署、运营100+端点的结构。

没有SWE也能规模化的原因：决策由人，实现和验证由机器。

但还缺一样。代码结构化了，系统结构化了。但数据呢？

第10课拼上最后一块拼图。

实操

必做实操（非技术人员）

目标： 添加/health端点并用Hurl验证。

步骤1 — 确保可观测性

对智能体说："给服务器添加/health端点。
用JSON返回DB连接状态、错误率、运行时间。
所有现有Hurl测试必须通过。"

步骤2 — 编写Hurl测试

对智能体说："做一个Hurl测试验证/health返回200。
也加上检查JSON响应中有db、status、uptime字段。"

确认事项：

• /health返回200吗？
• Hurl测试通过了吗？

挑战实操（可选）

不需要自己安装Docker或理解配置文件。全部交给智能体。

步骤1 — Docker Compose

对智能体说："如果没装Docker就帮我装。
用docker-compose.yml配置这个项目。
必须包含应用服务器和PostgreSQL。
docker compose up就全部启动。
在Makefile中添加build、deploy、test命令。"

智能体从Docker安装到配置文件生成、运行确认全部处理。你最后只确认"应用启动了吗？“出错Claude Code自动检测并尝试修复。

步骤2 — CI/CD流水线

对智能体说："创建GitHub Actions workflow。
push到main分支时：
1. 运行go test
2. 运行Hurl测试
3. Docker build
4. 全部通过就部署到staging
但production部署需要手动审批。"

步骤3 — 集成演示

让智能体添加一个功能。演示从SSOT编辑到staging部署智能体全程执行、只有production部署需要手动审批的完整流水线。

确认事项：

• 从"添加功能"到staging部署人介入了几次？
• 智能体失败时回滚花了几分钟？
• 智能体能读/health结果并掌握系统状态吗？

相关文章

• Reins Engineering — 有缰绳的AI
• yongol — AI编程SaaS的龙骨

Reins Engineering 全部课程

参考资料来源

• 第8课参考：Stanford “Lost in the Middle”（2024），Amazon “Context Length Alone Hurts LLM Performance”（2025）— 不必要的上下文使智能体性能下降30-85%
• 可观测性原则 — 机器可解析的结构化输出（/health端点、JSON日志）是智能体运营的前提条件
• Docker Compose — 声明式服务配置让智能体不用猜测就能读取和执行系统
• Terraform — Infrastructure as Code，基础设施状态的声明式定义和可逆变更
• CI/CD（GitHub Actions）— 构建-测试-部署流水线的声明式自动化
• Human-in-the-loop设计 — 可逆任务自动执行，影响大的任务必须有审批门控