OpenSpec + Claude Code 完整开发流程

从安装到归档，每一步你该输什么、看什么、做什么。

---

一、一次性安装（只做一次）

终端操作

# 1. 安装 OpenSpec
npm install -g @fission-ai/openspec@latest

# 2. 验证
openspec --version

# 3. 创建项目
mkdir mas-project && cd mas-project
git init

# 4. 初始化 OpenSpec（会问你项目类型和技术栈，务必具体回答）
openspec init --tools claude

初始化时的回答示例

❌ "Python app"
✅ "Python 3.12 多智能体系统，LangGraph 框架，asyncio 异步，Pydantic v2，pytest 测试"

---

二、填写 project.md（只做一次，后续持续补充）

打开 openspec/project.md，在 CC 里说：

请阅读 openspec/project.md 并帮我填写项目信息

CC 会问你问题，你回答，它帮你填。填完之后你自己加上这些关键规则：

## 测试规范
- 每个 propose 的 tasks.md 必须包含对应的单元测试任务
- 测试框架：pytest + pytest-asyncio
- 测试覆盖率目标：核心模块 > 80%
- 测试文件镜像源码结构：tests/agents/{name}/, tests/core/

## 错误处理
- Agent 失败返回标准 ErrorMessage，不抛异常
- Orchestrator 负责重试，最多 3 次

## 禁止事项
- 禁止硬编码 API key
- 禁止使用全局变量
- 禁止 Agent 直接调用 LLM，必须通过统一的 llm_client

这个文件是活的。以后每次发现 CC 做了不符合预期的事，就回来加一条规则。

---

三、正式开发循环（每个需求重复一遍）

以下是一个完整需求从开始到结束的全流程。

---

第 1 步：启动 CC

cd mas-project
claude

---

第 2 步：Propose（CC 做，你审核）

在 CC 里输入：

/opsx:propose 搭建MAS项目基础骨架，包含项目目录结构、MessageBus核心模块、
contracts数据模型定义、Orchestrator Agent基本调度循环，以及所有模块的单元测试

**关键：需求描述里要明确提到”以及对应的单元测试”**，否则 CC 不会自动加测试任务。

CC 会生成：

openspec/changes/你的变更名/
├── proposal.md      ← 做什么、为什么做
├── specs/           ← 具体需求和验收场景
├── design.md        ← 技术方案
└── tasks.md         ← 实现任务清单（含测试任务）

---

第 3 步：审核（你做，最重要的环节）

不要跳过。 逐个检查：

检查 proposal.md

在 CC 里说：

给我看 proposal.md 的内容

确认：

• CC 是否正确理解了你的需求？
• 范围是否合适？太大就让 CC 拆小

检查 design.md

给我看 design.md 的内容

确认：

• 技术方案是否符合 project.md 的约束？
• 有没有引入你不想要的依赖？
• 异步/同步方式是否正确？

检查 tasks.md

给我看 tasks.md 的内容

确认：

• 是否包含测试任务？（如果没有，让 CC 加上）
• 任务拆分粒度是否合适？
• 顺序是否合理？

有问题就让 CC 改

design.md 里用了 Redis，我不需要，改成内存中的 asyncio.Queue

tasks.md 里没有测试任务，请为所有模块补充 pytest 单元测试任务

反复调整，直到你对所有文件满意。

---

第 4 步：Apply（CC 做，你等）

确认 propose 没问题后：

/opsx:apply

CC 会按 tasks.md 逐个执行：

• 创建目录结构
• 编写业务代码
• 编写测试代码
• 勾选 tasks.md 的 checkbox

等它全部跑完。

---

第 5 步：验收（你做）

apply 完成后，按以下顺序验收：

5.1 确认任务完成度

给我看 tasks.md，是否所有任务都已勾选

如果有未勾选的，问 CC 为什么。

5.2 跑测试

用 pytest 跑一下所有测试，给我看结果

如果测试挂了：

测试 test_message_bus.py::test_publish 失败了，请修复

CC 修完后再跑一遍，直到全绿。

5.3 检查代码结构

这次 apply 创建和修改了哪些文件？列一个清单

确认：

• 目录结构是否符合 project.md 的约定
• 文件放的位置对不对
• 有没有多余的文件

5.4 检查关键代码

给我看 src/core/message_bus.py 的内容

给我看 src/contracts/messages.py 的内容

重点看：

• 是否符合 design.md 的方案
• 类型标注是否完整
• 有没有违反 project.md 的禁止事项

5.5 手动运行（如果可以）

帮我写一个简单的 main.py 跑一下 Orchestrator 的基本调度流程，
验证消息能正确收发

5.6 发现问题就让 CC 修

message_bus.py 的 publish 方法没有做异步，请改成 async def

CC 改完 → 你再跑测试 → 再检查 → 循环直到满意。

---

第 6 步：Archive（CC 做）

一切没问题后：

/opsx:archive

CC 会：

• 把这次的 spec 合并到主 openspec/specs/ 目录
• 把 change 移到 openspec/changes/archive/ 归档
• 你的 spec “数据库”更新了

---

第 7 步：Git 提交（你做）

git add .
git commit -m "feat: 搭建MAS项目基础骨架 + Orchestrator + MessageBus"

---

四、下一个需求，重复第三部分

/opsx:propose 实现 Researcher Agent，接收调研任务并返回结构化结果，包含单元测试

→ 审核 → apply → 验收 → 跑测试 → archive → git commit

---

五、建议的需求拆分顺序

每个都是一个独立的 propose → apply → archive 循环：

第 1 轮：项目骨架 + Orchestrator + MessageBus
第 2 轮：完善 contracts（所有 Agent 间的消息类型）
第 3 轮：Researcher Agent
第 4 轮：Coder Agent
第 5 轮：Reviewer Agent
第 6 轮：端到端集成测试
第 7 轮：配置管理 + 错误处理增强
第 8 轮：日志 + 监控

---

六、命令速查

你在哪	输入什么	干什么
终端	openspec init --tools claude	初始化（一次性）
终端	openspec update	升级后刷新配置
CC 里	/opsx:explore	讨论、调研、想清楚再动手
CC 里	/opsx:propose 需求描述	生成提案+设计+任务
CC 里	/opsx:apply	按任务清单写代码
CC 里	/opsx:archive	归档，合并 spec
终端	git add . && git commit	提交代码

---

七、踩坑提醒

propose 里不提测试 = 没有测试
永远在需求描述末尾加”包含单元测试”，或者在 project.md 里写死规则。

不要跳过审核直接 apply
CC 生成的 design.md 可能不符合你的预期，apply 之后再改成本很高。

不要手动改代码
所有修改都通过 CC 做，保持它的上下文完整。如果你手动改了文件，CC 下次可能不知道。

一个 propose 不要太大
如果你觉得一个需求会改 10+ 个文件，就拆成两个 propose。

project.md 是活文档
每次发现 CC 做了不对的事，就去 project.md 加一条规则。这是你训练 CC 的方式。