SPEC-KIT简介+结合CODEX使用

原创已于 2025-10-23 17:04:11 修改 · 1.6k 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#specify

于 2025-10-23 16:48:03 首次发布

AI 专栏收录该内容

27 篇文章

订阅专栏

spec-kit

1. 背景 & 核心理念

What & Why

传统开发中，代码往往是「源真理（source of truth）」，而需求／规格／设计文档仅为辅助。
在 SDD 中，流程被反转：规格为主，代码为“实现规格”的表达。
规格必须具备“可执行性”——足够清晰、完整、无歧义，以致于能够“生成”可工作的系统。
开发流程由 “规格 → 实施计划 → 任务 → 代码” 构成，而不仅是“先写代码再补文档”。 oai_citation:3‡The GitHub Blog

主要流程阶段

以下是关键阶段，每个阶段有其目的、关键活动、产出。

阶段	名称	目的	关键活动	产出
0	Constitution	建立项目的治理原则／开发指导方针	定义项目原则（代码风格、测试标准、架构约束等）	`constitution.md`
1	Specify	定义“我要做什么”、为什么做、范畴是什么	明确目标、用户、范围、成功标准、约束条件	`spec.md`
2	Plan	在“做什么”明确之后，定义“我怎么做”	技术栈选择、架构设计、数据模型、接口契约	`plan.md` (+子文档)
3	Tasks	将计划转化为可执行、分配的任务清单	将 plan 中模块拆分、定义任务、责任人、完成条件	`tasks.md`
4	Implement	执行任务，实现代码、测试、发布	编写代码、测试、集成、部署	完整系统／功能 + 测试 + 文档

附加支持阶段（可选）：

Clarify：在规格阶段，有未澄清之处 (“NEEDS CLARIFICATION”) 时，进行澄清。
Analyze：在 plan/tasks 等阶段，进行交叉文档一致性／覆盖性检查。
Checklist：生成自定义质量检查清单，例如“所有用户故事都有测试”“接口定义包含错误代码”等。

2.安装+codex结合

Install Specify

## 方法1
### 安装specify-cli
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

### init
specify init <PROJECT_NAME>  # --here , 选择codex,sh


## 方法2: 一次性init
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

快捷命令: uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai codex --script sh

init后目录结构

.
├── .codex
│   └── prompts
│       ├── speckit.analyze.md
│       ├── speckit.checklist.md
│       ├── speckit.clarify.md
│       ├── speckit.constitution.md
│       ├── speckit.implement.md
│       ├── speckit.plan.md
│       ├── speckit.specify.md
│       └── speckit.tasks.md
└── .specify
    ├── memory
    │   └── constitution.md
    ├── scripts
    │   └── bash
    │       ├── check-prerequisites.sh
    │       ├── common.sh
    │       ├── create-new-feature.sh
    │       ├── setup-plan.sh
    │       └── update-agent-context.sh
    └── templates
        ├── agent-file-template.md
        ├── checklist-template.md
        ├── plan-template.md
        ├── spec-template.md
        └── tasks-template.md

codex中使用speckit.*命令

与claude-code不同，在codex中无法直接使用speckit.*命令，但是可以通过如下mention speckit.*.md来使用。
在这里插入图片描述

codex命令:.codex/prompts/speckit.constitution.md XXXX

spec-driven

3.案例：评论模块（“用户评论与回复”）

假设我们要为一个在线产品平台新增「用户评论与回复」功能。

阶段 0：Constitution（治理／约定阶段）

目的

建立项目层面的原则、团队约定、技术边界，为后续所有规格、计划、任务提供指导。

内容（示例）

项目原则：
- 所有新功能必须通过规格驱动（Spec First）——规格文档为主，代码为实现。
- 功能必须支持国际化 (i18n) 与移动友好。
- 评论数据必须符合隐私与合规要求（例如不得存储敏感个人信息）。
- 服务必须具备可扩展性，设计时考虑高并发评论场景。
技术约定：
- 后端主要使用 Java + Spring Boot，数据库使用 PostgreSQL。
- API 响应时间控制在 300 ms 内。
- 所有新接口必须伴随自动化测试（单元＋集成）且覆盖率 ≥ 80%。
文档约定：
- 每个功能须有 spec.md（规格）、plan.md（计划）、tasks.md（任务清单）三个文档。
- 文档存放路径遵循 specs/feature‑xxx/ 约定。

产出

constitution.md 文件（或在项目 Wiki 中一个专页）记录上述原则与约定。

阶段 1：Specify（规格阶段）

目的

明确“我们要做什么”、为什么做、成功标准是什么、范围和边界是什么。避免模糊需求。

内容（示例）

背景

平台现有产品展示模块中尚未支持用户评论功能。用户希望能够在产品页面发表评论、查看他人的评论并回复。该功能有助于提升社区互动、增加用户黏性。

功能目标

支持用户对某产品发表评论。
支持用户对已有评论进行 一次回复（回复无需再递归多级回复，仅一层）。
评论列表按时间倒序展示（最新在前）。
支持分页加载评论（每页 20 条）。
评论必须经过审核（管理员审批后才能公开显示）。

范围 & 不在范围

在范围：标准用户发表评论、回复、查看；管理员可审核评论。
不在范围：匿名用户发表评论；评论点赞／踩；多层嵌套回复。

成功标准

评论模块上线后，用户评论功能使用率 ≥ 5%／日。
评论列表加载响应时间 ≤ 500ms。
评论发布接口错误率 < 1%。

约束条件

所有评论数据需脱敏存储，用户名以别名显示。
评论服务必须可横向扩展，支持同时 1000 用户并发发表评论。
UI 要兼容移动端和桌面端。

产出

spec.md 文档，包含上述背景、目标、功能清单、范畴、成功标准、约束。

阶段 2：Plan（计划阶段）

目的

在明确“做什么”之后，制定“怎么做”：技术选型、模块划分、接口契约、数据模型、风险识别等。

内容（示例）

技术栈：后端 Spring Boot 3 + Hibernate；前端 React 18；数据库 PostgreSQL。
模块划分：
- 评论服务模块（CommentService）
- 审核服务模块（ReviewService）
- API 层（CommentController）
- 前端评论组件（CommentList、CommentForm、ReplyForm）
数据模型（简要）：
- comments 表：id、product_id、user_id、content、reply_to_comment_id（nullable）、status（PENDING/APPROVED/REJECTED）、created_at、updated_at。
接口契约（示例）：
- POST /api/v1/products/{productId}/comments — 提交评论。请求体 { content: string }，返回评论对象或错误。
- GET /api/v1/products/{productId}/comments?page=1&size=20 — 获取评论列表。返回分页结构 { items: Comment[], total: int, page: int, size: int }。
- POST /api/v1/comments/{commentId}/reply — 回复评论。请求体 { content: string }。
风险与非目标：
- 风险：高并发下评论写入冲突、审核延迟导致用户体验差。
- 非目标：实时通知其他用户评论被回复、评论多媒体（图片／视频）支持。
性能预算：在并发 1000 条／秒写入情况下，95 percentile 响应时间 < 300ms。
安全／隐私：内容需过滤敏感词；用户账号需先登录后才能评论。

产出

plan.md 文档，包含上述技术架构、模块划分、接口定义、数据结构、风险清单、性能目标等。

阶段 3：Tasks（任务拆解阶段）

目的

将计划拆解成可执行、可分配、可追踪的任务清单。每个任务明确产出、负责人、完成标准。

内容（示例任务清单）

编号	任务标题	描述	负责人	完成标准
T‑01	建立 `comments` 数据表	在数据库中创建表定义	后端	表结构正确、迁移脚本通过、字段符合 plan 中定义
T‑02	实现提交评论接口	`POST /api/v1/products/{productId}/comments`	后端	接口调用成功、内容存储、`status = PENDING`、返回 201
T‑03	实现分页查询评论接口	`GET /api/v1/products/{productId}/comments`	后端	分页接口正常返回，排序正确，测试覆盖
T‑04	实现回复评论接口	`POST /api/v1/comments/{commentId}/reply`	后端	回复成功、`reply_to_comment_id` 正确设置、返回符合规范
T‑05	前端显示评论列表组件	React 组件 `CommentList`	前端	评论列表显示正确、分页加载、样式符合设计规范
T‑06	前端评论提交表单组件	React 组件 `CommentForm`	前端	表单校验、提交成功后刷新列表、错误提示正确显示
T‑07	管理后台评论审核功能	审核页面／接口实现	后端+前端	管理员可查看评论、批准或拒绝
T‑08	性能测试与高并发模拟	编写负载测试脚本	测试	模拟 1000 条／秒写入、响应时间 < 300ms、结果报告