用 AI 开发
用 AI 编程工具（Claude Code、Codex、Cursor、GitHub Copilot 等）写业务时，最常见的问题不是它写不出代码，而是它不知道你这个项目的规矩：表名怎么起、权限码怎么写、租户条件加在哪里、改完要跑什么检查。于是生成的代码看着能用，合进来却到处是返工。
栖梧从 1.7.0 版开始，把这些规矩写成 AI 能直接读的文件，随仓库一起发布。它是一套 AI 编程工具读得懂的企业后台底座：你只描述要做的业务，AI 按模板的约定去写，写错了有检查拦下，并告诉它怎么改。
本页是介绍。规则全文和细节以仓库的用 AI 开发为准。
为什么适合 AI 编程
- 一份规则，所有工具都读它：开发约定集中在仓库根目录的
AGENTS.md，各工具的入口文件都指向它。不会出现给 Cursor 写一套、给 Claude Code 写一套、两边慢慢对不上的情况。 - 约定严格，而且能自动检查：分层、命名、租户条件、数据范围、操作日志、多语言都有固定写法，大部分由
pnpm verify检查。AI 写错时当场被拦下，不用等到评审或上线后才发现。 - 生成器优先：标准的增删改查、树表、主子表由代码生成器生成前后端代码和测试，AI 只在生成的代码上写业务扩展，写得少，错得也少。
- 报错带改法：检查失败时写明哪个文件、为什么错、怎样改，AI 照着改完再跑一遍就行。
- 项目地图：一份自动生成的清单，列出项目里已有的模块、表、接口、权限码等，AI 不用翻遍整个仓库就知道该复用什么。
仓库里有哪些文件
| 文件 | 谁读它 | 内容 |
|---|---|---|
AGENTS.md | Codex，以及其他支持 AGENTS.md 约定的工具 | 规则正文：目录与分层、命名、接口、多语言、多租户与数据范围、安全默认、增删改查套件、迁移与种子、测试与完成标准、命令，以及常见报错的改法 |
CLAUDE.md | Claude Code | 只有一行 @AGENTS.md，导入上面的规则 |
.cursor/rules/qiwu.mdc | Cursor | 始终生效的简短规则，要求先读 AGENTS.md、按配方做、结束前跑 pnpm verify |
.github/copilot-instructions.md | GitHub Copilot | 同上的简短指引 |
.claude/skills/qiwu-*/ | Claude Code | 十个技能，每个对应一篇任务配方，在对话里按任务自动选用 |
docs/ai/recipes/ | 人和所有 AI 工具 | 十篇任务配方，见下文 |
docs/ai/project-map.md | 人和所有 AI 工具 | 项目地图，由 pnpm ai:map 生成 |
入口文件里不写规则正文。要改约定，只改 AGENTS.md（或下面的项目规则文件），各工具读到的内容就始终一致。各工具的入口见仓库的各工具读哪个文件。
写上项目自己的规则
AGENTS.md 属于模板，升级模板时会随新版本更新，尽量不要直接改它。你的项目特有的约定，比如业务术语、领域怎么划分、团队的编码习惯、禁止做的事，写在 docs/project-rules.md。
- 模板不提供这个文件，由你新建，所以升级模板时它永远不会冲突；
AGENTS.md开头就要求 AI 先看这个文件是否存在：存在就先读它，两者冲突时以它为准。
例如：
# 项目规则
- 本项目的领域：`crm`（客户关系）、`erp`（进销存）；新表只能放这两个领域。
- “客户”统一叫 customer，不用 client。
- 金额一律用分（整数）存储，界面上再换算成元。见仓库的加上项目自己的规则。
十个任务配方
docs/ai/recipes/ 里是写业务时最常做的十件事，每篇都按“适用场景 → 步骤（文件和命令）→ 完成检查 → 常见错误”来写。能用生成器的步骤一律先用生成器。人可以照着做，也可以直接让 AI 按配方做：
| 配方 | 什么时候用 |
|---|---|
| 新增业务模块 | 给一张新表做增删改查页面（单表、树、主子表），生成器优先 |
| 建表与迁移 | 新建或修改表：迁移命名、租户列、软删除、唯一键 |
| 权限与菜单 | 新增权限点、菜单、菜单分组、操作日志动词，给角色授权 |
| 字典与系统参数 | 新增字典或参数，写进种子，前后端读取 |
| 数据权限 | 让表按部门、创建人过滤；手写 SQL 读带数据范围的表 |
| 手写 SQL 与租户 | 用原始 SQL 读写租户表、跨租户扫描 |
| 队列任务与定时任务 | 把耗时的工作交给后台队列，或新增定时任务 |
| MCP 工具 | 让智能体通过 MCP 调用你模块的能力 |
| 多语言词条 | 新增界面、校验、字段、菜单、服务端消息的中英文词条 |
| 接口测试 | 给接口写端到端测试：成功、403、400、404，以及跨租户 404 |
配方列表和每篇的链接见仓库的任务配方。Claude Code 里，.claude/skills/ 下的十个 qiwu-* 技能会按你描述的任务自动选中对应的配方；其他工具直接告诉它“按 docs/ai/recipes/ 里的某篇配方做”即可。
项目地图
pnpm ai:map 静态解析源码（不连数据库），生成 docs/ai/project-map.md，列出：
- 领域与模块、功能开关；
- 表；
- 每个接口，以及它需要的权限码；
- 权限码、菜单路由名、字典码、系统参数；
- 队列、定时任务处理器、MCP 工具。
AI 读这一个文件，就知道项目里已经有什么，新代码该复用哪个字典、权限码该怎么起名。
改了模块、表、接口、权限、菜单、字典、参数、任务或 MCP 工具以后，运行一次 pnpm ai:map。pnpm verify 会检查项目地图是否和源码一致，过期了就报错并提示你重新生成。合并模板的新版本以后也要重新生成，这个文件有冲突时不要手工解决，直接重新生成，见升级模板版本。
报错带改法
架构检查、多语言检查、原创性检查和许可检查失败时，报错后面会多两行：
fix:：应该怎样改；see:：解释这条规则的文档链接。
项目地图过期时，提示运行 pnpm ai:map。AI（或者你）照着 fix: 改完，再跑一遍检查就行，不需要猜规则。lint、类型检查只给出工具原本的报错。AGENTS.md 末尾的“常见错误”表也列出了常见的几类报错和改法，见仓库的开发规则。
不要让 AI 用关掉检查、加忽略注释的方式“修好”报错。
怎样开始
- 用你的 AI 编程工具打开项目仓库的根目录。工具会自己读到对应的入口文件，不需要额外配置。
- （可选）新建
docs/project-rules.md，写上项目自己的规则。 - 用自然语言描述任务，比如“给
crm_customer表新增客户管理页面”。任务属于十个配方之一时，让它按对应的配方做。 - 让它在结束前运行检查：
pnpm ai:map # 改了模块、表、接口、权限、菜单、字典、参数、任务或 MCP 工具时
pnpm verify # 完成线，必须通过改了接口时，再跑对应的服务端测试，比如 pnpm --filter @qiwu/server test crm-customer.e2e（需要测试库，见快速开始）。
pnpm dev 由你在终端里运行，不要让 AI 启动常驻的开发服务器。完整的本地检查 pnpm ci:local 耗时较长，由你在合并前决定什么时候跑。
仍然要人来把关
规则、配方和检查能让 AI 少犯错，但不能代替你。AI 写的代码请像同事提交的代码一样逐行阅读，确认业务逻辑、权限和数据范围是对的；运行测试，在页面上实际操作一遍，再合并、发布。
和 MCP 智能体接入的区别
本页讲的是开发阶段：AI 帮你写代码。MCP 智能体接入是运行阶段的功能：部署好的系统让智能体以某个用户的身份调用后台工具。两者互不依赖。