Back to Details

spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/spec

/spec

Manage protocol-level specifications - the contract defining what a system must do.
管理协议级规范——定义系统必须实现内容的契约。

What is a Spec?

什么是Spec？

A spec (specification) defines requirements at the protocol/standard level:
  • External specs: Standards you implement (LEAF spec, OAuth, OpenAPI)
  • Self-authored specs: Your own protocol defining what your system does
Specs are NOT feature breakdowns or epics. They are the source of truth for requirements.
spec（规范） 在协议/标准层面定义要求：
  • 外部规范：需实现的标准（LEAF spec、OAuth、OpenAPI）
  • 自定义规范：由你方定义的、描述系统功能的协议
Spec并非功能分解或史诗级需求，而是需求的唯一可信来源。

Usage

使用方法

bash
/spec                           # Show current project's spec status
/spec --import <url>            # Import external spec (GitHub, raw URL)
/spec --init                    # Create new protocol spec for project
/spec --sync                    # Sync imported spec with upstream
/spec --section <name>          # Show specific section of spec
bash
/spec                           # 显示当前项目的spec状态
/spec --import <url>            # 导入外部spec（GitHub、原始URL）
/spec --init                    # 为项目创建新的协议spec
/spec --sync                    # 与上游同步已导入的spec
/spec --section <name>          # 显示spec的特定章节

File Structure

文件结构

spaces/[project]/
├── docs/
│   ├── specs/                  # The protocol spec (source of truth)
│   │   ├── README.md           # Spec overview and compliance status
│   │   ├── api-specification.md # API contract
│   │   ├── data-models.md      # Data structures
│   │   ├── required-features.md # Feature requirements
│   │   └── ...
│   └── adrs/                   # Architecture decisions
└── src/                        # Implementation

ideas/[project]/
├── project-brief.md            # Strategy (private)
└── issues/
    └── 001-auth/
        └── TASK.md             # implements: docs/specs/required-features.md#authentication
Why specs live with code:
  • Specs are the contract the code fulfills
  • Developers need them alongside implementation
  • Changes to spec and code can be atomic commits
  • All documentation (specs, ADRs) lives together in docs/
spaces/[project]/
├── docs/
│   ├── specs/                  # 协议spec（唯一可信来源）
│   │   ├── README.md           # spec概述与合规状态
│   │   ├── api-specification.md # API契约
│   │   ├── data-models.md      # 数据结构
│   │   ├── required-features.md # 功能需求
│   │   └── ...
│   └── adrs/                   # 架构决策记录
└── src/                        # 实现代码

ideas/[project]/
├── project-brief.md            # 策略文档（私有）
└── issues/
    └── 001-auth/
        └── TASK.md             # implements: docs/specs/required-features.md#authentication
Spec与代码共存的原因：
  • Spec是代码需满足的契约
  • 开发者需要在实现时随时参考Spec
  • Spec与代码的变更可作为原子提交
  • 所有文档（Spec、ADR）统一存放在docs/目录下

Execution Flow

执行流程

1. Determine Context

1. 确定上下文

bash
Read: ideas/[project]/project-brief.md    # Strategy context
Glob: spaces/[project]/docs/specs/*.md    # Existing specs
Questions:
  • Does this project implement an external spec?
  • Or does it need its own protocol spec?
bash
Read: ideas/[project]/project-brief.md    # 策略上下文
Glob: spaces/[project]/docs/specs/*.md    # 现有spec
需明确的问题：
  • 该项目是否需要实现外部spec？
  • 还是需要自定义专属的协议spec？

2a. Import External Spec

2a. 导入外部Spec

For projects implementing a standard (like leaf-nextjs-convex → LEAF spec):
bash
/spec --import https://github.com/leafspec/spec
Process:
  1. Clone/fetch spec files
  2. Copy to 
    spaces/[project]/docs/specs/
  3. Create 
    docs/specs/README.md
    with:
    • Source URL and version
    • Last synced date
    • Compliance checklist
  4. Suggest initial TASKs based on spec sections
Sync upstream changes:
bash
/spec --sync
对于需实现标准的项目（如leaf-nextjs-convex → LEAF spec）：
bash
/spec --import https://github.com/leafspec/spec
流程：
  1. 克隆/拉取spec文件
  2. 复制到
    spaces/[project]/docs/specs/
    目录
  3. 创建
    docs/specs/README.md
    ，包含：
    • 源URL与版本
    • 最后同步日期
    • 合规性检查清单
  4. 根据spec章节建议初始TASK
同步上游变更：
bash
/spec --sync

2b. Create Protocol Spec

2b. 创建协议Spec

For projects that need their own spec (like coordinatr):
bash
/spec --init
Conversational creation:
  1. What does this system do? (elevator pitch)
  2. Who are the actors/users?
  3. What are the core operations?
  4. What are the API boundaries?
  5. What are the data models?
Output structure:
markdown
undefined
对于需要自定义spec的项目（如coordinatr）：
bash
/spec --init
交互式创建流程：
  1. 该系统的功能是什么？（电梯演讲式描述）
  2. 参与者/用户有哪些？
  3. 核心操作包含哪些？
  4. API边界如何定义？
  5. 数据模型是什么？
输出结构：
markdown
undefined

[Project] Specification

[项目名称] 规范

Overview

概述

[What this system does and why]
[该系统的功能与存在价值]

Actors

参与者

[Who/what interacts with the system]
[与系统交互的对象/角色]

Core Operations

核心操作

[The fundamental things the system must do]
[系统必须实现的基础功能]

API Specification

API规范

[Endpoints, inputs, outputs, errors]
[接口、输入、输出、错误处理]

Data Models

数据模型

[Entity definitions, relationships, constraints]
[实体定义、关系、约束]

Required Features

必备功能

[Feature requirements organized by domain]
[按领域划分的功能需求]

Test Criteria

测试标准

[How to verify compliance]
undefined
[如何验证合规性]
undefined

3. Spec Status Dashboard

3. Spec状态仪表盘

bash
/spec  # No arguments
Shows:
  • Spec source (external URL or self-authored)
  • Last updated/synced
  • Sections and their implementation status
  • Linked TASKs per section
bash
/spec  # 不带参数
显示内容：
  • Spec来源（外部URL或自定义）
  • 最后更新/同步时间
  • 各章节及其实现状态
  • 每个章节关联的TASK

Spec vs Old "Feature Specs"

Spec与旧版“功能Spec”的对比

Old Model (Wrong)New Model (Correct)
SPEC-001, SPEC-002...Single protocol spec
Feature breakdownRequirements contract
Internal planning docsSource of truth
Created per featureCreated once, evolved
TASKs link to SPEC-###TASKs implement spec sections
旧模型（错误方式）新模型（正确方式）
SPEC-001、SPEC-002...单一协议spec
功能分解需求契约
内部规划文档唯一可信来源
按功能创建一次性创建，逐步演进
TASK关联到SPEC-###TASK实现spec章节

Integration with /issue

与/issue命令的集成

When creating a TASK, link to the spec section it implements:
yaml
---
implements: docs/specs/required-features.md#authentication
---
The 
/issue
command will prompt:
"Which spec section does this implement? (or 'none' for standalone)"
创建TASK时，需关联其实现的spec章节：
yaml
---
implements: docs/specs/required-features.md#authentication
---
执行
/issue
命令时会提示：
“该任务实现哪个spec章节？（若为独立任务请输入'none'）”

Compliance Tracking

合规性跟踪

Status is tracked inline within spec documents at the requirement level:
markdown
undefined
状态在spec文档内内嵌跟踪，精确到需求级别：
markdown
undefined

§1 Authentication

§1 认证

Requirements:
  • ✅ User registration with email/password
  • ✅ User login with JWT token
  • ⏳ Password reset flow
  • ⏳ Email verification
API Endpoints:
  • ✅ 
    POST /api/auth/register
  • ✅ 
    POST /api/auth/login
  • ⏳ 
    POST /api/auth/reset-password

**Status markers:**
- ✅ Implemented and working
- 🚧 In progress
- ⏳ Not started

This allows granular visibility into what's done without referencing private TASKs.

The `/complete` command updates these markers when work is finished.
需求：
  • ✅ 邮箱/密码用户注册
  • ✅ JWT令牌用户登录
  • ⏳ 密码重置流程
  • ⏳ 邮箱验证
API接口：
  • ✅ 
    POST /api/auth/register
  • ✅ 
    POST /api/auth/login
  • ⏳ 
    POST /api/auth/reset-password

**状态标记：**
- ✅ 已实现且可用
- 🚧 开发中
- ⏳ 未启动

这种方式无需参考私有TASK，即可清晰查看已完成的内容。

当工作完成时，`/complete`命令会更新这些标记。

Self-Authored Spec Guidelines

自定义Spec指南

When creating your own protocol spec:
  1. Be specific - Vague specs lead to vague implementations
  2. Define boundaries - What's in scope vs out of scope
  3. Include test criteria - How do you verify compliance?
  4. Version it - Specs evolve; track changes
  5. Keep it stable - Changes should be deliberate
创建专属协议spec时需遵循：
  1. 具体明确 - 模糊的spec会导致模糊的实现
  2. 定义边界 - 明确范围与非范围
  3. 包含测试标准 - 如何验证合规性？
  4. 版本化 - Spec会演进，需跟踪变更
  5. 保持稳定 - 变更需经过审慎考虑

Spec Versioning (differs from ADRs)

Spec版本控制（与ADR不同）

ADRs are immutable - changes create a new superseding document.
Specs are edited in place - they're living contracts that evolve:
  1. Frontmatter version - Use semantic versioning (
    version: 1.0.0
    )
  2. Git history - Preserves full evolution
  3. Git tags - Mark release points (
    git tag spec-v1.0.0
    )
  4. CHANGELOG - Note significant spec changes
Version bumps:
  • Patch (1.0.1): Typos, clarifications, no behavior change
  • Minor (1.1.0): New optional features, backwards compatible
  • Major (2.0.0): Breaking changes, removed requirements
This keeps specs simple while git provides the audit trail.
ADR是不可变的 - 变更会创建新的替代文档。
Spec可原地编辑 - 它们是不断演进的活契约：
  1. 前置元数据版本 - 使用语义化版本（
    version: 1.0.0
    ）
  2. Git历史 - 完整保留演进过程
  3. Git标签 - 标记发布节点（
    git tag spec-v1.0.0
    ）
  4. CHANGELOG - 记录重大spec变更
版本升级规则：
  • 补丁版本（1.0.1）：错别字修正、说明补充，无行为变更
  • 次要版本（1.1.0）：新增可选功能，保持向后兼容
  • 主要版本（2.0.0）：破坏性变更、移除需求
这种方式让spec保持简洁，同时Git提供完整的审计轨迹。

Workflow

工作流

/spec --init or --import    # Define what to build
        ↓
/issue                      # Create work items that implement spec sections
        ↓
/plan                       # Break down implementation
        ↓
/implement                  # Build against the spec
        ↓
/complete                   # Verify spec compliance
/spec --init 或 --import    # 定义需实现的内容
        ↓
/issue                      # 创建实现spec章节的工作项
        ↓
/plan                       # 分解实现任务
        ↓
/implement                  # 基于spec进行开发
        ↓
/complete                   # 验证spec合规性

Related Commands

相关命令

  • /issue
    - Create TASKs that implement spec sections
  • /plan
    - Break down implementation of a TASK
  • /validate-spec
    - Check implementation against spec
  • /project-status
    - See spec compliance overview
  • /issue
    - 创建实现spec章节的TASK
  • /plan
    - 分解TASK的实现细节
  • /validate-spec
    - 检查实现是否符合spec要求
  • /project-status
    - 查看spec合规性概览