实战丨我们如何把 AI Coding 变成＂可控的工程能力＂

基于 Claude Code + OpenSpec 的 AI 编码实践复盘

阅读时长：约 10 分钟

适合人群：AI Coding 实践者、工程治理负责人，开发团队

01 背景

    最近一段时间，我们在一个企业级系统管理平台项目上，全面引入 AI 辅助编码。项目背景：

• 前后端分离架构（Spring Boot + Vue 3）

• 成熟业务系统，功能模块相对稳定

• 团队有一定规模，需要规范协作

    引入 AI 编码后，效果确实明显——原来需要数天的 CRUD 功能，AI 能在几小时内给出不错的实现。开发效率提升，团队也有更多精力去思考业务逻辑。但问题也随之而来。

02 踩过的坑

坑一：AI 改 API，把历史接口弄挂了

    AI 在优化某个查询接口时，顺手改了返回结构，删掉了一个历史字段。前端不知道这个变化，联调时才发现数据对不上。一查 commit才发现是 AI 改的。

坑二：AI 写的 SQL 没有 where 条件

    让 AI 批量更新一批数据，它生成的是 UPDATE user SET status = 1。没有 where。差点全表更新。幸好测试环境先跑了。

坑三：AI 不懂项目的"隐性约定"

    项目有个约定：deleted = 0 是正常，deleted = 1 是已删除。但AI不知道，它写的查询有时候过滤的是 deleted = 1。本地能跑，联调就出问题。

坑四：评审和验证混在一起

    用OpenSpec管变更，但评审和验证分不开。verify 通过了，不等于代码质量没问题，也不等于SQL没风险。

03 问题分析与解决思路

踩坑原因分析：这四个坑，表面上是AI"不听话"，实际上是没有给AI建立清晰的约束体系：

解决思路

我们引入了 Harness的思想，重新梳理了 OpenSpec + Claude Code 的协作关系。

为什么需要 Harness？

光有 OpenSpec 不够。OpenSpec 只解决了"变更有没有记录"的问题，但没解决：

这就是 Harness 存在的意义。

三者关系

简单来说：

• OpenSpec 管"这次改什么"

• Harness 管"改的过程中怎么不乱来"

• Claude Code 是 AI 执行操作的工具

OpenSpec（管变更）+ Harness（管约束）+ Claude Code（管执行）= 可控的 AI Coding

核心公式：Harness = 需求工件化 + 知识显性化 + 执行加护栏 + 评审验证分离

04 解决方案：四大核心原则

原则一：AGENTS.md 只做导航，不做知识库

问题：把所有知识都塞进 AGENTS.md，最后变成了 500 行的"没人看的文档"。

解决：让 AGENTS.md 只做入口导航，真正的知识放到 docs/ 目录。

# AGENTS.md（导航入口）## 必读文件（按顺序）1. docs/architecture/implicit-contracts.md  ← 隐性约定2. docs/architecture/index.md              ← 架构总览3. docs/product/index.md                  ← 产品规则

原则二：隐性约定必须显性化

问题：项目中"大家都知道"的东西，AI 不可能稳定推断出来。

解决：把所有隐性约定显性化到文档。

# docs/architecture/implicit-contracts.md## 数据库层面### 软删除机制- deleted = 1 表示已删除- deleted = 0 表示正常- 所有查询默认过滤 deleted = 1## API 层面- 统一使用 POST（不用 GET）- 返回格式：R<T>，成功 R.ok() / 失败 R.fail()

原则三：硬护栏靠 permissions + hooks

问题：把规则写进提示词，AI 有时候还是会违规。

解决：用权限配置 + 钩子函数构建硬护栏。

// .claude/settings.json{  "permissions": {    "deny": [      "Edit(path:db/migration/**/*)",      "Edit(path:application*.yml)",      "Bash(git push)"    ]  }}# .claude/hooks/guard_write.pyPROTECTED_PATTERNS = [    "application",     # 配置文件    "db/migration",   # 数据库脚本    "deploy/",        # 部署文件    "secrets/",       # 密钥]

原则四：评审与验证必须分离

问题：verify 通过了，不等于代码质量没问题。

解决：明确职责，各司其职。

评审技能链：

/opsx verify → /prepare-review → /sql-risk-review → reviewer → /opsx archive

05 落地效果

效果一：联调问题大幅减少

    AI 改 API 前会先查隐性约定文档，不再"自作主张"删字段。

效果二：高风险操作被有效拦截

    配置文件、数据库脚本没人敢直接改了。guard_write.py 真的在拦截。

效果三：评审效率提升

    PR 摘要自动生成，人工评审聚焦重点，不用在海量 diff 里找重点。

效果四：变更可追溯

    每个 change 都有完整的 proposal → design → tasks → verify → archive 闭环。

06 经验总结

经验一：AGENTS.md 不是知识库，是导航

    把 AGENTS.md 当成存放所有知识的地方，是最容易踩的坑。正确的做法是让它保持简洁，只做入口导航。

经验二：隐性约定不显性化，AI 不可能稳定理解

    这是最值钱的经验。项目中那些"大家都知道"的东西，必须显性化到文档，否则 AI 每次都可能猜错。

经验三：硬护栏比软约束更可靠

    提示词是"软约束"，permissions + hooks 是"硬护栏"。关键的高风险操作，必须靠硬护栏拦截。

经验四：评审和验证是两件事

    verify 是检查实现和方案是否对齐，不等于代码质量审查。两件事分开做，才能真正覆盖风险。

07 完整目录结构

repo/├─ docs/│  ├─ architecture/│  │  ├─ index.md│  │  └─ implicit-contracts.md│  ├─ product/│  │  └─ index.md│  └─ standards/│     ├─ testing.md│     └─ database.md├─ AGENTS.md├─ REVIEW.md├─ openspec/│  ├─ docs/│  │  ├─ requirements/TEMPLATE.md│  │  ├─ analysis/TEMPLATE.md│  │  ├─ design/TEMPLATE.md│  │  ├─ sprint/TEMPLATE.md│  │  └─ README.md│  ├─ changes/│  │  ├─ <change-name>/│  │  │  ├─ proposal.md│  │  │  ├─ design.md│  │  │  ├─ tasks.md│  │  │  └─ specs/│  │  └─ archive/│  └─ config.yaml└─ .claude/   ├─ settings.json   ├─ hooks/   │  ├─ guard_write.py   │  ├─ ensure_change_context.py   │  └─ run_checks.sh   ├─ agents/   │  └─ reviewer.md   └─ skills/      ├─ prepare-review/SKILL.md      └─ sql-risk-review/SKILL.md

08 一句话总结

Harness 不是限制 AI，而是让 AI 在可控的路上跑。

AI很像一个特别能干的小弟：干活快、出活多，但不代表它知道哪条线不能碰。

所以我们要给它规则、给它边界、给它检查、也给它刹车。

这不是约束，这是工程治理。

附：检查清单

你的项目 Harness 达标了吗？

仓库层

• 是否有 AGENTS.md（导航用，不是知识库）
• 是否有 docs/architecture/implicit-contracts.md
• 是否有 REVIEW.md

流程层

• 没有 change 时，AI 不能直接开发
• proposal/design/tasks 有人工审查
• verify 和评审是分开执行的

护栏层

• 高风险目录有 permissions.deny
• 有 guard_write.py 做写入保护
• 有 run_checks.sh 做自动检查

如果大部分没打勾，那 Harness 落地该提上日程了。

你的团队有遇到 AI Coding 失控的问题吗？又是怎么解决的？欢迎留言交流。