构建后台管理系统：创建功能

一个功能就是一项管理任务——"管理文章"、"管理订单"、"管理客户"。这一页讲怎么在 创建项目搭好的空架子上从零加一个新功能，一共五句提示词， 每句都以一个不用看代码就能检查的结果收尾。每个功能的形状都一样：一张数据库表存 信息，一个后台干活的服务负责读写，一个管理页面上面放着按钮。下面以文章为例， 换成你真正需要管理的东西都行——换的是名词，形状不变。

隔了一段时间再回来？

如果电脑重启过，之前运行的东西就都停了——让 Agent 把系统需要的一切都启动起来， 等页面可以打开了告诉你。

第 1 步 —— 说清楚你要管理什么

动代码之前，先用大白话想清楚三件事，把答案写进提示词里：它只管理哪一种东西、人实际 要填哪些字段、能对它做什么操作（日常操作标准功能都已覆盖）。"做一个文章功能"这种 模糊要求会把每个决定都丢给 Agent，而它猜的八成和你想的不一样。

提示词

我想要一个新功能来管理文章。动任何东西之前，先读 apps/api/AGENTS.md 和 apps/web-admin/AGENTS.md，然后把方案给我看，等我批准。

每篇文章包含这些信息：

• 标题——文本，必填
• 作者——文本
• 摘要——几行文字
• 是否发布——一个是/否开关，默认为否
• 发布日期——一个日期

我需要常用的管理功能：带搜索的分页列表、新增、编辑、删除、批量删除，以及 Excel 导入和导出。还要带上标准的记录字段（谁在什么时候创建、谁在什么时候最后修改）。

你应该看到： 一份写出来的方案，还不是代码。方案里应该点到数据库表、后台干活的 各部分、管理页面和菜单条目。把字段清单对照你自己的要求读一遍——这是说"不对，我要 的不是这个"成本最低的时候。先要方案（纠正方案只要一句话，拆写错的代码要花一个下午）， 一次也只做一个功能。

第 2 步 —— 知道一个完整功能包含什么

这些东西不用你亲手写，但你可以检查它们是否都到位。一个功能横跨两个半端，漏掉 任何一层都是最常见的失败：

层	是什么	在哪里
数据存放处	一篇文章一行、一个字段一列	跑在盒子里的数据库
实体类	与表对应的 Java 类	apps/api/
Mapper 和 XML	读写这张表	apps/api/
Service 接口和实现	页面与表之间的业务规则	apps/api/
Controller	页面调用的地址：列表、新增、编辑、删除、导入、导出	apps/api/
列表页、表单、列配置、接口文件	表格、新增/编辑弹窗以及它们发出的请求	apps/web-admin/
菜单和按钮权限	左侧菜单里的入口，以及谁能按每个按钮	以数据形式注册，而不是写在程序里

一个普通功能大约是六个后台文件加四个网页文件。项目自带的代码生成器会根据你的 描述，按现有功能（比如职务管理）的同一套模式，把这十个文件一次性生成出来——Agent 知道该用它，所以你的提示词只需要说结果。

提示词

用项目的标准方式做这个功能——和现有功能的做法一样——包括管理页面、在后台存放 数据的服务，还有菜单入口。照现有功能的模式来，不要自创目录结构。

你应该看到： 新文件分布在两个半端，另外还有一个负责注册菜单的文件（文件名里带有 menu_insert 字样）。如果 Agent 提出"我直接按自己的风格手写就行"，就说："不行——用 标准方式做，照现有功能的模式来。"

第 3 步 —— 让菜单出现、把数据存放处准备好

光有代码是看不见的：管理网页在你登录时从数据存放处读取菜单。标准做法会生成一个小小 的注册文件——一条主菜单加六个按钮（新增、编辑、删除、批量删除、导出、导入），并且 已经授权给管理员账号。

提示词

把新功能注册好，让它出现在菜单里、可以直接使用；同时准备好存放它数据的地方。 告诉我它会出现在左侧菜单的什么位置。

你应该看到： Agent 确认这两件事都完成了，并且说出入口会出现在左侧菜单的什么 位置。

为什么菜单是数据，不是代码

这个管理后台采用的是 BACK 模式：业务菜单是数据，不是写死在网页里的入口——正 因为这样，管理员才能不改版就把某个菜单或按钮授权给某个角色。代价是：把程序拷到 另一台机器并不会把菜单带过去，在那台机器上重新注册才会。

第 4 步 —— 重启、打开、把每个按钮试一遍

正在运行的系统只有重新启动之后才会认识新代码，网页还需要重新加载一下。之后像真实 用户一样把整个功能走一遍。

提示词

该重启的都重启一下，确认管理网页已经准备好。然后你自己检查文章功能：菜单出现了； 列表打开是空的但不报错；能新增一篇文章并在列表里看到；能搜索它；能编辑它（包括把 发布开关拨到"是"）；能把列表导出成电子表格，再导回来；能删除一条，也能一次勾选 多条删除。每一项的结果都向我报告。

你应该看到： 一张每个操作都通过的清单。特别留意发布开关：它必须在三个地方 都存在（存下来的字段、取数据的接口、屏幕上的那一列）；一个开关看得见却永远存不进去， 就说明后台干活的那一半漏了。如果 Agent 报告的文件清单只涉及一半，就说："你只做了 一半，把另一半补上。"

第 5 步 —— 写下来

提示词

把文章功能包含什么、是怎么生成的，作为内部笔记写下来。然后在文档站上加一页面向 读者的页面，介绍这个新功能，并且在侧边栏里注册。

Agent 总是搞混两个写东西的地方：

你写什么	放哪里
笔记、方案、给自己和团队看的记录	.docs/——私有的，不对外发布
给读者看的页面	docs/content/，并且要在 docs/sidebars.ts 里注册

你应该看到： 笔记在私有文件夹里，页面在公开文件夹里，还有一个新的侧边栏条目。 不在侧边栏里的页面在文档站上根本不会出现，所以问："你加的是哪个侧边栏条目？"然后 说："构建一下文档站，告诉我是否通过了。"文档站内部链接一断就构建失败，所以构建通过 是实打实的证据。

每个按钮都能用、也写下来了，这个功能就算做完了。下一步：部署上线。

卡住了怎么办

你不需要诊断任何东西。找到你的症状，说那句话：

你看到什么	这样说
功能做好了，但没有菜单入口	"菜单要先注册才会出现——注册一下，然后重新登录"
页面打开了，但每个操作都报错	"该重启的重启一下，让新代码加载进来，然后刷新页面"
一列能显示却永远存不进去	"后台干活的那一半漏了——这个字段既要存下来，也要能通过数据接口读到"
生成的文件全都挤在一半	"功能横跨两半——存数据的服务和管理页面要一起做"
按钮看得见，但非管理员账号点了没反应	"把这六个按钮的使用权限授予那个角色——管理员是自动拥有的"
列表一直转圈加载不出来	"页面拿不到数据——去运行日志里找到真正的报错，然后修掉它"
Agent 按自己的布局手写了一堆文件	"把这些扔掉，用项目的标准方式做，照现有功能的模式来"