Back to Details

specification-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Specification Writing

技术规格编写

Follow writing-voice for prose sections.
A specification gives an agent (or human) the context they need to implement a feature autonomously. The goal is NOT to describe everything exhaustively; it's to provide enough initial context that the implementer can do their own research and make informed decisions.
Note: This guide uses 
[PLACEHOLDER]
markers for content you must fill in. Code blocks show templates; replace all bracketed content with your feature's details.
prose部分请遵循写作风格。
技术规格能为Agent（或人类）提供自主实现功能所需的上下文。其目标并非详尽描述所有内容，而是提供足够的初始背景，让实现者可以开展自主研究并做出明智决策。
注意：本指南使用
[PLACEHOLDER]
标记表示您必须填充的内容。代码块展示模板；请将所有带括号的内容替换为您的功能细节。

The Core Philosophy

核心理念

Specs should:
  • Provide context, not instructions: Give the "why" and "what", let the implementer figure out "how"
  • Document research, not conclusions: Show what was explored, what exists, what doesn't
  • Leave questions open: The Open Questions section is a feature, not a bug
  • Enable autonomous implementation: An agent reading this should spawn sub-agents to verify and extend
A good spec is a launching pad, not a script to follow.
技术规格应做到：
  • 提供上下文，而非指令：说明“原因”和“内容”，让实现者自行探索“方法”
  • 记录研究过程，而非结论：展示已探索的内容、现存方案和空白领域
  • 保留开放性问题：“开放性问题”是特色，而非缺陷
  • 支持自主实现：阅读本规格的Agent应能生成子Agent来验证和扩展内容
优质的技术规格是一个起点，而非必须严格遵循的脚本。

Document Structure

文档结构

Header (Required)

标题（必填）

markdown
undefined
markdown
undefined

[Feature Name]

[功能名称]

Date: [YYYY-MM-DD] Status: Draft | In Progress | Implemented Author: [Name or AI-assisted] Branch: [optional: feat/feature-name if work has started]
undefined
日期：[YYYY-MM-DD] 状态：草稿 | 进行中 | 已实现 作者：[姓名或AI辅助] 分支：[可选：若已启动开发，填写feat/feature-name]
undefined

Overview

概述

One paragraph max. Describe what the feature does. Don't sell it.
markdown
undefined
最多一段。描述该功能的作用。无需刻意推销。
markdown
undefined

Overview

概述

[One to two sentences describing what this feature adds or changes and what it enables. Be specific about the capability, not vague about benefits.]
undefined
[1-2句话，描述该功能新增或修改的内容，以及它能实现的效果。请具体说明能力，而非模糊提及收益。]
undefined

Motivation

动机

Structure as Current State → Problems → Desired State.
markdown
undefined
按照当前状态 → 存在问题 → 期望状态的结构撰写。
markdown
undefined

Motivation

动机

Current State

当前状态

[Show actual code or configuration demonstrating how things work TODAY. Use real code blocks, not prose descriptions.]
This creates problems:
  1. [Problem Title]: [Specific explanation of what breaks or is painful]
  2. [Problem Title]: [Specific explanation of what breaks or is painful]
[展示体现当前工作方式的实际代码或配置。请使用真实代码块，而非文字描述。]
这会引发以下问题：
  1. [问题标题]：[具体说明出现的故障或痛点]
  2. [问题标题]：[具体说明出现的故障或痛点]

Desired State

期望状态

[Brief description of what the target looks like. Can include a code snippet showing the ideal API or structure.]
undefined
[简要描述目标状态。可包含展示理想API或结构的代码片段。]
undefined

Research Findings

研究成果

This is where specs shine. Document what you FOUND, not what you assumed.
markdown
undefined
这是技术规格的核心价值所在。记录您发现的内容，而非假设的内容。
markdown
undefined

Research Findings

研究成果

[Topic Researched]

[研究主题]

[Description of what you investigated and methodology]
[Category][Dimension 1][Dimension 2]
[Project/Lib][What they do][Their approach]
[Project/Lib][What they do][Their approach]
Key finding: [Your main discovery—could be that no standard exists, or that everyone does X]
Implication: [What this means for your design decisions]

Include:

- What similar projects do (comparison tables)
- What you searched for but didn't find ("No Established Pattern Exists")
- Links or references to documentation you consulted
[描述您的研究内容和方法]
[类别][维度1][维度2]
[项目/库][他们的做法][他们的实现思路]
[项目/库][他们的做法][他们的实现思路]
关键发现：[您的主要结论——可能是尚无标准方案，或是所有方案均采用X方式]
影响：[这对您的设计决策意味着什么]

需包含：

- 同类项目的做法（对比表格）
- 您搜索但未找到的内容（“无既定模式”）
- 您参考的文档链接或资料

Design Decisions

设计决策

Use a table for traceability. Every decision should have a rationale.
markdown
undefined
使用表格确保可追溯性。每个决策都应有理由。
markdown
undefined

Design Decisions

设计决策

DecisionChoiceRationale
[Decision point][What you chose][Why this over alternatives]
[Decision point][What you chose][Why this over alternatives]
[Deferred decision]Deferred[Why it's out of scope for now]
undefined
决策点选择理由
[决策项][您的选择][为何选择该方案而非其他替代方案]
[决策项][您的选择][为何选择该方案而非其他替代方案]
[延迟决策项]延迟[为何当前不将其纳入范围]
undefined

Architecture

架构

Diagrams over prose. Show relationships visually with ASCII art.
markdown
undefined
优先使用图表而非文字。通过ASCII图直观展示关系。
markdown
undefined

Architecture

架构

[Describe what the diagram shows]

┌─────────────────────────────────────────┐
│ [Component Name] │
│ ├── [field]: [type or value] │
│ └── [field]: [type or value] │
└─────────────────────────────────────────┘
│
▼ [relationship label]
┌─────────────────────────────────────────┐
│ [Component Name] │
└─────────────────────────────────────────┘


For multi-step flows:

```markdown
STEP 1: [Step name] ──────────────────── [What happens in this step]
STEP 2: [Step name] ──────────────────── [What happens in this step]
undefined
[描述该图表展示的内容]

┌─────────────────────────────────────────┐
│ [组件名称] │
│ ├── [字段]: [类型或值] │
│ └── [字段]: [类型或值] │
└─────────────────────────────────────────┘
│
▼ [关系标签]
┌─────────────────────────────────────────┐
│ [组件名称] │
└─────────────────────────────────────────┘


对于多步骤流程：

```markdown
步骤1: [步骤名称] ──────────────────── [该步骤的具体内容]
步骤2: [步骤名称] ──────────────────── [该步骤的具体内容]
undefined

Implementation Plan

实现计划

Break into phases. Use checkboxes for tracking. Phase 1 should be detailed; later phases can be rougher (the implementer will flesh them out).
markdown
undefined
拆分为多个阶段。使用复选框跟踪进度。第一阶段应详细；后续阶段可相对粗略（实现者会自行完善细节）。
markdown
undefined

Implementation Plan

实现计划

Phase 1: [Phase Name]

阶段1: [阶段名称]

  • 1.1 [Specific, atomic task]
  • 1.2 [Specific, atomic task]
  • 1.3 [Specific, atomic task]
  • 1.1 [具体、原子化的任务]
  • 1.2 [具体、原子化的任务]
  • 1.3 [具体、原子化的任务]

Phase 2: [Phase Name]

阶段2: [阶段名称]

  • 2.1 [Higher-level task—implementer will break down]
  • 2.2 [Higher-level task]
undefined
  • 2.1 [较宏观的任务——实现者会自行拆解]
  • 2.2 [较宏观的任务]
undefined

Edge Cases

边缘情况

List scenarios that might break assumptions or need special handling.
markdown
undefined
列出可能打破假设或需要特殊处理的场景。
markdown
undefined

Edge Cases

边缘情况

[Scenario Name]

[场景名称]

  1. [Initial condition]
  2. [What happens]
  3. [Expected outcome or "See Open Questions"]
  1. [初始条件]
  2. [发生的情况]
  3. [预期结果或“参见开放性问题”]

[Scenario Name]

[场景名称]

  1. [Initial condition]
  2. [What happens]
  3. [Expected outcome]
undefined
  1. [初始条件]
  2. [发生的情况]
  3. [预期结果]
undefined

Open Questions

开放性问题

This section signals "you decide this" to the implementer. Include your recommendation but don't close the question.
markdown
undefined
本部分向实现者传递“由您决定”的信号。请给出您的建议，但不要直接定论。
markdown
undefined

Open Questions

开放性问题

  1. [Question about an unresolved design decision]
    • Options: (a) [Option A], (b) [Option B], (c) [Option C]
    • Recommendation: [Your suggestion and why, but explicitly leave it open]
  2. [Another unresolved question]
    • [Context about why this is uncertain]
    • Recommendation: [Suggestion or "Defer until X"]
undefined
  1. [关于未解决设计决策的问题]
    • 选项：(a) [选项A], (b) [选项B], (c) [选项C]
    • 建议：[您的建议及理由，但需明确保留决策空间]
  2. [另一个未解决的问题]
    • [关于该问题存在不确定性的背景]
    • 建议：[建议或“延迟至X阶段再处理”]
undefined

Success Criteria

成功标准

How do we know this is done? Checkboxes for verification.
markdown
undefined
如何判断任务已完成？使用复选框便于验证。
markdown
undefined

Success Criteria

成功标准

  • [Specific, verifiable outcome]
  • [Specific, verifiable outcome]
  • [Tests pass / build succeeds / docs updated]
undefined
  • [具体、可验证的结果]
  • [具体、可验证的结果]
  • [测试通过/构建成功/文档已更新]
undefined

References

参考资料

Files that will be touched or consulted.
markdown
undefined
将被修改或参考的文件。
markdown
undefined

References

参考资料

  • [path/to/file.ts]
    - [Why this file is relevant]
  • [path/to/pattern.ts]
    - [Pattern to follow or reference]

---
  • [path/to/file.ts]
    - [该文件的相关性说明]
  • [path/to/pattern.ts]
    - [需遵循或参考的模式]

---

Good vs Bad Specs

优质与劣质技术规格对比

Good Spec Characteristics

优质技术规格的特点

  • Research is documented: Shows what was explored, not just conclusions
  • Decisions have rationale: Every choice has a "why" in a table
  • Questions are left open: Implementer has room to decide
  • Code shows current state: Not described abstractly
  • Architecture is visual: ASCII diagrams over prose
  • Phases are actionable: Checkboxes that can be tracked
  • 记录研究过程：展示已探索的内容，而非仅呈现结论
  • 决策有依据：每个选择都在表格中说明“原因”
  • 保留开放性问题：实现者有决策空间
  • 代码展示当前状态：不使用抽象描述
  • 架构可视化：使用ASCII图而非文字
  • 阶段可执行：使用可跟踪的复选框

Bad Spec Characteristics

劣质技术规格的特点

  • Prescriptive step-by-step: Reads like a tutorial, no room for autonomy
  • Assumes without research: "We'll use X" without exploring alternatives
  • Closes all questions: No Open Questions section
  • Abstract descriptions: "The system will handle Y" without showing code
  • Wall of prose: No tables, no diagrams, no structure
  • 过于指令化：读起来像教程，无自主决策空间
  • 无研究支撑：未探索替代方案就直接“我们将使用X”
  • 无开放性问题：缺少开放性问题部分
  • 抽象描述：仅说“系统将处理Y”，未展示代码
  • 大段文字堆砌：无表格、无图表、无结构

Writing for Agent Implementers

为Agent实现者编写规格的要点

When an agent reads your spec, they should:
  1. Understand the problem from Motivation section
  2. Know what's been explored from Research Findings
  3. See the proposed direction from Design Decisions
  4. Have a starting point from Implementation Plan Phase 1
  5. Know what to investigate further from Open Questions
The agent will then:
  • Spawn sub-agents to verify your research
  • Explore the Open Questions you left
  • Flesh out later phases of the implementation plan
  • Make decisions where you left room
If your spec is too prescriptive, the agent will blindly follow it. If it's too vague, the agent will flounder. The sweet spot is: enough context to start, enough openness to own the implementation.
当Agent阅读您的规格时，应能：
  1. 从动机部分理解问题
  2. 从研究成果部分了解已探索的内容
  3. 从设计决策部分了解拟定方向
  4. 从实现计划的第一阶段获得起点
  5. 从开放性问题部分了解需进一步研究的内容
随后，Agent会：
  • 生成子Agent以验证您的研究成果
  • 探索您提出的开放性问题
  • 完善实现计划后续阶段的细节
  • 在您留出的空间内做出决策
如果您的规格过于指令化，Agent会盲目遵循；如果过于模糊，Agent会陷入困境。理想状态是：足够的上下文以启动工作，足够的开放性以让实现者主导实现过程。

Quick Reference Checklist

快速参考检查清单

markdown
- [ ] Header (Date, Status, Author)
- [ ] Overview (1-2 sentences)
- [ ] Motivation
  - [ ] Current State (with code)
  - [ ] Problems (numbered)
  - [ ] Desired State
- [ ] Research Findings
  - [ ] Comparison tables
  - [ ] Key findings
  - [ ] Implications
- [ ] Design Decisions (table with rationale)
- [ ] Architecture (ASCII diagrams)
- [ ] Implementation Plan (phased checkboxes)
- [ ] Edge Cases
- [ ] Open Questions (with recommendations)
- [ ] Success Criteria
- [ ] References
Not every spec needs every section. A small feature might skip Research Findings. A migration spec might focus heavily on Edge Cases. Use judgment.
markdown
- [ ] 标题（日期、状态、作者）
- [ ] 概述（1-2句话）
- [ ] 动机
  - [ ] 当前状态（附带代码）
  - [ ] 问题（编号列出）
  - [ ] 期望状态
- [ ] 研究成果
  - [ ] 对比表格
  - [ ] 关键发现
  - [ ] 影响
- [ ] 设计决策（带理由的表格）
- [ ] 架构（ASCII图）
- [ ] 实现计划（分阶段复选框）
- [ ] 边缘情况
- [ ] 开放性问题（带建议）
- [ ] 成功标准
- [ ] 参考资料
并非所有规格都需要包含所有部分。小型功能可跳过研究成果部分。迁移类规格可重点关注边缘情况。请根据实际情况判断。