openspec-brownfield-baseline

用途

OpenSpec Brownfield Baseline 用于在已有软件项目中途引入 OpenSpec，并从当前实现中创建可信的基线规格。当项目已有大量实现但缺少 OpenSpec 基线，团队希望从代码优先转向规格驱动开发，或用户要求从现有仓库生成/引导规格时，可使用此技能。

核心原则

openspec/specs/ 是系统行为的当前事实来源。
聚焦行为契约，而非内部实现细节。
反向推导的规格在人工审查前仅为草稿。
优先从高变更或高风险领域开始；除非明确要求，不要尝试为整个仓库编写规格。
优先基于用户可见能力划分领域边界，而非文件夹布局。

预期输出

为 openspec/specs/ 提议的领域映射。
为选定领域起草的 spec.md 文件。
一份简短审查说明，列出：已确认的预期行为、需要审查的推断行为、未提升为规格的疑似缺陷或意外行为。
关于未来变更应如何在 openspec/changes/ 下进行的建议。

标准工作流

初始化或规范化 OpenSpec 结构：若 OpenSpec 不存在，运行 openspec init（若 CLI 可用），否则手动创建 openspec/specs/ 和 openspec/changes/。不要先写变更工件，先建立当前状态基线。
起草前选择范围：默认不要尝试全仓库覆盖。提议第一批领域，如 auth、users、billing、public-api、webhooks、admin、sync、notifications。通过回答以下问题选择领域：存在哪些外部契约？哪些区域经常变更？哪些区域在没有基线时修改有风险？哪些区域已有测试或稳定工作流？
为每个领域收集证据：检查当前实现表面，从路由、控制器、处理器、模式、验证、序列化器、服务层入口点、测试（尤其是集成和端到端测试）、README/文档/API 参考、数据库约束或状态转换、日志、遥测、重试语义、幂等性和副作用中收集证据。优先将现有测试作为预期行为的有力证据。
提取契约而非代码结构：将证据转化为行为陈述，回答：接受什么输入？产生什么输出或状态变化？成功条件是什么？哪些失败对用户可见？发生什么副作用？存在哪些授权或时序约束？存在哪些排序、幂等性或重试保证？除非是外部契约的一部分，否则不要将实现细节复制到规格中。
以 OpenSpec 格式起草 spec.md 文件：每个领域通常位于 openspec/specs/<domain>/spec.md。使用如下结构：

<Domain Name>

Purpose

<简短说明该领域负责什么>

Requirements

Requirement: <Behavior name>

The system SHALL <observable behavior>.

Scenario: <Happy path>

GIVEN <context>
WHEN <action>
THEN <expected outcome>

Scenario: <Failure or edge case>

GIVEN <context>
WHEN <action>
THEN <expected outcome>

适当使用 RFC 2119 语言：SHALL、MUST、SHOULD。优先选择少量扎实的需求和具体场景，而非大量实现琐事。

将草稿置信度与最终事实分开：起草时跟踪每个需求是：由测试或文档确认、从代码推断、需要人工审查。此置信度标注可放在审查说明或草稿注释中，但不应污染最终基线规格，除非用户明确要求。
提升为事实来源前进行审查：在将生成的规格视为规范之前，进行审查，区分：有意的产品行为、实现泄漏、遗留怪癖、已知缺陷、规格不足的区域。如果某些内容看起来像缺陷或意外行为，应指出而非静默将其变为需求。
验证基线：完成前验证：选定的高价值领域已覆盖；每个需求可观察且可测试；场景不仅包括正常路径，还包括相关失败或边界条件；规格语言与当前行为足够接近以指导未来变更；基线足够小以便维护。如被要求，识别规格与代码/测试之间的差距。

使用 OpenSpec CLI 验证规格：起草规格后，运行 OpenSpec 验证器检查结构和格式正确性：

如果 CLI 已全局安装

openspec validate --specs --json

或通过 npx 无需全局安装

npx @fission-ai/openspec@latest validate --specs --json

--specs 标志针对 openspec/specs/ 下的规格文件。--json 标志产生机器可读输出，适用于 CI 管道和自动检查。在将规格提升为事实来源前修复任何报告的错误。常见问题包括：缺少必需部分（Purpose、Requirements）、场景块格式错误（GIVEN/WHEN/THEN）、RFC 2119 语言使用无效。如果 CLI 不可用，回退到根据步骤 5 中描述的格式手动审查规格结构。

将未来工作切换到变更：基线被接受后，建议所有新工作通过以下路径进行：openspec/changes/<change-id>/proposal.md、openspec/changes/<change-id>/specs/...、design.md、tasks.md。基线捕获当前事实；变更捕获增量。

智能体操作指南

应用此技能时：先提议领域映射和狭窄的第一批范围；在起草规格前检查仓库和测试；逐领域起草规格；明确指出的歧义和可能的意外行为；除非实际覆盖，否则不要声称整个仓库已有规格覆盖；如果用户希望执行，在 openspec/specs/ 下创建文件，而不仅仅是描述方法。

良好响应结构

回复用户时，优先使用此结构：推荐的第一批领域；建议在 openspec/specs/ 下创建的文件；一个领域的示例需求/场景；审查风险或歧义；下一步行动：立即起草基线规格，还是从选定的一个领域开始。

陷阱

试图一次性为整个系统编写规格。
将当前代码视为自动正确。
编写实现细节而非契约。
省略失败场景。
将当前状态基线与未来变更设计混合。
不检查测试或外部可见行为就生成规格。

完成标准

成功应用此技能的条件：openspec/specs/ 存在，且为选定领域包含草稿基线规格；每个基线规格以需求/场景形式捕获可观察行为；可疑行为被指出以供审查，而非静默规范；用户可通过 openspec/changes/ 继续未来工作。

技能介绍

用途