使用 GitHub SpecKit + VS Code Codex 构建闪卡应用（规范驱动教程）

在本文中，我们将使用 GitHub SpecKit 配合 Codex VS Code 扩展来构建一个本地 闪卡 应用。我们将遵循规范驱动开发（Spec-Driven Development）的全流程：规范 → 方案 → 任务 → 实现。

为什么这个项目要用 SpecKit？ #why-speckit-for-this-project

传统的“氛围编程（vibe-coding）”往往导致结果模糊。SpecKit 反其道而行：你先编写清晰的规范，制定技术方案，将其拆解为任务，然后让编程代理在你的把关下实现一个个可测试的小切片。

前置准备 #prerequisites

• 安装 VS Code 并配备 Codex 扩展（使用 ChatGPT 账号登录）。
• 安装 Git、Python 3.11+ 和 uv（包管理器/启动器）。
• 支持 macOS、Linux 或 Windows（在 Windows 上推荐使用 WSL 以获得最佳 Codex 体验）。

公共仓库： https://github.com/nicklaunches/flashcards-speckit

安装 Specify CLI #install-specify-cli

持久化安装（推荐）：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify check

初始化项目并连接 Codex #init-project-wired-to-codex

创建一个文件夹并为 Codex 初始化 SpecKit：

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Windows 用户可以添加：--script ps

在 VS Code 中打开该文件夹，并确认 Copilot 面板已登录。

设置护栏：宪章（Constitution） #set-guardrails-constitution

在 Copilot 聊天中运行：

/speckit.constitution
创建原则，重点关注：
- 纵向切片；90% 的任务耗时 < 30 分钟
- React + Next.js + TypeScript；使用 Drizzle 连接 SQLite
- 核心逻辑编写单元测试；Playwright 冒烟测试
- 无障碍访问（WCAG AA）；性能预算：首屏 JS < 160KB
- 离线优先（无外部服务，全部本地运行）

这将创建/更新一个宪章文件，后续步骤必须遵循该文件。

编写规范（做什么与为什么） #write-the-spec-what-and-why

/speckit.specify
构建一个本地、离线优先的闪卡应用，用于快速学习。

用户故事：
1) 作为学习者，我可以创建卡组（名称和描述）。
2) 我可以添加、编辑和删除卡片（正面/背面）。
3) 我可以学习卡组并进行测验（显示正面 → 翻转 → 标记 简单/困难）。
4) 间隔重复：根据难度提升/降低卡片，使其稍后重新出现。
5) 搜索：通过文本筛选卡组和卡片。
6) 数据存储在本地；应用无需网络即可运行。
7) 良好的用户体验：快捷键（J/K/Space）、响应式布局、深色模式。

验收标准：
- CRUD 操作在会话之间保持持久化
- 测验显示进度和准确率
- 移动端 + 桌面端响应式

请专注于 做什么/为什么。技术选型留到下一阶段。

制定技术方案（怎么做） #create-the-technical-plan-how

/speckit.plan
技术与架构：
- Next.js + React + TypeScript；使用 Tailwind 进行 UI 开发
- 使用 Drizzle ORM 连接 SQLite 文件数据库；仓库抽象层
- App Router；使用 Server Actions 进行数据变更
- 单元测试：Vitest；E2E 测试：Playwright（冒烟流程）
- 快捷键工具类；通过 CSS 变量实现深色模式
- 学习页面代码分割；保持打包体积较小

这将成为 Codex 遵循的蓝图。

拆解为任务 #break-it-into-tasks

/speckit.tasks

预期会生成一个 tasks.md，包含有序的步骤、文件路径和测试存根。可选的质量检查步骤：

• /speckit.clarify — 紧缩未详述的部分
• /speckit.analyze — 交叉检查规范与方案的覆盖范围
• /speckit.checklist — 生成 QA 检查清单（例如“英语的单元测试”）

使用 Codex 实现 #implement-with-codex

/speckit.implement

Codex 会遵循 tasks.md 来搭建应用、编写代码，并在你的批准下连接测试。

运行与测试 #run-and-test

pnpm i
pnpm dev
# 打开 http://localhost:3000

完成方案中的所有任务后： 尝试：创建卡组 → 添加卡片 → 点击 学习 → 在测验中使用 J/K/Space。

添加间隔重复 #add-spaced-repetition

要求 Codex 扩展该功能：

/speckit.tasks
添加调度器：
- 每张卡片具有难度层级 (1..3)
- 简单 → +1 层级（最大 3）；困难 → -1（最小 1）
- 会话优先从较低层级抽取更多卡片
- 持久化 lastReviewed（上次复习时间）, nextDue（下次到期时间）

然后再次运行 /speckit.implement。

推荐的仓库结构 #recommended-repo-structure

flashcards-speckit/
  .specify/          # 规范、方案、任务、研究产物
  .github/           # SpecKit 添加的提示/模板
  app/               # Next.js 路由与 UI
  db/                # drizzle 模式 + 种子数据
  tests/             # 单元 + e2e 测试
  README.md

故障排除 #troubleshooting

• 斜杠命令未出现在 Codex 菜单中：确保使用 --ai codex 初始化，在项目根目录下操作，且 Codex CLI/扩展已更新。如果只显示 /speckit.constitution，请更新工具和模板；部分代理集成会随时间修复。
• 代理检查失败：在 specify init 中添加 --ignore-agent-tools 以跳过检查并强制获取模板。
• Windows：Codex 在 Windows 上处于实验阶段——使用 WSL 以获得最佳效果。

后续构想 #next-ideas

• 作为 JSON 导入/导出卡组
• 卡片正反面支持 Markdown
• 图片卡片
• 连续打卡（Streaks）+ 洞察视图
• 使用 nextDue 实现“再次学习”智能卡组

资料来源 #sources

• SpecKit 仓库（README：安装、代理、斜杠命令）— https://github.com/github/spec-kit
• GitHub 博客：Spec-driven development with AI: Get started with a new open-source toolkit — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• GitHub 博客：Spec-driven development — Using Markdown as a programming language — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/
• Codex IDE 扩展文档 — https://developers.openai.com/codex/ide/