Skip to content

本页由 AI 根据韩语原文翻译,可能存在错误。

第3章 规划与规格说明——接受访谈,写出 SPEC.md ​

必读 想跟着这个阶段学下去,一定要读这一章。

一句话总结:要做什么还模模糊糊的时候,不要自己一个人全部理清楚,而是让 Claude 来采访你。访谈结束后,Claude 会把那些内容写成 SPEC.md(规格说明书)。 规格说明讲的不是"怎么做",而是**"应该变成什么样"的约定**。这个约定,就是第4~6章里制作、确认、评审的依据。

这一章依据 2026年11月1日确认的 Claude Code、GitHub 官方文档,以及 spec-kit、OpenSpec 仓库里的说明写成。具体说明要交代什么的要领,在 Claude Code 第5章学过了。这一章把那些要领扩展到"制作之前的阶段"。

为什么要先做规划 ​

就像第1章看到的,AI 常常做出和我脑子里想的不一样的东西,常见的原因是缺了只读仓库是看不出来的信息。[1] 那些信息只在我脑子里。比如谁来用、哪里不方便、什么事不做。

GitHub 的入门教程也说,写代码之前,先把要做的东西记下来,并追踪进度。[2]

说得越具体,来回修改的次数就越少。官方文档要求一开始就点明文件、说出症状,并说明"做完了"是什么样子。[3]

不够好的例子更好的例子
做一个显示待办事项的页面一个把会议纪要里的待办事项表汇总起来,按负责人、期限分别显示的页面。做完时,备忘里的 5 个待办事项必须全部看得到

来源:本指南的例子(要领来自官方文档)[3:1]

理解检查

官方文档指出,AI 做出来的东西和我脑子里想的不一样,常见原因是什么?

接受访谈,写出 SPEC.md ​

想要的东西还不清楚也没关系。官方文档说,不需要在写提示词之前全部想清楚,可以让 Claude 来采访你。[4] 把文档里的示例译成中文,大致是这样。

我想做这样一个东西,但还没有深入想过。请先采访我,直到能写出规格说明为止,做完后写进 SPEC.md。

这样,Claude 会针对还没有定下来的部分,用选择题(从选项里挑一个的问题)反过来问你。[5] 比如"待办事项按负责人归类,还是按期限归类?"这种只要挑一个就行的问题。实际的问题每次都不一样,从选项里挑一个,或者用自己的话回答都可以。

如果是待办事项看板,请求就会是这样。

我想做一个网页,把第3阶段整理工具生成的会议纪要里的待办事项表汇总起来显示。我还没有深入想过。请先采访我,直到能写出规格说明为止,做完后写进 SPEC.md。

SPEC.md 生成之后,在新会话里让它看着这个文件来制作。这是为了从干净的上下文,以及用文字写下来的"完成的定义"开始。[6] 这样可以让访谈中来回的那一长串对话,不要掺进制作过程里。

做完之后,要对照 SPEC.md 来确认。 这件事,在第6章评审里还会再讲。

理解检查

要做什么还很模糊的时候,官方文档建议怎么做?

好的规格说明是什么样 ​

规格说明里写的是从外面看得到的行为。意思是只写看界面的人能察觉到的东西。如果是待办事项看板的 SPEC.md,就会有这样的句子。

好的句子不够好的句子
会议纪要里的待办事项,一个不漏地都显示出来用 JavaScript 读取表格
过了期限的待办事项,标记不一样看起来漂亮
不显示个人姓名,只显示角色用整洁的代码来做

来源:本指南的例子

左边的句子,可以用"是/否"来确认。 到了第5章,这些句子就直接成了确认的手段。

右边的句子,是怎么做(技术)或者模糊的感觉。下一节要看的规格说明工具,它们的说明书也是这么说的。OpenSpec 的说明书说,规格说明"不是实现计划,而是行为的约定",而且不改变外部可见行为的实现细节,通常不放进规格说明。[7] spec-kit 也说,在规格说明阶段,应该专注于做什么、为什么,而不是技术,技术选择要推迟到下一个计划阶段。[8]

理解检查

在待办看板的 SPEC.md 里,适合写进去的是哪一行?

规格驱动开发工具 ​

以规格说明为中心的开发方式,叫作规格驱动开发(Spec-Driven Development)。先定下要做什么、为什么做,再把那份规格说明变成计划、任务、代码。[9] 帮助做这件事的工具有 spec-kit 和 OpenSpec。

本指南不安装这两个工具。 只靠上面学过的"访谈 → SPEC.md → 新会话"流程,也能实践同样的想法。这一节只记住名字就往下走也可以。

两个工具都在中间留了人来确认的位置。

  • spec-kit(GitHub 做的工具):一个阶段一个阶段地执行规格说明 → 计划 → 任务清单 → 实现,审查结果之后再往下走。[10]
  • OpenSpec(Fission-AI 做的工具):让 AI 写文档,而人在代码写出来之前审查计划。[11]

这和本指南流程里阅读并批准 SPEC.md 是同一个思路。

进一步了解这两个工具(点击展开)
工具出品方做什么
spec-kitGitHub分阶段完成规格说明 → 计划 → 任务清单 → 实现
OpenSpecFission-AI每次变更都建立提案、规格、设计、任务文件夹

来源:各工具的说明(只摘录了一部分)[12][11:1]

安装时需要另外的开发工具。spec-kit 需要 Python 3.11 及以上,以及叫 uv 的工具[13],OpenSpec 需要在终端安装(或者 Node.js 22.12 及以上)。[14] Python、uv、Node.js 是用来运行程序的开发工具。跟着本指南做,一样都用不到。以后做更大的项目时,再去了解它们。

理解检查

这份指南是怎样处理 spec-kit 和 OpenSpec 的?

动手试试 ​

  1. 在 Claude Code 应用里,打开第2章建的 todo-board 文件夹。
  2. 发送上面的访谈请求,回答 Claude 的问题。不知道的话,说"给我推荐"也可以。
  3. 读一读生成的 SPEC.md,每一句都问问"能用是/否来确认吗?"。不能的话,请它修改。
  4. 确认 SPEC.md 里没有放入真实姓名、联系方式(因为是公开仓库)。
  5. 满意的话,就留下记录(提交)。

连续任务:第4章里,我们会在新会话里依据 SPEC.md 拿到计划,并在分支上做出第一个画面。

总结 ​

  • AI 常常做出离谱的东西,常见原因是缺了我脑子里的信息。制作之前先写下来。
  • 不清楚的话,让 Claude 采访我,把结果写成 SPEC.md。
  • SPEC.md 生成之后,在新会话里制作。做完之后,对照 SPEC.md 检查。
  • 规格说明里写的是从外面看得到的行为,而且要写成能用是/否来确认。
  • spec-kit、OpenSpec 是帮助实践同样想法的工具。本指南不安装。

术语整理 ​

术语中文名称一句话解释
Spec规格说明写下应该变成什么样的约定
SPEC.mdSPEC.md 文件写着规格说明的文件
Spec-Driven Development规格驱动开发先定规格说明,再据此制作的方式
Definition of done完成的定义"做完了"的标准

这一章读完了吗?

学习记录只保存在这个浏览器中。整体进度可以在 全部目录中查看。

下一章:第4章. 制作

参考资料(14 条)
  1. Claude Code 官方文档,「Best practices for Claude Code」。 "Claude built something different from what you had in mind, or it has to rediscover the same fact at the start of every session. It's missing information it can't get from reading the repo." code.claude.com (确认日期 2026-11-01) ↩︎

  2. GitHub 官方文档,「Planning your work」。 "Before you write code, capture what you want to build and track your progress." docs.github.com (确认日期 2026-11-01) ↩︎

  3. Claude Code 官方文档,「Best practices for Claude Code」。 "If you name the file, describe the symptom, and say what "fixed" looks like up front, you usually save yourself a round of corrections later." code.claude.com (确认日期 2026-11-01) ↩︎

  4. Claude Code 官方文档,「Best practices for Claude Code」。 "When you don't know exactly what you want yet, you don't have to work it all out before you prompt. Ask Claude to interview you instead:" code.claude.com (确认日期 2026-11-01) ↩︎

  5. Claude Code 官方文档,「Best practices for Claude Code」。 "Claude comes back with multiple-choice questions about the parts you haven't pinned down: per-user versus per-key limits, what happens to requests over the limit, what's out of scope." code.claude.com (确认日期 2026-11-01) ↩︎

  6. Claude Code 官方文档,「Best practices for Claude Code」。 "Once SPEC.md exists, start a fresh session to build from it, so the build begins with a clean context and a written definition of done." code.claude.com (确认日期 2026-11-01) ↩︎

  7. OpenSpec 文档,「Concepts」。 "A spec is a behavior contract, not an implementation plan." / "If implementation can change without changing externally visible behavior, it likely does not belong in the spec." github.com (确认日期 2026-11-01) ↩︎

  8. spec-kit 文档,「Spec-Driven Development Quickstart」。 "Creates the feature specification from a natural-language description. Focus on the what and why, not the tech stack." github.com (确认日期 2026-11-01) ↩︎

  9. spec-kit README. "Define what to build and why, then turn the specification into a plan, tasks, and working code." github.com (确认日期 2026-11-01) ↩︎

  10. spec-kit README. "Create a constitution once per project and repeat the remaining steps for each feature. Run these skills in your agent's chat, not your terminal, one at a time, reviewing each result before continuing." github.com (确认日期 2026-11-01) ↩︎

  11. OpenSpec README. "Stay organized — each change gets its own folder with proposal, specs, design, and tasks" / "Your AI writes these; you review the plan before any code is written." github.com (确认日期 2026-11-01) ↩︎

  12. spec-kit README. "Spec Kit is an open source toolkit that gives AI coding agents structured processes, reusable templates, and documented outcomes." github.com (确认日期 2026-11-01) ↩︎

  13. spec-kit README. "You need Python 3.11+, uv, and a supported AI coding agent on Linux, macOS, or Windows." github.com (确认日期 2026-11-01) ↩︎

  14. OpenSpec README. "Install OpenSpec. On macOS or Linux, in your terminal:" / "(needs Node.js 22.12.0 or higher)" github.com (确认日期 2026-11-01) ↩︎