如何让 AI 理解项目：上下文、规则与任务拆解

这一篇给AI一份它能执行、你能复查的小任务：在ClearCopy的Astro页面添加原稿与功能事实两个输入框，只做页面，不接模型。完成后，你能从文件差异里检查它是否只改了指定位置。需要的上下文也会整理进项目文件，下次不用再从零讲一遍。

先看一次完整任务的成品要求：web/src/pages/check.astro出现两个有标签的文本框、一个“Check description”按钮和“最多500个字符”的提示；它不应该同时安装登录框架、创建数据库或把模型密钥放进前端。

把项目事实放到AI能找到的位置

在练习项目根目录保留上一节的SPEC.md。再创建一份给编程工具使用的说明文件。如果使用的工具支持AGENTS.md，可以放在根目录；如果使用GitHub Copilot，按官方自定义指令说明使用.github/copilot-instructions.md。不同工具支持情况不同，先核对当前工具的说明，不能靠文件名猜它一定会读取。

本书的已填项目说明如下：

# Project context
ClearCopy checks English App Store descriptions against supplied facts.
Frontend: Astro, under web/.
API: Node.js and Fastify, under api/.
Database planned: PostgreSQL. Hosting planned: Railway.
Read SPEC.md before changing behavior.

# Commands
npm run build
npm run dev:api

# Rules
Preserve the packing-app facts: trips, check-off, reuse, offline.
Do not add account, cloud sync, or AI trip planning to the example.
Never put model keys or database URLs into browser code.
Do not install dependencies unless the task requires and explains it.
Report changed files and commands actually run.

这份说明写长期有效的项目事实。今天要改哪个按钮，放在当次任务里；不然几周后每个任务都背着一条早已做完的临时要求。配图里的Copilot References展示了指令文件作为上下文引用的样子。它能帮助你确认文件是否被带入，但“读到了规则”不保证每条改动都遵守规则，结果仍要看。

Copilot答复的References列表中突出显示仓库指令文件 — GitHub官方Copilot截图：References中明确列出copilot-instructions.md，提醒检查AI是否确实取得仓库规则；引用了规则仍不等于修改已通过验收。 GitHub, Inc. and contributors · CC BY 4.0。

第一条消息先让AI复述这次工作

打开自己的练习项目，不要在正式业务目录直接试。给AI下面这段请求，等待它读文件后说出计划：

先阅读SPEC.md、package.json和web/src/pages/index.astro。
本次只做静态页面，不修改API。
请先用三句话说明：
1. 当前项目用什么技术，页面在哪个目录。
2. 本次新增哪个文件，页面上有什么。
3. 你会运行什么命令检查。
先回复计划，不安装依赖，不修改文件。

正常的回答应指出Astro、web/src/pages/check.astro和构建命令。如果它计划新增React应用或直接调用付费模型，你已经在写代码前发现偏离，可以把它拉回现有项目。这一步不是为了收集一篇华丽方案，而是确认它找到了正确文件与范围。

GitHub的提示编写指导讨论提供清楚目标、相关上下文与拆分复杂任务。这里把这些做法落到具体文件，避免只说“请像资深工程师一样完成”。

给它一个足够小、但结果完整的任务

计划符合要求后，发送下面的实施请求。它包含已填例子，AI不用猜输入是什么。

按刚才计划新增web/src/pages/check.astro。

页面必须有：
- English draft：textarea，id为draft
- What your app already does：textarea，id为facts
- Check description：按钮，本轮不发请求
- 提示：最多500个字符，技术计数按Unicode码点

预填draft：
This app can let you make trips and check your things.
You can use a list again. It works offline.

预填facts：
Create trips; check off items; reuse lists; work offline.

每个label的for必须对应输入id。
保留lang="en"；不要新增登录、支付、模型或数据库。
只新增这一份页面文件，运行npm run build。
说明实际构建结果，不把未执行的命令写成已通过。

本轮故意不把“漂亮页面、完整API、登录、支付、部署”放在一条消息里。静态页面建立后，下一个任务再接接口。每次都能看见一个完整的小结果，出错时也容易定位到这一轮。

接受代码前自己看差异

在终端运行：

git status --short
git diff -- web/src/pages/check.astro

如果新文件还没被Git跟踪，普通git diff不会显示它的内容。直接在编辑器打开文件查看即可，或先明确执行git add -N web/src/pages/check.astro，让Git把它当作待比较的新文件，再运行diff；这个命令只标记意图，不会提交。

看文件时先核对三件具体的事：路径是否正确，两个标签是否分别指向draft与facts，输入是否仍是离线清单的四项事实。然后运行npm run build。构建失败就把第一条有用错误与相关文件发给AI，不用贴含密钥的环境文件。

第一章已经在独立目录实跑过Git差异练习；这里沿用同一方法。一个常见例子是页面正文被改成“Sync lists across devices”。把这行新增内容与SPEC.md里的“offline”一起给AI，要求它只恢复这一句，不要重写整个页面。

错了就发一个可复现的反馈

相比“还是不行”，下面这段信息更容易修好问题：

文件：web/src/pages/check.astro
实际：点击English draft标签，没有聚焦到原稿文本框。
预期：点击标签后焦点进入id=draft的textarea。
请检查label的for与textarea的id是否一致。
只修这个关联，不改布局，不安装依赖。
修后说明修改行，并重新构建。

这是一个教学反馈示例；只有你真的看到该现象时才写成实际问题。你也可以贴构建错误的文件名、行号与错误消息，先去掉环境变量、用户原稿和私人路径中无关的信息。

GitHub的代理责任说明提醒使用者审查生成内容。对本书练习，这项责任具体表现为你自己查看文件与运行结果，尤其不让AI的一句“已完成”替代页面是否可用。

现在项目里有三份能复用的材料：产品行为的SPEC.md、长期项目说明、当次的小任务。以后增加接口或处理错误时，只替换当次任务与样例，继续要求同样的文件范围和实际验证结果。AI理解项目的成本会下降，你也能清楚看见每次增加了什么。