codely-openspec-spec-create-from-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🧬 How to create OpenSpec specs from existing code

🧬 如何从现有代码创建 OpenSpec 规范

An OpenSpec change can only

MODIFY

REMOVE

a requirement that already lives in

openspec/specs/

. Behaviour built before the team adopted OpenSpec has no spec, so every change over it lands as

ADDED

and the spec forgets what was there before. This skill writes that missing baseline: main specs for behaviour that already ships.

The baseline is the spec OpenSpec would have archived if the feature had been built with it: intent that was implemented and verified. Every sentence holds against the code, and every requirement is something someone meant. A baseline that flatters the code is worse than none, because the next proposal builds on it.

一次 OpenSpec 变更只能

MODIFY

或

REMOVE

已经位于

openspec/specs/

中的 requirement。团队采用 OpenSpec 之前构建的行为没有 spec，因此对这些行为的每次变更都会作为

ADDED

落地，而 spec 会忘记之前已有的内容。该 skill 会写入这份缺失的 baseline：为已经交付的行为创建主 spec。

baseline 是：如果该功能从一开始就使用 OpenSpec 构建，OpenSpec 本应归档的 spec：已经实现并验证的 intent。每句话都能与代码相符，每条 requirement 都代表某个人确实有意实现的内容。一个只会粉饰代码的 baseline 比没有 baseline 更糟糕，因为下一份 proposal 会以它为基础。

📥 Input

📥 输入

The argument is free text. Read it as one of these:

Input	Example	Scope
Nothing, or a question about what lacks a spec	`which features have no spec?`	The inventory in `resources/evidence-guidelines.md` . Build it and stop until the user picks a row.
A capability	`checkout`	That capability.
A change the user is about to make	`add discount coupons to checkout`	The current behaviour the change will touch. The new behaviour belongs to the change, not to the baseline.
A path or a screen	`src/app/admin/orders`	The business concept that path serves, traced back from it.

参数是自由文本。按以下类型之一理解：

输入	示例	范围
无，或询问哪些功能缺少 spec	`which features have no spec?`	`resources/evidence-guidelines.md` 中的清单。构建清单并停止，直到用户选择一行。
一项 capability	`checkout`	该 capability。
用户即将进行的变更	`add discount coupons to checkout`	该变更将触及的当前行为。新行为属于变更，而不属于 baseline。
路径或界面	`src/app/admin/orders`	从该路径反向追踪出的业务概念。

🪜 Steps

🪜 步骤

1. Check the preconditions

1. 检查前置条件

Run
```
openspec --version
```
. If the CLI is missing, stop and ask the user to install it.
Locate the OpenSpec root: the
```
openspec/
```
folder holding
```
config.yaml
```
. When that config points to a store, the specs live in the store.
Read the
```
context:
```
of
```
config.yaml
```
. It sets the language of the specs; without it, write them in English.

Done when the CLI answers and you know the folder the specs go into.

执行
```
openspec --version
```
。如果 CLI 缺失，停止并请用户安装。
定位 OpenSpec 根目录，即包含
```
config.yaml
```
的
```
openspec/
```
文件夹。当该 config 指向一个 store 时，spec 位于该 store 中。
读取
```
config.yaml
```
的
```
context:
```
。它设置 spec 的语言；如果没有它，则用英语编写。

完成条件：CLI 已正常响应，并且已确定 spec 的存放目录。

2. Bound the capability

2. 确定 capability 边界

A capability is one folder under
```
openspec/specs/
```
, named in kebab-case after the business concept (
```
checkout
```
,
```
order-management
```
), never after a class, a table or a folder.
Run
```
openspec list --specs
```
. When an existing spec already covers part of the behaviour, extend that spec.
When the areas involved share no business concept, they are several capabilities: propose the split to the user.
For a change the user is about to make, list the existing behaviour it will touch and confirm that scope with the user.
Run
```
openspec list
```
and look for
```
openspec/changes/<change>/specs/<capability>/
```
in each active change. When an active change has a delta on the capability, warn the user that extending the main spec can break that change's archive, and ask whether to go on.

Done when the user has confirmed every capability, and whether each one is new or extended.

capability 是
```
openspec/specs/
```
下的一个文件夹，以业务概念命名并使用 kebab-case（如
```
checkout
```
、
```
order-management
```
），绝不能按 class、table 或 folder 命名。
执行
```
openspec list --specs
```
。如果现有 spec 已覆盖部分行为，则扩展该 spec。
如果涉及的领域不共享任何业务概念，则它们属于多个 capability：向用户建议拆分。
对于用户即将进行的变更，列出该变更将触及的当前行为，并与用户确认范围。
执行
```
openspec list
```
，并在每个 active change 中查找
```
openspec/changes/<change>/specs/<capability>/
```
。如果 active change 对该 capability 有 delta，应警告用户：扩展主 spec 可能破坏该变更的归档，并询问是否继续。

完成条件：用户已确认每个 capability，以及每个 capability 是新建还是扩展。

3. Collect the evidence

3. 收集证据

Read

resources/evidence-guidelines.md

and dispatch the subagents it describes. Delegate the exploration: your job is to cross the reports, not to read the codebase.

Done when every area of every capability has a report, and every candidate behaviour in it carries its evidence.

读取

resources/evidence-guidelines.md

，并按照其中描述分派 subagents。将探索工作委托出去：你的职责是交叉核对报告，而不是亲自阅读代码库。

完成条件：每个 capability 的每个领域都有报告，且其中每个候选行为都附有证据。

4. Classify

4. 分类

Sort every candidate behaviour into one of the four cases of

resources/evidence-guidelines.md

. Then ask the user about all the ambiguous candidates in a single round, as that file describes. Use the tool to question the user if you have one.

Done when every candidate has a case, and every ambiguous one has the user's verdict.

将每个候选行为归入

resources/evidence-guidelines.md

所述四种情况之一。随后按照该文件的说明，在一轮中向用户询问所有 ambiguous 候选。如果有可用的提问工具，就使用它向用户提问。

完成条件：每个候选行为都有明确分类，且每个 ambiguous 候选都有用户的判断。

5. Write the specs

5. 编写 spec

Read

resources/spec-format.md

and write

openspec/specs/<capability>/spec.md

with the intended and verified behaviour only.

When you extend an existing spec, add requirements and scenarios and keep every existing one exactly as it is. An existing requirement that the code contradicts is drift: it goes to the report, and changing it is the job of an OpenSpec change.

Done when every intended and verified candidate is a requirement or a scenario in the spec.

读取

resources/spec-format.md

，并编写

openspec/specs/<capability>/spec.md

，只写入符合 intent 且已验证的行为。

扩展现有 spec 时，添加 requirements 和 scenarios，并原样保留所有现有内容。如果现有 requirement 与代码矛盾，则属于 drift：将其记录到报告中；修改它是 OpenSpec change 的职责。

完成条件：每个符合 intent 且已验证的候选行为，都已成为 spec 中的一条 requirement 或 scenario。

6. Validate

6. 验证

Run

openspec validate <capability> --type spec --strict

for every spec you wrote, fix every error and warning, and rerun.

Done when every spec passes strict validation.

对每个编写的 spec 执行

openspec validate <capability> --type spec --strict

，修复所有错误和警告，然后重新运行。

完成条件：每个 spec 都通过严格验证。

7. Report and close

7. 报告并结束

Answer in the language the user writes in. Report, in this order:

The specs written or extended, each with its capability id.
The scope decisions: splits, extensions, what you left out of the scope and why.
The candidates you left out of the spec, each with its case and its evidence.
The drift between existing requirements and the code.

Do not paraphrase the specs: the files are the deliverable. Then close with the steps that this run's facts call for, in this order, translated to the user's language:

Always, the review:

Review <spec paths>: they come from the code, and from now on agents will treat them as the truth. Once you agree with them, commit them with `/codely-git-conventional-commit`.

When the input was a change the user is about to make, the way back to it:

With the baseline ready, go on with your change: `/openspec-explore <the change, as the user described it>`

When you left a bug out of the spec, one ready-to-paste command per bug, with the evidence inline:

⚠️ <n> inconsistencies left out of the spec. To fix one:
- `/openspec-explore <the behaviour the intent asks for> fails when <the case that breaks> (<file:line>; <the test that covers it, or "no test covers it">)`

使用用户所用的语言回答。按以下顺序报告：

已编写或扩展的 spec，并附上每个 spec 的 capability id。
范围决策：拆分、扩展、排除在范围外的内容及其原因。
未纳入 spec 的候选行为，以及每个候选行为所属的情况和证据。
现有 requirement 与代码之间的 drift。

不要转述 spec：文件才是交付物。然后按照此次运行的事实所要求的顺序收尾：

始终执行审阅：

Review <spec paths>: they come from the code, and from now on agents will treat them as the truth. Once you agree with them, commit them with `/codely-git-conventional-commit`.

当输入是用户即将进行的变更时，返回该变更：

With the baseline ready, go on with your change: `/openspec-explore <the change, as the user described it>`

当有 bug 未纳入 spec 时，为每个 bug 提供一条可直接粘贴的命令，并在其中附上证据：

⚠️ <n> inconsistencies left out of the spec. To fix one:
- `/openspec-explore <the behaviour the intent asks for>` fails when <the case that breaks> (<file:line>; <the test that covers it, or "no test covers it">)

🧱 Boundaries

🧱 边界

Write only under
```
openspec/specs/
```
. Changes,
```
config.yaml
```
and the code stay as they are.
Leave the specs uncommitted: committing comes after the user's review.

只能写入
```
openspec/specs/
```
。change、
```
config.yaml
```
和代码保持原样。
保持 spec 未提交：提交应在用户审阅后进行。