specdriven

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

specdriven

A deliberately small, three-phase scaffold for building software with AI coding agents — designed for people who would rather describe their idea than write a technical spec. No constitution document, no clarification phase, no ceremony. Just three plain-English artifacts the agent reads on every turn.

If you (the agent) need to know whether to invoke this skill, see When to use below. Otherwise, the rest of this file is the playbook.

这是一个专为AI编码Agent设计的极简三阶段框架，面向那些更愿意描述想法而非编写技术规格的人群。无需章程文档，无需澄清阶段，也没有繁琐流程。仅需三个纯英文文档，Agent在每次工作时都会参考这些文档。

如果你（Agent）需要判断是否调用此技能，请查看下方的使用场景。否则，本文档剩余部分即为操作手册。

When to use this skill

何时使用此技能

Invoke when:

The user describes a new project ("I want to make…", "I'm thinking about building…")
The user wants a new feature on an existing project but acceptance is fuzzy
The user explicitly says "concept", "roadmap", "feature", "spec", "plan", "what should I build first?"
The user lists a wish-list and you can't tell what to build first

Do not invoke when:

The task is small and scoped ("rename this variable", "fix this typo", "why isn't this loop terminating?")
A
```
specdriven/
```
folder already exists and the user is in the middle of building a specific feature — just consult the existing artifacts and keep working

在以下场景调用：

用户描述一个新项目（“我想做一个……”、“我正在考虑构建……”）
用户希望在现有项目中添加新功能，但验收标准尚不清晰
用户明确提及“concept”、“roadmap”、“feature”、“spec”、“plan”、“我应该先构建什么？”
用户列出了愿望清单，但你无法判断优先构建内容

请勿在以下场景调用：

任务范围小且明确（“重命名这个变量”、“修复这个拼写错误”、“为什么这个循环无法终止？”）
项目中已存在
```
specdriven/
```
文件夹，且用户正处于构建特定功能的过程中——只需参考现有文档继续工作即可

The three phases

三个阶段

  ┌────────────┐     ┌────────────┐     ┌────────────┐
  │  CONCEPT   │ ──▶ │  ROADMAP   │ ──▶ │  FEATURES  │
  │  the why   │     │  the path  │     │  the work  │
  └────────────┘     └────────────┘     └────────────┘
   concept.md         roadmap.md         features/NN-name.md

Each phase produces ONE markdown artifact under a top-level

specdriven/

folder in the user's project:

<user-project>/
└── specdriven/
    ├── concept.md
    ├── roadmap.md
    └── features/
        ├── 01-sign-up.md
        ├── 02-create-post.md
        └── 03-share-link.md

These artifacts are the contract between the user and the agent. Read them on every turn. If the user says something that contradicts them, surface the contradiction before acting.

  ┌────────────┐     ┌────────────┐     ┌────────────┐
  │  CONCEPT   │ ──▶ │  ROADMAP   │ ──▶ │  FEATURES  │
  │  the why   │     │  the path  │     │  the work  │
  └────────────┘     └────────────┘     └────────────┘
   concept.md         roadmap.md         features/NN-name.md

每个阶段会在用户项目的顶级

specdriven/

目录下生成一个markdown文档：

<user-project>/
└── specdriven/
    ├── concept.md
    ├── roadmap.md
    └── features/
        ├── 01-sign-up.md
        ├── 02-create-post.md
        └── 03-share-link.md

这些文档是用户与Agent之间的约定。每次工作时都要阅读它们。如果用户提出的内容与文档矛盾，需先指出矛盾再采取行动。

Phase 1 — Concept

第一阶段——Concept（概念）

Goal: capture what the user wants to build, who it's for, and what done looks like — in plain English, on one page.

How to run it:

Read whatever the user just said. If anything is fuzzy, ask 3–5 short clarifying questions. Keep it light — a numbered list works, or one at a time, whichever the user prefers.
Pull the answers into the
```
concept.md
```
template below. If something is genuinely unknown after asking, write
```
?
```
in that slot. Never invent requirements.
Show the filled draft. Ask for fixes. Save to
```
specdriven/concept.md
```
.

concept.md
template:

markdown

undefined

目标：用纯英文在单页文档中记录用户想要构建的内容、目标用户以及完成状态的定义。

操作步骤：

阅读用户刚说的内容。如果有模糊之处，提出3-5个简短的澄清问题。保持轻松——可以用编号列表，也可以逐个提问，按用户偏好选择。
将答案填入下方的
```
concept.md
```
模板。如果提问后仍有内容未知，在对应位置填写
```
?
```
。切勿自行编造需求。
展示填写好的草稿，请求用户修正。保存至
```
specdriven/concept.md
```
。

concept.md
模板：

markdown

undefined

Concept: <one-line title>

Concept: <一行标题>

Elevator pitch. <one or two sentences a non-technical friend would understand>

Who's it for. <who the user is — be specific>

The problem. <what's broken or missing today>

Done looks like. <3–5 bullets describing success>

Ground rules. <non-negotiables: e.g. "must work on phone", "no login", "free to host">

Out of scope. <tempting additions we will NOT do in v1>

Open questions. <things to flag — never invent>


**Anti-patterns:**

- ✗ Don't write a 5-page spec. One page, max.
- ✗ Don't propose a tech stack here — that's roadmap territory.
- ✗ Don't list features here — that's roadmap territory.
- ✗ Don't ask 20 questions. 3–5 short ones.

When the concept is saved and the user approves, move to Roadmap.

---

电梯游说 <一两句话，让非技术背景的朋友也能理解>

目标用户 <具体描述用户群体>

解决的问题 <当前存在的痛点或缺失的功能>

完成状态 <3-5条描述成功标准的项目符号>

基本原则 <不可协商的要求：例如“必须支持手机端”、“无需登录”、“托管免费”>

不在v1范围内 <诱人但v1不会实现的功能>

待解决问题 <需要标记的问题——切勿自行编造>


**反模式**：

- ✗ 不要写5页长的规格文档，最多一页。
- ✗ 不要在此阶段提议技术栈——这属于Roadmap阶段的内容。
- ✗ 不要在此阶段列出功能——这属于Roadmap阶段的内容。
- ✗ 不要提出20个问题，3-5个简短问题即可。

当概念文档保存并获得用户批准后，进入Roadmap阶段。

---

Phase 2 — Roadmap

第二阶段——Roadmap（路线图）

Goal: turn the concept into an ordered list of features that, built one by one, deliver the concept.

How to run it:

Re-read
```
specdriven/concept.md
```
. Every feature in the roadmap must map to at least one bullet under "Done looks like".
Propose 4–10 features. Each gets a name, a one-line "why", and a rough size (S / M / L). Order them so the user has something usable as early as possible — skateboard before car, not wheels before chassis.
Note dependencies in plain English ("needs sign-up done first").
Show the proposal. Let the user reorder, drop, or add. Save to
```
specdriven/roadmap.md
```
.

roadmap.md
template:

markdown

undefined

目标：将概念转化为有序的功能列表，逐个构建这些功能即可实现概念目标。

操作步骤：

重新阅读
```
specdriven/concept.md
```
。路线图中的每个功能必须至少对应“完成状态”下的一条项目符号。
提议4-10个功能。每个功能包含名称、一行描述“为什么需要此功能”以及大致规模（S / M / L）。排序时要确保用户能尽早获得可用版本——先做滑板，再做汽车，而不是先做轮子再做底盘。
用纯英文标注依赖关系（“需要先完成注册功能”）。
展示提案，允许用户重新排序、删除或添加功能。保存至
```
specdriven/roadmap.md
```
。

roadmap.md
模板：

markdown

undefined

Roadmap

Built in this order so we have something usable as early as possible.

按此顺序构建，以便尽早获得可用版本。

1. <feature name> — S

1. <功能名称> — S

Why. <one line tied to a "Done looks like" bullet from concept.md> Depends on. none Status. ☐ not started

原因 <一行描述，关联concept.md中“完成状态”的某条项目符号> 依赖无状态 ☐ 未开始

2. <feature name> — M

2. <功能名称> — M

Why. ... Depends on. #1 Status. ☐ not started

原因 ... 依赖 #1 状态 ☐ 未开始

3. <feature name> — S

3. <功能名称> — S

Why. ... Depends on. #1 Status. ☐ not started

...


**Sizing guide (rough — not hours):**

- **S** — one sitting, one file or two, no new concepts
- **M** — a few sittings, multiple files, maybe a new library
- **L** — week or more, new architectural piece. If something feels L, *try to split it*.

**Anti-patterns:**

- ✗ More than 10 features in v1. If there are more, this is really two roadmaps; pick one.
- ✗ Sequencing by easiest-first instead of "what makes the thing usable soonest".
- ✗ Putting "research X" or "figure out the database" as a feature. Either it's a real feature or it's an open question on `concept.md`.

When the roadmap is saved and approved, move to Features.

---

原因 ... 依赖 #1 状态 ☐ 未开始

...


**规模指南（大致划分，非耗时）**：

- **S** — 一次完成，涉及1-2个文件，无新概念
- **M** — 分几次完成，涉及多个文件，可能需要引入新库
- **L** — 需要一周或更长时间，涉及新的架构组件。如果某个功能看起来是L级，尝试拆分它。

**反模式**：

- ✗ v1版本包含超过10个功能。如果超过，说明实际上是两个路线图，请选择其中一个。
- ✗ 按“最简单优先”排序，而非“尽早实现可用版本”优先。
- ✗ 将“研究X”或“确定数据库选型”列为功能。要么是真实功能，要么是concept.md中的待解决问题。

当路线图保存并获得批准后，进入Features阶段。

---

Phase 3 — Features

第三阶段——Features（功能）

Goal: pick the next feature off the roadmap, expand it just enough to build it well, then build it.

How to run it:

Look at
```
specdriven/roadmap.md
```
. The next feature is the lowest-numbered one whose dependencies are done.
Create
```
specdriven/features/NN-feature-name.md
```
from the template below. Fill it in with your best understanding; flag any open questions.
Show the feature card to the user. If they approve, build it. If they push back, revise the card first — do not argue while coding.
After building:
- Tick the acceptance checks you actually verified (ran the code, clicked the flow). Untested boxes stay unticked.
- Mark this feature ☑ done in
```
roadmap.md
```
  .
- Ask the user whether to move to the next feature.

features/NN-name.md
template:

markdown

undefined

目标：从路线图中选取下一个功能，将其扩展到足够详细的程度以便顺利构建，然后开始构建。

操作步骤：

查看
```
specdriven/roadmap.md
```
。下一个要构建的功能是编号最小且依赖已完成的功能。
根据下方模板创建
```
specdriven/features/NN-feature-name.md
```
。根据你的理解填写内容，标记所有待解决问题。
向用户展示功能卡片。如果用户批准，开始构建。如果用户提出异议，先修改卡片——不要在编码时争论。
构建完成后：
- 勾选你实际验证过的验收检查项（运行代码、测试流程）。未测试的项保持未勾选状态。
- 在
```
roadmap.md
```
  中将此功能标记为☑ 已完成。
- 询问用户是否继续下一个功能。

features/NN-name.md
模板：

markdown

undefined

Feature N — <name>

Feature N — <名称>

From: roadmap.md item #N

What it does. <1–2 sentences in user terms>

User flow.

User does X
System responds with Y
...

Acceptance checks. <what must be true for this to count as done>

Tech notes. <specific choices: library, file layout, API. Brief.>

Open questions. <flag, don't invent>


**Rules of thumb:**

- A feature card is half a page, not three pages.
- Acceptance checks must be testable by clicking around or running one command. "Works well" is not a check; "user lands on /home after sign-in" is.
- If building reveals a missing feature, don't silently bolt it onto this card — open a new card and update the roadmap.
- If building reveals the *concept* was wrong, **stop and update `concept.md` first**. The artifacts are a contract; do not drift.

---

来自：roadmap.md 第N项

功能描述 <1-2句话，以用户视角描述>

用户流程

用户执行操作X
系统响应Y
...

验收检查项 <功能完成必须满足的条件>

技术说明 <具体选择：库、文件布局、API。简要描述>

待解决问题 <标记问题，切勿自行编造>


**经验法则**：

- 功能卡片最多半页，不要超过三页。
- 验收检查项必须可通过点击操作或运行单个命令测试。“运行良好”不是有效检查项；“用户登录后跳转到/home页面”才是。
- 如果构建过程中发现缺少某个功能，不要悄悄添加到当前卡片中——创建新卡片并更新路线图。
- 如果构建过程中发现**概念**有误，**先停止并更新`concept.md`**。文档是约定，不能偏离。

---

Working agreement (cross-cutting rules)

工作约定（通用规则）

These apply across all three phases:

Read the artifacts every turn.
```
concept.md
```
and
```
roadmap.md
```
are the source of truth. If a request contradicts them, surface the contradiction before acting.
Plain English wins. No jargon unless the user used it first. Say "who's it for", not "ICP". Say "first usable version", not "MVP scaffolding". Say "what done looks like", not "acceptance criteria for the user story".
One page per artifact. If a doc sprawls, scope was split wrong.
Flag, don't invent. If something is unknown, write
```
?
```
and ask. Never fabricate requirements to fill a gap.
Tick boxes truthfully. Only mark an acceptance check ☑ if you actually verified it. If you couldn't test (e.g. no browser available), say so explicitly — don't claim success.
Keep the roadmap honest. When a feature ships, mark it ☑ done in
```
roadmap.md
```
so the next session has accurate state.
Small features beat big ones. If a feature card grows past 7 acceptance checks, split it.

这些规则适用于所有三个阶段：

每次工作时都要阅读文档。
```
concept.md
```
和
```
roadmap.md
```
是唯一的事实来源。如果请求与文档矛盾，需先指出矛盾再采取行动。
优先使用纯英文。除非用户先使用了术语，否则不要用行话。说“目标用户是谁”，而不是“ICP”。说“第一个可用版本”，而不是“MVP脚手架”。说“完成状态是什么样的”，而不是“用户故事的验收标准”。
每个文档仅限一页。如果文档篇幅过长，说明范围拆分有误。
标记问题，切勿编造。如果有内容未知，填写
```
?
```
并询问。切勿编造需求填补空白。
如实勾选检查项。只有实际验证过的验收检查项才能标记为☑。如果无法测试（例如没有浏览器），请明确说明——不要声称已完成。
保持路线图真实准确。功能完成后，在
```
roadmap.md
```
中标记为☑ 已完成，以便下一次工作时有准确的状态。
小功能优于大功能。如果功能卡片的验收检查项超过7条，拆分它。

Quick start (when you, the agent, walk in fresh)

快速入门（当你作为Agent刚接手项目时）

State machine:

What you see in the user's project	What to do
No `specdriven/` folder	Ask the user: "Want me to set this up — describe what you're building, and I'll draft the concept page, then we'll plan the roadmap together." On yes, run Phase 1.
`specdriven/concept.md` exists, no `roadmap.md`	Read concept.md, run Phase 2.
Both exist, user wants to build	Run Phase 3 on the next undone feature.
User asks something unrelated mid-feature	Answer it, then offer to return to the feature.
User contradicts an existing artifact	Surface the contradiction, ask whether to update the artifact, do not silently drift.

状态机：

在用户项目中看到的内容	操作
无 `specdriven/` 文件夹	询问用户：“需要我帮你搭建吗？描述一下你要构建的内容，我会起草概念文档，然后我们一起制定路线图。”如果用户同意，执行第一阶段。
存在 `specdriven/concept.md` ，无 `roadmap.md`	阅读concept.md，执行第二阶段。
两者都存在，用户想要构建	对下一个未完成的功能执行第三阶段。
用户在构建功能中途提出无关问题	回答问题，然后提议回到功能构建。
用户提出的内容与现有文档矛盾	指出矛盾，询问是否更新文档，切勿悄悄偏离约定。

What this skill is NOT

此技能不具备的能力

Not a project manager. No time tracking, no assignees, no dates.
Not a design tool. It captures what, not how the UI looks.
Not a replacement for your judgment when coding. Once a feature card is approved, you (the agent) pick the implementation.
Not opinionated about tech stack. The roadmap can note choices; this skill doesn't dictate them.
Not a heavy methodology. For an engineer-grade flow with constitutions, dependency graphs, and cross-artifact analyzers, see GitHub's spec-kit. specdriven is the friendly cousin.

不是项目管理工具。不跟踪时间，不分配负责人，不设置日期。
不是设计工具。它记录的是“做什么”，而非UI外观。
不能替代你编码时的判断。功能卡片获得批准后，由你（Agent）选择实现方式。
不对技术栈做强制要求。路线图可以记录选择，但此技能不做规定。
不是重型方法论。如果需要面向工程师团队的包含章程、依赖图和跨文档分析的流程，请查看GitHub的spec-kit。specdriven是它的简化友好版。

Why these three phases (and only three)

为什么是这三个阶段（且只有三个）

GitHub's spec-kit ships seven phases (Constitution, Specify, Clarify, Plan, Tasks, Analyze, Implement). That's the right shape for engineering teams; it's too much friction for a hobbyist building a side project on Replit.

specdriven folds the seven into three:

spec-kit phase	specdriven home
Constitution	One paragraph inside Concept's "Ground rules"
Specify	Concept
Clarify	The 3–5 questions during Concept
Plan	Roadmap (with tech notes inline)
Tasks	Features (each card is a small task list)
Analyze	Done implicitly: every feature reads concept + roadmap
Implement	Build step at the end of each Feature card

Three phases is the smallest scaffold that still forces clarity. Anything fewer collapses back into vibe-coding.

GitHub的spec-kit包含七个阶段（Constitution、Specify、Clarify、Plan、Tasks、Analyze、Implement）。这对工程团队来说是合适的，但对于在Replit上做副业的爱好者来说，流程过于繁琐。

specdriven将七个阶段合并为三个：

spec-kit阶段	specdriven对应阶段
Constitution	Concept阶段的“基本原则”中的一段内容
Specify	Concept
Clarify	Concept阶段的3-5个澄清问题
Plan	Roadmap（包含内嵌的技术说明）
Tasks	Features（每个卡片本身就是一个小型任务列表）
Analyze	隐式完成：每个功能都会参考concept + roadmap
Implement	每个Feature卡片末尾的构建步骤

三个阶段是既能保证清晰度又最精简的框架。少于三个阶段会退回到凭感觉编码的状态。