📒 学霸笔记：17｜需求与设计：在框架中演练，从模糊想法到清晰的 spec.md

Top Student Notes: 17 | Requirements & Design: From a Fuzzy Idea to a Clear spec.md

课程 / Course: AI 原生开发工作流实战 / AI-Native Development Workflow in Practice
讲师 / Instructor: Tony Bai
章节 / Chapter: 17
主题 / Topic: 需求澄清、角色设定、多轮 Prompt 编排、从模糊意图到 spec.md、规范驱动开发、目录结构生成、接口草图生成

一、这一讲在解决什么问题？

What Problem Does This Lecture Solve?

上一讲我们做的是：

先搭驾驶舱，建立 AI 原生开发的协作框架。

这一讲才真正开始“发动项目”。

但 Tony 没有一上来就让 AI 写代码，而是先把第一站放在了：

需求与设计

这非常关键，因为软件工程里最贵的错误，往往不是代码写错了，而是：

• 需求理解错了
• 功能边界没说清
• MVP 范围不明确
• 未来扩展没预留空间
• 做出来的东西不是用户真正要的

所以这一讲要解决的问题是：

如何在 AI 原生开发模式下，把一个模糊想法通过结构化协作，逐步“编译”为一份清晰、结构化、可执行的需求规范 spec.md。

二、本讲核心结论

Core Conclusion of This Lecture

一句话总结

AI 原生开发中的需求阶段，不是让 AI 直接“替你写文档”，而是通过角色设定、需求澄清、多轮头脑风暴和结构化 Prompt，把模糊意图逐步编译成项目的“真理之源”——spec.md。

三、这一讲最重要的角色切换：你是“需求编译器”

The Most Important Role Shift: You Become a “Requirement Compiler”

Tony 这一讲有一个特别精彩的提法：

需求编译器

这个词非常值得背。

为什么叫“编译器”？

因为原始需求在一开始常常是这样的：

• 我想做个工具……
• 能不能把这个自动化……
• 大概支持一下……
• 以后也许还要做 Web……
• 评论也要处理，但我还没想清楚……

这其实是“人类自然语言里的模糊意图”。

而编译器的作用是把模糊输入转成结构化产物。

所以在这里，你和 AI 一起做的事情就是：

模糊想法
→ 提问澄清
→ 边界收缩
→ 功能取舍
→ 输出结构化规范

这就是“需求编译”。

学霸理解

传统开发里，需求常常停留在：

• 会上讨论
• 聊天记录
• 产品文档
• 脑海印象

AI 原生开发里，需求应该尽早变成：

可以被人和 AI 共用的结构化规格文档。

四、为什么不直接用 spec-kit？

Why Not Use spec-kit Directly?

这是 Tony 在开头专门解释的问题。

你可能会想：

• 既然已经有现成 SDD 工具
• 为什么还要自己写 Prompt 做这件事？

Tony 给了三个层面的理由。

1. 掌握第一性原理

Master the First Principles

重点不是会用某个工具，而是要掌握：

如何与 AI 协作生成高质量规范。

因为工具会变化，但方法论更持久。

这意味着你要学的是：

• 怎么设角色
• 怎么提问
• 怎么引导澄清
• 怎么控制范围
• 怎么让 AI 最终落地为结构化文档

而不是只会按某个工具的按钮。

2. 获得极致灵活性

Gain Maximum Flexibility

现成工具的模板往往是固定的。
但实际项目未必适合完全照搬。

例如这个 Go 项目有自己的哲学：

• 简单性优先
• TDD
• 显式错误处理
• 架构解耦

那么需求文档的组织方式，也应和这些原则一致。

3. 验证“驾驶舱”本身的价值

Validate the Value of the Cockpit

第 16 讲我们已经搭好了自己的 AI 协作框架。

那么现在就是要验证：

不用现成大而全工具，只靠我们设计的协作框架 + Claude 的能力，能不能完成高质量需求编译。

这既是练习，也是验证。

五、这一讲的真实场景是什么？

What Is the Real Scenario in This Lecture?

Tony 选的是一个非常典型、非常适合 AI 原生开发练习的项目：

issue2md

这个项目的原始痛点是：

• 经常需要归档 GitHub Issue / PR / Discussion
• 手动复制粘贴很麻烦
• 希望给一个 URL，就自动转成 Markdown 文件

这是一种很真实的“自用工具”起点。

为什么这个案例特别好？

因为它具备典型的软件产品模糊性：

原始想法看起来清楚，其实远远不够

例如：

• “所有内容”具体指什么？
• PR 的 diff 要不要？
• 评论全保留吗？
• Reactions 要不要？
• 用户链接怎么处理？
• 输出到 stdout 还是文件？
• Token 怎么传？
• 要不要支持 Web？
• CLI 参数如何设计？

这说明：

从一个想法到一个可开发的 spec，中间其实隔着很多轮需求编译。

六、第一步：启动会话之前，框架已经在发挥作用

Step 1: Even Before the Conversation Starts, the Framework Is Already Working

这一讲有一个很容易被忽略、但其实非常重要的点：

当你在项目根目录启动 Claude Code 时，它已经自动加载了：

• CLAUDE.md
• constitution.md

所以你不是从“空白 AI”开始协作，而是从：

已经入职当前项目、已知项目规则和哲学的 AI
开始协作。

这意味着什么？

在传统 Prompt 使用方式里，你每次都要重新说：

• 我们用 Go
• 我们强调简单性
• 我们使用 Makefile
• 我们遵守 Conventional Commits
• 我们强调 TDD

而在这套框架里，这些已经变成运行环境的一部分。

所以从这一讲开始，你真正体验到第 16 讲“驾驶舱”的价值了。

七、为什么 Tony 特别强调要关闭 Plan Mode？

Why Does Tony Specifically Ask You to Turn Off Plan Mode?

这点非常实战。

Plan Mode 很适合什么场景？

• 已经有明确任务
• 想让 AI 一次性规划并执行
• 编码与修改阶段

但这一讲处于什么阶段？

• 需求探索
• 多轮澄清
• 头脑风暴
• 边界讨论
• 反复修正

这时候你要的不是：

“AI 快点给答案”

而是：

“AI 多问我、帮我挖需求、一起把问题想透”

所以在需求阶段，保持标准模式更合适。

学霸理解

• Plan Mode：适合方案收敛和执行
• 普通模式：适合探索式协作和需求澄清

八、Prompt 1 的本质：设定角色，切换 AI 思维模式

The Essence of Prompt 1: Set the Role and Switch the AI’s Thinking Mode

第一条 Prompt 不是问功能细节，而是先给 AI 定位：

• 你是资深 Go 工程师
• 你也是经验丰富的产品经理
• 你要通过提问来帮助我澄清需求
• 最终目标是共创高质量 spec.md

这里的精妙之处非常大。

为什么角色设定这么重要？

因为 AI 的输出风格会强烈受角色影响。

如果你只说：

帮我写个 spec

AI 可能直接给你一个粗略文档。

但如果你说：

你既是 Go 工程师，又是产品经理，要通过提问帮助我澄清需求

AI 的行为就会变成：

• 先问问题
• 不急着实现
• 关注边界条件
• 关注 MVP 与 future scope
• 从产品与技术双视角思考

学霸理解

Prompt 1 的本质不是“输入需求”，而是：

把 AI 从“回答者”切换成“需求访谈者 + 设计共创者”。

九、第二步：需求澄清的价值，不在问多少，而在问得准

Step 2: The Value of Requirement Clarification Lies in Asking the Right Questions

AI 在收到 Prompt 1 后，开始问问题。

这些问题非常经典，几乎覆盖了软件需求分析的核心维度：

• 功能范围
• 资源类型差异
• 转换粒度
• 认证与权限
• 输出格式
• 使用场景
• MVP 边界

这一轮问题为什么关键？

因为很多“模糊需求”最危险的地方在于：

说的时候大家都觉得懂了，做的时候才发现每个人理解不一样。

例如：
“支持 PR”
听起来很简单，但 PR 到底包括：

• 描述？
• 评论？
• review comments？
• diff？
• commit 历史？

如果不问清楚，后面写代码时一定会分歧。

学霸理解

这一轮的目标不是立刻决定所有细节，而是：

把隐含歧义显性化。

这是需求工程里极其关键的一步。

十、Prompt 2 的本质：做减法、定边界、锁定 MVP

The Essence of Prompt 2: Subtract, Set Boundaries, and Lock Down the MVP

Tony 在第二轮回答里做得最漂亮的一件事，是：

大量做减法。

具体怎么做减法？

要的：

• 支持 Issue / PR / Discussion
• PR 只关注描述与 review 对话
• 反应（Reactions）可选
• 用户链接可选
• stdout 默认输出，支持文件输出

不要的：

• 不要 PR diff
• 不要 commits 历史
• 不要图片下载
• 不要自定义模板
• 不做复杂认证
• 不做 Web（当前迭代）

为什么这一步极其重要？

因为需求阶段最大的风险之一就是：

MVP 失控。

AI 很擅长“帮你想更多功能”，但产品设计里，想得更多不一定更好。

如果你不主动收缩范围，AI 很容易把一个简单工具设计成“功能大全”。

学霸理解

Prompt 2 的本质是：

把一个“不错的想法”，压缩成一个“能落地的第一版产品边界”。

十一、这一轮还完成了什么？——隐性技术决策

What Else Happens in This Round? — Implicit Technical Decisions

除了需求澄清，这一轮其实还顺带做了几类技术决策：

• 认证方式：只支持 GITHUB_TOKEN
• 输出方式：stdout 优先
• Markdown 风格：GitHub Flavored Markdown
• 可选特性：Reactions / user links 通过 flag 控制

这说明一件事：

需求阶段和技术设计阶段并不是完全割裂的。

尤其在工具型项目里，很多产品选择天然就是技术约束。

十二、第三步：最后一轮确认，开始从“对话”转为“规格”

Step 3: Final Confirmation — Shift from Conversation to Specification

第三轮 Prompt 是整讲的关键转折点。

因为它完成了两个动作：

1. 回答最后的细节问题
2. 直接下达生成 spec.md 的指令

这一步为什么重要？

如果只回答问题，不给“收束命令”，对话可能继续发散。

而需求编译的目标不是永远讨论，而是：

在合适时机收敛，生成规范。

所以 Prompt 3 本质上是：

• 继续澄清
• 同时收口
• 把讨论结果固化为文档

十三、Prompt 3 最精彩的地方：继续做减法

The Best Part of Prompt 3: Continue Saying No

这一轮里 Tony 又一次做了非常工程化的判断：

不需要按 Review 分组

保留时间线平铺即可

不需要复杂重试机制

保持 CLI 工具轻量

不提供 --token

避免 token 出现在 shell history 中

这些点非常体现“项目宪法”的影响。

为什么这很重要？

因为“需求编译”并不只是把用户说的话记下来，而是要：

在合理范围内拒绝复杂性，保护项目简单性。

这和 constitution.md 中的“简单性原则”完全呼应。

十四、这一讲里的安全意识非常值得背

The Security Awareness in This Lecture Is Worth Memorizing

最值得单独拎出来的一点是：

Token 只通过环境变量获取，不提供 --token 参数。

这是一个非常典型、非常实战的安全设计。

为什么？

因为如果提供：

issue2md --token xxx

那么：

• shell history 里会留下 token
• 可能被截图
• 可能被复制粘贴传播
• 可能暴露在 CI 日志中

而使用环境变量则相对安全得多。

学霸理解

这一讲说明了一点：

好的 spec.md 不只是写清功能，也应该尽早纳入安全最佳实践。

十五、spec.md 不是普通文档，而是“真理之源”

spec.md Is Not Just a Document — It’s the “Source of Truth”

Tony 在结尾明确说：

这份 spec.md，现在就是我们项目的“真理之源”。

这句话很重要。

为什么是“真理之源”？

因为它承载了：

• 用户故事
• 功能性需求
• 非功能性需求
• 验收标准
• 输出格式示例
• Future scope（比如 Web）

从这以后：

• 开发计划要基于它
• 任务拆解要基于它
• 实现取舍要回到它
• 争议讨论也要回到它

学霸理解

如果没有 spec.md，后续 plan / tasks 很容易失去锚点。
所以需求阶段的真正产出，不是“一次聊得很顺”，而是：

一份足够好、可持续引用的规格文档。

十六、为什么 spec.md 里要写未来的 Web 版？

Why Include the Future Web Version in spec.md?

这是思考题的核心，也是一种非常成熟的架构思维。

Tony 明确说：

• 当前重点是 CLI
• Web 不在本次实现范围
• 但仍然要作为用户故事写进 spec

这样做的深远价值是什么？

1. 让架构从一开始就避免过度绑定 CLI

如果只考虑 CLI，很可能把：

• 输入输出
• 参数处理
• 业务流程
• 数据转换

都写死在 CLI 层。

这样以后做 Web 时就得大重构。

2. 提前识别哪些部分必须解耦

因为未来还有 Web，所以你会更自然地想到：

• internal/github/：负责 GitHub 数据获取
• internal/converter/：负责 Markdown 转换
• internal/parser/：负责 URL 解析
• internal/cli/：CLI 只是接口层
• cmd/issue2mdweb/：未来 Web 入口

这样你的核心业务逻辑不会被入口层绑死。

3. 减少“走一步看一步”的重构成本

如果完全只盯当下，很容易出现：

• 现在先写快点
• 以后再抽层
• 真到以后才发现牵一发动全身

而在 spec 阶段提前纳入未来用户故事，会促使你：

做出“最小但正确的架构抽象”。

十七、第四步：为什么还要生成目录结构和 API 草图？

Step 4: Why Generate the Directory Structure and API Sketch Too?

生成 spec.md 后，Tony 又让 AI 继续做两件事：

1. 创建目录结构
2. 生成 api-sketch.md

这不是多余，而是非常工程化的一步。

1. 目录结构的意义

这会把需求与架构开始对齐。

从 spec.md 到目录结构，意味着：

• 需求不再漂浮
• 架构开始承接需求
• 开发空间已经具象化

2. API 草图的意义

它不是正式实现，但它有两个价值：

价值 A：帮助继续思考边界

例如：

• github 包该暴露什么接口？
• converter 如何接收数据与选项？
• parser 是纯函数还是对象？

价值 B：为下一讲 plan / tasks 铺路

因为一旦接口边界初步清楚，任务拆解就会更自然。

学霸理解

api-sketch.md 不是为了“马上编码”，而是为了：

降低从规格到架构再到实现的跳跃成本。

十八、为什么目录结构设计本身也体现了 constitution.md？

Why Does the Directory Structure Itself Reflect constitution.md?

Tony 在 Prompt 4 里专门强调：

基于 constitution.md，特别是关于包内聚的原则来设计包结构。

这说明架构设计不是脱离项目哲学的。

例如当前结构里：

• parser 只做 URL 解析
• github 只做 API 交互
• converter 只做转换
• cli 只做命令行接口
• config 只做配置

这是一种非常典型的：

单一职责 + 内聚性设计

学霸理解

好的 spec.md 不会自动长出好架构，
但如果你的项目已经有：

• 宪法
• 操作手册
• 驾驶舱框架

那么 AI 可以把这些原则带入架构设计中。

十九、这一讲的 AI 协作方法论非常值得抽象出来

The AI Collaboration Method in This Lecture Is Worth Abstracting

这一讲实际上给了你一套非常通用的需求编译流程。

通用流程可以抽象成四步

1. 角色设定

让 AI 进入合适思维模式

2. 多轮澄清

挖出歧义、边界和隐藏决策

3. 范围收敛

不断做减法，锁定 MVP

4. 固化产物

生成 spec.md、目录结构、接口草图

如果再压缩成一句话

先问清，再裁剪，后固化。

二十、这一讲和第 16 讲怎么串起来理解？

How Does This Lecture Connect to Lesson 16?

16 讲搭的是：

• 框架
• 规则
• 目录
• AI 运行环境

17 讲做的是：

• 在这个框架中第一次正式“跑工作流”

所以 17 讲其实是在证明：

驾驶舱不是摆设，而是真的能支撑从想法到规格的工程化协作。

对应关系

constitution.md

约束需求和架构不要过度复杂

CLAUDE.md

提供项目技术与协作规则

specs/

承载规范产物

settings.json

确保 AI 工具调用在安全边界内进行

.claude/

未来还可以把本讲 Prompt 封装为命令或技能

二十一、这讲为什么比“让 AI 帮我写需求文档”高级得多？

Why Is This More Advanced Than “Let AI Write the Requirement Document for Me”?

因为真正发生的不是“代写文档”，而是：

人和 AI 在共同完成需求分析与边界设计。

普通用法

“帮我写个产品需求文档”

常见结果：

• 看起来像样
• 但很多细节没想清
• 落地时问题很多

本讲的方法

• 先设角色
• 再让 AI 连续提问
• 人来做关键取舍
• 最后由 AI 结构化固化

这其实是：

AI 参与需求工程，而不是帮你做文书工作。

二十二、这一讲最值得学习的 Prompt 设计思想

The Most Valuable Prompt Design Ideas in This Lecture

1. 先设定协作模式，再开始问答

不是一上来给任务，而是先说清：

• 你是什么角色
• 我们怎么协作
• 目标是什么

2. 让 AI 通过提问来工作

不是让 AI 直接产出，而是先当访谈者和产品经理。

3. 人类负责边界判断

AI 可以提出选项，但：

• 做或不做
• 先做还是后做
• 简单还是复杂

这些决策仍由人来拍板。

4. 在最后一轮中“收口”

把前面的讨论压缩成结构化执行命令。

5. 从文档继续推进到目录与 API 草图

不让需求停在文档层，而是继续向架构层传导。

二十三、本讲知识结构图

Knowledge Structure of This Lecture

项目框架已搭建完成
        ↓
进入 AI 原生开发第一阶段：需求与设计
        ↓
原始输入是模糊意图
        ↓
角色切换：人成为“需求编译器”
        ↓
方法
├── 角色设定
├── 多轮需求澄清
├── 功能边界收缩
├── MVP 范围锁定
└── 最终固化为 spec.md
        ↓
spec.md 内容
├── 用户故事
├── 功能性需求
├── 非功能性需求
├── 验收标准
└── 输出格式示例
        ↓
进一步生成
├── 项目包结构
└── API 草图
        ↓
结果
从模糊想法
变成结构化规格与初始架构蓝图

二十四、学霸速记表

Quick Revision Table

二十五、学霸自检题

Self-Check Questions

基础题

1. 为什么这一讲把你定义为“需求编译器”？
2. 为什么需求阶段不适合开 Plan Mode？
3. 为什么 spec.md 不是普通需求文档，而是“真理之源”？

进阶题

4. Prompt 1、2、3 分别解决了什么问题？
5. 为什么在需求阶段要不断“做减法”？
6. 为什么在 CLI MVP 中不提供 --token 参数？

思辨题

7. 你当前项目中有哪些“模糊需求”适合用这种多轮需求编译方式来澄清？
8. 如果你要把本讲方法封装成 Slash Command，你会怎么设计？
9. 为什么在 spec.md 中写入未来需求，有助于今天做出更好的架构设计？

二十六、学霸总结

Top-Student Summary

这一讲正式开启了 AI 原生开发实战的第一阶段：需求与设计。
它的核心不是让 AI 代替你写一份需求文档，而是让你和 AI 一起完成一次真正的 需求编译。

所谓“需求编译”，就是把一个最初只有方向感、但细节模糊的产品想法，通过：

• 角色设定
• 多轮提问
• 边界澄清
• MVP 收敛
• 结构化固化

逐步转化为一份可以支撑后续计划、任务拆解和编码实现的规范文档 spec.md。

Tony 这一讲特别强调，不直接使用 spec-kit 等专用工具，并不是否定工具，而是为了掌握需求生成的第一性原理：
真正重要的能力不是“会用某个模板”，而是会和 AI 协作，把模糊意图变成高质量规格。

围绕 issue2md 这个真实项目案例，我们看到了需求阶段最典型的问题：

• 功能边界是否清晰？
• PR 要不要 diff？
• 评论是否全部保留？
• reactions 是否支持？
• 输出方式怎么定？
• token 如何安全传递？
• Web 是否进入当前迭代？

这些问题如果不在规范阶段问清楚，后面一定会以更高成本回到开发中重新解决。

因此，这一讲最重要的方法论是：

1. 先设角色
   让 AI 进入“产品经理 + Go 工程师”的双重视角，而不是急着给出实现方案。

2. 再做多轮澄清
   通过提问把需求里的隐含歧义显性化。

3. 持续做减法
   明确拒绝无必要复杂度，把 MVP 锁定在真正可落地的最小范围内。

4. 最后固化规范
   把讨论结果收束成 spec.md，并继续推进到目录结构和 API 草图。

这份 spec.md 的意义非常关键。
它不是一次讨论的纪要，而是项目接下来所有设计、任务拆解和实现 decisions 的真理之源。

而且，这一讲还展示了一个很成熟的架构意识：
即使未来的 Web 版本不在当前迭代范围内，也应该在规范阶段作为用户故事纳入考虑。这样可以让今天的架构设计从一开始就避免对 CLI 入口过度耦合，为未来扩展保留空间，降低后续大规模重构成本。

最终，这一讲完成的事情是：

把一个“我想做个工具”的念头，转化成了一份结构化规格和初始架构蓝图。

这也标志着 AI 原生开发真正进入工程节奏：
从“想法”开始，经过 AI 协作，被编译为“可以执行的工程输入”。

二十七、一句话记忆

One-Sentence Memory Hook

17 讲的本质，是把人和 AI 的对话变成一次“需求编译”过程，最终把模糊想法固化为项目的真理之源 spec.md。