让 AI 写出团队统一代码风格：我给编码助手装上「项目规范」后，体验差太大了

发表于 更新于 分类于

用 AI 写代码差不多大半年了，从 Cursor 到 Claude Code 再到 OpenCode，主流工具基本都摸过一遍。效率确实提上来了，但随之而来的问题也越来越明显——

直到我差点被 AI 生成的一段”看起来正常”的批量导入代码搞挂生产环境。

先说怎么被坑的

我们有个商品管理模块，需求很简单：支持 Excel 批量导入商品，导入时校验数据，校验不通过的行汇总返回给用户。

我跟 AI 说了需求，十分钟不到，它给我生成了 ImportController、ImportService、ExcelParser 三个文件。看着挺像回事，但我仔细一看：

  • ❌ 用的是 @Autowired 字段注入，但项目里其他三个 Service 全是构造器注入
  • ❌ 异常处理直接在 Controller 里 try-catch 返回了个 Map，但项目有统一的 Result 封装和全局异常拦截器
  • ❌ 校验逻辑全写在一个 200 行的大方法里，没有拆分，没有测试
  • ❌ BigDecimal 的价格比较用了 ==，这个坑 Java 程序员都知道

我花了大半天去改它生成的代码。改完之后想：这跟我自己写有啥区别？还多了个”审查 AI 代码”的步骤。

一套让我眼前一亮的框架

后来组内另一个同事推荐了一个叫 praxis-devos 的开源框架，说是能”给 AI 立规矩”。

我一开始没当回事。又是什么框架，多半是个花架子。但看到他用 AI 写的代码风格跟手写的几乎一样整齐，我就有点好奇了。

花了一个周末研究了一下，发现这东西的思路挺对的。它不是在 AI 的”能力”上做文章，而是在 AI 的”工作流程”上做文章。

简单说就是三层：

层 管什么 怎么实现
OpenSpec 规范工作流 做什么？需求想清楚了吗？ 提案 → 设计 → 规范场景 → 验证
可插拔技术栈 按什么标准做？ 编码规范 + 领域 Skills
SuperPowers 执行质量 怎么做？质量有保障吗？ 强制 TDD、完成前验证

安装就两行：

1
2
git clone https://github.com/chhuax/praxis-devos.git
./praxis-devos/install.sh --stack java-spring --dir ./my-project

它在项目里注入了一套文件：AGENTS.md（AI 的入职手册）、openspec/ 目录（管需求和规范）、.claude/skills/（AI 能读到的技能包）。

三个阶段，感受一下差距

阶段一：Propose——“先想清楚再动手”

以前 AI 会直接开始写 Controller。现在新功能必须先过提案阶段，AI 会生成三个文件：

  • proposal.md —— 动机、影响范围、风险评估
  • design.md —— 技术设计，关键决策写清楚（比如”SKU 查重用批量查询而非逐行查库，避免 N+1”）
  • spec.md —— 验收场景，用 Given/When/Then 格式写清楚每个 case

看 design.md 的时候我发现一个问题：它把文件大小限制设成了 10MB，但我们的服务器配置一般，我改成了 5MB。

这就是关键：方案是 AI 出的，但决策权在你手里。 你可以 review、质疑、改动，确认之后再让它动手。

阶段二：Apply——“按规矩写代码”

方案确认后，AI 开始写代码。但这次不一样——它先写测试，而且用的是 TDD。

1
2
3
4
5
6
@Test
@DisplayName("部分行校验失败时，只导入合法行，返回错误明细")
void should_import_valid_rows_and_return_errors_for_invalid() {
    // 先跑测试，红了
    // 然后 AI 才去写实现
}

而且这次生成的代码，构造器注入、统一异常处理、BigDecimal 比较，全都对。因为 rules.md 里写得清清楚楚，AI 不遵守就会触发规范检查报错。

阶段三：Verify——“实现和方案对得上吗？”

代码写完后，AI 触发 code-review 自审：

1
2
3
4
✅ 正确性：5 个 spec 场景均有对应测试和实现
✅ 安全性：文件大小限制、格式校验、SQL 参数化
✅ 性能：SKU 批量查询而非逐行、分批 100 条入库
✅ 测试覆盖：核心 Service 方法 85% 覆盖

最后跑 openspec validate，确认代码实现覆盖了 spec.md 里的所有场景。

两周后真实感受

好用的点：

  • AI 生成的代码风格统一了。不管开几个对话窗口，rules.md 在，风格就在
  • 需求不会做歪。spec.md 框着，多一个少一个功能都会被 openspec validate 抓出来
  • review 时间少了很多。以前花大半天检查代码，现在主要精力花在审 proposal 上（文字比代码好审多了）

不那么美好的点：

  • 有学习成本。AGENTS.md 的决策树、OpenSpec 三阶段、skill 路由，概念需要消化一下
  • 简单任务会觉得重。改个按钮文案走一遍提案流程确实多余（不过小改动会自动跳过提案）
  • 非 Java 技术栈的 skill 要自己写（框架自带 java-spring，Go/Python 需自建）

几个设计上值得关注的地方

  • 技术栈可插拔：切换技术栈只是换一套 rules.md 和 skills/，通用工作流不受影响
  • 私有栈：公司内部规范不想开源？在 stacks/ 下建个目录，加入自己的规范就行
  • 意图门控：框架会自动判断任务复杂度，简单任务跳过提案直接实现

总结

这个框架的核心思路一句话：与其每次在对话框里反复叮嘱 AI “记得写测试、记得构造器注入”，不如把这些规矩写成项目文件，让 AI 自己去读。

如果你也在用 AI 辅助开发，又受够了生成代码风格不统一的问题，可以试试。

项目地址：https://github.com/chhuax/praxis-devos