GitHub 地址：https://github.com/github/spec-kit

一、什么是 Spec-Kit？

Spec-Kit 不是一个新的 AI 编程工具，而是一套工作流和方法论。

它通过一套命令行工具和模板，将 AI 编程助手（Claude Code、GitHub Copilot、Gemini 等）"调教"成一个既懂需求、又懂架构的"靠谱工程师"。

核心理念：规范驱动开发（Spec-Driven Development, SDD）

一句话总结：代码为规范服务，而不是规范为代码服务。

类比：

• Vibe Coding = 没图纸，凭感觉边盖边想 → "歪歪扭扭的茅草屋"
• Spec Coding = 先有详细建筑图纸（规范），再按图施工 → "坚固可靠的摩天大楼"

二、为什么使用 Spec-Kit？

Vibe Coding 的痛点

Spec-Kit 的核心价值

1. 高质量、可预测的输出 - 通过前置的规范和计划，AI 的"自由发挥"被管住了，产出更符合预期
2. 自动化文档生成 - 整个开发过程（需求、方案、任务）都被记录下来，形成跟代码同步的"活文档"
3. 团队协作效率飙升 - 标准化的流程和文档，让沟通成本大大降低，项目维护和交接变得简单
4. 沉淀团队最佳实践 - 把架构约定、代码规范写进 /constitution，让经验变成可复用的资产
5. 真正的"AI 工程师" - 让 AI 从"打字员"变成能理解意图、参与设计的"工程师"伙伴

三、安装指南

1. 安装 uv（Python 包管理工具）

macOS:

bash
复制
  brew install uv                                                                                                                                

2. 安装 Spec-Kit CLI

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

3. 初始化项目

bash
复制
# 创建新项目并初始化
specify init my-todo-app
cd my-todo-app

# 或在已有项目中初始化
specify init .

初始化时会让你选择：

• AI 助手（Claude Code、GitHub Copilot、Gemini 等）
• 脚本类型（如 sh）

完成后项目中会生成 .claude/ 和 .specify/ 目录，存放 Spec-Kit 的配置和模板。

四、使用流程：六步流水线

Step 1: 立规矩 /constitution（可选但推荐）

给项目定好基本原则和约束，相当于项目"宪法"。

/speckit.constitution 这是一个基于React的待办事项应用，要注重简洁和用户体验。

AI 会生成 constitution.md，内容包括：

• 技术栈偏好（如：优先用 React Hooks，别用 Class Components）
• 代码风格（如：按 Airbnb JavaScript Style Guide）
• 测试要求（如：核心功能必须有单元测试）
• 用户体验原则（如：交互响应时间低于 100ms）

这份"宪法"就是天条，后面所有开发工作都得按此执行。

Step 2: 提需求 /specify

用大白话描述需求，只谈功能，别谈技术。

/speckit.specify 我要做一个待办事项应用。
核心功能：
- 用户可以添加新的待办事项。
- 用户可以标记待办事项为"已完成"。
- 用户可以删除待办事项。
- 完成任务时，要有一个好玩儿的庆祝动画。

Spec-Kit 会自动：

• 在 specs/ 目录下创建新版本（如 001-todo-app-core-features）
• 生成详细的 spec.md（含用户故事、验收标准、边界条件等）
• 自动创建新的 Git 分支（如 feat/001-todo-app-core-features）

Step 3: 清疑点 /clarify（可选）

让 AI 主动提问，消除需求中模棱两可的地方。

/speckit.clarify

AI 可能会反问：

• "好玩儿的庆祝动画"具体是啥风格？放烟花还是撒花？
• 待办事项有字数限制吗？
• 要不要支持任务优先级？

回答问题后，AI 会自动更新 spec.md。

Step 4: 出方案 /plan

AI 变身架构师，根据"宪法"和"需求"生成完整技术方案。

/speckit.plan

生成的文档可能包括：

• plan.md - 技术栈决策（如 React 18 + Zustand + Framer Motion）
• data-model.md - 数据结构定义
• contracts/ - API 接口或组件接口定义
• research.md - 选型调研和决策依据

Step 5: 拆任务 /tasks

把方案拆解成可执行的任务列表。

/speckit.tasks

生成 tasks.md：

Phase 1: 项目设置 (3个任务)

• T001: 初始化 React + Vite 项目
• T002: 安装 Zustand 和 Framer Motion 依赖
• T003: 配置 ESLint 和 Prettier

Phase 2: 核心组件开发 (4个任务)

• T004: 开发 TodoItem 组件
• T005: 开发 AddTodoForm 组件
• ...

Step 6: 写代码 /implement

AI 按照任务列表严格执行编码。

/speckit.implement

• AI 按 tasks.md 逐个完成编码和测试
• 每完成一个任务，自动在清单上打勾 [x]
• 可选 YOLO 模式一口气干完，或逐步确认模式逐个检查

YOLO 模式 vs 逐步确认模式

YOLO 模式的优点：

• 效率极高，全程无需人工干预，适合夜间/离开时挂机运行
• 任务间上下文连贯，AI 可以自行协调跨任务的依赖关系
• 对于前期 /constitution → /specify → /plan 做得够扎实的项目，产出质量可靠

YOLO 模式的缺点：

• 一旦某个任务方向跑偏，后续任务会在错误基础上继续堆砌，"错上加错"
• 出问题后回滚成本高，可能需要推翻多个任务的代码重来
• 不适合规范不够清晰或 AI 对项目上下文理解不足的场景
• Token 消耗大，长任务链可能触发上下文窗口限制

建议：

• 首次使用 Spec-Kit 或项目较复杂时，先用逐步确认模式，建立信任
• 当 /constitution 和 /specify 足够详尽，且你对流程已经熟悉后，再切换到 YOLO 模式
• 折中方案：按 Phase 分批 YOLO，每个阶段完成后人工 Review 一次

五、应用场景

六、流程速查表

specify init <project>        # 初始化项目
    ↓
/speckit.constitution         # [可选] 定义项目规范和约束
    ↓
/speckit.specify              # 描述需求（只谈功能）
    ↓
/speckit.clarify              # [可选] 消除需求歧义
    ↓
/speckit.plan                 # AI 生成技术方案
    ↓
/speckit.tasks                # AI 拆解任务列表
    ↓
/speckit.implement            # AI 按任务编码实现

七、常见问题（FAQ）

Q1: Spec-Kit 会不会很复杂，反而增加工作量？

上手需要一点学习成本，但对于中大型项目，它通过减少返工、降低沟通成本，长期绝对提升效率。如果只是做个小 demo，直接用 AI 助手也完全没问题。

Q2: 能在老项目里用 Spec-Kit 吗？

完全可以！在项目根目录运行 specify init . 即可。它不会动现有代码，可以先从一个小功能开始试水。

Q3: 需求变了怎么办？

回到 /specify 描述新需求或变更，Spec-Kit 会创建新的版本和分支，然后再走一遍 /plan → /tasks → /implement 流程。所有历史版本都会保留，迭代过程清晰可追溯。

Q4: 支持哪些 AI 工具？

几乎所有主流 AI 编程工具：

• GitHub Copilot
• Claude Code
• Gemini
• Cursor
• 通义千问
• Roo Code
• 等等

初始化时可自由选择。

Q5: 注意事项

• 工程路径中不要有中文
• 初始化时需选择 AI 助手和脚本类型
• constitution 和 clarify 步骤虽可选，但强烈推荐使用

八、完整示例：用 Spec-Kit 制作一个技术博客网站

下面以开发一个"个人技术博客网站"为例，完整演示 Spec-Kit 的六步流水线。

8.1 初始化项目

bash
复制
specify init tech-blog
cd tech-blog
# 选择 AI 助手: Claude Code
# 选择脚本类型: sh

8.2 立规矩 /constitution

/speckit.constitution 这是一个个人技术博客网站，面向开发者群体。
要求：
- 基于 Next.js + TypeScript 构建
- 使用 Tailwind CSS 做样式
- 文章内容使用 Markdown 编写，存放在本地文件系统
- 代码风格遵循 ESLint + Prettier
- 页面需要支持 SSG（静态站点生成），方便部署到 Vercel/Netlify
- 注重 SEO 和页面加载性能
- 设计风格简约、专业，参考 Dan Abramov 的 overreacted.io

AI 生成的 constitution.md 要点：

技术约束

• 框架: Next.js 14 (App Router) + TypeScript
• 样式: Tailwind CSS 4.x
• 内容: MDX (Markdown + JSX)，存放在 /content/posts/ 目录
• 部署: 静态导出 (next export)，目标平台 Vercel

代码规范

• 使用函数式组件 + React Server Components
• 文件命名: kebab-case
• 组件命名: PascalCase
• 禁止使用 any 类型

性能要求

• Lighthouse 评分 > 90
• 首屏加载 < 1.5s
• 所有图片使用 next/image 优化

8.3 提需求 /specify

/speckit.specify 我要做一个个人技术博客网站。

核心功能：
- 首页展示文章列表，按发布时间倒序，支持分页
- 文章详情页，支持 Markdown 渲染（含代码高亮）
- 文章支持标签分类，可以按标签筛选
- 有一个"关于我"页面
- 支持深色/浅色主题切换
- 文章页面底部有上一篇/下一篇导航
- 支持 RSS 订阅
- 响应式布局，移动端友好

AI 自动生成 specs/001-tech-blog/spec.md：

技术博客网站 - 需求规范

用户故事

US-001: 浏览文章列表

作为一个访客，我希望在首页看到所有文章的列表， 以便我可以快速找到感兴趣的内容。

验收标准：

• 每页展示 10 篇文章
• 每篇文章显示：标题、摘要(前 200 字)、发布日期、标签
• 按发布时间倒序排列
• 底部有分页导航

US-002: 阅读文章详情

作为一个访客，我希望点击文章标题进入详情页， 以便我可以阅读完整内容。

验收标准：

• 完整渲染 Markdown 内容
• 代码块支持语法高亮（支持 20+ 种语言）
• 显示预计阅读时间
• 文章底部有上一篇/下一篇导航

US-003: 按标签筛选

...

US-004: 主题切换

...

边界条件

• 无文章时首页展示"暂无文章"提示
• 标签不存在时展示 404 页面
• Markdown 渲染需防范 XSS 攻击

同时自动创建 Git 分支 feat/001-tech-blog。

8.4 清疑点 /clarify

/speckit.clarify

AI 提问与回答：

Q1: 代码高亮使用哪个库？Shiki 还是 Prism？
A1: 用 Shiki，效果更好。

Q2: 文章的 Markdown 文件命名规则是什么？
A2: 用日期+标题，如 2026-03-05-getting-started-with-nextjs.mdx

Q3: RSS 需要全文输出还是仅摘要？
A3: 全文输出。

Q4: 深色模式的默认状态？跟随系统还是默认浅色？
A4: 跟随系统偏好，用户可手动切换，选择会记住。

AI 自动将这些细节更新到 spec.md 中。

8.5 出方案 /plan

/speckit.plan

AI 生成的 plan.md 关键内容：

技术方案

技术栈

项目结构

tech-blog/
├── app/
│   ├── layout.tsx            # 根布局（导航、主题、页脚）
│   ├── page.tsx              # 首页（文章列表）
│   ├── posts/[slug]/page.tsx # 文章详情页
│   ├── tags/[tag]/page.tsx   # 标签筛选页
│   ├── about/page.tsx        # 关于我
│   └── feed.xml/route.ts     # RSS 订阅
├── components/
│   ├── PostCard.tsx           # 文章卡片
│   ├── Pagination.tsx         # 分页
│   ├── TagList.tsx            # 标签列表
│   ├── ThemeToggle.tsx        # 主题切换
│   ├── PostNavigation.tsx     # 上/下篇导航
│   └── MdxRenderer.tsx        # MDX 渲染器
├── content/
│   └── posts/                 # Markdown 文章目录
├── lib/
│   ├── posts.ts               # 文章读取/解析
│   └── utils.ts               # 工具函数
└── public/

AI 同时生成 data-model.md：

Post (文章)

8.6 拆任务 /tasks

/speckit.tasks

AI 生成的 tasks.md：

Phase 1: 项目基础搭建 (4 个任务)

• T001: 初始化 Next.js 14 + TypeScript 项目，配置 Tailwind CSS
• T002: 配置 ESLint + Prettier，添加 .editorconfig
• T003: 集成 contentlayer，配置 MDX 解析和 Shiki 代码高亮
• T004: 创建根布局 layout.tsx（导航栏 + 页脚 + 字体）

Phase 2: 核心页面开发 (5 个任务)

• T005: 实现文章读取工具 lib/posts.ts（解析 frontmatter、计算阅读时间）
• T006: 开发 PostCard 组件和首页文章列表（含分页）
• T007: 开发文章详情页（MDX 渲染 + 代码高亮 + 上/下篇导航）
• T008: 开发标签系统（TagList 组件 + 标签筛选页）
• T009: 开发"关于我"页面

Phase 3: 增强功能 (3 个任务)

• T010: 实现深色/浅色主题切换（next-themes + localStorage 持久化）
• T011: 实现 RSS 订阅 (feed.xml)
• T012: 响应式布局适配（移动端导航、文章排版）

Phase 4: 优化与收尾 (3 个任务)

• T013: SEO 优化（meta 标签、Open Graph、sitemap.xml）
• T014: 性能优化（图片优化、字体加载、Lighthouse 达标）
• T015: 添加示例文章，编写 README 部署文档

8.7 执行实现 /implement

/speckit.implement

AI 开始逐个任务编码。以 T006 为例，AI 生成的代码：

components/PostCard.tsx：

tsx
复制
import Link from 'next/link';

interface PostCardProps {
  slug: string;
  title: string;
  date: string;
  excerpt: string;
  tags: string[];
  readingTime: number;
}

export function PostCard({ slug, title, date, excerpt, tags, readingTime }: PostCardProps) {
  return (
    <article className="py-6 border-b border-gray-200 dark:border-gray-700">
      <Link href={`/posts/${slug}`}>
        <h2 className="text-xl font-bold hover:text-blue-600 dark:hover:text-blue-400 transition-colors">
          {title}
        </h2>
      </Link>
      <div className="mt-2 flex items-center gap-3 text-sm text-gray-500 dark:text-gray-400">
        <time dateTime={date}>{date}</time>
        <span>{readingTime} min read</span>
      </div>
      <p className="mt-3 text-gray-600 dark:text-gray-300 line-clamp-3">{excerpt}</p>
      <div className="mt-3 flex gap-2">
        {tags.map((tag) => (
          <Link
            key={tag}
            href={`/tags/${tag}`}
            className="text-xs px-2 py-1 rounded-full bg-gray-100 dark:bg-gray-800 hover:bg-blue-100"
          >
            #{tag}
          </Link>
        ))}
      </div>
    </article>
  );
}

app/page.tsx（首页）：

tsx
复制
import { getAllPosts } from '@/lib/posts';
import { PostCard } from '@/components/PostCard';
import { Pagination } from '@/components/Pagination';

const POSTS_PER_PAGE = 10;

export default async function HomePage({ searchParams }: { searchParams: { page?: string } }) {
  const currentPage = Number(searchParams.page) || 1;
  const allPosts = getAllPosts();
  const totalPages = Math.ceil(allPosts.length / POSTS_PER_PAGE);
  const posts = allPosts.slice(
    (currentPage - 1) * POSTS_PER_PAGE,
    currentPage * POSTS_PER_PAGE
  );

  return (
    <main className="max-w-2xl mx-auto px-4 py-8">
      <h1 className="text-3xl font-bold mb-8">Latest Posts</h1>
      {posts.length === 0 ? (
        <p className="text-gray-500">No posts yet.</p>
      ) : (
        <>
          {posts.map((post) => (
            <PostCard key={post.slug} {...post} />
          ))}
          <Pagination current={currentPage} total={totalPages} />
        </>
      )}
    </main>
  );
}

每完成一个任务，tasks.md 自动更新：

• T006: 开发 PostCard 组件和首页文章列表（含分页） ✅

8.8 最终产出

完成所有 15 个任务后，你得到的不仅是代码，还有完整的项目文档链路：

tech-blog/
├── .specify/
│   └── specs/001-tech-blog/
│       ├── spec.md          # 需求规范
│       ├── constitution.md  # 项目宪法
│       ├── plan.md          # 技术方案
│       ├── data-model.md    # 数据模型
│       └── tasks.md         # 任务清单（全部 ✅）
├── app/                     # 完整的页面代码
├── components/              # 可复用组件
├── content/posts/           # 示例文章
├── lib/                     # 工具函数
├── public/                  # 静态资源
└── README.md                # 部署文档

任何新加入的团队成员，只需阅读 .specify/ 目录下的文档，就能完整理解项目的需求、技术决策和实现细节。

订阅我，关注更多ai开发范式！