1.4 在 Trae 中开发图书管理系统：从模板到可验证功能¶
用工程方法完成第一个真实模块¶
这一节不只是“让 AI 写几个页面”
现在你已经有了开发工具、工程方法和项目规则。接下来，要把它们用在一个真实项目上：基于课程提供的图书管理系统模板，完成一个可以运行、可以验证、也能够解释的功能模块。
- 模板仓库：提供已有项目结构、基础代码和参考原型；
- Trae：帮助你阅读代码、拆分任务、修改文件和定位问题；
- Superpowers-zh：提醒你先分析、再计划、分步实现并验证；
AGENTS.md：约束 AI 不要脱离项目事实自由发挥；- 你：审核方案、运行代码、确认结果，并对最终提交负责。
本节学习目标
在模板项目基础上，用 Trae 按“阅读 → 计划 → 实现 → 验证 → 提交”的流程完成一个图书管理系统模块。
🎯 本次带练要完成什么¶
本节使用课程提供的 图书管理系统模板仓库 开始开发。模板克隆后位于本机的 lab2_2/book_template 目录；功能实现必须以 doc/需求分析说明书.md 和 doc/系统设计说明书.md 为依据。模板不是交付成品，而是让你把时间放在理解业务、补全功能和验证结果上。
建议先选择一个完整但范围可控的模块。例如：
| 模块 | 最小可交付成果 | 可以验证什么 |
|---|---|---|
| 图书浏览 | 图书列表、搜索、详情页 | 能查询、展示并打开详情 |
| 我的借阅 | 当前借阅与历史借阅列表 | 登录后只能看到自己的记录 |
| 图书管理 | 管理员查询、新增或编辑图书 | 管理端操作后数据正确变化 |
| 借阅办理 | 用户申请借阅或管理员确认归还 | 库存和借阅记录符合业务规则 |
| 个人中心 | 查看资料并修改允许编辑的信息 | 修改后重新进入页面仍能看到结果 |
先完成一个闭环，不要一次做完整系统
一个模块的“闭环”至少包括：用户入口、页面或接口、核心业务处理、数据变化和验证结果。先让一条主流程跑通，再补边界情况和体验细节。
📦 第一步：获取并运行模板项目¶
模板已克隆到本机后，直接进入项目目录：
然后用 Trae 打开 book_template 目录。不要急着修改代码，先完成下面的检查：
- 优先阅读
doc/需求分析说明书.md与doc/系统设计说明书.md，再阅读README、数据库脚本、配置文件和已有代码； - 确认前端、后端和数据库分别位于哪个目录；
- 找到项目已有的启动方式、默认端口和测试账号；
- 按模板说明完成依赖安装、数据库配置和项目启动；
- 在浏览器中打开页面，确认初始系统能够访问。
先运行模板，再开始开发
如果模板尚未运行，就直接让 AI 增加功能，后续很难区分问题来自环境、原有代码还是新修改。只有先确认“初始状态可运行”，新增功能的验证才有依据。
记录你的初始检查结果¶
建议在自己的任务记录中写下：
| 检查项 | 需要记录的内容 |
|---|---|
| 本机环境 | JDK、Node.js、数据库等版本是否满足模板要求 |
| 启动命令 | 前端和后端各使用什么命令启动 |
| 访问地址 | 页面地址、接口地址或 API 文档地址 |
| 初始功能 | 登录、图书列表、管理端等哪些功能已可访问 |
| 已知问题 | 启动报错、缺失配置、页面异常或待补功能 |
📄 第二步：先为项目写好 AGENTS.md¶
在修改任何业务代码前，先在 book_template 根目录创建或完善 AGENTS.md。它不需要很长，但必须反映当前项目的真实情况。
可以从下面的内容开始，再根据模板实际目录和技术栈调整：
规则要和项目一起成长
第一次只写最重要的 3—5 条即可。等你在开发中遇到反复出现的问题，例如 AI 总是漏测、总是修改无关文件，再把针对性的规则补进 AGENTS.md。
🧠 第三步：让 Superpowers-zh 管住开发节奏¶
安装 Superpowers-zh 后，不是每次都要背诵全部流程，而是根据任务主动使用合适的方法。
| 任务阶段 | 建议使用的工程方法 | 你应该看到的结果 |
|---|---|---|
| 需求还不清楚 | 头脑风暴 | AI 先询问角色、流程、边界和验收标准 |
| 功能范围较大 | 编写计划 | 任务被拆成可以逐步验证的小步骤 |
| 修改核心逻辑 | 测试驱动开发 | 先明确预期行为，再实现代码 |
| 出现报错 | 系统化调试 | 先收集报错与复现步骤，再分析原因 |
| 完成一个模块 | 代码审查、完成前验证 | 有检查清单、测试结果和改动说明 |
在 Trae 对话中，可以先这样发出请求：
如果 AI 直接开始生成大量代码，提醒它回到计划阶段；如果它提出的方案与项目现状不符，要求它重新阅读对应文件。先纠正上下文，再继续实现。
🧩 第四步：把一个模块拆成小任务¶
以“图书浏览与图书借阅”为例，不要让 AI 一次完成所有内容。可以拆成下面的任务卡：
| 顺序 | 小任务 | 可能涉及的内容 | 完成标准 |
|---|---|---|---|
| 1 | 阅读现状 | 页面、接口、实体、数据库脚本 | 说清当前数据从哪里来、页面如何获取数据 |
| 2 | 明确规则 | 可借条件、库存展示、登录要求 | 写出主流程和异常场景 |
| 3 | 图书列表 | 查询接口、列表页面、搜索条件 | 能正确显示并按条件查询 |
| 4 | 图书详情 | 详情接口或页面、借阅入口 | 能看到正确图书信息 |
| 5 | 提交借阅 | 校验、记录创建、库存或状态处理 | 成功与失败场景都符合规则 |
| 6 | 验证与审查 | 测试、浏览器操作、代码检查 | 主流程可复现，改动说明完整 |
一次只处理一个可以验证的小任务
不要在“列表还没显示”时就同时让 AI 修改详情、借阅、库存、权限和统计。改动范围越大，错误越难定位，也越难解释每一段代码的作用。
给 AI 的单任务提示词¶
每次只把一个小任务交给 AI。例如先做“阅读现状”：
确认分析无误后，再让 AI 提交实施方案：
🔍 第五步：实施时保持“最小改动”¶
收到 AI 的方案后，先检查它是否回答了以下问题：
- 是否复用了模板已有的分层结构和组件？
- 是否明确了请求参数、返回数据和页面交互？
- 是否出现了设计文档或已有代码中没有的新概念？
- 是否修改了数据库表结构、依赖版本或无关模块？
- 是否给出了可执行的验证方法？
确认后再实施。实施过程中坚持下面的原则：
| 原则 | 正确做法 | 常见误区 |
|---|---|---|
| 先读再改 | 修改目标文件前阅读完整上下文 | 只看几行匹配结果就整体覆盖 |
| 最小改动 | 只改完成当前任务必需的文件 | 顺手重构无关代码或改全局配置 |
| 复用优先 | 使用已有组件、请求封装和错误处理 | 重新造一套重复工具 |
| 边改边验 | 一个小任务完成就运行对应验证 | 全部改完才第一次启动 |
| 保留证据 | 记录命令、截图、测试结果和问题 | 只口头说“已经完成” |
不要接受“我已完成”的空结论
AI 说功能完成后，必须让它给出改动文件、关键逻辑、执行过的命令和结果。你还要亲自运行并观察页面或接口返回。没有证据的“完成”不计入项目成果。
✅ 第六步：用三层验证确认功能真的可用¶
完成一个小功能后，至少从三个层面检查：
| 验证层次 | 要做什么 | 示例 |
|---|---|---|
| 代码层 | 检查改动范围、类型、参数和错误处理 | 搜索是否有硬编码账号、无效导入或未使用变量 |
| 运行层 | 启动项目并查看终端、网络请求和控制台 | 前后端是否正常启动，接口是否返回预期数据 |
| 业务层 | 用真实用户路径操作页面 | 搜索图书 → 查看详情 → 提交借阅 → 查看借阅记录 |
最小验收清单¶
每完成一个模块，请逐项确认：
- 项目仍能正常启动，没有新增编译错误；
- 主流程在页面或接口中可以真实操作；
- 至少验证一个失败或边界场景，例如未登录、库存不足、查询无结果；
- 没有泄露账号、密码、密钥或本机配置；
- 改动文件数量与任务范围相符；
- 能解释每个主要改动解决了什么问题；
- 已记录验证命令、结果和仍待确认的问题。
如果出现报错，不要只把报错截图发给 AI 并要求“修一下”。应提供完整证据：
👀 第七步：完成前进行 AI 代码审查¶
功能跑通不代表代码一定可靠。提交前，让 AI 以审查者身份重新检查，而不是继续让同一个思路“自证正确”。
可以这样提问：
审查结论也需要你判断
AI 可能提出不适合当前课程范围的架构升级，或把“个人偏好”说成“必须修复”。优先处理会导致功能错误、数据错误、安全问题或违反项目规则的问题；其他建议记录下来即可。
📝 第八步：让每一次提交都能说明成果¶
当功能通过验证后，再创建 Git 提交。一次提交应尽量对应一个可说明的小成果。
提交前，先检查：
确认不会误提交 .env、本机配置、依赖缓存、构建产物或无关文件后，再执行：
提交信息不必追求复杂，但应说明完成了什么可验证的成果。例如：
| 场景 | 示例提交信息 |
|---|---|
| 新增功能 | feat(book): 支持按书名搜索图书 |
| 修复问题 | fix(borrow): 修正重复提交导致的库存异常 |
| 补充测试 | test(book): 覆盖图书搜索无结果场景 |
| 更新文档 | docs: 补充图书借阅模块验证记录 |
🚦 本节完成后，你应该拥有¶
完成带练后，不只是拥有“AI 生成的一批代码”，而是拥有一段可以复盘的真实开发过程：
- 一个已运行的图书管理系统模板项目；
- 一份与项目实际情况一致的
AGENTS.md； - 一个拆分清晰、已完成主流程验证的功能模块；
- 一份包含启动、操作、错误和修复证据的任务记录；
- 一次或多次能说明功能成果的 Git 提交；
- 对关键页面、接口、业务规则和改动原因的理解。
先从模板跑起来，再让一个模块形成闭环；先让 AI 提出方案，再让代码和运行结果证明它正确。
📝 本节小结¶
- 模板是起点，不是成品：先确认它能运行，再在已有结构上开发；
- 规则先于代码：用
AGENTS.md写清项目边界，让 AI 基于真实项目协作； - Superpowers-zh 管理过程：用计划、测试、调试和审查避免“直接开写”；
- 小任务逐步交付：每次只完成一个可验证的改动，降低调试难度；
- 验证与提交留下证据：运行结果、测试记录和 Git 历史共同证明你的真实成果。