在 AI 辅助编程的时代，如何让 AI 助手精准理解项目规范并遵循统一的工作流是提升开发效率的关键。OpenSpec 是一套规格驱动开发（Spec-driven development）的标准框架。本文将介绍如何安装 OpenSpec CLI、初始化项目，并深入解析其核心文件结构与 AI 指令集。

---

1. 安装 OpenSpec CLI

首先，在终端中执行以下命令进行全局安装：

npm install -g @fission-ai/openspec

安装完成后，验证是否成功：

openspec --version

---

2. 初始化项目

在项目根目录下执行初始化命令。在此过程中，你需要选择 AI 工具，本示例选择 Codex：

openspec init

初始化完成后，OpenSpec 会在项目目录和系统的提示词配置目录中创建一系列核心配置文件。

---

3. OpenSpec 初始化后的核心文件解析

在 OpenSpec 初始化后，项目结构中会生成两个同名但位置和职责完全不同的 AGENTS.md 文件（如果项目根目录下已经存在 AGENTS.md 文件，则会在原来的基础上插入相应的内容，不会重新生成或覆盖）。理解它们的区别是掌握 OpenSpec 工作流的关键。

3.1 项目根目录下的 AGENTS.md

这个文件是 AI 编程助手进入项目时的第一入口。它的核心作用是重定向，告诉 AI 在处理不同任务时应该去哪里寻找权威指南。

• 位置： /AGENTS.md（项目根目录）
• 核心内容与作用：
  • 引导机制： 明确指示 AI，当涉及“规划（Planning）”、“提案（Proposals）”、“架构变更”或“新功能”时，必须立即阅读 @/openspec/AGENTS.md。
  • 权威来源： 它规定了 @/openspec/AGENTS.md 是关于变更提案、规格格式和项目规范的唯一权威来源。
  • 自动更新保护： 包含 <!-- OPENSPEC:START --> 和 <!-- OPENSPEC:END --> 标记，确保通过 openspec update 命令可以随时刷新这些指令。

3.2 openspec 目录下的 AGENTS.md

这是 OpenSpec 的“操作手册”，包含了极其详尽的 AI 行为准则 和 三阶段工作流。

• 位置： /openspec/AGENTS.md
• 核心内容与作用：
  • 三阶段工作流：
    • Stage 1: 创建变更（Creating Changes）： 规定了何时需要创建提案（如新功能、破坏性变更），以及如何使用 change-id 进行脚手架（Scaffold）创建。
    • Stage 2: 实施变更（Implementing Changes）： 定义了 AI 必须遵循的步骤：阅读提案 -> 查阅设计 -> 顺序执行任务 -> 更新任务清单。
    • Stage 3: 归档变更（Archiving Changes）： 指导如何在部署后将 changes/ 移动到 archive/ 并更新 specs/。
  • 严格的格式规范： 例如，每个需求必须包含至少一个 #### Scenario: 格式的场景。
  • CLI 命令指南： 列出了 AI 可以调用的所有命令（如 openspec list, validate, show, archive 等）及其参数用法。
  • 搜索与调试建议： 指导 AI 如何通过 ripgrep 或 openspec show --json 来检索项目上下文。

3.3 openspec 目录下的 project.md

该文件是项目的核心上下文与规范字典，不仅为开发人员提供背景，更是 AI 助手理解项目逻辑的“法律依据”。（初始化后仅生成一个模板，具体的符合该项目的内容还需要补充）

• 位置： /openspec/project.md
• 作用： 确保 AI 助手和开发者在完全一致的技术上下文（Context）下工作，避免生成与项目架构冲突的代码。

---

4. AI 助手私有指令集 (位于 ~/.codex/prompts/ 目录下)

初始化后，在 ~/.codex/prompts/ 目录下会生成三个专为 Codex AI 准备的指令文件，它们定义了 AI 处理变更时的底层逻辑：

4.1 openspec-proposal.md (逻辑：如何策划变更)

• 要求 AI 在提案阶段禁止编写任何代码。
• 指导 AI 执行以下步骤：
  • 审查现有工作：执行 openspec list。
  • 选择一个唯一的 change-id。
  • 编写增量规格（Delta Specs）并运行 openspec validate --strict。

4.2 openspec-apply.md (逻辑：如何实现变更)

• 指导 AI 顺序执行 tasks.md 中的清单。
• 强调保持修改最小化，并确保在勾选任务前完全确认实施效果。

4.3 openspec-archive.md (逻辑：如何结束变更)

• 定义了部署后的归档流程：
  • 运行 openspec archive <id> --yes 自动更新项目规格并将变更移至历史存档。

---

5. 初始化后的目录结构（总结版）

根据 OpenSpec 的标准规范，初始化后的目录结构及文件分布如下：

5.1 本地项目目录结构

/ (项目根目录)
├── AGENTS.md                # 第一入口：AI 助手的重定向指南
└── openspec/                # OpenSpec 配置与规范根目录
    ├── AGENTS.md            # 执行手册：AI 的三阶段工作流与 CLI 使用指南
    ├── project.md           # 规范字典：项目的技术栈、代码风格与架构约束
    ├── specs/               # (初始为空) 存放已定稿的功能规格
    └── changes/             # 变更管理
        └── archive/         # 存放已归档的历史变更

5.2 全局指令集目录结构

.codex/                      # (位于用户家目录 ~ 下)
└── prompts/                 # AI 助手私有指令集 (Codex 专用)
    ├── openspec-proposal.md     # 策划变更的 SOP
    ├── openspec-apply.md        # 实现变更的 SOP
    └── openspec-archive.md      # 归档变更的 SOP

---

6. 总结

通过 OpenSpec 的初始化，项目不仅拥有了清晰的文档结构， prompts 目录下的指令为 AI 助手建立了严密的“执行手册”。这种规格驱动的模式，能够最大限度地减少 AI 在大型项目中偏离架构风格的风险。