Claude Code + OpenSpec + Everything Claude Code AI 协同开发实战指南

Claude Code + OpenSpec + Everything Claude Code AI 协同开发实战指南

前言：为什么需要三者协同？

2024 年 Google DORA 报告的数据令人困惑：AI 编码助手采用率每提升 25%，软件交付稳定性反而下降 7.2%。主观上用了 AI 写代码速度快了 20%，客观结果却是实际交付周期增加了 19%-35。问题出在哪？当 GPT-4o 的上下文从 1K Token 扩展到 32K Token 时，其准确率会从 99.3% 暴跌至 69.7%------这不是模型能力问题，而是上下文管理失效导致的"注意力漂移"和"上下文中毒"-35。

AI 编程的真正瓶颈，已经从"模型博弈"转向了"工程化落地"-35。而 Claude Code + OpenSpec + Everything Claude Code 的协同组合，正是解决这一问题的完整方案：

• Claude Code：强执行力的终端原生 AI 编程智能体（发动机）

• OpenSpec：规范驱动的开发工作流框架（方向盘）

• Everything Claude Code：工程化配置系统，将 Claude Code 从"对话助手"升级为"智能工程系统"

三者结合，让 AI 开发从"凭感觉聊天"升级为"按规范执行的流水线"-32。

第一部分：三大工具深度解析

1.1 Claude Code ------ 终端原生的"智能体化执行"

Claude Code 是 Anthropic 推出的终端原生 AI 编程助手，基于强大的 Claude 模型构建，经过专门针对编程场景的深度优化，赋予了卓越的代码生成和理解能力-。与 Cursor 等"编辑器优先"的工具不同，Claude Code 选择了"智能体优先"的设计哲学-35。

1.1.1 核心架构：智能体循环

Claude Code 的工作流程被设计为一个闭环系统，模仿人类工程师的思维范式：

1. Gather（收集） ：不盲目读取整个目录，而是通过文件搜索、Git 状态检查及 CLAUDE.md 建立认知

2. Take Action（行动） ：基于推理跨多个文件执行编辑，或调用终端工具操作环境

3. Verify（验证） ：自动运行测试、捕捉错误并根据反馈调整方案------这是 Claude Code 最具杀伤力的特性

关键洞察：带验证步骤的代码生成过程，其成功率远高于单次生成 -35。

1.1.2 最新功能：Routines（云端自动化）

2026 年 4 月 14 日，Anthropic 在 Claude Code 中上线了 Routines 功能。它把提示词、代码仓库、连接器打成一个包，Claude 就能按时间表、API 调用或 GitHub 事件自动运行，全程在 Anthropic 云上执行，本地电脑可以直接关机-1。

三种触发方式：

• 时间表触发：每晚凌晨 2 点从 Linear 拉一个优先级最高的 bug，尝试修复，然后开一个 draft PR，你第二天上班直接 review

• API 调用触发：每个 Routine 有独立端点和鉴权 token，Datadog 告警、CI/CD hook 都可以直接调用

• GitHub 事件触发：PR、push、issue 等事件都可触发，可按作者、标签、分支做过滤

⚠️ Routines 目前以研究预览形式开放，仅对 Pro/Max/Team/Enterprise 订阅可用，每天有次数上限-1。

1.1.3 快速入门

# 在项目目录中启动 Claude Code
cd /path/to/your/project
claude
​
# 交互式会话示例
> what does this project do?
> add a hello world function to the main file
> commit my changes with a descriptive message
> write unit tests for the calculator functions

Claude Code 在修改文件之前总是请求许可，你可以批准单个更改或为会话启用"全部接受"模式-37。

1.2 OpenSpec ------ 规范驱动开发框架

OpenSpec 是面向 AI 智能体的轻量级规范驱动开发框架，通过"提案-审查-实施-归档"工作流，解决 AI 编程中的需求偏移与不可预测性问题-11。它以机器可读的规范为"单一真相源"，将模糊提示转化为可落地的工程实践。

1.2.1 核心概念

概念	定义
Specs（规范）	已实现的功能，位于 openspec/specs/
Changes（变更）	待实现的提案，位于 openspec/changes/
Archive（归档）	已完成并部署的变更记录-51

1.2.2 解决了什么问题

传统 AI 编程的痛点：

• Prompt 太长太复杂，AI 容易遗漏细节

• 多轮对话后 AI 忘记早期上下文

• 代码分散在对话里，没有集中管理

• AI 经常遗漏细微需求、添加不需要的功能

OpenSpec 的优势：

• 结构化输入：提案文件模板化，要求你必须把需求写清楚

• 可审查：AI 生成的提案你可以先审核，确认理解正确再执行

• 版本管理 ：每次变更都有记录，随时可回溯-15

1.2.3 安装与初始化

# 全局安装
npm install -g @fission-ai/openspec@latest
​
# 验证安装
openspec --version
​
# 在项目中初始化（需要 Node.js >= 20.19.0）
cd your-project
openspec init

初始化后生成的核心目录：

openspec/
├── specs/      # 当前系统规范（单一真相源）
├── changes/    # 变更提案目录
└── archive/    # 历史归档

初始化向导会让你选择 AI 编程工具，选择 Claude Code-34。

1.2.4 四大核心命令

命令	作用	适用场景
openspec-propose	发起变更提案	新增功能、重构模块
openspec-explore	分析系统规范	理解现有系统、评估变更风险
openspec-apply-change	将规范落地到代码	规范定稿后正式开发
openspec-archive-change	归档已完成的变更	功能上线后沉淀规范

这四个命令构成了完整的 Propose → Explore → Apply → Archive 工作流-34。

1.3 Everything Claude Code ------ 工程化配置系统

Everything Claude Code 是一套完整的 Claude Code 配置集合与方法论，来自 Anthropic 黑客松冠军项目，GitHub 累计 14 万+ stars，覆盖 12+ 语言系统-3。它含 47 个代理、181 个技能、79 个命令 ，支持上下文持久化、验证闭环、安全扫描与持续学习，将 AI 从"对话助手"升级为可交付、可沉淀的智能工程系统-3。

1.3.1 核心模块拆解

Agents（子代理） 把大任务拆成可控的子任务委托执行：

• planner：任务规划

• architect：架构设计

• code-reviewer：代码审查

• security-reviewer：安全审查

• build-error-resolver：构建错误修复

• e2e-runner：端到端测试

Skills（技能） 把可复用的工作流固化为"可调用的模块"：

• TDD 工作流

• 代码审查流程

• 文档同步

• 持续学习

• 评估与验证

Commands（命令） 兼容传统 CLI 风格命令与 ECC 自带命名空间命令-3。

1.3.2 核心设计哲学：用 CLI+Skills 替代 MCP

作者提出一个反直觉的观点：很多 MCP 其实可以替代。比如 GitHub MCP、Supabase MCP、Vercel MCP，这些平台本身就有很强的 CLI，MCP 只是在外面包了一层，却会占用上下文窗口、消耗更多 token。

解决方案：把 MCP 的功能拆成 Skills 和 Commands。

• 不用 GitHub MCP，而是创建 /gh-pr 命令直接调用 gh pr create

• 不用 Supabase MCP，而是创建 Skills 直接调用 Supabase CLI

这样做的好处：上下文窗口省出来了，Token 消耗降下来了，功能一样能用-21。

1.3.3 安装与配置

# 克隆仓库
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
​
# 复制配置到你的 Claude Code 配置目录
cp -r agents/ ~/.claude/agents/
cp -r skills/ ~/.claude/skills/
cp -r commands/ ~/.claude/commands/
cp -r hooks/ ~/.claude/hooks/
cp -r rules/ ~/.claude/rules/

安装后即可获得一套完整的工程化配置。可以根据需要选择性启用某些模块-22。

第二部分：三者协同开发实战

2.1 整体协同架构

三者协同的核心逻辑可以用一句话概括：

OpenSpec 定义"做什么"，Everything Claude Code 提供"怎么做"的方法论和工具集，Claude Code 作为执行引擎完成实际工作。

发动机

工具箱

方向盘

OpenSpec 规范驱动工作流

Propose 提案

Explore 分析

Apply 实施

Archive 归档

Everything Claude Code

47 Agents

181 Skills

79 Commands

Hooks & Rules

Claude Code 执行引擎

Gather 收集

Act 行动

Verify 验证

Routines 自动化

2.2 完整开发流水线

阶段 1：提案创建（Propose）

目标：将需求转化为结构化的变更提案，由人类确认后再执行。

协同机制：

• OpenSpec 提供 openspec-propose 命令，在 openspec/changes/ 下创建结构化提案目录，包含 proposal.md 和 tasks.md

• Everything Claude Code 的 planner Agent 辅助做需求分析和任务拆解

• Claude Code 读取项目现有规范和代码结构，生成初始提案草案

实战步骤：

# 在 Claude Code 中触发提案创建
> /openspec-propose "实现用户认证模块，支持邮箱密码登录和 JWT token 认证"
​
# Claude Code 会调用 OpenSpec 创建提案目录：
openspec/changes/add-user-auth/
├── proposal.md      # 需求背景、目标范围
├── tasks.md         # 可执行任务清单
└── specs/           # 规范增量
    └── user-auth/
        └── spec.md  # 详细功能规范

proposal.md 示例模板：

# Proposal: 实现用户认证模块
​
## 背景
当前系统缺少统一的用户认证机制，需要实现基于 JWT 的认证方案。
​
## 目标
- 实现邮箱密码注册和登录 API
- 实现 JWT token 签发和验证
- 实现 token 刷新机制
​
## 范围
- 包含：注册、登录、登出、token 刷新
- 不包含：OAuth 第三方登录、多因素认证
​
## 影响评估
- 新增 User 数据表
- 新增 /api/auth/* 路由
- 新增认证中间件

审查与对齐 ：这是最关键的步骤。打开 AI 生成的 proposal.md，检查需求理解是否准确、范围边界是否清晰、任务拆解是否完整。如果有偏差，直接修改文件内容，AI 在执行时会按照你修改后的版本执行-15。

阶段 2：分析探索（Explore）

目标：在动手写代码前，让 AI 充分理解现有系统规范和上下文。

协同机制：

• OpenSpec 提供 openspec-explore 命令，读取 openspec/specs/ 中的现有规范

• Everything Claude Code 的 explore Agent 进行技术调研和依赖分析

• Claude Code 分析代码库结构，评估变更影响范围

实战步骤：

# 分析现有系统
> /openspec-explore add-user-auth
​
# Claude Code 会输出：
# - 当前规范概览
# - 与现有模块的依赖关系
# - 潜在冲突和风险点
# - 建议的技术方案

Everything Claude Code 的 Explore Agent 输出会被保存为 research-summary.md，作为后续阶段的输入-21。

阶段 3：实施开发（Apply）

目标：按照规范严格生成代码。

协同机制：

• OpenSpec 提供 openspec-apply-change 命令，按规范驱动生成代码

• Everything Claude Code 的 5 阶段 Agent 编排模式确保任务被稳定执行

• Claude Code 执行实际的代码生成、测试运行、错误修复

5 阶段 Agent 编排模式：

阶段	Agent	输入	输出
Phase 1: RESEARCH	explore	提案内容	research-summary.md
Phase 2: PLAN	planner	调研结果	plan.md
Phase 3: IMPLEMENT	tdd-guide	执行计划	代码改动
Phase 4: REVIEW	code-reviewer	代码改动	review-comments.md
Phase 5: VERIFY	build-error-resolver	审查意见	修复后的代码

关键规则：

• 每个 Agent 只有一个清晰的输入，产出一个清晰的输出

• 输出变成下一阶段的输入，永远不要跳过阶段

• 阶段之间用 /clear 清理上下文

• 中间输出存到文件里-21

实战步骤：

# 在 Claude Code 中执行变更
> /openspec-apply-change add-user-auth
​
# Claude Code 将依次：
# 1. 读取 proposal.md 和 tasks.md
# 2. 调用 tdd-guide skill 按 TDD 方式实现
# 3. 生成代码文件
# 4. 运行测试验证
# 5. 如遇错误，调用 build-error-resolver 修复

验证闭环 ：Everything Claude Code 的核心价值之一是每一步都有检查与验证------测试覆盖率、安全扫描、验证闭环-3。security-reviewer Agent 会在实施后自动扫描代码安全风险。

阶段 4：归档（Archive）

目标：将已完成的变更沉淀为项目规范，形成可追溯的历史。

协同机制：

• OpenSpec 提供 openspec-archive-change 命令，将变更规范合并到 specs/

• Everything Claude Code 的 docs-sync Skill 同步更新项目文档

• Claude Code 自动提交代码、生成变更记录

实战步骤：

# 归档已完成的变更
> /openspec-archive-change add-user-auth
​
# 效果：
# - 将本次变更的规范合并到 openspec/specs/
# - 将变更目录移动到 openspec/archive/
# - 更新项目规范文档

归档后，openspec/specs/user-auth/spec.md 成为新的"单一真相源"，供后续开发引用-51。

2.3 日常开发场景协同示例

场景一：Bug 修复

Bug 修复通常不需要走完整提案流程（OpenSpec 建议跳过提案）-51，但仍可借助 Everything Claude Code 的工具链提升效率：

# 1. 描述问题
> there's a bug where users can submit empty forms - fix it
​
# 2. Claude Code 自动定位相关代码
# 3. 调用 build-error-resolver Agent 分析根因
# 4. 实现修复并运行相关测试
# 5. 调用 code-reviewer 审查修复质量
> /review "Check the form validation fix for edge cases"
​
# 6. 提交修复
> commit my changes with "fix: prevent empty form submission"

场景二：代码审查

利用 Everything Claude Code 的 code-reviewer Agent 进行自动化代码审查：

# 调用代码审查 Agent
> /agent code-reviewer "Review all changes in src/auth/ directory"
​
# Agent 会输出：
# - 代码质量问题
# - 安全风险提示
# - 性能改进建议
# - 与项目规范的一致性检查

场景三：自动化 CI/CD 集成

利用 Claude Code Routines 实现自动化工作流：

# .github/workflows/ai-review.yml 示例
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]
​
jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Trigger Claude Code Routine
        run: |
          curl -X POST https://api.claude.ai/code/routines/your-routine-id/run \
            -H "Authorization: Bearer ${{ secrets.CLAUDE_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"pr_number": "${{ github.event.pull_request.number }}"}'

Routine 触发后，Claude Code 会在云端自动执行代码审查、生成评论、标记潜在问题-1。

第三部分：最佳实践与优化策略

3.1 上下文工程优化

3.1.1 Token 优化策略

Everything Claude Code 提供了一套完整的 Token 优化方案：

模型选择策略：

模型	适用场景
Haiku	探索和搜索任务、简单单文件编辑、写文档
Sonnet	多文件实现（90% 的编码任务）、PR 审查
Opus	复杂架构设计、安全分析、需要深度推理的任务-21

运行时配置：

# 钩子严谨度配置文件（默认值：standard）
export ECC_HOOK_PROFILE=standard
​
# 禁用指定钩子以节省 token
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

3.1.2 上下文持久化

Everything Claude Code 的"内存支持"功能让跨会话的经验不会丢失-3：

# 查看带有置信度的学习直觉
/instinct-status

# 从他人导入直觉
/instinct-import

# 保存当前会话上下文
/save-context session-20260115

# 恢复之前保存的上下文
/load-context session-20260115

3.2 规范文件编写规范

OpenSpec 的规范文件遵循特定的格式要求：

## ADDED Requirements
​
### Requirement: 用户注册
系统必须提供用户注册功能，允许用户通过邮箱和密码创建账号。
​
#### Scenario: 成功注册
- **WHEN** 用户提供有效的邮箱和符合强度要求的密码
- **THEN** 系统创建用户账号并返回 JWT token
​
#### Scenario: 邮箱已存在
- **WHEN** 用户提供的邮箱已被注册
- **THEN** 系统返回 409 错误并提示“邮箱已被注册”
​
## MODIFIED Requirements
​
### Requirement: 认证中间件
[完整的修改后的需求，包含所有场景]

关键要求：

• 每个需求必须至少有一个 #### Scenario:（4 个 #）

• 使用 SHALL/MUST 表示规范性需求

• MODIFIED 时必须包含完整的需求内容（不是部分增量）-51

3.3 AgentShield 安全扫描

Everything Claude Code 内置了 AgentShield 安全扫描功能，可实时检测 12 类安全风险-3：

# 触发安全扫描
> /agent security-reviewer "Scan the authentication module for vulnerabilities"
​
# 扫描结果示例：
# - SQL 注入风险：auth.ts L45（建议使用参数化查询）
# - 敏感信息泄露：config.ts L12（检测到硬编码密钥）
# - 输入验证缺失：register.ts L78

3.4 持续学习机制

Everything Claude Code 的持续学习功能让 AI 能记住你的工程习惯：

# 启用持续学习
/enable-learning
​
# AI 会记录：
# - 你的代码风格偏好
# - 常用的设计模式
# - 项目的特定约定
​
# 查看已学习的直觉
/instinct-status

第四部分：常见问题与解决方案

4.1 AI 抢跑问题

问题：AI 不等需求确认就开始写代码。

解决方案 ：强制执行 OpenSpec 的 Propose → Explore → Apply 流程，让 AI 先输出提案供你审核，确认无误后再进入实施阶段-32。

4.2 上下文漂移问题

问题：多轮对话后 AI 忘记早期约束。

解决方案：

1. 使用 OpenSpec 将规范落盘到文件系统，而非依赖会话记忆

2. 使用 Everything Claude Code 的阶段间 /clear 清理机制

3. 使用上下文持久化功能保存关键状态-32

4.3 多 AI 协同问题

问题：不同开发者 + 不同 AI 助手理解不一致。

解决方案 ：以 OpenSpec 的 specs/ 目录作为单一真相源，所有 AI 助手（Claude Code、Cursor、Codex 等）都基于同一份规范工作，避免理解偏差-29。

4.4 Token 消耗过高

问题：使用 Claude Code 时 Token 消耗太快。

解决方案：

1. 用 CLI+Skills 替代 MCP，减少上下文占用-21

2. 按任务复杂度选择合适的模型（90% 用 Sonnet）

3. 阶段之间及时 /clear 清理上下文

4. 合理配置 ECC_HOOK_PROFILE 禁用不必要的钩子-21

第五部分：快速上手指南

5.1 最小化实践配置

如果你刚接触这套体系，建议从以下"最小实践"开始-32：

# 1. 安装 Claude Code
# 访问 claude.ai/code 下载安装
​
# 2. 安装 OpenSpec
npm install -g @fission-ai/openspec@latest
​
# 3. 在项目中初始化 OpenSpec
cd your-project
openspec init
​
# 4. 安装 Everything Claude Code 基础配置
git clone https://github.com/affaan-m/everything-claude-code.git
cp everything-claude-code/agents/code-reviewer ~/.claude/agents/
cp everything-claude-code/skills/tdd ~/.claude/skills/
​
# 5. 开始第一个规范驱动开发
claude
> /openspec-propose "add a health check endpoint"

5.2 推荐的学习路径

1. 第一周：熟悉 Claude Code 的基本交互，完成一些简单的代码修改和 bug 修复

2. 第二周：引入 OpenSpec，尝试为一个新功能创建提案、执行、归档

3. 第三周：逐步启用 Everything Claude Code 的 Agent（从 code-reviewer 开始）

4. 第四周：配置 Routines 实现自动化任务，形成完整的 AI 开发流水线

总结：从"工具"到"系统"

维度	传统 AI 编程	三者协同后
需求管理	散落在聊天记录中	结构化提案 + 版本管理
执行质量	不稳定、易偏离	规范驱动、按任务执行
可追溯性	难以回溯	完整的变更历史
工程化程度	依赖人工串联	Agent 编排 + 验证闭环
团队协作	理解不一致	单一真相源

OpenSpec 解决"做什么"的问题，Everything Claude Code 解决"怎么做"的问题，Claude Code 解决"谁来做"的问题。三者协同，将 AI 编程从"凭感觉聊天"升级为"可交付、可沉淀的智能工程系统"-3。

这套体系的本质不是让 AI 写更多代码，而是让 AI 少写那些方向看似对、其实需求没对齐的代码 -32。当你开始用这套方法做真实项目，你会发现：AI 不再是那个"高产但容易跑偏的同事"，而是一个可以信赖的工程伙伴。

Claude Code + OpenSpec + everything-claude-code AI 协同开发实战指南

* * *

一、为什么需要三者协同？

这三个工具分别解决AI辅助开发流程中完全不同层面的问题，理解这一点是关键[\-57](https://jishuzhan.net/article/2027735143826391041)。

1.1 各工具的定位

| 工具 | 定位 | 核心作用 | 类比 |

| --- | --- | --- | --- |

| **OpenSpec** | 规格驱动开发框架 | 解决 **"做什么"** 的问题------在写代码前，让人和AI就需求规格达成共识[\-57](https://jishuzhan.net/article/2027735143826391041) | 项目经理的需求管理系统 |

| **Claude Code** | AI编码执行引擎 | 解决 **"谁来写"** 的问题------基于规范生成定制化代码、迭代优化[\-29](https://blog.csdn.net/u013970991/article/details/159208812) | 发动机 |

| **ECC** | Claude Code配置增强层 | 解决 **"怎么做更好"** 的问题------提供生产就绪的Agents、Skills、Commands等组件，最大化Claude Code的执行能力[\-57](https://jishuzhan.net/article/2027735143826391041) | 瑞士军刀 |

1.2 为何三者缺一不可？

| 痛点 | 单一工具解决方案 | 三协同的价值 |

| --- | --- | --- |

| ❌ 需求模糊，AI输出不稳定 | 仅用Claude Code → 猜测用户意图 | OpenSpec提供结构化规格，让AI"按规格任务执行"[\-30](https://juejin.cn/post/7627448009643966483) |

| ❌ 跨会话AI失忆，重复解释 | 仅用Claude Code → 每次重新说明项目背景 | ECC的持续学习系统实现跨会话记忆，自动保存上下文[\-20](https://help.apiyi.com/zh-hant/everything-claude-code-plugin-guide-zh-hant.html) |

| ❌ 代码与文档脱节，团队协作混乱 | 仅用Claude Code → 无法形成系统级约束 | OpenSpec以规范为唯一数据源，确保代码与接口规范高度一致[\-29](https://blog.csdn.net/u013970991/article/details/159208812) |

| ❌ 编码效率不足，重复劳动多 | 仅用Claude Code → 缺少自动化工作流 | ECC提供47个Agent + 142个Skills，覆盖TDD、代码审查、安全扫描等全流程[\-20](https://help.apiyi.com/zh-hant/everything-claude-code-plugin-guide-zh-hant.html) |

| ❌ Token消耗失控，成本高 | 仅用Claude Code → 盲目消耗上下文 | ECC提供模型路由策略和记忆钩子，90%编码任务用Sonnet节省成本[\-39](https://developer.aliyun.com/article/1710809) |

这三个工具通过 **"规格化驱动"与"代理化执行"双轮驱动**，构建了一套完整的AI研发闭环\-。

1.3 三协同的核心理念

• **OpenSpec作为"方向盘"**：提供规范驱动开发工作流，锁定了意图后再实现[\-1](https://www.npmjs.com/package/@forztf/openspec)

• **Claude Code作为"发动机"**：强大的编码能力和上下文感知，擅长基于规范生成定制化可运行代码[\-29](https://blog.csdn.net/u013970991/article/details/159208812)

• **ECC作为"增程包"**：让Claude Code不只是聊天工具，而是可以被深度定制的AI Agent编排平台[\-20](https://help.apiyi.com/zh-hant/everything-claude-code-plugin-guide-zh-hant.html)

二、核心工作流：从需求到上线

2.1 完整工作流全景图

```markdown

┌─────────────────────────────────────────────────────────────────────────────┐

│ AI 协同开发完整工作流（从需求到上线） │

├─────────────────────────────────────────────────────────────────────────────┤

│ Phase 1: 需求探索 Phase 2: 规格定义 Phase 3: 开发实现 │

│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────┐ │

│ │/opsx:explore │───▶│/opsx:new │───▶│/tdd │ │

│ │ECC辅助: 调研阶段 │ │/opsx:ff │ │或/multi-plan │ │

│ │用Haiku模型快速探索 │ │ECC辅助: 按规格生成规划│ │ECC辅助: 多Agent │ │

│ └─────────────────────┘ └─────────────────────┘ └────────┬────────┘ │

│ │ │

│ Phase 4: 质量审查 Phase 5: 规范同步 Phase 6: 归档上线 │

│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────┐ │

│ │/code-review │───▶│/opsx:verify │───▶│/opsx:archive │ │

│ │/security-scan │ │/opsx:sync │ │/build-fix │ │

│ │ECC辅助: 多维度审查 │ │ECC辅助: 验证一致性 │ │ECC辅助: 构建修复 │ │

│ └─────────────────────┘ └─────────────────────┘ └─────────────────┘ │

└─────────────────────────────────────────────────────────────────────────────┘

```

2.2 Phase 1：需求探索------用 `/opsx:explore` 梳理思路

**目的**：在动手开发前进行开放式的需求探讨和方案调研，解决"不知道要做什么"或"怎么做不确定"的问题。

**操作步骤**：

```markdown

在 Claude Code 中执行

/opsx:explore 用户个人资料搜索筛选器功能

AI 会：

- 只读模式查看代码库，不会做任何写入操作

- 分析现有代码结构和实现方式

- 对比多种实现方案（全文搜索 vs 数据库索引 vs 缓存策略）

- 输出调研摘要 research-summary.md

```

**ECC 辅助技巧**：在这一阶段，用 ECC 配置的 **Haiku 模型**来做探索和搜索任务------速度快、便宜、够用[\-39](https://developer.aliyun.com/article/1710809)。完成后可直接无缝过渡到 `/opsx:new` 创建正式变更\-。

2.3 Phase 2：规格定义------用 OpenSpec 锁定需求

OpenSpec 采用 **制品依赖图（Artifact DAG）** 来管理每一个变更的完整生命周期[\-57](https://jishuzhan.net/article/2027735143826391041)。每个变更包含四类核心制品：

| 制品文件 | 内容 | 依赖关系 |

| --- | --- | --- |

| `proposal.md` | 为什么改、改什么、影响范围 | 根制品 |

| `specs/`（Delta格式） | 行为变化（ADDED/MODIFIED/REMOVED） | 依赖proposal |

| `design.md` | 技术方案、架构决策 | 可选 |

| `tasks.md` | 带复选框的实施清单 | 依赖specs和design |

**两种创建方式**：

```markdown

方式一：快速生成（推荐，一步到位）

/opsx:ff add-user-profile-search

方式二：分步控制（复杂场景）

/opsx:new add-user-profile-search

/opsx:continue # 逐步生成下一个制品

```

`/opsx:ff` 会一口气生成所有规划阶段所需的制品（proposal.md、specs/、design.md、tasks.md），是端到端开发最快的方式[\-12](https://www.cnblogs.com/linyb-geek/p/19698435#commentform)。

**ECC 辅助技巧**：在规格定义阶段，ECC 的 **`/plan`** 命令可以帮助你自动分解任务。OpenSpec 定义规格文档，ECC 提供 Agent 编排框架来执行------两个工具形成 **"规格枢纽 + 智能执行"** 的组合[\-29](https://blog.csdn.net/u013970991/article/details/159208812)。

2.4 Phase 3：开发实现------多 Agent 协同编码

这是整个工作流的核心执行阶段，需要 ECC 的强大编排能力。

**两种开发模式**：

```markdown

模式一：TDD 驱动开发（适合新功能）

/tdd "根据 spec 实现用户资料搜索筛选器"

ECC 会自动执行：Red（写失败测试）→ Green（最少代码实现）→ Refactor（优化）

模式二：多 Agent 并行开发（适合复杂任务）

/multi-plan "实现登录注册功能（前端+后端+数据库）"

/multi-execute

```

ECC 提出的 **5 阶段 Agent 编排模式** 是关键方法论[\-39](https://developer.aliyun.com/article/1710809)：

| 阶段 | Agent | 产出 |

| --- | --- | --- |

| **Phase 1: RESEARCH** | Explore agent | `research-summary.md` |

| **Phase 2: PLAN** | Planner agent | `plan.md` |

| **Phase 3: IMPLEMENT** | TDD-guide agent | 代码改动 |

| **Phase 4: REVIEW** | Code-reviewer agent | `review-comments.md` |

| **Phase 5: VERIFY** | Build-error-resolver | 修复后的代码 |

**关键规则**：

• 每个 Agent 只有一个清晰输入、产出一个清晰输出

• 输出变成下一阶段的输入

• 阶段之间用 `/clear` 清理上下文

• 中间输出存到文件里，最多循环 3 轮

2.5 Phase 4：质量审查------多维度代码审查

```markdown

代码质量审查（ECC）

/code-review

启动多Agent审查流程，按严重程度分级问题并提供修复建议

安全漏洞扫描（ECC）

/security-scan

AgentShield 扫描配置和代码库中的漏洞，1282+测试，102+条规则

语言专属审查

/go-review # Go语言专项审查

/python-review # Python专项审查（PEP 8）

```

ECC 的 **AgentShield** 安全扫描器可以扫描 AI 配置（CLAUDE.md、hooks、MCP 等）中的漏洞和注入风险，甚至支持三个 Opus 代理的红队/蓝队/审计流水线[\-57](https://jishuzhan.net/article/2027735143826391041)。

2.6 Phase 5：规范同步------验证实现一致性

```markdown

验证实现与制品要求是否一致

/opsx:verify

检查代码实现是否与 proposal、specs、design、tasks 全部对齐

同步增量规格到主规格（不归档）

/opsx:sync

将 delta specs 合并到 openspec/specs/ 主规范

```

OpenSpec 的 **Delta Spec** 概念是其核心优势：不是重写整个规格，而是描述变化量（ADDED/MODIFIED/REMOVED），这对存量项目（brownfield）极其友好[\-57](https://jishuzhan.net/article/2027735143826391041)。`/opsx:verify` 和 `/opsx:sync` 只在扩展工作流（workflows profile）中可用，可通过 `openspec config profile` 启用\-。

2.7 Phase 6：归档上线------完成闭环

```markdown

归档完成的变更

/opsx:archive

将 delta specs 合并回 openspec/specs/ 主规范，变更移动到 archive/

批量归档（多个变更）

/opsx:bulk-archive

智能检测和提示规格冲突

自动修复构建问题

/build-fix

ECC自动分析错误日志并尝试修复

```

归档是整个工作流的最后一步，`/opsx:archive` 将变更中的增量规范精确地合并到项目的主规范中，保留完整的审计记录[\-30](https://juejin.cn/post/7627448009643966483)。如果是团队协作场景，建议在归档前进行 PR 评审，确保规格变更获得团队认可。

2.8 实战示例：完整开发一个"用户资料搜索筛选器"

| 步骤 | 命令 | 产出 | 预计耗时 |

| --- | --- | --- | --- |

| ① 需求探索 | `/opsx:explore 用户资料搜索筛选器` | 调研报告 | 5-10分钟 |

| ② 规格定义 | `/opsx:ff add-user-search` | proposal + specs + tasks | 10-15分钟 |

| ③ TDD开发 | `/tdd "实现搜索筛选器"` | 测试用例 + 代码实现 | 20-40分钟 |

| ④ 代码审查 | `/code-review` | 审查报告 | 5-10分钟 |

| ⑤ 安全扫描 | `/security-scan` | 安全报告 | 3-5分钟 |

| ⑥ 验证同步 | `/opsx:verify` | 一致性验证 | 2-3分钟 |

| ⑦ 归档上线 | `/opsx:archive` | 规范更新 | 1-2分钟 |

三、进阶技巧

3.1 ECC 5 阶段 Agent 编排实战

ECC 提出的 **5 阶段 Agent 编排模式** 是这套方案最值得学习的部分[\-39](https://developer.aliyun.com/article/1710809)：

**完整示例流程**：

```markdown

Phase 1: RESEARCH - 用 Explore agent 做调研

/plan "调研支付网关集成方案，输出 research-summary.md"

Phase 2: PLAN - 用 Planner agent 做规划

/plan "基于调研结果，输出 plan.md"

Phase 3: IMPLEMENT - 用 TDD guide 实现

/tdd "按 plan.md 实现支付网关集成"

Phase 4: REVIEW - 用 Code reviewer 审查

/code-review

Phase 5: VERIFY - 用 Build error resolver 修复

/build-fix

中间用 /clear 清理上下文

```

3.2 模型路由策略优化 Token 成本

根据 ECC 作者的实践，90% 的编码任务用 Sonnet 即可[\-39](https://developer.aliyun.com/article/1710809)：

| 模型 | 适用场景 | 成本考量 |

| --- | --- | --- |

| **Haiku** | 探索、搜索、简单编辑、写文档 | 最便宜，速度快 |

| **Sonnet** | 多文件实现、PR审查、日常编码 | 性价比最佳，90%任务用此 |

| **Opus** | 复杂架构设计、安全分析、深度推理 | 最贵，仅在必要时使用 |

在 Claude Code 中切换模型：

```markdown

/model sonnet # 日常编码

/model haiku # 探索任务

/model opus # 复杂架构

```

3.3 用 CLI + Skills 替代 MCP 节省 Token

ECC 的作者提出了一个反直觉但有效的思路：很多 MCP 其实可以用 CLI + Skills 替代[\-39](https://developer.aliyun.com/article/1710809)。

| 替代前 | 替代后 | 节省效果 |

| --- | --- | --- |

| GitHub MCP | `/gh-pr` 命令直接调用 `gh pr create` | 上下文窗口省出，Token消耗下降 |

| Supabase MCP | Skills 直接调用 Supabase CLI | 功能不变，成本降低 |

```markdown

.claude/settings.json 中配置自定义命令

{

"commands": {

"gh-pr": "gh pr create --title \"1\\" --body \\"2\""

}

}

```

3.4 多 Session 并行开发

对于复杂项目，可以将任务拆分为多个独立的 session 并行处理：

```markdown

Session 1：前端开发

claude -c --add-dir ./frontend

Session 2：后端开发（新终端）

claude -c --add-dir ./backend

Session 3：数据库设计（新终端）

claude -c --add-dir ./database

```

拆分后每个 session 专注一个领域，上下文更清晰，token 消耗更低。

3.5 持续学习系统：让 AI 越用越聪明

ECC 的 Instinct 持续学习系统（v2）是亮点[\-57](https://jishuzhan.net/article/2027735143826391041)：

```markdown

查看学习到的所有"直觉"

/instinct-status

显示每个直觉及其置信度评分

将相关直觉聚类并进化为可复用技能

/evolve

评估持续学习系统的效果

/learn-eval

```

这个系统会自动从会话中提取模式，支持跨团队导入导出。建议团队定期执行 `/evolve`，将积累的经验固化为团队共享的技能。

3.6 OpenSpec 中文配置

团队协作时建议统一文档语言，在 `openspec/config.yaml` 中添加：

```markdown

context: |

语言：中文（简体）

所有产出物必须用简体中文撰写。

```

3.7 团队协作：OpenSpec + ECC 的分工

OpenSpec 和 ECC 在团队中可以形成清晰的分工[\-57](https://jishuzhan.net/article/2027735143826391041)：

| 层级 | 工具 | 团队职责 |

| --- | --- | --- |

| **需求与规格管理** | OpenSpec | PM/架构师定义变更提案（proposal/specs），团队评审 |

| **编码执行增强** | ECC | 开发者用 `/tdd`、`/code-review` 等命令执行开发 |

| **质量与安全闭环** | ECC + 自动化 | 代码审查、安全扫描纳入 PR 流程 |

| **知识积累与传承** | ECC Instinct | 定期执行 `/evolve` 沉淀团队经验 |

四、避坑指南

4.1 OpenSpec 命令找不到？版本问题最常见

**问题**：`/opsx:explore` 等命令不存在，只有 `/openspec:proposal` 等旧命令。

**原因**：OpenSpec v1.0 将旧的三命令体系（proposal → apply → archive）重构为 10 个 OPSX 命令[\-10](https://newreleases.io/project/github/Fission-AI/OpenSpec/release/v1.0.0)。旧命令已被移除。

**解决方案**：

```markdown

1. 升级到最新版本

npm install -g @fission-ai/openspec@latest

2. 运行初始化

openspec init

3. 确认版本

openspec --version # 应为 1.0.0+

```

4.2 Token 窗口过载的三大原因及解决

| 原因 | 占比 | 解决方案 |

| --- | --- | --- |

| 会话历史累积 | 15-60% | 使用 `/compact` 或 `/clear` 清理[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/) |

| 文件自动读取 | 5-25% | 配置 `.claudeignore` 排除不必要文件[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/) |

| 系统提示+CLAUDE.md | 2-4% | 精简 CLAUDE.md 到 150 行以内，用项目符号而非段落[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/) |

**监控 Token 消耗**：

```markdown

/cost # 实时显示 token 用量和预估费用

```

当上下文超过 80% 时，Claude Code 会自动发出警告[\-48](https://institute.sfeir.com/en/claude-code/claude-code-context-management/faq/)。

4.3 各阶段常见问题与解决方案

| 阶段 | 常见问题 | 解决方案 |

| --- | --- | --- |

| **OpenSpec 初始化** | 工具列表中没有 Claude Code | 更新到最新版本后重新运行 `openspec init`[\-10](https://newreleases.io/project/github/Fission-AI/OpenSpec/release/v1.0.0) |

| **规格定义** | 变更制品依赖关系混乱 | 用 `/opsx:continue` 逐步生成，避免手动创建 |

| **ECC 安装** | 插件安装后命令不可用 | 确认手动复制了 rules 文件，重启 Claude Code |

| **代码审查** | 审查结果过于冗长 | 用 `/code-review` 启动多Agent审查，问题会按严重程度分级 |

| **归档** | delta specs 合并冲突 | 用 `/opsx:bulk-archive` 批量归档，自动检测冲突[\-10](https://newreleases.io/project/github/Fission-AI/OpenSpec/release/v1.0.0) |

4.4 Agent 编排的常见误区

| 误区 | 正确做法 |

| --- | --- |

| 跳过 RESEARCH 直接写代码 | 永远不要跳过阶段，每个 Agent 产出是下一阶段输入[\-39](https://developer.aliyun.com/article/1710809) |

| 一个 Agent 做所有事 | 每个 Agent 只有一个清晰的输入，产出一个清晰的输出[\-39](https://developer.aliyun.com/article/1710809) |

| 不清理中间上下文 | 阶段之间用 `/clear` 清理上下文，避免上下文污染 |

| 不保存中间输出 | 中间输出存到文件里，便于追溯和复用 |

五、性能优化

5.1 三大 Token 优化策略

根据 Claude Code 上下文管理最佳实践，以下三项策略组合使用可将 token 消耗降低 60% 以上[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/)：

| # | 优化策略 | 预估效果 | 难度 |

| --- | --- | --- | --- |

| 1 | **Plan Mode** | \-50% tokens | 低 |

| 2 | **PreCompact Hooks** | \-30% 信息丢失 | 中 |

| 3 | **Multi-sessions** | \-60% per session | 低 |

**策略 1：激活 Plan Mode**

在 Claude Code 中用 `Shift+Tab` 切换到 Plan Mode，AI 会先规划后执行，减少 50% 的 token 消耗[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/)。也可以在对话中直接要求："请在 Plan mode 下分析..."

**策略 2：配置 PreCompact Hooks**

在 `.claude/settings.json` 中添加：

```markdown

{

"hooks": {

"PreCompact": [{

"matcher": "*",

"hooks": [{

"type": "command",

"command": "echo 'Critical: 项目核心规则和API设计' >> .claude/compact-context.md"

}]

}]

}

}

```

PreCompact hooks 确保在上下文压缩时保留关键的指令和规则，避免丢失重要信息[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/)。

**策略 3：拆分任务为多 Session**

将大型任务拆分为多个有针对性的子任务，每个子任务在一个独立的 session 中完成。这能让上下文窗口始终保持在较低水平，减少 60% 的每个 session token 消耗[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/)。

5.2 CLAUDE.md 优化技巧

| 优化项 | 效果 | 操作 |

| --- | --- | --- |

| 限制在 150 行以内 | \-15% 系统 tokens | 精简内容，只保留核心规则\- |

| 使用项目符号而非段落 | 提升解析效率 | AI 解析列表比文本块更高效\- |

| 配置 `.claudeignore` | \-25% 文件 tokens | 排除 node\_modules、dist 等目录[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/) |

| 精准文件读取 | \-90% 读取 tokens | 用 `Read src/auth/login.ts` 而非 `Find all bugs`[\-48](https://institute.sfeir.com/en/claude-code/claude-code-context-management/faq/) |

5.3 上下文窗口管理技巧

Claude Code 使用 **200,000 token 窗口**，约 150,000 个单词[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/)。每个组件的大致消耗：

| 组件 | 平均消耗 | 占比 |

| --- | --- | --- |

| 系统提示 + CLAUDE.md | 3,000-8,000 tokens | 2-4% |

| 自动读取的文件 | 10,000-50,000 tokens | 5-25% |

| 会话历史 | 30,000-120,000 tokens | 15-60% |

| 当前响应 | 5,000-20,000 tokens | 3-10% |

**实用技巧**：

```markdown

/compact # 智能压缩对话历史为摘要

/clear # 硬重置，彻底清空当前会话

/cost # 实时查看 token 消耗

```

会话饱和在 180,000 tokens 时的处理时间是 40,000 tokens 时的 3-5 倍，因此及时使用 `/compact` 非常关键[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/)。

5.4 模型选择优化

| 模型 | 适用场景 | 注意事项 |

| --- | --- | --- |

| **Haiku** | 探索、搜索、简单编辑 | 不要用于复杂架构设计 |

| **Sonnet** | 多文件实现、PR审查、日常编码 | 默认选择，90%任务用此 |

| **Opus** | 复杂架构、安全分析 | 仅在必要时使用，成本最高[\-39](https://developer.aliyun.com/article/1710809) |

```markdown

日常编码用 Sonnet

/model sonnet

探索任务用 Haiku

/model haiku

复杂架构用 Opus

/model opus

```

5.5 ECC 验证循环：持续质量保障

ECC 内置了 **验证循环（Validation Loop）** 机制，在 Agent 编排过程中持续检查输出质量[\-39](https://developer.aliyun.com/article/1710809)：

```markdown

┌──────────────────────────────────────────────────────┐

│ 编排器评估每个 sub-agent 的返回 │

│ ↓ │

│ 接受前先问 follow-up 问题 │

│ ↓ │

│ Sub-agent 回去找答案，再返回 │

│ ↓ │

│ 循环直到满意，最多 3 轮 │

└──────────────────────────────────────────────────────┘

```

**关键原则**：传递目标上下文，而不只是查询。Sub-agent 只知道字面查询，不知道背后的目的，所以需要迭代检索模式[\-39](https://developer.aliyun.com/article/1710809)。

六、总结

6.1 核心优势总结

| 维度 | 原生 Claude Code | 三协同方案 | 提升效果 |

| --- | --- | --- | --- |

| **需求对齐** | 凭感觉猜测 | 结构化规格驱动 | 告别"开盲盒"式AI编程[\-30](https://juejin.cn/post/7627448009643966483) |

| **编码效率** | 手动描述任务 | ECC Agent 自动编排 | 减少80%重复编码工作[\-29](https://blog.csdn.net/u013970991/article/details/159208812) |

| **跨会话记忆** | 每次重新解释 | ECC持续学习系统 | 自动保存/加载上下文 |

| **代码质量** | 无内置审查 | 多Agent审查+安全扫描 | 1282+测试，102+规则[\-57](https://jishuzhan.net/article/2027735143826391041) |

| **团队协作** | 无规范约束 | OpenSpec统一规范 | 文档与代码高度一致 |

| **Token成本** | 盲目消耗 | 模型路由+记忆钩子 | 降低40-60%[\-40](https://institute.sfeir.com/en/claude-code/claude-code-context-management/optimization/) |

6.2 三工具协同的核心价值

```markdown

OpenSpec:

本质: 规范驱动开发框架

解决的问题: "做什么"（What）

核心机制: 制品依赖图 + Delta Spec

类比: 方向盘

Claude Code:

本质: AI编码执行引擎

解决的问题: "谁来写"（Write）

核心机制: 上下文感知 + 代码生成

类比: 发动机

ECC:

本质: Claude Code配置增强层

解决的问题: "怎么做更好"（How Better）

核心机制: Agents + Skills + Hooks + Instinct

类比: 增程包/瑞士军刀

```

三者形成 **"规格化驱动 + 代理化执行"双轮驱动** 的完整闭环\-。

6.3 快速上手指南

如果你是第一次接触这套方案，建议按以下顺序快速上手：

| 步骤 | 任务 | 预计耗时 |

| --- | --- | --- |

| **Step 1** | 安装 Claude Code 和 Node.js | 10分钟 |

| **Step 2** | 安装 OpenSpec：`npm install -g @fission-ai/openspec@latest`，运行 `openspec init` | 5分钟 |

| **Step 3** | 安装 ECC：插件市场安装 + 手动复制规则文件 | 5分钟 |

| **Step 4** | 运行 `openspec config profile` 切换 workflows 配置，启用扩展工作流 | 2分钟 |

| **Step 5** | 执行一次完整流程：`/opsx:ff` → `/tdd` → `/code-review` → `/opsx:archive` | 20分钟 |

**推荐学习路径**：

1. 先用 OpenSpec 独立跑通一个变更提案和归档流程，理解 SDD 工作流

2. 再用 ECC 跑通 `/plan` 和 `/tdd` 命令，体验 Agent 编排

3. 最后将两者结合，用 `/opsx:ff` 定义规格，用 `/tdd` 实现代码，完成完整闭环

6.4 适用场景建议

| 场景 | 推荐方案 | 理由 |

| --- | --- | --- |

| 个人开发者、小团队日常开发 | **OpenSpec + Claude Code** | 足够使用，ECC可选 |

| 需要长期维护的复杂项目 | **三协同全配** | 规格+记忆+审查缺一不可 |

| 团队协作、多 AI 工具混用 | **OpenSpec + ECC** | OpenSpec工具无关，ECC增强执行 |

| 快速原型验证 | **仅 Claude Code** | 三协同配置成本高，原型阶段可跳过 |

| 存量项目（brownfield）增量开发 | **OpenSpec + ECC** | Delta Spec对存量项目极其友好[\-57](https://jishuzhan.net/article/2027735143826391041) |

6.5 最终建议

三协同的核心价值在于将 **"凭感觉"的 AI 编程转变为"按规格"的工程化开发**[\-30](https://juejin.cn/post/7627448009643966483)。OpenSpec 提供规范和可追溯性，ECC 提供执行能力和效率提升，Claude Code 提供底层的编码能力。这套方案尤其适合需要长期维护、团队协作、质量要求高的项目。

建议从一个小功能开始，用 `openspec init` 初始化项目，用 `/opsx:ff` 创建第一个变更提案，用 ECC 的 `/tdd` 命令实现，体验完整的闭环流程。上手后，你可能会发现"开盲盒"式的 AI 编程再也回不去了。