4. 上下文计划与项目约定

来源：ZCode

第 3 课结束时，focus-board 已经有 index.html、styles.css 和 app.js，能够添加、完成和删除事项。现在要做一次小升级：显示事项统计，并把窄屏布局整理得更稳。

这次不直接把所有要求塞进一条消息。我们先把长期有效的规则写进 AGENTS.md，再用文件引用和计划模式完成修改。

临时要求和项目规则不是一回事

“这次给按钮换个颜色”只影响当前任务，适合写在消息里；“项目只用原生 JavaScript，不安装依赖”会影响以后每次修改，适合写进项目根目录的 AGENTS.md。

ZCode 会在任务开始时读取两个来源：用户级的 ~/.zcode/AGENTS.md，以及当前工作区根目录的 AGENTS.md。本教程只创建工作区文件，不修改全局规则。官方文档也提醒，ZCode 不会继续扫描子目录中的多层 AGENTS.md，所以重要的项目约定应放在工作区根目录。ZCode Agent：项目指令文件

创建工作区 AGENTS.md

在当前任务中发送：

请只在当前工作区根目录创建 AGENTS.md，不修改其他文件。内容需要准确表达以下项目规则：

- 项目是纯本地的“今日专注清单”。
- 只使用原生 HTML、CSS 和 JavaScript；不添加框架、第三方库、CDN、后端、构建工具或包管理器。
- 现有应用文件是 index.html、styles.css 和 app.js。
- 修改前先说明计划，只改实现当前需求必需的文件，避免无关重构。
- 不读取或修改工作区外的文件，不在代码中写入密钥。
- 修改后列出实际变更文件，并验证添加、完成、删除和空输入提示没有退化。
- 如果需求或验收标准不清楚，先说明疑点，不自行扩展功能。

请写成简短、明确的 Markdown 规则。

在确认请求中检查目标必须是 focus-board/AGENTS.md。允许后打开文件，对照上面的规则逐条检查。Agent 可以调整措辞，但不应增加部署、框架或团队流程等本课程没有要求的内容。

此时文件树应为：

focus-board/
├── AGENTS.md
├── index.html
├── styles.css
└── app.js

新建任务，让规则真正成为起点

AGENTS.md 是在旧任务开始后才创建的。为了避免误判它是否已经进入上下文，新建一个项目任务，再完成后续升级。

在新任务中，先不要输入需求。找到输入框附近的执行模式，切换到“计划模式”。计划模式会先检查项目并给出方案，不直接修改文件，适合第一次跨三个文件调整功能。执行模式说明

用 @ 精确提供上下文

在输入框键入 @，依次选择 index.html、styles.css 和 app.js。选中的文件会作为标签出现在输入框中。然后发送：

请基于我引用的三个文件，为“今日专注清单”规划一次小升级：

1. 在页面上显示总事项数和已完成数，初始为 0 和 0。
2. 添加、切换完成状态、删除事项后，统计立即更新。
3. 在 375px 左右的窄屏下，输入框、添加按钮、统计区和事项操作不能互相遮挡。
4. 保留现有添加、完成、删除和空输入提示行为。
5. 不加入持久化、筛选、导出或新依赖。

请说明准备修改哪些文件、每个文件为什么需要修改，以及完成后如何验收。当前只做计划。

检查计划，而不是只看它是否详细

合格计划应该把改动限制在三个现有应用文件中，并包含统计更新和窄屏检查。出现下面任一情况时，先纠正计划：

• 准备引入 React、Vue、npm 或 CSS 框架；
• 把统计做成后端接口；
• 顺手加入持久化、筛选或导出；
• 没有说明如何确认原有功能未退化。

计划越长不代表越好。只要路径、职责和验收闭环清楚，就可以实施。

按确认后的计划实施

把执行模式切回“变更前确认”，发送：

按刚才确认的计划实施。只修改计划中列出的文件。完成后列出实际修改文件，并给出人工验收顺序。

每次出现文件修改请求时，对照已确认计划检查路径。计划中没有出现的文件，不要因为 Agent 说“顺便整理”就直接允许。

独立验收统计和窄屏布局

用内置浏览器打开或刷新 index.html，依次操作：

1. 空列表应显示总数 0、已完成 0。
2. 添加“整理本周计划”和“阅读 20 分钟”，总数应变成 2。
3. 完成其中一项，已完成数应变成 1，总数保持 2。
4. 删除已完成项，总数应变成 1，已完成数变回 0。
5. 将浏览器面板宽度缩小到约 375px，确认输入区和事项操作仍可见、可点击，没有横向溢出遮挡。

最后查看文件树，工作区仍应只有四个文件。统计正确但多出了依赖或配置文件，也不算通过。

常见偏差

新任务没有遵守 AGENTS.md

先确认文件名是大写的 AGENTS.md，位置在工作区根目录，不是 docs/AGENTS.md。再确认当前任务是在文件创建后新建的。必要时用 @AGENTS.md 引用它，让 Agent 复述本次应遵守的三条关键规则；复述与文件不一致时，先停止编辑。

计划模式已经开始改文件

检查执行模式是否真的显示“计划模式”。聊天输入框聚焦时按 Shift + Tab 会循环切换模式，误触可能改变当前档位。发现路径或模式不对时拒绝操作，重新说明“当前只做计划”。

本课结束状态

工作区现在有四个文件；应用仍不保存刷新前的数据，但增加了总数和已完成数，窄屏布局经过人工检查。更重要的是，技术边界和验证要求已经进入 AGENTS.md，后续新任务不必每次从头交代。

下一课会在这些规则内加入 localStorage 和状态筛选，并第一次让 Agent 驱动浏览器完成一套明确的验收流程。