spec-driven-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ABOUTME: Spec-driven development framework for ecommerce project

ABOUTME: 面向电商项目的规范驱动开发框架

ABOUTME: Manages lifecycle: /spec.plan -> /spec.refine -> /spec.tasks -> /spec.run

ABOUTME: 管理生命周期：/spec.plan -> /spec.refine -> /spec.tasks -> /spec.run

Spec-Driven Development

规范驱动开发

Iterative feature development ensuring zero ambiguity before execution.

迭代式功能开发，确保执行前零歧义。

Quick Reference

快速参考

Command	Purpose
`/spec.plan <intent>`	Create spec from feature description
`/spec.refine [section]`	Improve spec with research
`/spec.clarify <response>`	Answer clarification questions
`/spec.tasks`	Break spec into executable tasks
`/spec.run [task#]`	Execute tasks with TDD

命令	用途
`/spec.plan <intent>`	根据功能描述创建规范
`/spec.refine [section]`	通过调研优化规范
`/spec.clarify <response>`	回答澄清问题
`/spec.tasks`	将规范拆解为可执行任务
`/spec.run [task#]`	采用TDD方式执行任务

Core Principle

核心原则

Iterate until clarity: No task execution begins until ALL questions are resolved. Claude must be able to execute without interruptions.

迭代直至清晰：在所有问题解决前，不得开始任何任务执行。Claude必须能够无中断地执行任务。

Phase 1:

/spec.plan

- Create Specification

阶段1:

/spec.plan

- 创建规范

Trigger:

/spec.plan <description>

or "I want to build/add X"

触发条件：

/spec.plan <description>

或语句"I want to build/add X"

Workflow

工作流程

Check
specs/
folder - create if missing
Generate spec file:
```
specs/{feature-slug}.md
```
Fill initial sections from user intent
Generate clarifying questions
STOP and present questions

检查
specs/
文件夹 - 若不存在则创建
生成规范文件：
```
specs/{feature-slug}.md
```
根据用户意图填充初始章节
生成澄清问题
停止操作并展示问题

Output

输出示例

Created: specs/feature-name.md (DRAFT)

Questions requiring clarification:
1. [Question about scope]
2. [Question about behavior]

Use /spec.clarify to answer.

已创建: specs/feature-name.md (草稿)

需要澄清的问题:
1. [关于范围的问题]
2. [关于行为的问题]

使用 /spec.clarify 命令回答。

Phase 2:

/spec.refine

- Research & Improve

阶段2:

/spec.refine

- 调研与优化

Trigger:

/spec.refine [section]

触发条件：

/spec.refine [section]

Workflow

工作流程

Load active DRAFT spec
Search codebase for similar patterns
Update Technical Strategy
Re-evaluate clarity
If questions remain: STOP and present

加载当前草稿规范
在代码库中搜索相似模式
更新技术策略
重新评估清晰度
若仍有问题：停止操作并展示

Phase 3:

/spec.clarify

- Answer Questions

阶段3:

/spec.clarify

- 回答问题

Trigger:

/spec.clarify <response>

触发条件：

/spec.clarify <response>

Example

示例

User: /spec.clarify Q1: OAuth2 with Google only. Q2: Admin can also delete.

Updated specs/auth-system.md:
- Added OAuth2/Google to Technical Strategy
- Updated permissions

Remaining questions: None
Spec ready. Use /spec.tasks

用户: /spec.clarify Q1: OAuth2 with Google only. Q2: Admin can also delete.

已更新 specs/auth-system.md:
- 在技术策略中添加OAuth2/Google
- 更新权限设置

剩余问题：无
规范已就绪。使用 /spec.tasks 命令。

Phase 4:

/spec.tasks

- Task Breakdown

阶段4:

/spec.tasks

- 任务拆解

Trigger:

/spec.tasks

触发条件：

/spec.tasks

Prerequisites

前置条件

Active spec must be DRAFT or APPROVED
"Open Questions" section must be empty
If questions exist: STOP → /spec.clarify

当前规范状态为草稿或已批准
“待澄清问题”章节必须为空
若存在问题：停止 → 执行/spec.clarify

Task Granularity

任务粒度

Tasks should be high-level logical units:

"Implement authentication middleware"
"Create user model and repository"
"Add API endpoints for user CRUD"

TDD cycle happens WITHIN each task during

/spec.run

任务应为高层级逻辑单元：

"实现认证中间件"
"创建用户模型与仓库"
"添加用户CRUD的API端点"

TDD周期在

/spec.run

执行期间，于每个任务内部完成。

Phase 5:

/spec.run

- Execute Tasks

阶段5:

/spec.run

- 执行任务

Trigger:

/spec.run [task#]

触发条件：

/spec.run [task#]

Prerequisites

前置条件

Task file must exist:
```
specs/{feature}.tasks.md
```
If no task file: STOP → /spec.tasks

任务文件必须存在：
```
specs/{feature}.tasks.md
```
若无任务文件：停止 → 执行/spec.tasks

Execution Rules

执行规则

TDD for each task: Red → Green → Refactor → Commit
Invoke language skills:
```
/typescript
```
for .ts files
Respect hooks: Pre-commit must pass
Mark completed in task file

每个任务采用TDD流程：红 → 绿 → 重构 → 提交
调用语言技能：针对.ts文件使用
```
/typescript
```
遵守钩子规则：必须通过预提交检查
在任务文件中标记已完成

File Structure

文件结构

specs/
├── README.md                   # Project config
├── user-wishlist.md            # Spec (APPROVED)
├── user-wishlist.tasks.md      # Task breakdown
├── payment-stripe.md           # Spec (DRAFT)
└── ...

specs/
├── README.md                   # 项目配置
├── user-wishlist.md            # 规范（已批准）
├── user-wishlist.tasks.md      # 任务拆解
├── payment-stripe.md           # 规范（草稿）
└── ...

Spec Status Flow

规范状态流转

DRAFT -> APPROVED -> IN_PROGRESS -> COMPLETED
          |              |
          v              v
      (questions?)   (blocked?)
          |              |
          v              v
        DRAFT      IN_PROGRESS

草稿 -> 已批准 -> 进行中 -> 已完成
          |              |
          v              v
      (存在问题?)   (被阻塞?)
          |              |
          v              v
        草稿        进行中

Ecommerce-Specific Scopes

电商特定模块范围

When creating specs, consider these modules:

Module	Files	Considerations
Auth	`apps/backend/src/modules/auth/`	JWT, sessions, rate limits
Catalog	`apps/backend/src/modules/catalog/`	Redis caching
Cart	Frontend hooks + Backend	Session persistence
Orders	`apps/backend/src/modules/orders/`	Transactions
Checkout	`apps/frontend/src/app/checkout/`	Payment flow

创建规范时，需考虑以下模块：

模块	文件路径	注意事项
认证	`apps/backend/src/modules/auth/`	JWT、会话、速率限制
商品目录	`apps/backend/src/modules/catalog/`	Redis缓存
购物车	前端钩子 + 后端	会话持久化
订单	`apps/backend/src/modules/orders/`	事务处理
结账	`apps/frontend/src/app/checkout/`	支付流程

Templates

模板

See

references/templates.md

for:

Spec file template
Task file template
specs/README.md template

查看

references/templates.md

获取：

规范文件模板
任务文件模板
specs/README.md模板

Session Resume

会话恢复

On context compaction:

Check
```
specs/
```
for files with status
```
IN_PROGRESS
```
Check
```
.tasks.md
```
files for unchecked items
Report: "Found in-progress spec: X with Y tasks remaining"
Ask: "Continue with /spec.run?"

当上下文压缩时：

检查
```
specs/
```
文件夹中状态为“进行中”的文件
检查
```
.tasks.md
```
文件中的未勾选项
报告：“发现进行中的规范：X，剩余Y个任务”
询问：“是否使用/spec.run继续？”