write-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Write Spec

编写 Spec

Synthesize what is already settled into a spec, adding the uncontested facts a decision record drops: no interview, no new decisions. If the work fits in the current context, say once that implementing directly is cheaper.
If an argument names a file, issue, or URL, read it in full first. With no argument, propose the one
spec/features/<slug>/decisions.md
that has no
spec.md
beside it, or ask. Read
spec/vision.md
and
spec/glossary.md
if they exist.
将已经确定的内容整合成一份 spec,并补充决策记录中遗漏的、无争议的事实:不进行访谈,也不引入新决策。 如果这项工作适合当前上下文,就说明一次:直接实现成本更低。
如果参数中提到了文件、issue 或 URL,先完整阅读它。 如果未提供参数,则提出唯一一个旁边没有
spec.md
的
spec/features/<slug>/decisions.md
,或向用户询问。 如果
spec/vision.md
和
spec/glossary.md
存在,则阅读它们。

1. Ground it in the code

1. 以代码为依据

Run three searches, as parallel subagents if your harness has them:
  • Locate: where the affected code lives.
  • Analyze: how the current implementation works, traced.
  • Prior art: the closest existing feature of the same shape, and its tests.
Each is a documentarian: describe, never design. Also look for a verification skill: a project skill (in
.agents/skills/
or a harness skills folder) whose
SKILL.md
says it runs the product and records whether a check passed.
Then sketch the seams where this gets tested. Prefer existing seams, the highest one available, and as few as possible; one is ideal. Check the seams with the user before writing.
运行三次搜索;如果 harness 支持,则将它们作为并行 subagents 运行:
  • 定位:受影响的代码位于何处。
  • 分析:当前实现如何工作,以及完整的调用链路。
  • 既有实践:形态最接近的现有功能及其测试。
三者都只负责记录和描述,绝不进行设计。 还要查找 verification skill:项目中的 skill(位于
.agents/skills/
或 harness 的 skills 文件夹中),其
SKILL.md
表明它会运行产品并记录检查是否通过。
然后勾勒该功能将在哪些**测试接缝(seams)**上进行测试。 优先使用现有接缝,在现有可用层级中选择最高的一层,并尽量减少接缝数量;理想情况是一个。 写入前,与用户确认这些接缝。

2. Write the spec

2. 编写 spec

Use these sections, in order, with these exact names. Facts about today cite
file:line
(Current state, Seams); Decisions and Sequence never do.
<spec-template>
按以下顺序使用这些章节,并采用这些确切名称。 关于当前事实的描述必须引用
file:line
(当前状态、测试接缝);决策和实施顺序不得引用文件路径。
<spec-template>

Problem

问题

The problem from the user's perspective, observable: who hits it, how often, how you know.
从用户视角描述可观察的问题:谁会遇到它、遇到它的频率,以及如何确认问题的存在。

Solution

解决方案

What changes for the user, in the narrowest version still worth shipping.
描述用户将获得的变化,并采用仍然值得交付的最窄范围版本。

Current state

当前状态

What exists today, with
file:line
, plus constraints and what is missing.
描述当前已有的内容,并引用
file:line
;同时说明约束条件以及缺失的内容。

Behaviour

行为

A numbered list of statements true once this works, one line each, each checkable by someone using the product. No "as an actor, I want" framing.
用编号列表描述功能完成后成立的事实,每项只写一行,并且每项都可以由产品使用者进行验证。 不要使用“作为某个角色,我希望……”这种表述方式。

Decisions

决策

Each decision, the alternative that lost, and why it lost. No file paths or code, except a trimmed snippet (schema, state machine, type shape) that encodes a decision more precisely than prose.
列出每项决策、未被采用的替代方案,以及该替代方案被否决的原因。 不要包含文件路径或代码,唯一的例外是经过精简且能够比文字更准确地表达决策的代码片段,例如 schema、状态机或类型结构。

Seams

测试接缝

Where this gets tested:
file:line
for existing seams, and for each new seam the reason no existing one would do.
说明该功能将在哪里进行测试:现有接缝引用
file:line
;对于每个新接缝,说明为什么现有接缝无法满足需求。

Sequence

实施顺序

The order behaviour arrives in, from the user's point of view. Product ordering only: no work units or blocking edges. Past about seven entries, say the scope got wide.
从用户视角描述各项行为呈现的顺序。 只描述产品层面的顺序,不写工作单元或阻塞依赖边。 超过大约七项时,说明范围已经扩大。

Out of scope

范围外

Named, so it cannot creep back in.
明确列出范围外的内容,避免其再次被纳入范围。

Accepted breakage

可接受的破坏

What breaks or gets worse, and why that is acceptable.
说明哪些内容会损坏或变得更差,以及为什么这种影响可以接受。

Done means

完成标准

  • Automated: what a machine can check.
  • Manual: what a person has to look at.
</spec-template>
With a verification skill, read its
SKILL.md
, then put every check it can run under Automated as agent steps, such as "verify: submit the signup form, the dashboard greets the new account, and one
accounts
row exists". Manual keeps only judging look and feel, or actions no agent can perform.
  • 自动化:机器能够检查的内容。
  • 人工:需要由人查看或判断的内容。
</spec-template>
如果存在 verification skill,先阅读其
SKILL.md
,然后将它能够运行的每项检查都以 Agent 步骤的形式放入自动化部分,例如“verify: 提交注册表单,仪表板会显示新账户的问候信息,并且存在一条
accounts
记录”。 人工部分只保留对外观和体验的判断,或 Agent 无法执行的操作。

3. Land it

3. 落地 spec

Write
spec/features/<slug>/spec.md
, beside the decision record when there is one; otherwise propose a short kebab-case slug and confirm it before writing. The spec file is the only artifact. Tell the user to commit the feature folder: implement-slice reads it from git.
将 spec 写入
spec/features/<slug>/spec.md
;如果存在决策记录,则写在其旁边,否则提出一个简短的 kebab-case slug,并在写入前与用户确认。 该 spec 文件是唯一需要产出的文件。 告知用户提交 feature 文件夹:implement-slice 会从 git 中读取它。