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

> 贯穿项目第一步。用 Claude Code 的访谈式提问，把「做一个个人书单网站」这句话变成一页纸规格：用户、场景、页面、数据、验收标准和不做什么。

- 网址：https://coding.chengyu.dev/learn/ship/idea-to-spec/
- 学习路径：实战：从想法到上线一个网站
- 预计用时：25 分钟；核实日期：2026-10-25
- 官方来源：[Best practices for Claude Code（Anthropic 官方文档）](https://code.claude.com/docs/en/best-practices)，[Manage Claude's memory（Claude Code 官方文档）](https://code.claude.com/docs/en/memory)，[Install and set up Astro（Astro 官方文档）](https://docs.astro.build/en/install-and-setup/)，[Deploy your Astro site to Cloudflare Workers（Astro 官方文档）](https://docs.astro.build/en/guides/deploy/cloudflare/)

## 学习目标

- 能让智能体先追问再动手，而不是直接开写
- 能写出包含验收标准和「不做什么」的一页纸规格
- 能把模糊需求改写成智能体可以自己验证的验收条目
- 理解规格文件如何成为后续每个会话共享的锚点

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

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

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

## 为什么要先写规格

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

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

> **规格 = 写给下一个会话的信**
>
> 想象明天打开一个全新的 Claude Code 会话，它什么都不记得。规格要写到：它读完这一页，就知道做什么、不做什么、怎样算做完。

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

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

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

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

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

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

## 一页纸规格的六个部分

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

| 部分 | 回答的问题 | 缺了会怎样 |
|---|---|---|
| 用户 | 谁用？一个人还是很多人？ | 智能体默认做成多用户系统，加登录、注册、找回密码 |
| 核心场景 | 用户最常做的 3 件事是什么？ | 功能平均用力，核心体验却粗糙 |
| 页面清单 | 有哪几个页面？各自展示什么？ | 页面数量和路由随会话漂移 |
| 数据模型 | 存哪些字段？哪些可为空？ | 每次改动都顺手改表结构 |
| 验收标准 | 怎样算做完？ | 「看起来差不多」就停 |
| 不做什么 | 明确排除哪些功能？ | 范围蔓延 |

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

```markdown
# 个人书单 · 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 导入、多语言。
```

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

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

| 写法 | 问题 | 改写后 |
|---|---|---|
| 页面要好看 | 谁来判断？ | 375px 和 1280px 截图无横向滚动，正文与背景对比度不低于 4.5:1 |
| 接口要安全 | 什么叫安全？ | 缺少 `Authorization` 头调用 `POST /api/books` 返回 401 |
| AI 要稳定 | 稳定到什么程度？ | AI 返回非 JSON 或抛错时，书仍然保存，`summary` 为空 |
| 数据别丢 | 在什么情况下？ | 重复提交同一本书不会产生两条（或明确允许重复） |

好的验收标准有一个共同点：**它描述的是可观察的行为，而不是实现方式**。第 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 采访你并写出 SPEC.md**

```text
我想做一个「个人书单」网站：我自己记录读过的书、写短评，可以把部分书公开分享给别人看，并且每本书保存后由 AI 自动生成一句话摘要和几个标签。前端用 Astro + Tailwind，后端用 Cloudflare Workers + D1，AI 用 Workers AI。

请先不要写任何代码。用提问工具采访我，要求：
1. 每轮只问 2–3 个问题，每个问题给出你的推荐选项，我可以直接说「按推荐来」；
2. 不要问显而易见的问题，重点挖我可能没想到的取舍：数据模型、公开与隐私、AI 失败时的行为、管理员身份怎么验证、后续不想维护的东西；
3. 聊完后写入项目根目录的 SPEC.md，包含这六个部分：用户、核心场景、页面清单、数据模型、验收标准、不做什么；
4. 验收标准每条都必须是可观察、可验证的行为（能写成一条命令、一个测试或一次截图检查），不要写「体验好」「界面美观」这类说法；
5. 全文控制在一页以内，不要自作主张加入我没同意的功能，拿不准的放进文末「待定问题」。

写完后列出你觉得最不确定的 3 个点，让我确认。
```

> 小测：你让智能体「做一个个人书单网站」，它很快生成了带用户注册和评论区的页面。最根本的原因是？

> 小测：下面哪一条最适合作为验收标准？

## 动手任务

- [ ] 新建空目录 `my-shelf`，用计划模式启动 `claude`，发送上面的提示词完成访谈
- [ ] 检查生成的 `SPEC.md`：删掉你不想要的功能，补全「不做什么」
- [ ] 确认每条验收标准都能变成命令、测试或截图检查，不能的就改写
- [ ] 检查 Node.js、Git、`gh`、Cloudflare 账号是否就绪（域名可以先没有）
- [ ] 把 `SPEC.md` 留着，第 2 课会连同它一起提交到 GitHub

下一课：[选技术栈并搭骨架](/learn/ship/scaffold/)。规格有了，我们让 Claude Code 把项目立起来。