OpenSpec 与 CodeGraph 搭配使用指南

# 概述

OpenSpec 和 CodeGraph 是两个强大的 AI 开发辅助工具，各自解决不同的问题：

工具	核心价值
OpenSpec	规范驱动开发，确保 AI 理解需求
CodeGraph	代码知识图谱，提供精准上下文

两者搭配使用，可以形成完整的 需求 → 规范 → 代码 工作流：

需求输入 → OpenSpec 规范 → AI 理解需求 → CodeGraph 精准定位 → 生成代码

# 快速安装

# 安装 OpenSpec

# 全局安装
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

1
2
3
4
5

# 安装 CodeGraph

方式一：一键安装（推荐）

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

1
2
3
4
5

方式二：npm 安装

npm i -g @colbymchenry/codegraph

# 验证安装

openspec --version
codegraph --version

1
2

# 项目初始化

# 初始化 OpenSpec

cd your-project
openspec init

1
2

这会创建：

openspec/
├── specs/           # 规范文件
├── changes/         # 变更提案
└── project.md       # 项目上下文

1
2
3
4

# 初始化 CodeGraph

codegraph init

这会创建 .codegraph/ 目录并构建代码索引。

# 验证状态

# 查看 OpenSpec 状态
openspec list

# 查看 CodeGraph 状态
codegraph status

1
2
3
4
5

# 常用命令速查

# OpenSpec 命令

命令	说明
`openspec init`	初始化项目
`openspec list`	查看所有变更
`openspec show <name>`	显示变更详情
`openspec validate <name>`	验证规范格式
`openspec archive <name>`	归档变更
`openspec update`	更新 AI 指导

# CodeGraph 命令

命令	说明
`codegraph init`	初始化项目索引
`codegraph status`	查看索引状态
`codegraph sync`	手动同步变更
`codegraph install`	配置 AI 代理
`codegraph upgrade`	升级版本
`codegraph serve --mcp`	启动 MCP 服务

# 搭配使用流程

# 工作流概览

┌─────────────────────────────────────────────────────────────┐
│                      开发工作流                               │
├─────────────────────────────────────────────────────────────┤
│  1. 需求分析    →  OpenSpec 创建变更提案                      │
│  2. 规范定义    →  OpenSpec 编写规范 + 验收标准               │
│  3. 代码定位    →  CodeGraph 查找相关代码                     │
│  4. 影响分析    →  CodeGraph 追踪调用链                       │
│  5. 代码实现    →  AI 按规范生成代码                          │
│  6. 归档更新    →  OpenSpec 归档变更                          │
└─────────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9
10

# 第一步：创建变更提案

使用 OpenSpec 定义需求：

# 在 Claude Code 中
/openspec:proposal Add user authentication with JWT

1
2

AI 会自动创建：

proposal.md - 变更说明
tasks.md - 实施任务
specs/ - 规范差异

# 第二步：定位相关代码

在编写规范时，使用 CodeGraph 查找相关代码：

你：我需要实现用户认证功能，请帮我找到相关的代码

AI：（通过 CodeGraph）
- 找到 routes/auth.ts - 认证路由
- 找到 models/User.ts - 用户模型
- 找到 middleware/auth.ts - 认证中间件
- 调用链：login → validateCredentials → generateToken

1
2
3
4
5
6
7

# 第三步：完善规范

结合 CodeGraph 提供的代码上下文，完善 OpenSpec 规范：

# Delta for Auth

## ADDED Requirements

### Requirement: JWT Authentication
The system SHALL issue a JWT token on successful login.

#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT token is returned with 24h expiration

#### Scenario: Invalid credentials
- WHEN a user submits invalid credentials
- THEN an error is returned with status 401

### Requirement: Token Validation
The system SHALL validate JWT tokens on protected routes.

#### Scenario: Valid token
- WHEN a request includes a valid JWT
- THEN the request proceeds to the handler

#### Scenario: Expired token
- WHEN a request includes an expired JWT
- THEN an error is returned with status 401

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 第四步：实施变更

# 应用变更
/openspec:apply auth-jwt

1
2

AI 会：

按照 tasks.md 清单逐步实施
使用 CodeGraph 定位需要修改的文件
根据规范生成代码

# 第五步：验证和归档

# 验证变更
openspec validate auth-jwt

# 归档
openspec archive auth-jwt --yes

1
2
3
4
5

# 实战示例

# 示例：添加用户权限检查功能

# 场景描述

需要在现有系统中添加基于角色的权限检查功能。

# 完整工作流

1. 使用 CodeGraph 分析现有代码

你：请分析当前系统的权限相关代码

AI：（通过 CodeGraph）
找到以下相关代码：
- middleware/auth.ts - 现有认证中间件
- models/Role.ts - 角色模型
- models/Permission.ts - 权限模型
- 调用链：request → authMiddleware → handler

1
2
3
4
5
6
7
8

2. 创建 OpenSpec 变更提案

你：基于现有代码，创建添加 RBAC 权限检查的变更提案

/openspec:proposal Add RBAC permission check

1
2
3

3. 编写规范

# Delta for Auth

## ADDED Requirements

### Requirement: Role-Based Access Control
The system SHALL check user permissions before allowing access to protected resources.

#### Scenario: User has required permission
- WHEN a user with the required permission accesses a protected resource
- THEN the request proceeds normally

#### Scenario: User lacks required permission
- WHEN a user without the required permission accesses a protected resource
- THEN an error is returned with status 403

### Requirement: Permission Assignment
Administrators SHALL be able to assign roles to users.

#### Scenario: Assign role
- WHEN an administrator assigns a role to a user
- THEN the user gains all permissions associated with that role

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

4. 使用 CodeGraph 追踪影响

你：如果我修改 auth middleware，会影响哪些文件？

AI：（通过 CodeGraph）
影响分析：
- 直接调用者：15 个路由处理器
- 间接依赖：3 个测试文件
- 建议更新：middleware/auth.ts, types/auth.ts, tests/auth.test.ts

1
2
3
4
5
6
7

5. 实施变更

/openspec:apply rbac-permission

6. 归档

openspec archive rbac-permission --yes

# 最佳实践

# 规范编写实践

# 结合 CodeGraph 编写精准规范

❌ 不好的规范：
"添加权限检查"

✅ 好的规范（结合 CodeGraph 分析）：
"在 authMiddleware 之后添加 checkPermission middleware，
检查用户是否具有访问资源所需的权限。
需要修改 routes/*.ts 中的路由定义，添加 permission 参数。"

1
2
3
4
5
6
7

# 明确验收标准

#### Scenario: Permission check passed
- GIVEN a user with "admin" role
- WHEN accessing /api/users endpoint
- THEN the request proceeds with status 200

#### Scenario: Permission denied
- GIVEN a user with "viewer" role
- WHEN accessing /api/users endpoint
- THEN returns status 403 with message "Insufficient permissions"

1
2
3
4
5
6
7
8
9

# 代码修改实践

# 先分析再修改

1. 使用 CodeGraph 查找相关代码
2. 使用 CodeGraph 追踪影响范围
3. 在 OpenSpec 中记录修改计划
4. 按规范实施修改

1
2
3
4

# 保持规范与代码同步

# 修改代码前
openspec validate feature-name

# 修改代码后
openspec show feature-name  # 确认任务完成
openspec archive feature-name

1
2
3
4
5
6

# 团队协作实践

# 共享规范和索引

# 规范文件纳入版本控制
git add openspec/

# CodeGraph 索引本地存储，每个开发者独立索引
# 但共享 .codegraph/config.json 配置

1
2
3
4
5

# 变更评审流程

1. 开发者创建变更提案
2. 团队评审规范
3. 使用 CodeGraph 验证影响范围
4. 批准后实施
5. 归档更新主规范

1
2
3
4
5

# 常见问题

# Q: 两个工具的安装顺序有要求吗？

A: 没有严格要求，但建议先安装 OpenSpec，再安装 CodeGraph。CodeGraph 的 install 命令会自动检测已配置的 AI 代理。

# Q: 如何处理大型项目的首次索引？

A: CodeGraph 首次索引可能需要几分钟，建议：

# 在后台运行
nohup codegraph init &

# 或使用 screen/tmux
screen -S codegraph
codegraph init

1
2
3
4
5
6

# Q: 规范变更后需要重新索引吗？

A: 不需要。OpenSpec 管理的是需求规范，CodeGraph 管理的是代码索引，两者独立。但当规范导致代码变更时，CodeGraph 会自动检测并同步。

# Q: 如何在多个项目间切换？

# 项目 A
cd /path/to/project-a
openspec list
codegraph status

# 项目 B
cd /path/to/project-b
openspec list
codegraph status

1
2
3
4
5
6
7
8
9

每个项目有独立的 openspec/ 和 .codegraph/ 目录。

# 性能对比

# 单独使用 vs 搭配使用

指标	单独 OpenSpec	单独 CodeGraph	搭配使用
需求理解	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
代码定位	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
影响分析	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
代码质量	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐
可维护性	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐

# 效率提升

场景	传统方式	搭配使用	提升
理解新需求	多轮沟通	规范驱动	减少 60% 沟通
定位代码	grep + read	一键查询	减少 70% 工具调用
影响分析	手动追踪	自动图谱	减少 80% 分析时间
代码生成	多次迭代	一次到位	减少 50% 返工

# 参考链接

# OpenSpec

官方网站: https://openspec.dev/
GitHub: https://github.com/Fission-AI/OpenSpec
NPM: https://www.npmjs.com/package/@fission-ai/openspec

# CodeGraph

官方网站: https://getcodegraph.com/
GitHub: https://github.com/colbymchenry/codegraph
NPM: https://www.npmjs.com/package/@colbymchenry/codegraph

# 相关文章

# 总结

OpenSpec 和 CodeGraph 搭配使用，形成了完整的 AI 辅助开发链：

阶段	工具	作用
需求理解	OpenSpec	规范驱动，明确需求
代码定位	CodeGraph	精准查询，减少搜索
影响分析	CodeGraph	自动追踪，避免遗漏
代码生成	两者结合	规范约束 + 上下文精准
变更管理	OpenSpec	归档追踪，持续演进

一句话总结：OpenSpec 确保 AI 理解「要做什么」，CodeGraph 帮助 AI 精准找到「在哪里做」，两者结合实现高效、可预测的 AI 辅助开发。

本文介绍 OpenSpec 与 CodeGraph 的搭配使用方法，帮助开发者构建完整的 AI 辅助开发工作流。

#OpenSpec #CodeGraph #Claude Code #AI开发 #规范驱动开发

上次更新: 2026/7/20 14:13:30

← codebase-memory-mcp 使用指南 Linux 安装 Hermes Agent→