3.6 接手现成项目，让 Agent 完成机房排座系统的第一次改造

上一节，我们从静态 HTML 和 PRD 出发，让 IDE Agent 分阶段补齐了后端、数据保存和统计看板。

这一次，我们换一个更接近学校真实情况的场景：手里已经有一个别人做好的校园项目，但它还需要根据本校的使用习惯做一点调整。

示例项目地址是：

https://gitee.com/yldj-it/computer-lab-reasign

它是一个机房排座系统，涉及机房布局、班级名单、座位安排、投屏展示和只读分享等功能。

这是作者亲自跑通的完整技术样板。不负责机房的老师也不需要把业务照搬到自己的学科；这一篇真正训练的是让 Agent 读懂、运行、解释并局部改造一个现成项目的方法。

这一篇的目标不是让你从头学会 Next.js、TypeScript 或数据库，而是完成一次更重要的迁移：

从让 Agent 搭建简单项目，
迁移到让 Agent 接手和改造现成项目。

不是先学完整套技术，而是先让项目跑起来

很多老师第一次打开完整项目，会先被这些词吓住：

• Next.js
• TypeScript
• Prisma
• MySQL
• 登录
• 拖拽

但你现在不需要先学会它们。

面对现成项目，第一步应该是：

先运行它，看看它现在能做什么。

项目能打开、流程能操作，你才知道自己真正想改什么。

先用 IDE 打开整个项目

可以先从 Gitee 下载项目压缩包，也可以使用 Git 克隆项目。为了保留项目原有的版本记录，更建议使用 Git 克隆：

git clone https://gitee.com/yldj-it/computer-lab-reasign.git

如果你还不熟悉 Git，也可以先让 VS Code、Trae 或 Qoder 中的 IDE Agent 协助你完成获取和打开。命令需要执行前，先让 Agent 说明它准备做什么。

打开项目时，要选择整个 computer-lab-reasign 文件夹，而不是只打开其中一个页面文件。

只有打开整个项目，IDE Agent 才能同时看到：

• README.md 中的使用和启动说明。
• PRD.md 中的需求描述。
• package.json 中的项目命令。
• 页面、组件、数据库和配置文件。

先保护数据

练习时不要把真实学生姓名、学号、成绩、账号密码或数据库文件交给公开 AI。名单和机房布局都使用模拟数据，配置文件中的密钥也不要上传。可以先使用测试数据，数量大的话，也可以让AI构造一部分测试数据。

让 Agent 先说明怎样运行

不要一打开项目就让 Agent 改代码。先让它阅读说明文件，并解释当前电脑还缺什么环境。

可以在 IDE Agent 中输入：

请先阅读这个项目的 README.md、PRD.md、package.json 和环境配置示例。

我准备在本机运行这个机房排座系统。
请用没有完整开发经验的老师能听懂的话告诉我：
1. 这个项目目前主要解决什么问题。
2. 本机运行还需要哪些环境。
3. 准备执行哪些命令，每条命令是做什么的。
4. 哪些步骤可能会创建或修改数据库。
5. 启动成功后，我应该按什么顺序体验主要功能。

先不要修改代码，也不要执行命令。请先给出检查结果和操作计划。

这一步的目的不是让 Agent 背技术名词，而是让你知道：

• 项目现在能不能运行。
• 运行它需要哪些条件。
• 哪些命令可能会影响数据。
• 接下来应该怎样体验项目。

如果 Agent 建议执行类似下面的命令，不要直接复制，而要先看清当前项目的说明：

npm install
npm run dev

涉及数据库初始化、数据库结构变更或清空测试数据的命令，更要先确认影响范围。

先按教师工作流体验一次

项目启动后，不要马上打开代码。先把自己当成一名真正使用系统的老师，走一遍主要流程：

1. 创建或打开一个机房布局。
2. 设置几行几列的座位。
3. 导入一个完全虚构的测试班级名单。
4. 生成排座结果。
5. 手动调整一两个座位。
6. 切换到投屏页面查看展示效果。
7. 如果项目支持，打开只读分享页面。

体验时记下三个问题：

• 哪一步看不懂？
• 哪一步操作麻烦？
• 哪个页面如果改一下，会更适合本校课堂？

这比一开始阅读几十个代码文件更有帮助。Vibe Coding 的需求，应该来自真实工作，而不是来自对技术名词的猜测。

给自己选一个小而可见的改造

第一次改造不要选择“重做排座算法”或“重新设计整个系统”。选择一个满足下面条件的任务：

• 老师能用一句话说清楚。
• 修改范围比较有限。
• 修改结果能在页面上直接看到。
• 可以使用模拟数据验证。
• 不会同时牵动登录、数据库和多个核心业务模块。

本篇建议使用这个示例：

让投屏页面更适合课堂使用，在顶部显示班级名称和课程名称，并把文字调整到后排也能看清。

这个任务和老师的日常使用直接相关，而且验收很直观：打开投屏页面，看信息是否出现、字号是否合适、座位内容是否仍然正常。

如果当前项目已经具备这些显示内容，就让 Agent 先检查现状，再改做同等规模的任务，例如优化学生名单导入时的错误提示。

让 Agent 只解释当前任务相关的部分

现在才需要项目地图。但项目地图不是让 Agent 把整个代码库讲一遍，而是只回答当前任务需要知道的问题。

可以这样输入：

我想完成一个小改造：
让投屏页面在顶部显示班级名称和课程名称，并适合教室后排观看。

请先不要修改代码，只完成分析：
1. 投屏页面对应哪个页面或路由。
2. 班级名称和课程名称目前保存在哪里，或者目前是否还没有这两个字段。
3. 投屏页面由哪些组件组成。
4. 预计需要修改哪些文件。
5. 这个改造会不会影响排座、数据库、登录和分享功能。
6. 你建议怎样用模拟数据验收。

请只分析与投屏页面有关的内容，不要介绍整个项目的所有技术细节。

Agent 输出的项目地图，只需要包含下面四类信息：

需要知道的内容	老师要确认什么
页面位置	改造会发生在哪个页面
数据来源	页面上的班级和课程信息从哪里来
相关文件	Agent 准备修改哪些文件
影响范围	会不会碰到排座、登录或数据库

如果 Agent 回复了一大段技术名词，可以继续追问：

请不要继续罗列框架名称。
请只用“页面、数据、文件、影响范围、验收方法”五项重新整理。

这就是项目拆解在本文中的作用：帮助你确认 Agent 找对了地方，而不是要求你自己先学会整个项目。

先看计划，再允许修改

拿到项目地图后，不要立刻说“开始改吧”。先让 Agent 给出一个最小修改计划：

请根据刚才的分析，给出一个最小修改计划。

要求：
1. 只处理投屏页面顶部信息和显示效果。
2. 不修改排座算法。
3. 不修改登录、分享权限和数据库结构。
4. 先列出准备修改的文件和每个文件的作用。
5. 说明修改后需要怎样测试。
6. 在我确认前不要修改文件，也不要执行危险命令。

老师重点看三件事：

• Agent 是否找到了与任务有关的文件。
• 修改范围是否比需求大很多。
• 验收方法是否能由自己完成。

如果 Agent 说要同时修改数据库、登录、座位算法和投屏页面，而你的需求只是调整投屏显示，就应该要求它重新缩小范围。

确认计划后，再输入：

我确认这个修改计划。
请只按计划完成投屏页面的局部改造，
不要重写页面，不要修改无关模块。

完成后请告诉我：
1. 实际修改了哪些文件。
2. 每个文件改了什么。
3. 运行了哪些检查。
4. 我应该怎样用模拟数据验收。

用模拟数据验收，而不是只看页面能打开

修改完成后，至少用下面几种情况进行检查：

验收场景	应该检查什么
选择测试班级	顶部显示正确的班级名称
选择另一测试班级	班级切换后不会显示上一班的信息
填写或选择课程信息	课程名称显示完整，不遮挡其他内容
打开投屏页面	后排观看时文字仍然清楚
刷新页面	已保存的排座结果没有消失
返回排座页面	座位、学生和调整功能没有被破坏

如果改的是名单导入错误提示，则可以使用这些模拟文件：

• 空文件。
• 缺少姓名或学号的文件。
• 含有重复学号的文件。
• 格式正确的测试班级名单。

不要只验证“首页能打开”。一个校园工具真正完成，至少要能走完与教师工作有关的一条完整流程。

遇到报错时，仍然只处理当前任务

如果修改后出现报错，不要直接让 Agent “重写整个项目”。把现象和完整日志交给它，并限制处理范围：

修改投屏页面后出现下面的报错：

请先解释报错原因，定位到具体文件。
只修复这次投屏页面改造引入的问题，
不要重构其他模块，也不要升级无关依赖。
修复后请告诉我需要重新验收哪些场景。

如果 Agent 建议删除数据库、重装所有依赖或批量重写文件，要先停下来确认原因和影响。复杂项目最怕的不是出现一个小报错，而是为了解决小报错引入更大的未知改动。

这次改造完成后，交给 Git 存档

到这里，你已经完成了一个完整的小步：

打开现成项目
  -> 运行并体验
  -> 提出真实需求
  -> Agent 定位相关文件
  -> 确认计划
  -> 完成局部修改
  -> 使用模拟数据验收

在继续让 Agent 做下一件事之前，先进入 3.7 保存这个可用节点。Git 的具体操作包括：

• 查看修改了哪些文件。
• 确认没有把真实数据和密钥提交进去。
• 记录这次改造的结果。
• 需要多台电脑或协作时，再推送到 Gitee 远程仓库。

下一篇会把这条安全带讲清楚。

以后接手英语练习页、实验记录工具或教研组已有的小系统时，也可以沿用同一顺序：先运行和体验，再提出一个边界清楚的小需求，最后用模拟数据验收。

用流程图回看这次项目接手

flowchart TD
  A[打开现成项目] --> B[运行并体验流程]
  B --> C[提出一个真实小需求]
  C --> D[Agent 定位相关文件]
  D --> E[确认最小修改计划]
  E --> F[完成局部改造]
  F --> G[模拟数据验收]
  G --> H[进入 3.7 Git 存档]

封面