夜雨聆风基于 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建立清晰的约束体系：
| 问题 | 根因 |
|---|---|
| 改挂历史接口 | AI 不清楚项目的隐性约定 |
| SQL 无 where | 没有硬护栏拦截高危操作 |
| 不懂隐性约定 | 知识没有显性化，AI 靠猜 |
| 评审验证混淆 | 评审和验证职责不清 |
解决思路
我们引入了 Harness的思想，重新梳理了 OpenSpec + Claude Code 的协作关系。
为什么需要 Harness？
光有 OpenSpec 不够。OpenSpec 只解决了"变更有没有记录"的问题，但没解决：
| 问题 | OpenSpec 能解决吗？ |
|---|---|
| AI 怎么知道项目的隐性约定？ | ❌ 不能 |
| AI 怎么知道哪些路径不能改？ | ❌ 不能 |
| verify 通过了，代码质量谁管？ | ❌ 不能 |
这就是 Harness 存在的意义。
三者关系
| 组件 | 职责 |
|---|---|
| OpenSpec | 变更生命周期管理（骨架） |
| Harness | 约束机制 + 知识沉淀 + 评审分离（血肉） |
| Claude Code | AI 编码工具/执行环境 |
简单来说：
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 | 检查实现是否对齐 OpenSpec 工件 |
reviewer | 代码质量和逻辑审查 |
sql-risk-review | SQL 风险检查 |
评审技能链：
/opsx verify → /prepare-review → /sql-risk-review → reviewer → /opsx archive05 落地效果
效果一：联调问题大幅减少
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 失控的问题吗？又是怎么解决的？欢迎留言交流。
