BadouCMS 开发规范 Skill 正式发布：让 AI 帮你写出更规范的代码

近期，我们更新了 BadouCMS 开发规范 Skill（更新于 2026-09-19）。与以往面向开发者的文档不同，这套规范从设计之初就是写给 AI 看的——它将被放入 BadouCMS 源码中，作为 Codex、Claude Code、Cursor 等 AI 编程工具的“项目说明书”，让 AI 在修改你的 BadouCMS 项目时，能严格遵循项目约定的技术栈、分层规范和代码风格。

本文将为你梳理其中的核心要点，帮助你理解这套规范如何让 AI 开发更靠谱、更省心。

一、为什么需要一套“给 AI 看”的开发规范？

当你用 AI 工具修改 BadouCMS 代码时，AI 通常会根据通用 PHP/ThinkPHP 知识来生成代码。但每个项目都有自己的约定：事务怎么写、Controller 该多薄、视图用哪个组件、注释用什么语言……如果 AI 不了解这些，生成的代码往往“能跑但不对味”，甚至引入难以排查的隐患。

这套 Skill 就是为解决这个问题而生。它把项目中最容易踩坑、最需要统一的地方，用 AI 能理解的结构化方式写清楚，让 AI 在动手前就知道“什么必须做、什么**不能做”。

二、AI 最容易踩的坑：try {} 内禁止直接结束页面执行

这是规范中第一条“不可违反的规则”。AI 在生成事务代码时，常犯的错误是在 try {} 里直接调用$this->success()或 $this->error()，而这个在 Thinkphp 的代码体系中是不行的，会导致事务状态混乱、异常处理被跳过。

规范明确要求：

try {} 内只负责执行和提交。需要中止事务时，抛出 \RuntimeException 或项目已有的业务异常。

catch {} 中先完成回滚、日志等清理，之后才允许调用 $this->error()。

成功响应必须放在完整的 try/catch 之后。

推荐写法示例：

php
$this->model->startTrans();

try {
// ... 业务逻辑
$this->model->commit();
} catch (\Throwable $e) {
$this->model->rollback();
$this->error($e->getMessage());
}

$this->success(__('Operation completed'));

三、AI 必须遵守的 MVC 分层：别把逻辑都塞进 Controller

AI 生成代码时，容易把所有逻辑堆在 Controller 里。规范明确划定了各层职责：

Controller：保持轻薄，只负责接收请求、组织响应。禁止新增 Db::name()、db() 等直接数据库访问。

Model：负责所有数据库查询和写操作，封装有语义的方法。

Service：承载跨 Model 的业务编排、事务流程、第三方调用。

Validate / View / Route：各司其职。

四、AI 写视图时必须优先复用 BadouAdmin 组件

AI 往往倾向于自己写一套表格、表单或上传逻辑。规范要求优先查找并复用 public/assets/libs/badouadmin/ 下的封装组件：

表格：默认使用 bdTable.api.init() + bdTable.render()。

表单：默认使用 layui-form + bdForm.api.bindevent()。

上传/请求/弹窗：优先使用 bdUpload、badou、bdHttp。

权限显隐：使用 data-operate-* 和 $auth->check()。

规范中提供了标准的表格和表单写法示例，AI 可直接参照生成，避免“另起炉灶”。

五、注释与复杂度：AI 也要说“人话”

新增注释一律使用中文，只为关键业务规则、状态流转、安全边界等说明“为什么这样做”。

实现以简约、易读为优先，不要为了形式上的分层过度拆分方法或 Service。

六、开发流程与 Review 清单：AI 也要自检

规范提供了完整的开发流程，包括编码前查找相近功能、编码时确定数据流、完成后运行 PHP 语法检查和 rg 检索，以及提交前运行 gitnexus_detect_changes()。文末还附有 13 项 Review 清单，AI 在完成任务前可逐项核对。

最后提醒：如何让 Codex 等 AI 工具使用这个 Skill？

这套开发规范 Skill 会随 BadouCMS 源码一起提供。你在使用 Codex、Claude Code、Cursor 等 AI 工具修改项目时，可以：

直接让 AI 读取该 Skill 文件：在对话中告诉 AI“请先阅读项目中的 BadouCMS 开发规范 Skill，再开始修改”，AI 会自动加载并遵循其中的规则。

在项目配置中引用：如果 AI 工具支持项目级指令文件（如 AGENTS.md、.cursorrules 等），可将该 Skill 的核心约束写入其中，让 AI 在每次对话时自动遵循。

修改前先确认：让 AI 在动手前先复述它理解的关键规则，确认无误后再让它生成代码。

这样，AI 就不再是“凭感觉写代码”，而是真正按照 BadouCMS 的项目规范来协作，大幅减少返工和隐藏 bug。

​相关链接​：

• BadouCMS 开发规范 Skill 原文