spec-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SDD Spec Writer

SDD Spec 编写器

When to Use

使用场景

Use this skill when you need to:

Create a new
```
*.spec.md
```
file from a feature request, bug report, or product idea.
Rewrite a vague spec into a precise, verifiable, agent-operable document.
Extract a spec from existing code, tests, routes, or workflows.
Add acceptance criteria, guardrails, or traceable requirements before implementation starts.
Normalize specification files so coding agents can implement them with less ambiguity.

当你需要以下操作时，可使用本技能：

根据功能需求、Bug报告或产品创意创建新的
```
*.spec.md
```
文件。
将模糊的规范重写为精确、可验证、可供Agent执行的文档。
从现有代码、测试、路由或工作流中提取规范。
在开发开始前添加验收标准、约束规则或可追溯的需求。
规范化规范文件，减少编码Agent实现时的歧义。

Goal

目标

Produce a single

*.spec.md

file that is clear, bounded, verifiable, and directly usable by coding agents.

The spec must behave like an execution contract:

It defines the intended outcome.
It limits scope and unsafe changes.
It makes verification explicit.
It gives agents enough context to act without guessing.

生成单个清晰、边界明确、可验证且可直接供编码Agent使用的

*.spec.md

文件。

该规范需具备执行契约的特性：

定义预期结果。
限制范围和不安全变更。
明确验证方式。
为Agent提供足够上下文，无需猜测即可执行操作。

Critical Patterns

关键模式

1. Separate intent from implementation detail

1. 区分意图与实现细节

Write the spec around observable behavior and constraints first. Add implementation notes only when they are necessary to avoid wrong architectural choices.

首先围绕可观察的行为和约束编写规范。仅当需要避免错误架构选择时，才添加实现说明。

2. Prefer one requirement per behavior

2. 每个行为对应一项需求

Each requirement must describe one behavior only. Do not combine multiple independent behaviors into a single requirement.

每项需求仅描述一种行为。请勿将多个独立行为合并到同一项需求中。

3. Make every requirement testable

3. 确保每项需求可测试

Use stable IDs and write requirements in a way that can be verified:

REQ-<DOMAIN>-<NNN>

: The system must or must not

<behavior>

when

<condition>

so that

<user or business outcome>

Good example:

REQ-AUTH-001

: The system must reject a login attempt after 5 consecutive failures from the same IP within 15 minutes and return HTTP 429.

Bad example:

REQ-AUTH-001

: The login should feel secure and robust.

使用稳定ID，并以可验证的方式编写需求：

REQ-<领域>-<序号>

：当<条件>时，系统必须/不得<执行行为>，以实现<用户或业务目标>。

正面示例：

REQ-AUTH-001

：同一IP在15分钟内连续5次登录失败后，系统必须拒绝后续登录尝试并返回HTTP 429状态码。

反面示例：

REQ-AUTH-001

：登录功能应安全且可靠。

4. Acceptance criteria must be observable

4. 验收标准必须可观察

Use

Given / When / Then

for main flows and edge cases.

Example:

Given an authenticated admin user
When the user opens
```
/admin/users
```
Then the system must render the users table with at least one row and show edit and delete actions

主流程和边缘场景使用

Given / When / Then

格式。

示例：

Given 已认证的管理员用户
When 用户打开
```
/admin/users
```
页面
Then 系统必须渲染至少包含一行数据的用户表格，并显示编辑和删除操作按钮

5. Define boundaries explicitly

5. 明确定义边界

Every spec must include three guardrail groups:

```
Always allowed
```
```
Ask before
```
```
Never do
```

This reduces unsafe or out-of-scope implementation by coding agents.

每个规范必须包含三组约束规则：

```
Always allowed
```
（始终允许）
```
Ask before
```
（执行前需询问）
```
Never do
```
（禁止操作）

这可减少编码Agent执行不安全或超出范围的实现。

6. State scope with inclusions and exclusions

6. 通过包含和排除说明范围

Every spec must say what is in scope and what is out of scope. If this is missing, agents will infer and overreach.

每个规范必须明确说明哪些内容在范围内，哪些在范围外。若缺失此部分，Agent会自行推断并超出范围。

7. Make verification part of the contract

7. 将验证作为契约的一部分

The spec must say how completion will be validated:

unit tests
integration tests
manual checks
performance or security checks
files or commands expected to change or run

规范必须说明如何验证完成情况：

单元测试
集成测试
人工检查
性能或安全检查
预期会变更或运行的文件/命令

8. Ask for clarification only when ambiguity blocks correctness

8. 仅当歧义影响正确性时才请求澄清

If a missing detail changes behavior, data model, public contracts, or scope, pause and ask. If the missing detail is editorial and a safe default exists, proceed and document the assumption in

Open Questions / Assumptions

若缺失的细节会改变行为、数据模型、公共契约或范围，请暂停并询问。若缺失的细节仅为编辑性内容且存在安全默认值，则继续执行并在

Open Questions / Assumptions

（未解决问题/假设）中记录假设。

Operating Workflow

操作流程

Step 1. Gather inputs

步骤1：收集输入

Collect as much as possible from the user request and repository context:

feature or problem statement
target users or actors
expected outcome
constraints or dependencies
relevant code paths if the spec comes from existing code

If the request is too vague, ask only for the missing information that changes the resulting behavior.

从用户请求和仓库上下文收集尽可能多的信息：

功能或问题描述
目标用户或角色
预期结果
约束或依赖
若规范源自现有代码，需相关代码路径

若请求过于模糊，仅询问会影响最终行为的缺失信息。

Step 2. Inspect before writing

步骤2：编写前检查

If code already exists, inspect the current implementation in read mode first and infer:

current behavior
impacted modules
hidden constraints
terminology already used by the project

Do not invent architecture that conflicts with the repository.

若已有代码，先以只读模式检查当前实现并推断：

当前行为
受影响的模块
隐藏约束
项目已使用的术语

请勿创建与仓库冲突的架构。

Step 3. Write the spec using the required structure

步骤3：使用要求的结构编写规范

Always create the output as

<feature-name>.spec.md

Use the exact section order below unless the user explicitly asks for a different format.

始终将输出创建为

<feature-name>.spec.md

。

除非用户明确要求其他格式，否则严格按照以下章节顺序编写。

Required

*.spec.md

Structure

要求的

*.spec.md

结构

markdown

undefined

markdown

undefined

<Feature or Change Title>

<功能或变更标题>

Metadata

元数据

Spec ID: SPEC-<DOMAIN>-<NNN>
Status: draft | approved | implemented
Owner: <team or person>
Last Updated: YYYY-MM-DD
Related Paths: <files, directories, routes, services>

Spec ID: SPEC-<领域>-<序号>
状态: draft（草稿）| approved（已批准）| implemented（已实现）
负责人: <团队或个人>
最后更新时间: YYYY-MM-DD
相关路径: <文件、目录、路由、服务>

Objective

目标

<一段简短的描述，说明业务或用户目标>

Context

背景

<相关背景、当前行为或仓库事实>

In Scope

范围内

<explicit inclusion>

<明确包含的内容>

Out of Scope

范围外

<explicit exclusion>

<明确排除的内容>

Actors

角色

<actor>: <role in the flow>

<角色>: <在流程中的作用>

Functional Requirements

功能需求

REQ-<DOMAIN>-001

REQ-<领域>-001

Acceptance Criteria

Given <state>
When <action>
Then <observable result>

<可验证的需求描述>

验收标准

Given <状态>
When <操作>
Then <可观察的结果>

REQ-<DOMAIN>-002

REQ-<领域>-002

Acceptance Criteria

Given <state>
When <action>
Then <observable result>

<下一项需求>

验收标准

Given <状态>
When <操作>
Then <可观察的结果>

Non-Functional Requirements

非功能需求

NFR-<DOMAIN>-001: <performance, security, availability, observability, accessibility, etc.>

NFR-<领域>-001: <性能、安全、可用性、可观测性、可访问性等>

Constraints and Dependencies

约束与依赖

<technical constraint>
<external dependency>

<技术约束>
<外部依赖>

Guardrails

约束规则

Always Allowed

始终允许

<safe changes an agent may make>

<Agent可执行的安全变更>

Ask Before

执行前需询问

<changes that require user confirmation>

<需要用户确认的变更>

Never Do

禁止操作

<forbidden changes>

<禁止的变更>

Relevant Components

Verification Plan

验证计划

<tests to add or update>
<manual validation steps>
<commands or checks>

<需添加或更新的测试>
<人工验证步骤>
<命令或检查项>

Definition of Done

完成定义

<condition that must be true at completion>

<完成时必须满足的条件>

Open Questions / Assumptions

未解决问题/假设

<question or explicit assumption>

undefined

<问题或明确的假设>

undefined

Writing Rules

编写规则

Write documentation in English.
Use short, direct sentences and active voice.
Keep terminology consistent through the whole document.
Prefer concrete numbers over vague adjectives.
Do not mix requirements, design rationale, and task sequencing in the same bullet unless the user explicitly asks for that.
Do not leave hidden scope. If something is excluded, say it explicitly.
Do not use filler such as "user-friendly", "robust", or "fast" without measurable meaning.
Do not create requirements without a trigger, behavior, and outcome.

文档使用英文编写。
使用简短、直接的句子和主动语态。
保持整个文档的术语一致。
优先使用具体数字而非模糊形容词。
除非用户明确要求，否则请勿在同一条目中混合需求、设计理由和任务顺序。
请勿隐藏范围。若某项内容被排除，请明确说明。
请勿使用无衡量标准的填充词，如“用户友好”“健壮”“快速”等。
请勿创建无触发条件、行为和结果的需求。

Agent-Operable Quality Bar

Agent可执行质量标准

Before finalizing a spec, verify that it answers these questions:

What exactly is being changed?
What must the system do?
What must the system not do?
What files, modules, routes, or services are likely involved?
What constraints limit the implementation?
How will success be verified?
What requires confirmation before implementation?

If one of these is missing, the spec is not ready.

在最终确定规范前，需验证其是否回答了以下问题：

具体要变更什么？
系统必须做什么？
系统必须不能做什么？
可能涉及哪些文件、模块、路由或服务？
哪些约束限制了实现？
如何验证成功？
哪些内容在实现前需要确认？

若其中任何一项缺失，则规范未准备就绪。

Default Output Behavior

默认输出行为

When the user asks for a spec and does not specify a filename:

derive a kebab-case feature name
create
```
<feature-name>.spec.md
```
use stable IDs inside the file
keep placeholders only where facts are truly unknown

当用户请求规范但未指定文件名时：

推导一个短横线分隔（kebab-case）的功能名称
创建
```
<feature-name>.spec.md
```
文件
在文件中使用稳定ID
仅在事实确实未知时保留占位符

Files to Read

需读取的文件

```
assets/spec-template.md
```
: reusable writing template for
```
*.spec.md
```
```
references/writing-principles.md
```
: condensed rules derived from the repository's SDD writing guide

```
assets/spec-template.md
```
: 可复用的
```
*.spec.md
```
编写模板
```
references/writing-principles.md
```
: 从仓库SDD编写指南提炼的浓缩规则

Example Prompts

示例提示

Example 1:

Input:

Create a spec for bulk user import with CSV validation and duplicate detection.

Output:

Creates
```
bulk-user-import.spec.md
```
Defines scope, actors, REQ and NFR sections, guardrails, and verification plan

Example 2: