从想法到规格：让 AI 先追问你

很多人第一次让智能体做网站，开场白是「帮我做一个个人书单网站」。十分钟后得到一个能跑的页面：紫色渐变标题、三张示例卡片、一个永远不会保存任何东西的表单。看起来像样，但它和你想要的东西几乎没有关系。

问题不在智能体。你给它的只有一句话，它只能用最常见的猜测去补全剩下的 95%。智能体擅长执行，不擅长替你做产品决定，而产品决定恰恰藏在那 95% 里：谁用？能不能公开？评分是五星还是十分？没读完的书算不算？

这一课开始，我们用 6 课做完一个真实项目：「个人书单」网站。你可以记录读过的书、写短评，生成一个公开分享页，由 AI 自动给每本书生成摘要和标签，最后部署到自己的域名。第一步不写任何代码，只做一件事：把想法变成一页纸规格。

为什么要先写规格

规格不是写给老板看的文档，它有三个很实际的用处：

1. 减少返工。「不做什么」写在纸上，智能体就不会顺手给你加登录系统、评论区和推荐算法。
2. 让会话可以重来。Claude Code 每个会话都从空白上下文开始。规格存成仓库里的文件，换一个会话、换一个子智能体，都能读到同一份共识。
3. 让验收有标准。官方最佳实践里反复强调的一点是：给智能体一个它能自己运行的检查，它才能自己判断做没做完。验收标准就是这个检查的原材料。

让 AI 采访你，而不是你给 AI 写作文

大多数人不擅长凭空写规格，因为你不知道自己没想到什么。更省力的办法是反过来：让智能体当采访者。Claude Code 官方的最佳实践里就推荐这种做法：给一句简短的需求，让它用提问工具持续追问，聊透之后再落成文件。

两个细节会明显提升效果：

• 先进入计划模式（plan mode）。按 Shift+Tab 切换，直到状态栏显示计划模式，或用 claude --permission-mode plan 启动。这个模式下智能体只读不改，不会还没聊清楚就开始建文件。
• 要求它「别问显而易见的问题」。否则它会浪费你五轮来问「要不要响应式」。你要的是它挖出你没想过的取舍。

访谈结束、规格落盘之后，开一个新会话去实现。新会话上下文干净，只带着那份规格，不会被前面一长串讨论分散注意力。

$ mkdir my-shelf && cd my-shelf
$ claude --permission-mode plan
> 我想做一个个人书单网站。请用提问工具采访我，直到能写出完整规格……
⏺ 先确认几个会影响设计的问题：
  1. 这是只给你一个人写，还是允许别人也注册记录？
  2. 「公开分享」是整个书架公开，还是每本书单独设置公开？
  3. 没读完的书和想读的书，要不要和读完的放在一起？
> （逐条回答，遇到没想过的就说「你先给个建议」）
⏺ 已写入 SPEC.md，共 6 个部分。请检查「不做什么」是否符合你的想法。

一页纸规格的六个部分

下面是这个项目最终的规格结构。每个部分都回答一个会被智能体「脑补」的问题：

「个人书单」的规格，压缩后大致是这样（真实文件可以更详细，但别超过一页）：

# 个人书单 · SPEC

## 用户
只有一个所有者（我）。访客只读，不需要注册登录。

## 核心场景
1. 我添加一本书：书名、作者、状态（想读/在读/读完）、评分 1–5、短评。
2. 保存后，系统自动生成一句话摘要和 3–5 个标签。
3. 我把某几本书设为公开，访客在首页看到公开书架，点进去看详情。

## 页面
- `/`：公开书架（只显示公开的书），支持按标签筛选
- `/book/[id]`：书籍详情（封面占位、短评、摘要、标签）
- `/admin`：管理页（填入管理令牌后可新增、编辑、删除、切换公开）

## 数据模型：books
id、title（必填）、author、status、rating（可空，1–5）、review、
summary（AI 生成，可空）、tags（JSON 数组）、is_public（0/1）、created_at

## 验收标准
- 未带管理令牌调用任何写接口，返回 401，数据库不变
- 设为私有的书，不会出现在 `/`、`/book/[id]` 和公开接口里
- AI 调用失败时，书仍然保存成功，摘要为空
- 375px 宽和 1280px 宽下页面都无横向滚动
- 浅色和深色模式下正文对比度都清晰可读

## 不做什么
用户注册登录、评论、点赞、书籍封面上传、豆瓣/Goodreads 导入、多语言。

验收标准：让智能体能自己验证

规格里最容易写虚的是验收标准。判断标准很简单：这一条能不能变成一条命令、一个测试或一次截图。

好的验收标准有一个共同点：它描述的是可观察的行为，而不是实现方式。第 5 课我们会把这些条目逐条变成自动化测试，现在写得越具体，那时越省事。

规格也要「评审」，也会变

拿到智能体写的 SPEC.md 后别急着全盘接受，花五分钟做三件事：

1. 先看「不做什么」。智能体倾向于什么都想做，砍掉它加的功能比补上遗漏的功能更重要。
2. 找矛盾。比如页面清单里有「收藏夹」，数据模型里却没有对应字段。
3. 挑 2 条验收标准，想一想你会怎么亲手验证。如果想不出，说明它还不够具体。

规格也不是圣旨。做到第 4 课你可能发现「标签筛选」应该砍掉，这很正常。原则只有一条：需求变了，先改 SPEC.md，再改代码。否则规格和代码很快就会各说各话。

实际动手：先把环境备好

后面几课要用到这些东西，现在先检查一遍，免得到时卡住：

• Node.js：Astro 不支持奇数大版本的 Node，具体最低版本以 Astro 安装页写的为准（撰写时为 22.23.4 及以上）。
• Git 与 GitHub 账号，以及命令行工具 gh（第 2 课推送代码用）。
• Cloudflare 账号（免费计划够用）。账号需要你自己注册和登录，智能体不应该替你做这件事。
• 一个域名（可选）。没有的话，整个项目也能用 Cloudflare 提供的 workers.dev 地址跑通，最后一课再决定要不要绑定。

动手任务

下一课：选技术栈并搭骨架。规格有了，我们让 Claude Code 把项目立起来。