Harness 工程与 CI/CD：让 AI Agent 帮你跑通从代码到部署

大模型的能力够用，但需要引导。就像岷江的水够用，但需要都江堰。

---

目录

• AI 写代码，然后呢？
• Harness 是什么
• Loop 是什么
• Loop 的标准工作流
• 与 CI/CD 的结合
• 关键文件详解
• 实战：一次完整的 Loop + CI/CD
• 常见问题与踩坑
• 总结

---

AI 写代码，然后呢？

用 Claude Code 写代码已经很顺手了。告诉它需求，它读上下文、生成代码、跑测试，一气呵成。

但然后呢？

代码写完了，你手动 git add、git commit、git push。然后打开 GitLab，看 CI/CD 管道有没有跑通。如果挂了，你手动看日志、定位问题，再回到 CC 让它修。

这个流程本身没什么问题，但它是断裂的。AI 负责写代码，人负责提交和看结果。中间的衔接全靠人。

我在想：能不能让 AI 也参与后面的流程？不只是写代码，还能自己提交、自己看 CI 结果、自己修问题？

这就需要两样东西：

1. 一套约束：告诉 AI 什么能做、什么不能做、做完的标准是什么
2. 一个闭环：让 AI 的工作有反馈，失败了能自动修复

前者叫 Harness 工程，后者叫 Loop。

---

Harness 是什么

大模型的能力就像岷江的水——水量充沛，但如果不加引导，就会泛滥。

都江堰不是造水的，是治水的。它用鱼嘴分水、飞沙堰排沙、宝瓶口引水，把岷江的水引导到成都平原，浇灌万亩良田。

Harness 工程做的是同样的事。它不是造模型能力的，是引导模型能力的。

定义

Harness = 约束工程。通过文档和规则约束 AI Agent 的行为，让它在正确的路径上工作。

CC 本身就是一个通用的 Harness 工程。你写的 CLAUDE.md、AGENTS.md、skills，都是 Harness 的一部分。

四个核心原则

1. 分流/分步骤

大任务拆成小步骤。不是让 AI 一口气把所有事做完，而是一步一步来，每步确认后再走下一步。

就像都江堰把岷江分成内江和外江——各走各的路，互不干扰。

2. 控量约束

限制 AI 能做什么、不能做什么。比如：禁止批量删除文件、禁止修改某些关键配置、只能在一个明确的路径下操作。

3. 兜底机制

出错了怎么办？不是让 AI 自己瞎猜，而是有明确的错误处理流程：重试、回退、上报。

4. 长期维护

约束文档不是写一次就完事。项目在变，约束也要跟着变。每次 Loop 的学习成果要写回文档。

Harness 的存在形式

文件	作用
CLAUDE.md	用户级全局规范
AGENTS.md	项目级入口和架构说明
GUARDRAILS.md	行为边界，能做什么、不能做什么
DONE.md	完成标准，什么算「做完了」
skills/*.md	特定任务的工作流

这些文件不是给人看的文档，是给 AI 看的约束。它们和代码一样重要，甚至更重要——因为它们决定了 AI 生成的代码质量。

---

Loop 是什么

Loop 不是编程里的 for 循环。

在 Harness 工程的语境下，Loop 是 AI Agent 的一轮工作周期：接收任务、读取上下文、生成代码、验证、写回学习成果——这一整个流程就是一次 Loop。

你可以把 Loop 理解为 AI 的「一轮活」。人有工作日，AI 有 Loop。

三层架构

每次 Loop 都在三层架构下工作：

L1 架构层    系统整体设计（服务划分、数据流、部署架构）
    |
L2 模式层    设计模式和约束规则（GUARDRAILS、接口约定、编码规范）
    |
L3 代码层    由 Loop 生成的实际代码

关键逻辑：每次 Loop 先读 L1 + L2 作为上下文，再在 L2 的约束下生成 L3。

L1 和 L2 是人写的（或者由之前的 Loop 沉淀的），L3 是 AI 生成的。这个分层保证了 AI 不会「自由发挥」到偏离项目方向。

---

Loop 的标准工作流

每次 Loop 都遵循一套标准操作流程（SOP）。七步走完，一个 Loop 才算闭环。

[1] 识别任务涉及的服务
         |
[2] 读取事实层：AGENTS.md + 架构文档
         |
[3] 检查跨服务需求：docs/contracts/
         |
[4] 检查护栏：GUARDRAILS.md
         |
[5] 自验证：编译 -> 启动 -> 测试
         |
[6] 关闭：按 DONE.md 检查完成度
         |
[7] 知识回写：将新知识写回 Harness 文档

Step 1：识别服务

接到任务后，先搞清楚这个任务涉及哪些服务。是只改用户服务，还是跨了订单服务和支付服务？

Step 2：读取事实层

读 AGENTS.md 了解项目结构和规范，读架构文档了解服务之间的关系。这一步是让 AI「搞清楚状况」。

Step 3：检查跨服务需求

看看 docs/contracts/ 里有没有接口约定。如果要改一个 API，得确认下游服务能不能兼容。

Step 4：检查护栏

读 GUARDRAILS.md，确认这个任务在 AI 的行为边界内。比如：不能改数据库 schema、不能动生产配置。

Step 5：自验证

按 BUILD.md 的指引，编译代码、启动服务、跑测试。这一步是 AI 自己检查自己。

Step 6：关闭

按 DONE.md 的标准检查完成度。代码写完了不代表做完了——有没有写测试？有没有更新文档？有没有改 changelog？

Step 7：知识回写

把这次 Loop 学到的东西写回 Harness 文档。比如：发现了一个新的边界情况、总结了一个新的最佳实践。

这一步最容易被忽略，但它是 Loop 和普通 AI 对话的核心区别。没有知识回写，每次 Loop 都是从零开始。有了知识回写，AI 会越来越懂你的项目。

---

与 CI/CD 的结合

Loop 保证了 AI 在本地做正确的事。但本地做对了，不等于线上也能跑通。

CI/CD 管道是最终的裁判。代码能不能用，管道说了算。

完整闭环

CC 写代码 --> Harness 约束检查 --> Git commit --> GitLab CI/CD
    ^                                              |
    |                                              v
    +------------ CC Loop 修复 <-- CI/CD 失败 <--+

每个环节的职责：

环节	做什么	谁负责
CC 写代码	在 Harness 约束下生成代码	AI Agent
约束检查	GUARDRAILS 行为边界检查	AI Agent（自动）
Git commit	代码提交到 GitLab	AI Agent（或人确认）
CI/CD 管道	自动构建、测试、部署	GitLab Runner
失败修复	读取错误日志，诊断并修复	AI Agent（下一个 Loop）

关键洞察

CI/CD 失败不是终点，是下一个 Loop 的起点。

传统的开发流程里，CI/CD 挂了，人去看日志、定位问题、改代码。现在这个工作可以交给 AI：

1. CI/CD 管道失败，GitLab 发送通知
2. CC 读取 CI 日志，定位失败原因
3. CC 启动新的 Loop，在 GUARDRAILS 约束下修复代码
4. 修复后再次提交，CI/CD 重新运行
5. 重复直到通过

这就是 Loop 和 CI/CD 的结合点：CI/CD 是 Loop 的反馈信号，Loop 是 CI/CD 失败的修复引擎。

GitLab CI 配置示例

一个简单的 .gitlab-ci.yml：

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - mvn clean package -DskipTests
  artifacts:
    paths:
      - target/*.jar

test:
  stage: test
  script:
    - mvn test
  artifacts:
    when: on_failure
    reports:
      junit: target/surefire-reports/*.xml

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  only:
    - main
  when: manual

这个配置做了三件事：编译、测试、部署。测试阶段如果失败，会生成报告——CC 的下一个 Loop 可以读这个报告来定位问题。

---

关键文件详解

Harness 工程的核心是这些文件。它们不是「顺便写写的文档」，是决定 AI 行为的关键配置。

文件	职责	变更频率	谁维护
AGENTS.md	Loop 入口，项目结构和规范	低（项目架构变时）	人
GUARDRAILS.md	行为边界，能做什么、不能做什么	中（新约束出现时）	人 + AI
DONE.md	完成标准，什么算做完了	低	人
BUILD.md	编译和测试指南	低	人
docs/contracts/	跨服务接口约定	中（接口变更时）	人 + AI

AGENTS.md

每个 Loop 的入口点。AI 启动时第一个读的就是这个文件。内容包括：

• 项目整体架构
• 服务划分和职责
• 代码规范和约定
• 关键文件的位置

GUARDRAILS.md

行为边界。定义 AI 能做什么、不能做什么。比如：

禁止：
- 修改数据库 schema
- 直接操作生产环境
- 删除用户数据

必须：
- 所有 API 变更要有对应的测试
- 修改公共模块前检查下游依赖
- 代码风格遵循项目规范

DONE.md

完成标准。代码写完了不代表做完了。DONE.md 定义了「完成」的 checklist：

- [ ] 代码编译通过
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] API 文档已更新
- [ ] CHANGELOG 已更新
- [ ] 无安全漏洞

---

实战：一次完整的 Loop + CI/CD

理论讲完了，来看一个真实的例子。

场景：给项目加一个「获取用户详情」的 API 接口。

Step 1：告诉 CC 需求

帮我加一个 GET /api/users/{id} 接口，返回用户详情。

CC 启动 Loop，第一步是读取 AGENTS.md 和架构文档，了解项目结构。

Step 2：CC 在约束下生成代码

CC 读完 GUARDRAILS.md，知道：

• API 必须有参数校验
• 必须有对应的单元测试
• 返回格式要遵循项目统一的 Response 结构

然后生成代码：Controller、Service、Repository、测试类。

Step 3：CC 自验证

按 BUILD.md 的指引：

mvn clean compile  # 编译通过
mvn test           # 测试通过

本地验证没问题。

Step 4：Git commit + push

CC 自动执行：

git add .
git commit -m "feat: add GET /api/users/{id} endpoint"
git push origin feature/user-detail

Step 5：CI/CD 管道运行

GitLab 检测到新的 push，自动触发 CI/CD 管道：

[build]  编译通过
[test]   测试失败 <-- 问题在这里
[deploy] 跳过（因为测试没过）

Step 6：CI/CD 报错

测试失败了。原因是：新增的接口和已有的权限模块有冲突——需要登录才能访问，但测试里没有模拟登录。

Step 7：CC Loop 修复

CC 读取 CI 日志，定位问题：

错误：401 Unauthorized
原因：测试未携带认证 Token
修复：在测试中添加 Mock 认证

CC 启动新的 Loop，修改测试代码，添加 @WithMockUser 注解。

Step 8：再次提交，CI/CD 通过

git commit -m "fix: add mock auth for user detail test"
git push

[build]  编译通过
[test]   全部通过
[deploy] 手动触发部署

整个过程，人只做了一件事：告诉 CC 需求。剩下的提交、报错、修复、再提交，都是 Loop 自动完成的。

---

常见问题与踩坑

Harness 文档太死板

问题：约束写得太细，AI 什么都不能做，每次都要人手动批准。

解法：约束要适度。GUARDRAILS.md 只写红线（不能做什么），不要写操作步骤（怎么做）。给 AI 留发挥空间。

Loop 陷入死循环

问题：修一个问题冒出两个新问题，Loop 停不下来。

解法：设置最大 Loop 次数（比如 3 次）。超过次数就停下来，把问题上报给人。

CI/CD 失败但本地通过

问题：本地编译测试都过了，CI/CD 环境却挂了。

原因：环境差异。本地是 JDK 17，CI 是 JDK 11；本地有某个依赖，CI 没有。

解法：用 Docker 保证开发环境和 CI 环境一致。Dockerfile 和 CI 配置用同一个基础镜像。

知识回写缺失

问题：每次 Loop 都重复犯同样的错。上次修过的 bug，这次又犯了。

解法：强制知识回写。每次 Loop 结束前，必须把学到的东西写回 AGENTS.md 或 GUARDRAILS.md。比如：「这个项目的测试必须用 @WithMockUser，否则会 401」。

---

总结

回顾一下我们走过的路：

1. 起点：AI 写代码很溜，但从代码到部署的流程是断裂的
2. Harness：用约束文件规范 AI 行为，像都江堰治水一样引导大模型的能力
3. Loop：AI 的一轮工作周期，七步标准流程，有闭环、有反馈、有积累
4. CI/CD 结合：CI/CD 是 Loop 的反馈信号，Loop 是 CI/CD 失败的修复引擎

三个核心观点：

• Harness 的定位：不是限制 AI，是引导 AI。约束不是枷锁，是轨道
• Loop 的价值：让 AI 的工作有闭环。没有 Loop，AI 只是在写代码；有了 Loop，AI 在做工程
• CI/CD 的意义：自动化不是目的，快速反馈才是。CI/CD 告诉你代码到底行不行

一句话：Harness + Loop + CI/CD = AI Agent 的工程化工作流。

---