write-specs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Specs

编写规格说明书

Specification

规范

The words

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

, and

OPTIONAL

are interpreted as described in RFC 2119.

术语

MUST

、

MUST NOT

、

REQUIRED

、

SHALL

、

SHALL NOT

、

SHOULD

、

SHOULD NOT

、

RECOMMENDED

、

MAY

和

OPTIONAL

的释义遵循 RFC 2119 中的描述。

Purpose

目的

Use this skill to turn loose project intent into a specification that implementors can build against and reviewers can validate. Prefer explicit contracts over narrative explanation. Make hidden decisions visible.

使用本技能将模糊的项目意图转化为可供开发者落地实现、评审者验证的规格说明书。优先采用明确契约而非叙事性说明，将隐藏的决策显性化。

Core Workflow

核心工作流

Ground the spec in available evidence.
- Read any linked docs, code, issues, PRs, diagrams, user notes, or product context before drafting.
- Separate confirmed facts from assumptions.
- Mark unresolved decisions as open questions only when they materially affect implementation.
Define the contract before the design details.
- State purpose, status, audience, and scope.
- If the spec uses
```
MUST
```
  ,
```
MUST NOT
```
  ,
```
REQUIRED
```
  ,
```
SHALL
```
  ,
```
SHALL NOT
```
  ,
```
SHOULD
```
  ,
```
SHOULD NOT
```
  ,
```
RECOMMENDED
```
  ,
```
MAY
```
  , or
```
OPTIONAL
```
  , use those key words only with their RFC 2119 meanings.
- Include a
```
Specification
```
  section in the resulting spec that explicitly states that these words are interpreted as described in RFC 2119.
- Clarify what is implementation-defined and require implementations to document those choices.
Establish boundaries.
- Write a problem statement that names the operational or user problems being solved.
- List goals and non-goals.
- Identify responsibility boundaries: what this system owns, what external systems own, and what humans or operators own.
Name the system shape.
- Define main components and their responsibilities.
- Define abstraction layers when useful, such as policy, configuration, coordination, execution, integration, storage, UI, and observability.
- Name external dependencies and required environment assumptions.
Specify the domain model.
- List entities with field names, types, nullability, defaults, and stable identifiers.
- Define normalization rules, derived values, ordering rules, uniqueness constraints, and path or naming constraints.
- State which identifier is used for logs, storage, API calls, UI display, and internal maps.
Specify configuration and repository contracts.
- Define config file discovery, parsing rules, schema, defaults, validation, environment-variable resolution, and unknown-key behavior.
- State whether config changes apply dynamically or require restart.
- Define behavior for invalid, missing, or partially valid config.
Specify lifecycle and state.
- Define state machines or lifecycle phases for important entities.
- List transition triggers, guards, side effects, retries, terminal states, and recovery behavior.
- Distinguish external state from internal runtime state.
Specify workflows and algorithms.
- Describe important flows in deterministic order.
- Include pseudocode only where sequencing, concurrency, retry, locking, or recovery would otherwise stay ambiguous.
- Define sorting, dispatch, batching, deduplication, idempotency, timeout, cancellation, and backoff behavior when relevant.
Specify failure behavior.
- List failure modes by operation.
- Define whether each failure aborts, retries, degrades, preserves last-known-good state, surfaces to operators, or requires manual intervention.
- Include cleanup behavior and what must remain durable after failure.
Specify safety and security invariants.
- State what must never happen.
- Define trust assumptions, permissions, sandboxing or approval posture, data retention, secret handling, and filesystem or network boundaries.
- Keep policy choices explicit when one universal answer is not appropriate.
Specify observability.
- Define required logs, metrics, events, traces, status surfaces, and operator-visible errors.
- Include stable field names for structured logs when possible.
- State what information must be available to debug a failed or partial run.
Specify compatibility and migration.
- Define backward-compatibility and forward-compatibility requirements for APIs, config, storage, file formats, user workflows, and operational behavior.
- Identify breaking changes, required migrations, rollout order, fallback behavior, downgrade behavior, and data retention or cleanup expectations.
- Mark compatibility or migration behavior as
```
Implementation-defined
```
  only when a single universal policy is not appropriate, and require implementations to document the selected policy.
Finish with validation.
- Provide conformance tests, acceptance criteria, smoke checks, and a definition of done.
- Split required core behavior from optional extension behavior.
- Include negative tests for invalid config, failures, retries, permissions, state transitions, compatibility boundaries, migrations, and boundary enforcement.

基于现有依据构建规格。
- 起草前阅读所有关联文档、代码、问题、PR、图表、用户笔记或产品上下文。
- 区分已确认事实与假设。
- 仅当未解决的决策会对落地实现产生实质性影响时，才将其标记为待解决问题。
先定义契约，再明确设计细节。
- 说明目的、状态、受众和范围。
- 若规格中使用
```
MUST
```
  、
```
MUST NOT
```
  、
```
REQUIRED
```
  、
```
SHALL
```
  、
```
SHALL NOT
```
  、
```
SHOULD
```
  、
```
SHOULD NOT
```
  、
```
RECOMMENDED
```
  、
```
MAY
```
  或
```
OPTIONAL
```
  ，这些术语必须严格遵循RFC 2119中的含义。
- 在最终规格中添加「规范」章节，明确说明这些术语的释义遵循RFC 2119。
- 明确哪些内容由实现方定义，并要求实现方记录这些选择。
明确边界。
- 撰写问题陈述，说明要解决的业务或用户问题。
- 列出目标与非目标。
- 明确责任边界：本系统负责的内容、外部系统负责的内容，以及人员或运维人员负责的内容。
定义系统形态。
- 定义核心组件及其职责。
- 必要时定义抽象层，如策略、配置、协调、执行、集成、存储、UI和可观测性层。
- 列出外部依赖项和所需的环境假设。
定义领域模型。
- 列出实体及其字段名、类型、可空性、默认值和稳定标识符。
- 定义规范化规则、派生值、排序规则、唯一性约束以及路径或命名约束。
- 指定用于日志、存储、API调用、UI展示和内部映射的标识符。
定义配置与仓库契约。
- 定义配置文件的发现、解析规则、schema、默认值、验证逻辑、环境变量解析方式以及未知键的处理行为。
- 说明配置变更是否动态生效，还是需要重启。
- 定义无效、缺失或部分有效配置的处理行为。
定义生命周期与状态。
- 为重要实体定义状态机或生命周期阶段。
- 列出状态转换的触发条件、守卫规则、副作用、重试机制、终端状态以及恢复行为。
- 区分外部状态与内部运行时状态。
定义工作流与算法。
- 按确定顺序描述重要流程。
- 仅当顺序、并发、重试、锁或恢复逻辑会存在歧义时，才添加伪代码。
- 相关时定义排序、调度、批处理、去重、幂等性、超时、取消和退避行为。
定义故障行为。
- 按操作类型列出故障模式。
- 定义每种故障是终止操作、重试、降级、保留最后已知有效状态、通知运维人员还是需要手动干预。
- 包含清理行为以及故障后必须保持持久化的内容。
定义安全与安保不变量。
- 说明绝对不允许发生的情况。
- 定义信任假设、权限、沙箱或审批机制、数据保留策略、密钥处理方式以及文件系统或网络边界。
- 当不存在通用解决方案时，明确列出策略选择。
定义可观测性。
- 定义所需的日志、指标、事件、追踪、状态展示以及运维可见的错误信息。
- 尽可能为结构化日志定义稳定字段名。
- 说明调试失败或部分成功运行时必须具备的信息。
定义兼容性与迁移。
- 定义API、配置、存储、文件格式、用户工作流和业务行为的向后兼容与向前兼容要求。
- 识别破坏性变更、所需的迁移操作、发布顺序、回退行为、降级行为以及数据保留或清理预期。
- 仅当不存在通用策略时，将兼容性或迁移行为标记为「Implementation-defined」，并要求实现方记录所选策略。
完成验证环节。
- 提供一致性测试、验收标准、冒烟测试以及完成定义。
- 区分必需的核心行为与可选的扩展行为。
- 包含针对无效配置、故障、重试、权限、状态转换、兼容性边界、迁移和边界约束的负面测试。

Spec Structure

规格结构

Use this default outline unless the project clearly needs another shape:

markdown

undefined

除非项目明确需要其他结构，否则使用以下默认大纲：

markdown

undefined

<Project or Feature> Specification

Status: Draft Audience: Implementors and reviewers Purpose: <one sentence>

Specification

The words

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

, and

OPTIONAL

are interpreted as described in RFC 2119.

The words

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

, and

OPTIONAL

are interpreted as described in RFC 2119.

1. Problem Statement

2. Goals and Non-Goals

3. System Overview

3.1 Main Components

3.2 Abstraction Layers

3.3 External Dependencies

4. Domain Model

5. Configuration and Contracts

6. Lifecycle and State

7. Core Workflows

8. Failure Handling

9. Safety and Security

10. Observability

11. Compatibility and Migration

12. Testing and Validation Matrix

13. Implementation Checklist

14. Open Questions


Remove sections that truly do not apply, but do not remove a section merely because the answer is inconvenient or still unknown. Use `Not applicable` with a short reason when omission would hide a design decision.


删除确实不适用的章节，但不能仅因为答案不便或未知就删除章节。如果省略会隐藏设计决策，请标注「Not applicable」并附上简短理由。

Detail Standard

细节标准

A concrete spec should answer these questions wherever relevant:

What is the exact input and output?
Who owns this behavior?
What names, identifiers, paths, states, or API fields are stable?
What defaults apply?
What is validated, when, and by whom?
What happens when data is missing, malformed, stale, duplicated, or unauthorized?
What happens on retry, restart, cancellation, timeout, and partial success?
What changes must remain compatible, and what migration or rollout path is required when they cannot?
What is logged or surfaced to an operator?
How can another implementor prove conformance?

一份具体的规格说明书应在相关场景下回答以下问题：

确切的输入和输出是什么？
谁负责该行为？
哪些名称、标识符、路径、状态或API字段是稳定的？
适用哪些默认值？
验证的内容、时机和执行者是什么？
当数据缺失、格式错误、过期、重复或未授权时会发生什么？
重试、重启、取消、超时和部分成功时会发生什么？
哪些变更必须保持兼容，当无法兼容时需要何种迁移或发布路径？
哪些信息会被记录或通知给运维人员？
其他实现方如何证明符合规格要求？

Writing Rules

编写规则

Use precise requirement language for behavior that must be testable.
Do not use RFC 2119 key words in all caps unless the statement is intended to be normative and testable.
Prefer tables or field lists for schemas, states, config keys, and errors.
Keep examples realistic and small.
Put policy choices in the spec instead of burying them in prose.
Preserve useful ambiguity only by labeling it
```
Implementation-defined
```
and requiring documentation.
Avoid implementation detail when it does not affect interoperability, safety, user-visible behavior, or validation.
End with concrete acceptance criteria, not a summary.

对可测试的行为使用精确的需求语言。
除非语句是规范性且可测试的，否则不要使用大写的RFC 2119术语。
优先使用表格或字段列表展示schema、状态、配置键和错误信息。
示例要真实且简洁。
将策略选择写入规格，而非隐藏在叙述性文字中。
仅通过标记为「Implementation-defined」并要求记录的方式保留必要的模糊性。
当内容不影响互操作性、安全性、用户可见行为或验证时，避免提及实现细节。
以具体的验收标准结尾，而非总结。

Output Modes

输出模式

When creating a spec artifact, write it to

SPEC.md

unless the user specifies another filename, path, or delivery format.

When the user asks for a full spec, produce the complete document.

When the user asks to prepare for a spec, produce:

the proposed outline,
the known contracts and decisions,
the missing decisions that block implementation,
the evidence still needed from code, docs, product, or operations.

When the user asks to review an existing spec, prioritize missing contracts, ambiguous behavior, untestable requirements, unsafe omissions, and places where goals conflict with lifecycle, failure, or validation sections.

创建规格文档时，除非用户指定其他文件名、路径或交付格式，否则写入

SPEC.md

。

当用户要求完整规格时，生成完整文档。

当用户要求准备规格时，生成以下内容：

建议的大纲，
已明确的契约和决策，
阻碍落地实现的待解决决策，
仍需从代码、文档、产品或运维环节获取的依据。

当用户要求评审现有规格时，优先关注缺失的契约、模糊的行为、不可测试的需求、不安全的遗漏以及目标与生命周期、故障处理或验证章节冲突的地方。