spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec

Overview

概述

Help turn proposals into fully specified requirements through natural collaborative dialogue.

Start by reading the proposal's Capabilities section to know which spec files to create, then walk through each capability conversationally — asking questions one at a time to elicit behaviors, boundaries, error conditions, and edge cases. Once you have enough information for a capability, present the proposed requirements and scenarios for user approval, then write the spec file.

<HARD-GATE> Do NOT write any spec files until you have presented the proposed requirements and scenarios to the user and received approval for that capability. Use the appropriate tool for asking the user a question or requesting input to get this approval. This applies to EVERY capability regardless of perceived simplicity. </HARD-GATE>

帮助通过自然协作对话将提案转化为完整的规范化需求。

首先阅读提案的Capabilities部分，确定需要创建哪些规格文件，然后以对话方式逐一梳理每个功能——一次提出一个问题，以获取行为、边界、错误条件和边缘情况。当你收集到某个功能的足够信息后，提交拟议的需求和场景供用户批准，然后编写规格文件。

<HARD-GATE> 在向用户提交拟议的需求和场景并获得该功能的批准之前，不得编写任何规格文件。使用合适的工具向用户提问或请求输入以获得批准。无论功能看似多么简单，这一要求适用于所有功能。 </HARD-GATE>

Anti-Pattern: "The Design Will Figure It Out"

反模式：“设计阶段再解决”

Every capability needs its behavioral contract specified before design begins. Edge cases, error conditions, and boundaries that feel "obvious" are where misaligned assumptions cause the most rework. The spec can be short (a few scenarios for simple capabilities), but you MUST elicit them conversationally and get approval.

每个功能在开始设计前都需要明确其行为契约。那些看似“显而易见”的边缘情况、错误条件和边界，正是不一致假设导致大量返工的地方。规格可以很短（简单功能只需几个场景），但你必须通过对话方式获取这些信息并获得批准。

Checklist

检查清单

You MUST create a task for each of these items and complete them in order:

Read the proposal — identify the Capabilities section and the list of capabilities to spec. Skip if you just wrote the proposal in this session.
Survey related existing specs — before asking questions, scan any existing spec files in neighboring or overlapping capabilities. Identify: requirements this change might conflict with, behaviors already specified that this change depends on, and naming/terminology conventions to stay consistent with. For modified capabilities, locate the existing spec file now so you can copy its requirement blocks verbatim when writing the delta. Skip specs you already read earlier in this session.
For each capability — walk through the conversational requirement-discovery process: a. Ask clarifying questions — one at a time, understand behaviors, boundaries, error conditions, edge cases b. Present spec sections for approval — show the proposed requirements and scenarios, get user approval c. Write the spec file — using the Artifact Template below
Write deferred-to-design markers — for scenarios that depend on unresolved architectural choices

你必须为以下每一项创建任务并按顺序完成：

阅读提案 —— 找到Capabilities部分并确定需要制定规格的功能列表。如果本次会话中你刚写完提案，则可跳过此步骤。
调研相关现有规格 —— 在提问前，浏览相邻或重叠功能的所有现有规格文件。确定：此变更可能冲突的需求、此变更依赖的已指定行为，以及需要遵循的命名/术语约定。对于需要修改的功能，立即找到现有规格文件，以便在编写增量内容时逐字复制其需求块。如果本次会话中你已读过相关规格，则可跳过此步骤。
针对每个功能 —— 执行交互式需求探索流程： a. 提出澄清问题 —— 一次一个问题，明确行为、边界、错误条件和边缘情况 b. 提交规格部分供批准 —— 展示拟议的需求和场景，获得用户批准 c. 编写规格文件 —— 使用下方的Artifact Template模板
编写deferred-to-design标记 —— 针对依赖未解决架构选择的场景

Process Flow

流程示意图

dot

digraph spec {
    "Read proposal capabilities" [shape=box];
    "Survey existing specs" [shape=box];
    "Pick next capability" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Present spec sections" [shape=box];
    "User approves?" [shape=diamond];
    "Write spec file" [shape=box];
    "More capabilities?" [shape=diamond];
    "Done" [shape=box];

    "Read proposal capabilities" -> "Survey existing specs";
    "Survey existing specs" -> "Pick next capability";
    "Pick next capability" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Present spec sections";
    "Present spec sections" -> "User approves?";
    "User approves?" -> "Ask clarifying questions" [label="no, revise"];
    "User approves?" -> "Write spec file" [label="yes"];
    "Write spec file" -> "More capabilities?";
    "More capabilities?" -> "Pick next capability" [label="yes"];
    "More capabilities?" -> "Done" [label="no"];
}

dot

digraph spec {
    "Read proposal capabilities" [shape=box];
    "Survey existing specs" [shape=box];
    "Pick next capability" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Present spec sections" [shape=box];
    "User approves?" [shape=diamond];
    "Write spec file" [shape=box];
    "More capabilities?" [shape=diamond];
    "Done" [shape=box];

    "Read proposal capabilities" -> "Survey existing specs";
    "Survey existing specs" -> "Pick next capability";
    "Pick next capability" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Present spec sections";
    "Present spec sections" -> "User approves?";
    "User approves?" -> "Ask clarifying questions" [label="no, revise"];
    "User approves?" -> "Write spec file" [label="yes"];
    "Write spec file" -> "More capabilities?";
    "More capabilities?" -> "Pick next capability" [label="yes"];
    "More capabilities?" -> "Done" [label="no"];
}

The Process

详细流程

Reading the proposal:

If the proposal was written earlier in this session, skip re-reading unless exact wording needs verification
Otherwise, open the proposal's Capabilities section
Use the capability names to determine which spec files to create (one per capability)
Work through capabilities one at a time

Asking clarifying questions:

Follow the
```
codagent:ask-questions
```
skill for how to ask questions (tool to use, batching strategy, question quality)
Focus on: what the system does (behaviors), what it rejects (boundaries), what goes wrong (error conditions), unusual situations (edge cases)
Prefer multiple-choice questions when possible, but open-ended is fine too
Do NOT ask about architecture, patterns, or technical approach — that belongs in design
Ask at least one targeted discovery question for each capability after surveying related specs, unless the proposal and existing specs already answer every behavior, boundary, error condition, and edge case needed for a testable spec. If you skip questions, state the concrete source that answered them.
Do NOT treat "does this spec look right?" as the clarifying question. Approval happens only after discovery questions are resolved.

When a requirement depends on architectural knowledge:

Acknowledge the dependency explicitly
Ask a best-effort question to capture as much as is knowable without the architecture
Mark the scenario with
```

```
— the design skill will complete or revise it
A spec file with deferred scenarios is still considered complete and unblocks design

Presenting for approval:

Once you have enough for a capability, present the full set of proposed requirements and scenarios
Use the appropriate tool for asking the user a question or requesting input to ask whether it looks right before writing the file
Be ready to go back and revise if something doesn't look right

Writing spec files:

Write each spec file using the Artifact Template below
Every requirement MUST have at least one scenario

阅读提案：

如果提案是在本次会话早期编写的，除非需要验证确切措辞，否则可跳过重读
否则，打开提案的Capabilities部分
根据功能名称确定需要创建的规格文件（每个功能对应一个文件）
逐一处理每个功能

提出澄清问题：

遵循
```
codagent:ask-questions
```
技能的指导来提问（工具选择、批量策略、问题质量）
重点关注：系统的行为（做什么）、拒绝的内容（边界）、可能出现的错误（错误条件）、异常情况（边缘情况）
尽可能优先使用选择题，但开放式问题也可接受
不得询问架构、模式或技术实现方式——这些属于设计阶段的内容
在调研相关规格后，必须为每个功能至少提出一个针对性的探索问题，除非提案和现有规格已回答了可测试规格所需的所有行为、边界、错误条件和边缘情况。如果跳过提问，请说明提供答案的具体来源。
不得将“这个规格看起来对吗？”作为澄清问题。只有在解决探索问题后才能进行批准环节。

当需求依赖架构知识时：

明确承认该依赖关系
提出一个尽力而为的问题，以在没有架构信息的情况下捕获尽可能多的内容
使用
```

```
标记该场景——设计技能将在获得架构上下文后完成或修改它
带有延迟场景的规格文件仍被视为完整，不会阻碍设计工作

提交供批准：

当收集到某个功能的足够信息后，提交完整的拟议需求和场景
使用合适的工具向用户提问或请求输入，询问内容是否正确，然后再编写文件
准备好如果内容不合适就返回修改

编写规格文件：

使用下方的Artifact Template模板编写每个规格文件
每个需求必须至少包含一个场景

Deferred-to-Design Scenarios

延迟至设计阶段的场景

When a scenario's behavior depends on an unresolved architectural decision, write the scenario with a best-effort condition and outcome, and add a

<!-- deferred-to-design: <reason> -->

comment explaining what architectural decision is needed to complete it.

The design skill reads all spec files before starting and will complete or revise these scenarios when it has the architectural context.

当场景行为依赖未解决的架构决策时，编写场景时采用尽力而为的条件和结果，并添加

<!-- deferred-to-design: <reason> -->

注释，说明完成该场景所需的架构决策。

设计技能在开始工作前会读取所有规格文件，并在获得架构上下文后完成或修改这些场景。

After All Capabilities Are Specced

所有功能完成规格制定后

Tell the user the relative path of each spec file created. This skill does not invoke other skills or manage sequencing.

告知用户每个已创建规格文件的相对路径。本技能不会调用其他技能或管理流程顺序。

Key Principles

核心原则

Use
codagent:ask-questions
— For tool choice and batching strategy when gathering information
Questions before spec text — Ask specific behavior, boundary, error-condition, and edge-case questions before presenting proposed requirements and scenarios
Multiple choice preferred — Easier to answer than open-ended when possible
Focus on "what", not "how" — Behaviors, boundaries, and error conditions — not architecture
Deferred is valid — A deferred-to-design marker is better than a forced answer
Incremental validation — Present spec for each capability, get approval before writing
Be flexible — Go back and revise when something doesn't look right

使用
codagent:ask-questions
—— 收集信息时遵循工具选择和批量策略
先提问再写规格文本 —— 在提交拟议需求和场景前，先提出关于行为、边界、错误条件和边缘情况的具体问题
优先选择选择题 —— 比开放式问题更容易回答
关注“是什么”而非“怎么做” —— 聚焦行为、边界和错误条件，而非架构
延迟标记是有效的 —— 延迟至设计阶段的标记强于强行给出答案
增量验证 —— 为每个功能提交规格，获得批准后再编写文件
保持灵活 —— 当内容不合适时返回修改

Never

禁止事项

Never present a full spec delta or ask for approval before asking the appropriate capability-specific discovery questions.
Never infer exact behavior from a rough proposal when a user answer would materially change requirements or scenarios.
Never use the approval gate as a substitute for clarifying behaviors, boundaries, error conditions, or edge cases.

不得在提出合适的功能探索问题前提交完整的规格增量内容或请求批准。
当用户的回答会实质性改变需求或场景时，不得从粗略的提案中推断确切行为。
不得用批准环节替代对行为、边界、错误条件或边缘情况的澄清。

Artifact Template

工件模板

Use this structure when writing spec files. Create one spec file per capability listed in the proposal's Capabilities section.

New capabilities: use the exact kebab-case name from the proposal (
```
specs/<capability>/spec.md
```
).
Modified capabilities: use the existing spec folder name when creating the delta spec.

编写规格文件时使用此结构。为提案Capabilities部分列出的每个功能创建一个规格文件。

新功能：使用提案中的准确kebab-case名称（
```
specs/<capability>/spec.md
```
）。
修改功能：创建增量规格时使用现有规格文件夹名称。

Format rules

格式规则

Each requirement:
```
### Requirement: <name>
```
followed by description
Use SHALL/MUST for normative requirements (avoid should/may)
Each scenario:
```
#### Scenario: <name>
```
with WHEN/THEN format
Scenarios MUST use exactly 4 hashtags (
####
). Using 3 or bullets will break parsing.
Every requirement MUST have at least one scenario

每个需求：
```
### Requirement: <name>
```
后跟描述内容
使用SHALL/MUST表示规范性要求（避免使用should/may）
每个场景：
```
#### Scenario: <name>
```
采用WHEN/THEN格式
场景必须恰好使用4个井号（
####
）。使用3个井号或项目符号会导致解析失败。
每个需求必须至少包含一个场景

Abstraction level

抽象级别

Scenarios describe observable behavioral contracts — what the system does when invoked under specific conditions. Focus on orchestration behavior (dispatch, gating, error handling, control flow), NOT file contents or internal structure.

Write scenarios as behavioral contracts the capability guarantees to its callers:

GOOD: "WHEN subagent finds task ambiguous THEN it returns questions without implementing"
GOOD: "WHEN validator retry limit is exhausted THEN subagent returns failure to coordinator"
BAD: "WHEN SKILL.md is read THEN it contains TDD instructions"
BAD: "WHEN config file exists THEN it has the correct YAML keys"

场景描述可观察的行为契约——系统在特定条件下被调用时的行为。聚焦编排行为（调度、门控、错误处理、控制流），而非文件内容或内部结构。

将场景编写为功能向调用方保证的行为契约：

正确示例："WHEN subagent finds task ambiguous THEN it returns questions without implementing"
正确示例："WHEN validator retry limit is exhausted THEN subagent returns failure to coordinator"
错误示例："WHEN SKILL.md is read THEN it contains TDD instructions"
错误示例："WHEN config file exists THEN it has the correct YAML keys"

Delta operations

增量操作

Use

##

headers to categorize changes:

ADDED Requirements — New capabilities
MODIFIED Requirements — Changed behavior. MUST include full updated content.
REMOVED Requirements — Deprecated features. MUST include Reason and Migration.
RENAMED Requirements — Name changes only. Use FROM:/TO: format.

When modifying existing requirements: if a prior spec file exists, copy the ENTIRE requirement block (from

### Requirement:

through all scenarios), paste under

## MODIFIED Requirements

, and edit to reflect new behavior. Using MODIFIED with partial content loses detail. If no prior spec file exists, investigate the existing code to understand current behavior, then write the full modified requirement (including all scenarios) as it should be after the change. If adding new concerns without changing existing behavior, use ADDED instead.

使用

##

标题对变更进行分类：

ADDED Requirements —— 新功能
MODIFIED Requirements —— 行为变更。必须包含完整的更新内容。
REMOVED Requirements —— 已弃用功能。必须包含原因和迁移方案。
RENAMED Requirements —— 仅名称变更。使用FROM:/TO:格式。

修改现有需求时：如果存在先前的规格文件，复制整个需求块（从

### Requirement:

到所有场景），粘贴到

## MODIFIED Requirements

下，然后编辑以反映新行为。使用MODIFIED但仅提供部分内容会丢失细节。如果没有先前的规格文件，调研现有代码以了解当前行为，然后编写完整的修改后需求（包括所有场景），即变更后的预期状态。如果添加新内容但不修改现有行为，请使用ADDED。

Template

模板

markdown

undefined

markdown

undefined

ADDED Requirements

Requirement:

Scenario:

WHEN
THEN

undefined

WHEN
THEN

undefined