Chapter 1 – Interact with AI

完成以下任务:

# 1 准备你的 AI 工具箱

编号 大模型/工具 说明 是否必须
1 Qwen(通义千问)
  1. 不限流量
  2. 百炼平台 token 价格低
  3. 聪明程度 ok
2 Sublime Text 编辑器 免费的 Markdown 编辑器,编写 Prompt 首选
3 Markdown 语法小抄在线版
Markdown 语法小抄下载
Markdown 语法小抄,下载的文件可以用上面的 Sublime 打开
4 HedgeDoc 多人协作 MD 文档在线协作

#2  学习以下内容

驾驭 AI 必备 – 有效提示词之 STAR 范式

元素 核心问题 推荐长度 常见错误 最佳实践
S – Situation 谁?什么背景?目前在做什么?为什么需要 AI? 100 字内 写成个人简历 • 无指令:不要写任务指令,只描述背景
• 只写跟任务有关的事实
• 使用 {}:用 {粘贴完整的背景和概念} 作为占位符,让用户动态填写,提高模板可复用性
T – Task 希望 AI 做什么?产出什么? 120 字内 模糊的指令,例如“帮我写个脚本” • 提供清晰、明确、无歧义的任务指令,让大模型清楚理解要做的事
• 分解:一句话一个指令
• 动词导向:使用动词引导的指令
• 关键要求:添加关键要求描述(例如 SMART 原则)
A – Action Role 希望 AI 扮演谁?具备什么技能? 200 字内 只写“你是某个领域的专家” • 专业角色:指定具备任务相关技能的角色
• 领域知识:强调应当具备的专业知识
R – Rule 等待什么输入?产出什么输出?格式限制? 120 字内 忽略格式限制,导致输出内容冗长杂乱 • 指定清晰、一致的任务规则
• 实例化:给出实例帮助 AI 理解
• 边界清晰,例如将“请尽可能清楚描述”改为“必须提供至少三个场景”
• 质量要求:如有质量标准,明确说明
• 模板:指定句式/结构模板
• 输出格式,例如纯文本、文本块等

# 3 在千问中尝试以下提示词

# S - Situation
## Chinese is my first language.
## English is my second language
## I need an assistant that can translate one language into the other.

# T - Task
## Wait for my input.
## Identify which language my input is written in.
## Translate it into the the other language.
## Output only the translations, not the original text.

# A - Action Roles
## You are a native-level expert in Simplified Chinese and English.
## You are a professional translator skilled at producing natural, accurate, and context-appropriate translations.

# R - Rules
## Do not answer anything until I provide text to translate.
## For every input, first detect the original language.
## Translate the input into the other language.
## Use prefixes:
### [CN:] for Simplified Chinese
### [EN:] for English

## Output only the translations.
## Do not add explanations, notes, or extra text.
## Output as plain text.
## Example: I enter the input "你叫什么名字?", the output should be:
[EN:] What is your name?

# 4 挑战:写一个编辑提示词的提示词,或者把 PRD 转为 用户故事 + AC 的提示词

Chapter 2 – 设置 SDD 开发工具

为什么我们叫“木刀道场”:
我们推荐的工具都是“木刀” - 不是最好的,但是免费,无门槛,不翻墙,皮实够用,虽然不够锋利,但是用来练功夫势大力沉,还不用担心误伤群众。
今朝木刀炉火纯青,至于屠龙刀和倚天剑,则留给大家明日笑傲江湖。

完成以下任务:

1. 安装 SDD 开发工具

推荐:

地区 IDE 备注 URL
China mainland TRAE CN 推荐

免费,够用,除了好的LLM (例如GLM5.1) 要排队,其他没限制。

https://trae.cn/
China mainland CodeBuddy CN 推荐

免费,够用,新工具,支持GLM5.1,限制少,似乎不用排队。【遇到 TRAE CN 排队太长的时候,CodeBuddy 是一个不错的备选。】

https://www.codebuddy.cn/ide/
China mainland Cursor LLM只能用Auto模式,免费版有 token 限制,很快就会用完 https://www.cursor.com/downloads

 

2. 从 git repository 获取最新代码

第一步,新建一个文件夹”playwhere”, 然后打开 TRAE CN,选择 Open Folder

第二步,获取最新代码

做法 1:向 AI 输入指令:
从以下 git repository 获取最新代码:
https://gitee.com/woodsw0rd/playwhere.git
做法 2:直接在终端输入:
git clone https://gitee.com/woodsw0rd/playwhere.git

3. 让 AI 理解项目上下文,并安装依赖项

向 AI 输入指令:
# 理解项目上下文
# 安装依赖项, 过程如遇到权限问题泽使用 sudo 命令 
## 生成 sudo 命令 
## 暂停进程, 等待我手动在 terminal 执行 
## 我完成执行后继续进程 
# 过程中如遇到其他问题, 则寻求我的帮助 
## 暂停进程, 说明问题, 给出选项 
## 等我提供方向后再继续

4. 运行 “去哪玩” app

做法 1:向 AI 输入指令:
run the app
做法 2:直接在终端输入:
npm run dev

Chapter 3 – Why NOT vibe coding?

完成以下任务:

1. 讨论:各组对 Vibe Coding 的心得?

2. 实践:针对现有的“去哪玩”功能,根据你们组的喜好自由增改功能

可选项:

* 点击某一个行程的标签卡,显示该行程的详情
* 收藏某一个行程,并提供配套的收藏管理功能
* 制定行程 itinerary —— 包含交通、餐饮、住宿三要素,并提供比价和推荐

3. Reflect:你的感受是什么?

4. Spec-Driven Development 和 Vibe Coding 的区别

Plan → Spec → Develop → Verify → Learn & Iterate

Chapter 4 SDD 第一步:根据 Init.md 初始化项目

通过完成以下任务,来初始化 “吃点啥” 项目:

 第一步:在 supabase.com 创建一个 PostgreSQL 免费数据库

# 步骤 说明 链接
1 注册一个免费 supabase 账号 免费账号可创建两个数据库实例 https://supabase.com/dashboard/sign-up
2 完善账户信息 需要建一个初始组织 https://supabase.com/dashboard/new
3 创建一个新 project
4 将数据库 url 记录下来

第二步:全新创建一个文件夹 “eatwhat”,并从该文件夹打开 IDE

第三步:在根目录新建一个 init.md 文件,并在其中添加以下内容:

# web app:吃点啥
## 主要功能
### 根据用户喜好,利用AI,生成每日家常菜谱
### 用户可以踩不喜的菜谱,或者赞喜欢的菜谱
### AI应该学习用户的喜好,为用户生成用户画像,从而更精准地提供用户喜欢的菜谱
### 后续根据用户反馈,增加新的功能,需要考虑扩展性

## 技术栈
### 前端
- Next.js 15或以上 (React 框架, 支持SSR/SSG)
- TypeScript (类型安全)
- Tailwind CSS (样式)
### 后端
- Next.js API Routes (服务端接口)
- Prisma (ORM, 数据库操作)
### 数据库
- 架设在 Supabase 上的PostgreSQL (存储用户数据、菜谱、偏好记录)
### AI 模型
- Qwen API (使用提供的秘钥调用大模型)

第三步:安装依赖项 – 向 AI 输入指令:

# 按照 ../init.md 安装依赖项,
# 过程如遇到权限问题泽使用 sudu 命令
## 生成 sudu 命令
## 暂停进程, 等待我手动在 terminal 执行
## 我完成执行后继续进程
# 过程中如遇到其他问题, 则寻求我的帮助
## 暂停进程, 说明问题, 给出选项
## 等我提供方向后再继续

第四步:在环境变量中设置千问 API Key 和数据库连接

1. 找到你们组的 API Key

# 组名 预分配的千问 API Key
1 第一组 sk-c6b4118e7fa94355bd41b837705db5c4
2 第二组 sk-fc05bf05da8f4aadbc56e65007775467
3 第三组 sk-496526ca729a4b0298a67a85974d0a53
4 第四组 sk-1d11cb64d99d42289590ca8a36874ac1
5 第五组 sk-392f4586ac0448ccb5de87b08cdf1907
6 第六组 sk-674381660f7d4cc3a46b1f3b63fac63a

2. 通义千问Base URL

https://dashscope.aliyuncs.com/compatible-mode/v1

3. 在TRAE CN中编辑 .env 文件

DATABASE_URL="your-db-url"
DASHSCOPE_API_KEY=your-api-key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
DASHSCOPE_MODEL=qwen-plus
PORT=3000

第五步:其他初始化工作

讨论:接下来你会想要做哪些其他的初始化工作?
A. 让 AI 写一个技术架构文档
B. 让 AI 建议一个项目目录结构
C. 让 AI 做一个 Hello World 页面来测试初始化结果
D. 其他[请描述]

Chapt 5 – SDD 四核心之一 – 规则

完成以下任务:

1,讨论:

* 如何避免之前“去哪玩”一蹴而就出现的问题?
* 如果希望 AI 按照你的规则执行,应该怎么做?

2,介绍:利用规则规范 AI

3,挑战:让 AI 帮你写一个增量交付的规则文件

4,讨论:如何设计工程文件夹目录结构?

Chapt 6 – SDD 四核心之二 – 技能

完成以下任务:

1,头脑风暴:既然是“规格驱动开发”,那么哪些规格是必要的?

2,我是新手,我怎么写出这些高质量的规格文件?

3,概念:技能

* 如何加载技能
* 技能市场:https://skillsmp.com

4,分组练习:用不同的技能,让每个组编写一个规格文件

* 需求规格(ATDD)(每日菜谱功能)
* 架构设计(全栈工程师)(全局)
* UI 设计规格(UI 设计师)(每日菜谱功能)
* 测试策略(测试工程师)(全局)

5,汇总后,实现每日菜谱功能

6,讨论:这个过程与传统 Vibe Coding 最大的区别是什么?

Chapter 7 – SDD 四核心之三 – 工作流

完成以下任务:

1,有了“规则”和“技能”,如何让 AI 按照软件工程流程进行开发?

2,介绍:“工作流 / Workflow”

3,Review 以下 “New Feature Development” 工作流:

# Workflow - New Requirement

新功能开发的完整工作流程

---

## 第一步:编写规格文档

首先判断功能类型:
- **全新功能**:在项目根目录创建 `specs/feature-name/` 文件夹
- **已有功能的子功能**:直接在已有的 `specs/feature-name/` 文件夹中更新

### 1.1 需求规格
- 使用 `atdd` 技能
- 将需求转化为用户故事和 Gherkin 格式的验收标准
- **全新功能**:创建 `specs/feature-name/req-feature-name.md`
- **子功能**:将新的用户故事和 AC 插入到 `req-feature-name.md` 的合适位置
- **依赖:** 无

### 1.2 设计规格
- 使用 `Fullstack` 技能
- **基于需求规格**,设计技术架构、API、数据模型
- **全新功能**:创建 `specs/feature-name/design-feature-name.md`
- **子功能**:在 `design-feature-name.md` 中新增或修改相关章节
- **依赖:** 需求规格必须先完成

### 1.3 UI 设计规格
- 使用 `Frontend Design` 技能
- **基于需求规格和设计规格**,设计界面布局、交互、组件
- **全新功能**:创建 `specs/feature-name/ui-feature-name.md`
- **子功能**:在 `ui-feature-name.md` 中新增或修改相关章节
- **依赖:** 需求规格和设计规格必须先完成

### 1.4 规格一致性检查
检查三个规格文档的一致性:
- [ ] 设计规格中的 API 是否满足需求规格中的所有场景
- [ ] UI 规格中的界面元素是否覆盖需求规格中的所有用户操作
- [ ] 设计规格中的数据模型是否支持 UI 规格中的所有展示需求
- [ ] 三个规格中的术语和命名是否一致
- [ ] 没有遗漏的功能点或边界情况

### 1.5 用户审核
- 请用户人工审核三个规格文档
- 确认需求理解正确、设计合理、UI 符合预期
- 未通过则返回修改,重新进行一致性检查

---

## 第二步:TDD 开发

### 2.1 开发原则
- 使用 `tdd` 技能
- 遵循 `Incremental Delivery` 规则:完整交付一个功能再开始下一个
- 遵循 `test-strategy` 规则:确保测试覆盖率和质量

### 2.2 开发流程(Red-Green-Refactor)
1. **Red(红灯)** - 为当前功能编写测试,测试失败
2. **Green(绿灯)** - 实现最小代码使测试通过
3. **Refactor(重构)** - 优化代码,保持测试通过
4. **Commit(提交)** - 每个测试通过后立即 git commit
   - Commit message 格式:`test: add test for [feature]` 或 `feat: implement [feature]`
   - 保持小步提交,便于回滚和追踪
5. 重复步骤 1-4 直到功能完成

### 2.3 Git Commit 时机
- ✅ 每个测试通过后立即 commit
- ✅ 重构完成后 commit(如果有)
- ❌ 不要等到整个功能完成才 commit
- ❌ 不要在测试失败时 commit

### 2.4 文档同步
- 如果开发过程中发现规格需要调整
- 使用 `update-docs` 技能立即更新对应的规格文档
- 在 commit message 中注明规格变更:`docs: update spec for [reason]`
- 确保代码和规格始终保持同步

---

## 第三步:DoD 验收

### 3.1 自动检查
使用 `dod` 技能自动执行以下检查:

**代码质量:**
- [ ] 所有测试通过(单元 + 集成 + e2e)
- [ ] 测试覆盖率达标(≥80% 整体,100% 关键路径)
- [ ] 无 lint 错误
- [ ] 无 TypeScript 类型错误

**功能完整性:**
- [ ] 所有验收标准(AC)已实现
- [ ] 错误处理已实现
- [ ] 边界情况已处理

**文档同步:**
- [ ] 规格文档已更新(如有变更)
- [ ] API 文档已更新(如适用)

**版本控制:**
- [ ] 代码已提交到 Git
- [ ] Commit message 清晰描述变更
- [ ] 无未追踪的临时文件
- [ ] 分支已推送到远程仓库

**非功能性要求:**
- [ ] 无明显性能问题
- [ ] 无安全漏洞(SQL注入、XSS等)
- [ ] 日志记录完整

### 3.2 人工测试
- 请用户按照 `req-feature-name.md` 中的验收标准手工测试功能
- 确认功能符合预期
- 记录测试结果

### 3.3 标记完成
如果所有检查通过:
- 在 `specs/feature-name/req-feature-name.md` 中标记功能为 ✅ 已完成
- 记录完成时间和验收人
- 示例:`✅ 已完成 - 2026-04-06 by Ethan Huang`

如果检查未通过:
- 列出所有失败项
- 修复后重新运行 DoD 检查
- 不要标记为完成

---

## 工作流检查点

| 阶段 | 检查点 | 产物 |
|------|--------|------|
| 规格编写 | 用户审核通过 | 3个规格文档 |
| TDD开发 | 所有测试通过 | 代码 + 测试 + Git commits |
| DoD验收 | 自检 + 人工测试通过 | 可交付功能 |

---

## 依赖的规则和技能

**规则(必须先创建):**
- Incremental Delivery
- DoD
- test-strategy

**技能(已有):**
- atdd
- Fullstack
- Frontend Design
- tdd
- dod
- update-docs

4,用新功能开发工作流开发一个新功能

  • 第一步:问 AI:如何执行这个工作流?
  • 第二步:让 AI 帮你们写一个新功能开发的技能,来执行这个工作流
  • 第三步:使用这个工作流 / 技能完成一个新功能的开发

5,挑战:写一个新的工作流

  • Change Requirement
  • Bug fixing
  • Testing
  • Code Refactory

6,加载 rules, skills & workflows

Chapter 8 – SDD 四核心之四 – 过程资产

完成以下任务:

1. 复习:Vibe Coding 和 SDD 最大的区别是什么?

2. 问题:如何执行 Learn & Iterate 步骤?

3. 使用 ADR(Architecture Decision Record)管理过程资产

4,分组练习,形成过程资产

第一步:让 AI 帮忙写一个 Retrospective 技能,用户总结过程资产,支持持续改进
第二步:开一个简短的 retrospective,并让 AI 使用 Retrospective 技能帮忙形成过程资产

5,问一下 AI,如何确保每次开始新任务之前,adr 目录下的过程资产会被自动加载?

Chapter 9 – Openspec

OpenSpec 安装与使用说明

安装步骤

1. 确认已安装 Node.js 和 npm:
node -v
npm -v

 

2. 全局安装 OpenSpec:
sudo npm install -g @fission-ai/openspec@latest

 

3. 进入项目目录:
cd your-project-name

 

4. 初始化 OpenSpec:
openspec init

 

5. 初始化后会生成目录:
openspec/
specs/ 当前系统行为
changes/ 变更记录
config.yaml 项目配置

常用命令

初始化与配置:

npm install -g @fission-ai/openspec@latest
openspec init
openspec config profile
openspec update

核心工作流命令:

/opsx:propose
/opsx:explore
/opsx:apply
/opsx:verify
/opsx:archive

流程说明

* propose:定义要做什么
* explore: 理清思路,生成artifacts
* apply:实现功能
* verify:验证是否符合预期
* archive:归档沉淀

扩展命令:

/opsx:new
/opsx:continue
/opsx:ff
/opsx:sync
/opsx:bulk-archive
/opsx:onboard

挑战:使用 Openspec 框架,开发一个新功能