8. 迁移练习

来源：ZCode

主项目已经完成。下面三组练习分别测试三种不同能力：修缺陷、理解陌生代码、沉淀重复流程。它们不是把“今日专注清单”换个名字再做一遍。

课程目录中的 exercises/ 已提供起始文件。每次练习先复制对应文件夹，在副本中操作，保留原始材料便于重来。

练习一：修复刷新后丢失的计数

起始材料：01-counter-bug

起始问题

这是一个能加一、减一和归零的本地计数器。减一和归零会保存，但“加一”后刷新页面会回到旧值。

你的任务

1. 在 ZCode 中把练习副本作为独立工作区打开。
2. 先点击“归零”，再连续加一两次并刷新，记录实际值和期望值。
3. 新建任务，引用 app.js，要求 Agent 先复现，再做最小修复。
4. 回归减一、归零和刷新，不修改页面结构与样式。

新判断

症状发生在刷新后，不代表问题一定出在“读取”。保存路径和读取路径都要检查。让 Agent 先描述数据何时写入、何时读取，再决定修改哪一处。

验收

• 连续加一两次后刷新，数字保持不变；
• 减一和归零仍正常；
• 只修改实现问题所需的文件；
• Review 中没有框架、依赖或无关重构。

练习二：读懂仓库，但先不改代码

起始材料：02-reading-list

起始问题

你接手了一个“阅读清单”网页。它能按状态筛选书目，但没有面向新维护者的结构说明。产品希望以后加入评分功能，你现在还不应该直接实现。

准备基线

把副本作为工作区打开，在终端中建立本地 Git 基线：

git init
git add README.md index.html styles.css data.js app.js
git commit -m "baseline: reading list sample"

若提示缺少身份，沿用第 6 课的仓库本地配置。建立 Git 仓库后，如果工作区顶部出现“仓库 Wiki”入口，可以先生成架构导读；无论是否使用 Wiki，都要用 @ 引用实际源文件核对结论。

你的任务

让 Agent 只创建两个文档：

• ONBOARDING.md：说明页面入口、数据来源、渲染流程、筛选流程和各文件职责；
• CHANGE_PLAN.md：规划加入 1～5 星评分需要修改哪些数据字段、文件、页面元素和验收步骤。

提示词中明确：不修改现有 HTML、CSS 或 JavaScript，不实现评分。

新判断

区分“源码能证明的事实”和“对未来改造的建议”。例如，data.js 当前提供哪些字段是事实；评分应该使用星形按钮还是下拉框是方案选择，不能写成仓库现状。

验收

• ONBOARDING.md 的关键结论能指向具体文件和函数或变量；
• CHANGE_PLAN.md 说明数据迁移和无评分数据的兼容方式；
• git status --short 只显示两个新文档；
• 原有网页仍可打开和筛选。

练习三：把发布检查保存为 Command

起始材料：03-release-candidate

起始问题

这个示例准备发布 1.2.0。package.json、CHANGELOG.md 和源码中的版本常量需要一致，但每次人工重复检查容易漏项。

创建工作区 Command

先把 exercises 中的 03-release-candidate 复制到自己的练习目录，并在 ZCode 中将该副本作为当前工作区打开；检查 package.json、版本常量文件和变更说明都位于该副本，不能仍停在 02-reading-list。确认后打开“设置 → 命令”，点击“新建命令”，填写：

• **作用域：**工作区；
• 名称：release-check；
• **描述：**检查版本一致性、变更说明和发布清单；
• **参数提示：**留空；
• **提示词：**使用下面内容。

只读检查当前工作区的发布准备状态，不修改文件：

1. 比较 package.json 的 version 与 src/version.js 的 APP_VERSION。
2. 检查 CHANGELOG.md 是否包含该版本且有实际变更说明。
3. 按 RELEASE_CHECKLIST.md 逐项判断能否从当前文件中找到证据。
4. 如果工作区是 Git 仓库，报告未提交文件；不是 Git 仓库则明确说明未检查 Git 状态。
5. 输出“阻塞问题、警告、已通过”三组结果，每条都引用证据文件。

不要把缺少证据的项目判断为通过，也不要自动修复。

保存后，在新的任务输入框输入 /release-check 调用。ZCode 官方说明，自定义 Command 用于保存简单、重复的提示词，可选择用户级或工作区级作用域；本练习使用工作区级，避免污染其他项目。Command

新判断

第一次运行应该发现 src/version.js 与 package.json 不一致。检查命令的职责是报告，不是自动修复。确认报告准确后，再单独要求 Agent 只修正版本常量，然后第二次调用 /release-check。

验收

• 第一次运行准确报告版本不一致；
• 修正后第二次运行不再报告该阻塞；
• 两次报告结构一致，方便比较；
• Command 没有自行修改项目；
• 你能说明为什么这是一段适合 Command 的固定提示词，而不是需要脚本、模板和多份资源的 Skill。

完成练习后的自评

如果三组都能完成，你应该已经能根据任务类型改变工作方式：

• 有明确故障时，先复现再修复；
• 面对陌生仓库时，先建立证据充分的理解；
• 面对重复但简单的流程时，保存为 Command；
• 不把所有问题都处理成“让 Agent 直接改代码”。

下一课将把整套课程中最可能阻塞完成的问题整理成症状式排障表，并给出继续学习不同 ZCode 能力的选择路线。