本篇文章是 2026 年 5 月 2 日在 Dabakodan DaoLab VibeCoding Guild 上，关于“Harness 工程”案例介绍的演示内容。
Nextain 是一家为拥有软件产品的企业开发和支持 AX 技术的公司，目前已接管韩国教会门户网站 Onmam.com 的系统运营，并正在进行 AX 相关工作。 我们正在将位于旧 IDC 中心的遗留系统进行迁移，并设置了基于代理的开发和运营环境，同时进行稳定化和功能改进工作。 由于是老旧的遗留系统，我们经历了一些试错，并通过将 naia-business-adk 应用于 Onmam.com，将其转化为企业的经验和技术。 作为这一经验的分享，我们在活动中介绍了 Harness 工程的案例。
本文的核心信息 "比起善用 AI，创建一个让 AI 不犯错的环境更为重要。"
1. 首先，介绍我们的服务
Onmam.com — 全国 13,876 家教会使用的教会管理平台
www.onmam.com ← 教会查找，会员门户
home.onmam.com ← 频道应用 (内容/支付)
{教会名}.onmam.com ← 各教会主页
基础设施：老旧 IDC 服务器 → 2026 年 4 月完全迁移至 GCP（谷歌云） 数据库：13,876 家教会数据 × Cloud SQL
2. 从一个事件开始
"2026 年 4 月的某一天"
上午 11 点。Onmam.com 所有服务突然无响应。
用户们：“网站怎么打不开？”
追溯原因发现 — Board.php 文件中的公告板列表查询代码。
-- 出现问题的查询 (简化)
SELECT * FROM boards
JOIN (
SELECT bbs_id, COUNT(*) FROM all_boards GROUP BY bbs_id -- ← 这是问题所在
) AS summary ON boards.id = summary.bbs_id
WHERE church_id = ?
这个查询每次都会全量扫描 13,876 家教会的所有数据。 流量高峰时，600~800 秒的查询同时执行 145 次 → 服务器完全瘫痪。
这与 AI 有什么关系？
这段代码最初可能是一位人类开发者编写的。 但如今，开发者们会与 AI 共同编写这类代码。
问题是 — AI 不知道“这段代码在 13,876 家教会的环境中如何运行”。 AI 专注于实现所请求的功能，却不了解我们服务的上下文。
因此，开发者们开始思考：“如果 AI 在不了解我们服务的情况下编写代码，我们该如何阻止？”
3. Harness 工程 — 30 秒解释
就像驾驭马匹需要缰绳和马具 (Harness) 一样，
AI 代理也需要限制、指导和验证装置。
代理 = 模型 + Harness
Harness = 设计 AI 工作的整个环境
这不仅仅是“向 AI 提出好问题”。 当 AI 犯错时，从结构上防止其再次犯相同错误的系统设计。
4. Onmam.com 实际构建的 Harness
[Harness #1] AGENTS.md — 给 AI 的“我们服务地图”
alpha-adk/
├── CLAUDE.md ← AI 会话开始时必须阅读的文件
├── AGENTS.md ← 项目规则列表
└── .agents/
└── context/
└── agents-rules.json ← 具体操作规则
AI 在触碰 Onmam.com 代码之前，必须阅读这些文件。 其中包含以下内容：
- “测试和代码修改仅在 alpha 环境中进行”
- “home.onmam.com 不是 portal，而是独立的 channel 应用”
- “Board.php 中 GROUP BY 派生表模式绝对禁止”
刚才的故障？现在 AI 如果尝试编写相同的模式，就会看到这些规则并停止。
[Harness #2] Hooks — AI 行为前后运行的“安全装置”
当前此工作空间中实际运行的 Hooks：
AI 执行 Bash 命令之前 →
✓ pr-guard.js : 阻止未经审查的 PR 合并
✓ commit-guard.js : 阻止违反规则的提交
✓ deploy-guard.js : 阻止未经批准的生产服务器部署
✓ git-push-guard.js : 阻止未经批准的 git push
✓ destructive-git-guard.js : 阻止 git reset --hard 等破坏性命令
AI 修改文件之前 →
✓ prod-gateway-guard.js : 阻止在开发环境文件中使用生产 API 密钥
✓ design-doc-guard.js : 阻止未经授权的设计文档修改
AI 修改文件之后 →
✓ cascade-check.js : 检查受修改文件连锁影响的文件
deploy-guard.js 实际运行示例：
AI 尝试执行生产部署命令：
$ gcloud run deploy onmam-web ...
→ [Harness] 阻止生产部署命令：gcloud run deploy
项目：onmam-web
生产部署需要事先批准。
批准方法：在 .claude/deploy/approvals.json 中添加批准项
AI 不会直接执行生产部署。
即使 AI 错误地，或者过于积极地尝试将某些内容部署到生产服务器，也会被物理性地阻止。
[Harness #3] Alpha 环境 — AI 专属的实验场
生产 (Production) : www.onmam.com ← 实际教会使用
预发布 (Staging) : staging.onmampick.org ← 部署前最终确认
Alpha (Alpha) : luke-*-alpha.onmampick.org ← 与 AI 共同工作空间
规则：所有与 AI 共同进行的工作都仅在 alpha 环境中。
为什么这很重要 — 2026 年 4 月 29 日实际发生的事情：
AI 误将
home.onmam.com视为portal应用，编写了错误的 vhost 配置。 由于是在 alpha 环境 → 对实际服务无影响。 将此错误记录在 AGENTS.md 中 → AI 不会再犯同样的错误。
Harness 的本质在于此： 发生错误 → 记录在 Harness 中 → 下次从结构上防止该错误再次发生。
[Harness #4] Skills — 给 AI 的“我们自己的工具”
skills/
├── email/ ← 邮件发送 (包含收件人，SMTP 规则)
├── sms/ ← 短信发送
├── web-monitoring/ ← 服务状态监控
└── service-management/ ← 服务操作命令
当 AI 说“发送邮件”时 — 它会读取这个技能文件，自动知道发送给谁、以何种格式、通过哪个 SMTP。 无需每次都问“收件人邮箱地址是什么？”
5. 为什么开发者对此感兴趣
“没有 AI 的开发时代的问题”
依赖开发者个人能力 → 资深人员离开后质量下降
需要通过代码审查发现 → 需人工检查
“有 AI 但没有 Harness 的团队的问题”
AI 快速生成代码 → 但不了解我们服务的上下文
重复犯错 → Bug 由 AI 制造，由人修复
AI 可直接访问生产服务器 → 不知何时会出事故
“有 AI + Harness 的团队”
AI 了解我们的规则并编写代码 → 具有上下文的生成
发生错误时记录在 Harness 中 → 结构性防止相同错误
生产访问由人工批准 → 安全的自主性
借用 Toss 的说法：
"通过 Harness 提升整个组织的生产力下限。 不依赖个人能力，所有团队成员都能产出一定水平以上的结果。"
6. 总结 — 想对非开发者说的话
在 AI 时代，“做得好”的定义正在改变。
以前：擅长编写代码的开发者 现在：擅长设计 AI 编写代码环境的开发者
这种环境设计的核心就是Harness 工程。
而且，这不仅仅是开发者的故事。
非开发者也能做的 Harness：
→ 将业务规则清晰地文档化
→ 为 AI 定义“哪些可以做，哪些不可以做”
→ 当 AI 犯错时，记录“为什么会犯错”
= 这本身就是 Harness 工程的开始
Onmam.com Harness 结构一览
alpha-adk/
├── CLAUDE.md ← [Guide] AI 会话开始时必读
├── AGENTS.md ← [Guide] 项目规则 (SoT)
├── .agents/context/
│ └── agents-rules.json ← [Guide] 具体操作规则
├── .claude/
│ ├── hooks/
│ │ ├── deploy-guard.js ← [Sensor] 阻止生产部署
│ │ ├── prod-gateway-guard.js← [Sensor] 阻止生产 API 密钥
│ │ ├── commit-guard.js ← [Sensor] 验证提交规则
│ │ ├── pr-guard.js ← [Sensor] 强制 PR 批准
│ │ ├── session-inject.js ← [Sensor] 每个会话注入上下文
│ │ └── cascade-check.js ← [Sensor] 修改后检查连锁影响
│ └── settings.json ← [Permission] Hook 执行设置
├── skills/
│ ├── email/ ← [Tool] 邮件发送技能
│ ├── web-monitoring/ ← [Tool] 服务监控
│ └── service-management/ ← [Tool] 服务操作命令
└── data-private/memory/ ← [Feedback Loop] 错误记录 → 防止再发生
├── project_onmam_incidents.md ← Board.php 故障模式记录
├── project_onmam_app_structure.md← home≠portal 错误记录
└── feedback_alpha_only.md ← alpha 专用规则记录
Harness = 这些文件的集合 所有这些都提交到 Git 仓库。团队的所有上下文！都以代码形式积累。
