DEV Community

cognitalk
cognitalk

Posted on

Beginner's Guide to Spec-Driven Development (SDD) With OpenSpec | OpenSpec 入门指南：用规范驱动开发（SDD）高效构建 AI 应用

#ai #beginners #softwaredevelopment #tutorial


https://www.youtube.com/watch?v=9MImID9o8MQ

整文标题：OpenSpec 入门指南：用规范驱动开发（SDD）高效构建 AI 应用

第一部分：引言与背景介绍 （开始时间 0% - 10%）

  1. 课程目标与适用范围

    • 这是一个面向初学者的完整课程，旨在教授如何使用“规范驱动开发”（SDD），特别是结合 OpenSpec 工具。
    • 无论你正在构建什么类型的软件（网站、后端、移动应用），这套方法论都同样适用。

  2. 学习前提条件

    • 必备条件：
      • 需要一个 AI 代理工具（Agent Harness），例如 Claude Code、Codex、Copilot 等。
      • 需要一个终端（Terminal），因为通常在这些工具中运行代理任务。
    • 推荐条件：
      • 拥有一个集成开发环境（IDE）或代码编辑器，如 Android Studio、VS Code 等。

  3. 主讲人介绍

    • 主讲人是 Philip，一名谷歌开发者专家（Google Developer Expert）。
    • 他的目标是帮助开发者利用 AI 和代理，通过稳定的、可扩展的基础架构来构建更好的软件。

第二部分：规范驱动开发（SDD）解决的问题 （开始时间 10% - 25%）

  1. 核心问题：AI 的上下文窗口限制

    • AI 模型有一个“上下文窗口”，即单次会话中能处理的 Token 数量是有限的（例如，Fable 模型有 100 万个 Token）。
    • 随着软件规模变大，工作必须被分割成更小的块（Chunk），并在多个独立的 AI 会话中完成。例如，会话 1 实现功能 A，会话 2 实现功能 B。

  2. 新会话的“失忆”问题

    • 当你开启一个新的 AI 会话时，它完全不知道之前会话的任何信息。
    • 然而，一个项目中存在大量始终相关的“上下文”，例如源代码文件、需求、设计决策和架构决策。

  3. 解决方案：上下文工程（Context Engineering）

    • “上下文工程”是指管理和喂送给 AI 会话所需上下文的过程。
    • 规范驱动开发（SDD） 本质上是一种上下文工程的形式。它将软件的“规范”（Specification）作为单一事实来源（Single Source of Truth）。

  4. SDD 的工作机制

    • 为了在不同会话间共享上下文，可以将一个会话的输出写入文件。在 AI 领域，Markdown (.md) 文件是标准格式，因为它易于 AI 和人类阅读。
    • 另一个新会话可以直接读取这些 Markdown 文件中的上下文，无需重新指定。

  5. SDD 的核心步骤

    • 第一步：思考与规划：在开始任何工作或功能之前，仔细思考要构建什么。
    • 第二步：撰写规范文档：不要立即执行计划，而是先将计划转化为详细的设计文档（规范文档）。内容包括：构建目标、原因、目标用户、粗略的实现计划、任务列表及执行顺序。

  6. 规范文档的作用

    • 它是一个“活文档”（Living Document），存放在项目的独立文件夹中。
    • 未来的团队成员也可以阅读它来理解某个功能的用途。
    • 在每次新的 AI 会话中，都可以将这个规范文档喂给 AI，让它知道当前正在构建什么。

第三部分：主流 SDD 框架对比与 OpenSpec 的优势 （开始时间 25% - 45%）

  1. SDD 框架的必要性

    • 虽然 SDD 没有一个固定的形式，但人们通常会遵循一个框架。框架定义了一系列步骤：头脑风暴 -> 创建规范 -> 实施规范。

  2. 三大主流 SDD 框架介绍

    • GitHub SpecIt：由微软维护，在 GitHub 上有 13.9 万颗星，非常流行。但主讲人不喜欢它，认为其过于冗长（Verbose）。生成的 MD 文件会非常长且多，从头脑风暴到生成规范的路径也很长，审查起来费时费力。主讲人的经验是，不那么详细的规范反而能得到更好的输出。
    • Cairo：这是一个独立的 IDE（VS Code 的分支），将 SDD 功能内置其中。优点是开箱即用，缺点是锁定在特定工具中，灵活性差。对于移动端开发（如 Android/iOS），无法替代 Android Studio 或 Xcode 这类重型 IDE。
    • OpenSpec：主讲人认为它是赢家。

  3. OpenSpec 的核心优势

    • 轻量级（Lightweight）：非常快速，不需要执行一大堆命令才能得到规范。
    • 灵活（Flexible）：可以自定义规范模板，控制详细程度。不像其他框架那样固化流程。
    • 适合棕地开发（Brownfield Work）：特别适合在已有代码库上工作。
    • 增量规范（Delta Specs）：这是 OpenSpec 独有的特性。当需求发生变化时，只记录新旧规范之间的差异，而不是重写整个文档。这是一种高效的变更管理方式。

第四部分：OpenSpec 的安装与核心工作流详解 （开始时间 45% - 85%）

  1. 安装 OpenSpec

    • OpenSpec 是一个命令行工具（CLI）。可以通过 npm 或 brew（MacOS）命令进行全局安装。

  2. 初始化项目

    • 在项目的根目录下的终端中（非 AI 代理会话内），运行 openspec init 命令。
    • 选择你想要集成的 AI 代理工具（如 Claude Code）。
    • 初始化后，项目结构中会生成一系列命令和技能（Skills）。“技能”本质上是命令的自然语言版本。

  3. 四大核心技能（Commands/Skills）

    • openspec explore (探索)：
      • 目的：正式起草规范前的头脑风暴阶段。
      • 过程：与 AI 代理进入一个对话循环，探讨你要构建什么。AI 会提出澄清性问题，帮助你完善想法。此阶段不会生成任何规范文件。
      • 示例：描述要构建一个待办事项 App，AI 会就 iOS 支持、创建方式、数据模型、保存逻辑、导航库等问题提问。
    • openspec propose (提议)：
      • 目的：基于探索阶段的共识，生成实际的规范文件（Markdown 文档）。
      • 产出物：在项目 openspec/changes/ 文件夹下生成一系列文件。
        • specs/ 文件夹：包含多个“能力（Capability）”子文件夹，每个能力对应功能的一个切片（如“App Shell”、“To-Do Detail Screen”）。每个能力都有一个 spec.md 文件，描述“做什么”和“为什么做”。
        • proposal.md 文件：是整个功能的摘要，说明为什么要做这个改动、改了什么，并链接到各个能力的 spec 文件。它还记录了“新增能力”和“修改能力”。
        • design.md 文件：侧重于“怎么做”，包含技术实现细节，如模块名、数据库 Schema、伪代码、关键决策等。
        • tasks.md 文件：一个按步骤分解的任务清单，AI 代理将按照这个清单逐步实施。任务可以被勾选标记为已完成。
    • openspec apply (应用)：
      • 目的：让 AI 代理根据 tasks.md 文件中的任务清单，开始编写代码。
      • 过程：在一个全新的 AI 会话中执行此命令。新会话不记得之前的对话，但可以读取项目中的规范文件。这就是上下文工程的核心。
      • 效果：如果规范文件做得足够好，代码实施过程会非常顺利。
    • openspec archive (归档)：
      • 目的：当一个功能被完全实现后，将其规范文件归档，表示该功能已完成。

  4. 重要配置文件：openspec-config.yaml

    • 作用类似于 AI 代理的“系统提示词”（System Prompt），但专门用于 OpenSpec 流程。
    • 可以在此文件中定义项目级别的通用规则，例如技术栈、库、编码风格、领域知识等。
    • 如果配置得当，在 explore 阶段，AI 就不会再问那些已经定义好的通用问题。

  5. 工作流演示（以构建待办事项 App 为例）

    • Explore 阶段：描述 App 需求，AI 提出 8 个问题（如是否支持 iOS、创建方式、数据模型字段、保存逻辑、导航库等），用户逐一回答。过程中可能发现原有想法不够好而进行调整（例如将自动保存改为手动保存按钮）。
    • Propose 阶段：AI 根据讨论结果，自动生成了 proposal.md、design.md、tasks.md 以及多个 spec.md 文件。
    • Apply 阶段：清除旧会话上下文，在新会话中执行 /opsx apply。AI 读取规范文件，开始执行 tasks.md 中的 43 个任务，最终成功构建出一个功能完整的跨平台（iOS & Android）待办事项 App。

第五部分：总结与展望 （开始时间 85% - 100%）

  1. 回顾与肯定

    • 再次强调，对于复杂的需求，花时间制定规范的收益巨大。
    • 展示最终构建出的 App 效果：创建、编辑、删除、标记完成、筛选等功能均正常工作。

  2. OpenSpec 的价值重申

    • 它是一个超级灵活的框架，适用于每个项目，并能集成到自定义工作流中。

  3. 进阶方向

    • 仅有 OpenSpec 还不够，一个完善的 AI 工作流还应包括测试用例（单元测试、端到端测试）、验证机制等，形成一个真正的系统。
    • 随着项目变大和交付速度变快，不能依赖逐行的人工审查。

  4. 结语与号召

    • OpenSpec 是进入 AI 代理开发的绝佳起点，解决了上下文工程的大部分难题。
    • 鼓励观众关注频道，查看更多相关视频和资源（如指导计划）。

Top comments (0)