OpenSpec 深度解析报告

当前软件工程的痛点

  • ✕ 模糊性 (Ambiguity)： 人类习惯脑补需求，但 AI 只能基于概率预测。Spec 不准，AI 必错。
  • ✕ 上下文丢失： 需求在 PM -> 架构师 -> 开发者 -> 代码 的传递中逐层失真。
  • ✕ 维护成本： 代码改了，文档没改。下次 AI 读取文档时，得到的是过时信息。

Spec Engineering 的价值

graph LR A[模糊意图] -->|Spec工程化| B(结构化契约) B -->|驱动| C[Human Dev] B -->|驱动| D[AI Agent] C --> E[高质量软件] D --> E B -->|自动生成| F[测试用例]
Spy (关键洞察)

"如果是架构的关键文档，你就建一个 Agents/ 目录... 这样渐进式加载，会节省不少 token。"

>> 解析：Spec 是 AI 的外挂显存，管理 Spec 就是管理 AI 的认知边界。
Jun (关键洞察)

"结构化拆解管理spec从头到尾的过程，pm实际上参与很少... 大坑也在这。"

>> 解析：Spec 能力的缺失是产品与工程脱节的根本原因。

Artifact 层次

  • 1. Proposal (Why)
    战略意图，不可逆决策
  • 2. Specs (What)
    系统行为，验收标准 (SHALL/MUST)
  • 3. Design (How)
    技术实现，架构权衡

Spec 示例：AI 可读性对比

❌ 传统文档 (给人类看)

"用户登录后应该能看到仪表盘，如果没权限就提示一下。"

AI 困惑：具体的 URL 是什么？没权限返回 401 还是 403？提示是 Toast 还是 Alert？
✅ OpenSpec (给 Agent 看)
Scenario: 用户登录重定向
- WHEN: User logs in successfully
- THEN: System SHALL redirect to `/dashboard`

Scenario: 权限不足处理
- WHEN: User lacks `view_dashboard` permission
- THEN: System SHALL return HTTP 403
- AND: System SHALL display error toast "Access Denied"

Spec Engineering: 智能时代的“元编程”

在 AI 辅助编程时代，我们不再直接编写循环和判断，我们编写约束 (Constraints) 和 意图 (Intents)。
Spec 的质量，直接决定了 AI 生成代码的上限。

作用一 消除歧义的“分界线”

Spec 是划分“业务期望”与“工程实现”的刚性界面。如果没有这一层，业务的模糊性会直接污染代码库。

graph TD Business[业务: 模糊、多变] -->|Spec Engineering| Spec[Spec: 精确、逻辑闭环] Spec -->|Prompt| AI[AI Agent] Spec -->|Constraint| Human[工程师] AI --> Code[代码实现] Human --> Code style Spec fill:#dbeafe,stroke:#2563eb,stroke-width:2px

作用二 V-Model 的测试基准

Spec 不仅仅是生成代码的依据，更是生成测试用例的依据。AI 可以根据 Spec 同时写出 Code 和 Test，实现自我验证。

graph TD Spec[Spec 文档] Spec -->|生成| Code[业务代码] Spec -->|生成| Test[测试代码] Code -->|运行| Runner{CI/CD} Test -->|验证| Runner Runner -->|通过| Pass[✅ 交付] Runner -->|失败| Fail[❌ 修正Spec或代码] style Spec fill:#d1fae5,stroke:#059669,stroke-width:2px

为什么“写好、管好 Spec”是核心能力？

🧠

对抗认知负荷

现代软件太复杂，没人能记住所有细节。Spec 是外挂大脑。

AI场景 AI 的 Context Window 是有限的。良好的 Spec 拆分（如 OpenSpec 的分层结构）允许 AI 按需加载上下文，避免“遗忘”或“幻觉”。

⚖️

单一真理来源 (SSOT)

代码会变，口头沟通会忘。只有 Spec 应该是法律条文。

AI场景 当 AI 修改了代码但没改文档时，系统就腐烂了。必须强制 AI 遵循 Spec First 流程：先改 Spec，再改代码。

💬

低成本试错

修改 Spec 的成本是修改代码的 1/10，是修复线上 Bug 的 1/100。

AI场景 让 AI 先输出 Proposal/Design 进行审查，这本质上是在自然语言层面进行 Debug，成本极低。

致团队：如何提升 Spec 能力？

01

产品经理要懂“结构化表达”

告别文学性的“用户故事”，转向逻辑性的“行为契约”。学习 Gherkin (Given/When/Then) 语法，这是人机共通的语言。

02

工程师要成为“Spec 审查员”

以前 Review 代码，现在 Review Spec。如果 Spec 没写清楚边界条件（如：空值怎么处理？并发怎么处理？），坚决不让 AI 开始写代码。

03

建立 Spec 的 CI/CD

Spec 文档也应该纳入版本控制（Git）。每一次 Spec 的变更都应触发 Review。不要让文档游离于工程之外。

原文

源链接