---
url: https://qiwuadmin.com/guide/ai.md
description: >-
  栖梧是一套 AI 编程工具读得懂的企业后台底座：一份开发规则供 Claude Code、Codex、Cursor、Copilot
  共同读取，项目规则单独存放，十个任务配方，自动生成的项目地图，检查失败时给出改法和文档链接。
---

# 用 AI 开发

用 AI 编程工具（Claude Code、Codex、Cursor、GitHub Copilot 等）写业务时，最常见的问题不是它写不出代码，而是它**不知道你这个项目的规矩**：表名怎么起、权限码怎么写、租户条件加在哪里、改完要跑什么检查。于是生成的代码看着能用，合进来却到处是返工。

栖梧从 1.7.0 版开始，把这些规矩写成 AI 能直接读的文件，随仓库一起发布。它是一套 **AI 编程工具读得懂的企业后台底座**：你只描述要做的业务，AI 按模板的约定去写，写错了有检查拦下，并告诉它怎么改。

本页是介绍。规则全文和细节以仓库的[用 AI 开发](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/ai.md)为准。

## 为什么适合 AI 编程

* **一份规则，所有工具都读它**：开发约定集中在仓库根目录的 `AGENTS.md`，各工具的入口文件都指向它。不会出现给 Cursor 写一套、给 Claude Code 写一套、两边慢慢对不上的情况。
* **约定严格，而且能自动检查**：分层、命名、租户条件、数据范围、操作日志、多语言都有固定写法，大部分由 `pnpm verify` 检查。AI 写错时当场被拦下，不用等到评审或上线后才发现。
* **生成器优先**：标准的增删改查、树表、主子表由[代码生成器](/features/codegen)生成前后端代码和测试，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`（或下面的项目规则文件），各工具读到的内容就始终一致。各工具的入口见仓库的[各工具读哪个文件](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/ai.md#各工具读哪个文件)。

## 写上项目自己的规则

`AGENTS.md` 属于模板，升级模板时会随新版本更新，尽量不要直接改它。你的项目特有的约定，比如业务术语、领域怎么划分、团队的编码习惯、禁止做的事，写在 **`docs/project-rules.md`**。

* 模板**不提供**这个文件，由你新建，所以升级模板时它永远不会冲突；
* `AGENTS.md` 开头就要求 AI 先看这个文件是否存在：存在就先读它，两者冲突时**以它为准**。

例如：

```md
# 项目规则

- 本项目的领域：`crm`（客户关系）、`erp`（进销存）；新表只能放这两个领域。
- “客户”统一叫 customer，不用 client。
- 金额一律用分（整数）存储，界面上再换算成元。
```

见仓库的[加上项目自己的规则](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/ai.md#加上项目自己的规则)。

## 十个任务配方

`docs/ai/recipes/` 里是写业务时最常做的十件事，每篇都按“适用场景 → 步骤（文件和命令）→ 完成检查 → 常见错误”来写。能用生成器的步骤一律先用生成器。人可以照着做，也可以直接让 AI 按配方做：

| 配方 | 什么时候用 |
| --- | --- |
| 新增业务模块 | 给一张新表做增删改查页面（单表、树、主子表），生成器优先 |
| 建表与迁移 | 新建或修改表：迁移命名、租户列、软删除、唯一键 |
| 权限与菜单 | 新增权限点、菜单、菜单分组、操作日志动词，给角色授权 |
| 字典与系统参数 | 新增字典或参数，写进种子，前后端读取 |
| 数据权限 | 让表按部门、创建人过滤；手写 SQL 读带数据范围的表 |
| 手写 SQL 与租户 | 用原始 SQL 读写租户表、跨租户扫描 |
| 队列任务与定时任务 | 把耗时的工作交给后台队列，或新增定时任务 |
| MCP 工具 | 让智能体通过 [MCP](/features/mcp) 调用你模块的能力 |
| 多语言词条 | 新增界面、校验、字段、菜单、服务端消息的中英文词条 |
| 接口测试 | 给接口写端到端测试：成功、403、400、404，以及跨租户 404 |

配方列表和每篇的链接见仓库的[任务配方](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/ai/recipes/README.md)。Claude Code 里，`.claude/skills/` 下的十个 `qiwu-*` 技能会按你描述的任务自动选中对应的配方；其他工具直接告诉它“按 `docs/ai/recipes/` 里的某篇配方做”即可。

## 项目地图

`pnpm ai:map` 静态解析源码（不连数据库），生成 `docs/ai/project-map.md`，列出：

* 领域与模块、功能开关；
* 表；
* 每个接口，以及它需要的权限码；
* 权限码、菜单路由名、字典码、系统参数；
* 队列、定时任务处理器、MCP 工具。

AI 读这一个文件，就知道项目里已经有什么，新代码该复用哪个字典、权限码该怎么起名。

改了模块、表、接口、权限、菜单、字典、参数、任务或 MCP 工具以后，运行一次 `pnpm ai:map`。`pnpm verify` 会检查项目地图是否和源码一致，过期了就报错并提示你重新生成。合并模板的新版本以后也要重新生成，这个文件有冲突时不要手工解决，直接重新生成，见[升级模板版本](/guide/upgrade#合并后的检查)。

## 报错带改法

架构检查、多语言检查、原创性检查和许可检查失败时，报错后面会多两行：

* `fix:`：应该怎样改；
* `see:`：解释这条规则的文档链接。

项目地图过期时，提示运行 `pnpm ai:map`。AI（或者你）照着 `fix:` 改完，再跑一遍检查就行，不需要猜规则。lint、类型检查只给出工具原本的报错。`AGENTS.md` 末尾的“常见错误”表也列出了常见的几类报错和改法，见仓库的[开发规则](https://github.com/732124645/qiwu-vue-admin/blob/main/AGENTS.md#常见错误)。

不要让 AI 用关掉检查、加忽略注释的方式“修好”报错。

## 怎样开始

1. 用你的 AI 编程工具打开项目仓库的根目录。工具会自己读到对应的入口文件，不需要额外配置。
2. （可选）新建 `docs/project-rules.md`，写上项目自己的规则。
3. 用自然语言描述任务，比如“给 `crm_customer` 表新增客户管理页面”。任务属于十个配方之一时，让它按对应的配方做。
4. 让它在结束前运行检查：

```bash
pnpm ai:map    # 改了模块、表、接口、权限、菜单、字典、参数、任务或 MCP 工具时
pnpm verify    # 完成线，必须通过
```

改了接口时，再跑对应的服务端测试，比如 `pnpm --filter @qiwu/server test crm-customer.e2e`（需要测试库，见[快速开始](/guide/getting-started)）。

`pnpm dev` 由你在终端里运行，不要让 AI 启动常驻的开发服务器。完整的本地检查 `pnpm ci:local` 耗时较长，由你在合并前决定什么时候跑。

::: warning 仍然要人来把关
规则、配方和检查能让 AI 少犯错，但不能代替你。AI 写的代码请像同事提交的代码一样逐行阅读，确认业务逻辑、权限和数据范围是对的；运行测试，在页面上实际操作一遍，再合并、发布。
:::

## 和 MCP 智能体接入的区别

本页讲的是**开发阶段**：AI 帮你写代码。[MCP 智能体接入](/features/mcp)是**运行阶段**的功能：部署好的系统让智能体以某个用户的身份调用后台工具。两者互不依赖。