开发前的准备：需求文档与验收清单
这一次写一份可以直接交给AI编程工具的需求文件，名字叫SPEC.md。它只描述ClearCopy匿名短试用：两项输入、一份结果、三种错误处理。文档附上完整原稿与预期结果，开发者不用猜你说的“检查一下文案”究竟是什么意思。
成品先看这一句：
在
/check页面提交不超过500个Unicode码点的英文原稿和功能事实；系统保留输入，显示改写正文与解释；空白或超长时不调用模型，失败不扣成功检查次数。
其中的500是本书为短试用设定的规则，不是App Store的描述上限。正式购买仍按9美元10次成功检查处理，但本次任务不实现收费。
先把三种容易误解的词写清楚
“检查”在这里包括改善英文表达、对照提供的功能事实、解释修改。它不包括代提交审核，也不保证商店审核通过。
“成功”表示用户拿到符合格式的结果，里面包含正文与解释；是否真正写对仍要经过实际样例检查，不能只看HTTP返回200。“失败重试不扣次数”是以后付费额度的规则，本轮匿名接口先不做扣次逻辑。
“500字符”容易出现技术歧义。JavaScript的字符串length统计UTF-16代码单元，部分字符可能占两个单位。MDN的String.length说明给出了这个差别。因此本书统一用Array.from(text).length计算Unicode码点；它仍不等于人眼所见的全部字形数，界面写“最多500个字符”即可；技术需求注明按Unicode码点计数，让前后端保持同一种计算方法。
明确这些词后，AI才不会替你决定“成功就是有响应”“字符就是字节数”。
把这一份已填需求存成文件
在练习项目根目录创建SPEC.md，放入以下内容；这就是本轮任务的基础版，可以直接复制。
# ClearCopy anonymous trial
## Goal
Check a short English App Store description against supplied facts.
## Page
/check
## Inputs
- draft: required, trim before counting, max 500 Unicode code points
- facts: required, max 1000 Unicode code points
## Fixed example
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.
Not provided: Account, cloud sync, AI trip planning.
## Result
Show revised text and explanations in separate sections.
Copy only the revised text.
Do not add features not supplied in facts.
## Errors
Empty draft: 请填写英文原稿
Too long draft: 原稿超过500个字符，请缩短后重试
Service unavailable: 暂时未完成，请保留原稿后重试
Keep input values after errors.
## Out of scope
Accounts, history, payments, team collaboration, file uploads.
No secrets in frontend code or logs.
注意这里将事实输入也设了1000码点上限，避免正文有限、另一项输入却无限增长。第三章后面的实现与测试都沿用这一份文件；如果修改规则，先改文档，再改对应代码与样例，不让两个版本各自漂移。
给成功结果，而不只给“效果要好”
在文件后面加上这份由本书撰写的编辑示范。模型不必逐字相同，但应保留四项功能，不添加未提供的能力。
{
"revisedText": "Create a packing list for each trip, check off items as you pack, and reuse your lists for future journeys. Works offline.",
"explanations": [
"Use check off to describe marking an item as packed.",
"Keep reusable lists and offline use.",
"Do not add account, cloud sync, or AI trip planning."
]
}
现在就能提出具体问题：正文能单独复制吗？解释是否对应输入？有没有把offline改成需要联网？这些比“更专业”“更流畅”容易判断。若结果暗示跨设备同步，即使英语通顺也要修改，不应算作可直接采用。
用四组输入写出可复查的表现
把下面这张表继续贴进SPEC.md。它既帮助开发者实现，也方便你按同一材料复查。
| 输入 | 期待看到什么 | 不应发生什么 |
|---|---|---|
| 本篇固定原稿与事实 | 正文和解释分区；可复制正文 | 添加同步、账号、AI规划 |
| 原稿只有空格 | 原稿旁提示必填 | 发起模型请求或清空事实 |
| 原稿为501个a | 提示超过500个字符，保留内容 | 静默截断后继续处理 |
| 接口故障 | 显示失败提示，可再次提交 | 把错误页文字当成英文结果 |
最后一组需要在开发环境模拟故障，不能通过破坏正式服务测试。后续调试篇会给具体方法。等待期间重复点击同样要处理：按钮进入等待状态，避免同一浏览器同时发送多份检查。
Fastify验证文档展示了使用JSON Schema验证请求的方式；不过本书选定的Unicode码点计算要在实现中保持一致，不能随手换成另一个计数规则。文档只说明可采用的技术方法，不代表这份需求已经实现。
把文档变成一个有范围的开发任务
打开自己的GitHub仓库，在Issues中创建“Build anonymous check page”。无需现在连接App Store或部署服务。描述里贴上SPEC.md的目标、页面、示例和错误表，再写“先提交实现方案，不安装额外服务”。
GitHub Issue Forms文档可以把现象、预期等字段做成结构化表单；配图展示的就是这类表单。对于第一次练习，普通Issue已经够用。观察配图中“What happened”和预期字段的区分，把同样的习惯用在错误反馈里：先写实际出现什么，再写原本应该发生什么。
这份需求文件完成后，读者不需要猜你说的“好用”是哪一种表现。把它连同当前页面交给AI，每次只实现一个小任务；验收时直接用这四组材料重走，不靠AI自己的一句“全部完成”结束工作。
