OpenSpec 定规矩 + LingMa 练技能 + GitNexus 理关系，让 AI 写代码不再“瞎编“

唯媛

269人浏览 · 2026-05-25 09:56:19

唯媛 · 2026-05-25 09:56:19 发布

AI 编程三件套：OpenSpec 定规矩 + LingMa 练技能 + GitNexus 理关系，让 AI 写代码不再"瞎编"

本文面向所有正在用 AI 辅助编程的开发者，用最直白的大白话，讲清楚这三个工具各自解决什么问题、怎么搭、注意什么。

一、先说说为什么要用这三个工具

现在用 AI 写代码的人越来越多了，不管是 Cursor、Claude Code、Qoder、通义灵码还是 GitHub Copilot，大家都在用。但用着用着你会发现几个让人头疼的问题：

AI 不守规矩 —— 你让它写个 API，它给你返回的格式每次都不一样；你让它改个功能，它顺手把你之前写好的逻辑给改了。没有统一约束，AI 就像一匹脱缰的野马。
技能没法复用 —— 你好不容易调教出一个"代码审查"的提示词，在 Cursor 里能用，换到 Claude Code 又得重新配一遍。每个工具各玩各的，skills 散落一地。
AI 看不懂你的项目 —— 你让 AI 改一个函数，它压根不知道这个函数被哪些地方调用、依赖了哪些模块，改完直接炸一片。缺乏对代码关系的全局理解。

这三个问题，刚好对应三款工具来解决：

痛点	工具	一句话概括
AI 不守规矩	OpenSpec	项目的"法律条文"，告诉 AI 什么能做、什么不能做
技能没法复用	LingMa（通义灵码）	把提示词变成可复用的"技能包"，一次编写到处使用
AI 看不懂项目	GitNexus	把代码库变成"关系地图"，让 AI 看清楚每个函数之间的来龙去脉

下面逐个拆解。

二、OpenSpec —— 给 AI 立规矩

2.1 它是什么？

OpenSpec 是 Fission AI 开源的一套规范驱动开发（SDD）框架。通俗讲，就是你在项目里建一个 openspec/ 目录，把所有"项目该怎么做"的规矩写进去。以后每次让 AI 干活，它会先读这些规矩，然后按规矩办事。

它的核心目录结构长这样：

openspec/
├── specs/          # 主规范库 —— 项目的"宪法"
├── changes/        # 变更提案 —— 每次要改什么，先写提案
├── archive/        # 归档 —— 改完的提案存这里
├── AGENTS.md       # AI 执行手册 —— AI 干活前必读
└── project.md      # 项目规范字典 —— 技术栈、架构、编码规范

2.2 核心工作流（5 步闭环）

OpenSpec 把每次改动都变成一次有据可查的流程：

提案（Propose） → 审查对齐（Review & Align） → 实施（Implement） → 归档（Archive） → 合并回主规范

也就是说，不是张嘴就让 AI 改代码，而是先写提案，说清楚要改什么、为什么改、预期效果是什么，审过之后再动手。改完之后归档，主规范保持同步。

2.3 搭建步骤

前提条件：Node.js 18+ 环境。

第一步，全局安装 OpenSpec CLI：

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

第二步，进入你的项目根目录，初始化：

cd your-project
openspec init

初始化完成后，项目根目录会多出一个 openspec/ 文件夹。

第三步：编写 project.md

这是最关键的一步。project.md 是你的"项目说明书"，AI 每次干活前都会读它。里面应该写清楚：

# 项目上下文

## 技术栈
- 后端：Python 3.11 + Flask 3.0
- 数据库：MySQL 8.0 + PostgreSQL 14
- ORM：SQLAlchemy 2.0

## 代码风格
- 变量命名：snake_case
- 函数命名：动词_名词，如 get_user_by_id
- 每行不超过 120 字符

## 架构约束
- 路由层（routes/）只负责参数校验和响应，不写业务逻辑
- 业务逻辑全部放在 services/ 层
- 数据库操作通过 models/ 定义
- 不直接在路由里写 SQL

## 安全边界
- 所有数据库查询必须参数化，禁止字符串拼接 SQL
- 用户输入必须校验和转义
- 敏感配置通过环境变量注入，不硬编码

第四步：配置 AGENTS.md

这个文件告诉 AI 在什么情况下该干什么：

# AI Agent 执行规范

## 工具使用规范
- 修改代码前必须先读取相关文件
- 修改后必须运行相关测试
- 新功能必须先创建 openspec 变更提案

## 代码修改边界
- 可以修改：services/、routes/、models/
- 谨慎修改：config/（涉及全局配置）
- 禁止修改：migrations/（数据库迁移文件，由专人管理）

## 输出格式规范
- 所有 API 返回统一格式：{"code": 0, "data": {}, "message": "success"}
- 错误响应：{"code": 错误码, "data": null, "message": "错误描述"}

第五步：创建变更提案

# 每次要改东西时，先创建提案
openspec proposal "新增批量导出Excel功能"

这会在 changes/ 下生成一个对应的提案目录，你在这个目录里写清楚要改什么，AI 照着执行。

2.4 注意事项

不要跳过提案直接改代码 —— OpenSpec 的灵魂就是"先写提案再动手"，跳过这一步等于白装。
project.md 越详细越好 —— 这个文件是 AI 的"知识库"，你写得越清楚，AI 犯错的概率越低。不要怕啰嗦。
规范要持续维护 —— 项目在变，规范也要跟着变。每次改完代码记得把变更归档、合并回主规范。
团队共享 —— openspec/ 目录要纳入 Git 版本控制，全团队共用一套规范。
兼容性 —— OpenSpec 原生支持 Claude Code、Cursor、Windsurf、GitHub Copilot 等 20+ 工具，Qoder 通过 AGENTS.md 也能兼容。

三、LingMa（通义灵码）—— 把经验沉淀成技能

3.1 它是什么？

通义灵码是阿里云推出的 AI 智能编码助手。除了基础的代码补全和智能问答，它支持一套文件级 Skill（技能）系统，让你可以把反复使用的提示词、规则、模板打包成一个个"技能包"。

3.2 Skill 解决了什么问题？

以前我们是这样用 AI 的：

“帮我审查这段代码，关注安全漏洞、性能问题、代码规范…”

每次都要重新打一遍提示词，烦不烦？

有了 Skill 之后：

“用代码审查技能检查这段代码”

一句话搞定。因为"代码审查"的标准、流程、检查清单已经预先写好在 Skill 文件里了。

3.3 Skill 长什么样？

每个 Skill 是一个目录，核心文件是 SKILL.md，结构如下：

.lingma/skills/
└── code-review/
    ├── SKILL.md          # 必须：技能描述文件
    ├── checklist.json    # 可选：检查清单
    └── examples/         # 可选：使用示例

SKILL.md 的模板：

---
name: code-review
description: 代码审查技能，检查安全、性能、规范
trigger: 审查代码、code review、检查代码
---

# 角色
你是一名资深代码审查专家。

# 目标
对提供的代码进行全面审查，发现潜在问题。

# 执行流程
1. 先通读代码，理解业务逻辑
2. 按以下维度逐项检查：
   - 安全漏洞（SQL注入、XSS、敏感信息泄露）
   - 性能问题（N+1查询、未使用索引、内存泄漏）
   - 代码规范（命名、注释、异常处理）
   - 逻辑错误（边界条件、空值处理）
3. 输出审查报告

# 规则
- 每个问题必须指明具体行号
- 每个问题必须给出修改建议
- 按严重程度排序：致命 > 严重 > 建议

# 输出模板
## 审查报告

### 致命问题
- [行号] 问题描述 → 修改建议

### 严重问题
- [行号] 问题描述 → 修改建议

### 建议
- [行号] 问题描述 → 修改建议

3.4 搭建步骤

第一步：安装通义灵码插件

到通义灵码官网下载对应 IDE 的插件：

VS Code：插件市场搜索 “TONGYI Lingma”
JetBrains（IDEA / PyCharm 等）：插件市场搜索 “通义灵码”

安装后用阿里云账号登录。

第二步：创建技能目录

在项目根目录下（或用户全局目录 ~/.lingma/skills/）创建技能：

# 项目级 Skill（推荐，可以 Git 共享给团队）
mkdir -p .lingma/skills/code-review

# 用户级 Skill（个人使用，所有项目通用）
mkdir -p ~/.lingma/skills/code-review

第三步：编写 SKILL.md

在 code-review/ 目录下创建 SKILL.md，按上面的模板填写内容。

第四步：使用技能

在灵码对话框中输入：

请使用技能 code-review 审查 app/routes/api.py

灵码会自动加载 SKILL.md 里的规则，按你定义的流程执行。

3.5 实用 Skill 推荐

Skill 名称	用途
`code-review`	代码审查
`api-standard`	API 设计标准检查
`generate-test`	自动生成单元测试
`db-migration`	数据库迁移脚本生成
`error-handling`	统一异常处理模式
`log-format`	日志格式规范检查

3.6 注意事项

Skill 层级 —— 项目级 .lingma/skills/ 优先级高于用户级 ~/.lingma/skills/，同名 Skill 以项目级为准。
纳入版本控制 —— 项目级的 .lingma/skills/ 一定要提交到 Git，这样整个团队共享同一套技能。
触发词要精准 —— SKILL.md 中的 trigger 字段决定了什么时候自动激活这个技能，不要设得太宽泛。
持续迭代 —— Skill 不是写一次就完事，用着用着你会发现规则不够完善，持续打磨。
Windows 路径 —— Windows 下用户级 Skill 目录在 %USERPROFILE%\.lingma\skills\。

四、GitNexus —— 给 AI 画一张代码地图

4.1 它是什么？

GitNexus 是一个代码知识图谱工具，把你的代码库扫描一遍，生成一张"关系地图"——哪个函数调用了哪个函数、哪个类继承了哪个类、哪个模块依赖了哪个模块，一目了然。

然后通过 MCP（Model Context Protocol）协议，把这个地图喂给 AI 编辑器，让 AI 在改代码之前能看清楚全局影响。

4.2 为什么需要它？

举个实际场景：

你让 AI 改 db_connector.py 里的 get_connection 函数。

没有 GitNexus：AI 直接改了，但它不知道 batch_export_service.py、file_generator.py、data_transformer.py 都在调用这个函数，改完参数之后三个文件全部报错。

有了 GitNexus：AI 在动手之前先查知识图谱，发现这个函数被 4 个地方调用，于是它知道：要么保持向后兼容，要么一并修改所有调用方。

4.3 核心能力

依赖关系图谱 —— 自动解析 import / require，画出模块之间的依赖关系
调用链追踪 —— 从入口函数一路追踪到底层实现
代码聚类 —— 把功能相关的代码自动分组
MCP 集成 —— 把图谱数据通过 MCP 协议暴露给 AI 编辑器

4.4 搭建步骤

前提条件：Node.js 18+、Git。

# 验证环境
node -v    # 必须 >= 18
npm -v
git --version

第一步：全局安装

npm install -g gitnexus --legacy-peer-deps

Windows 下建议加上 --legacy-peer-deps 避免依赖冲突。

第二步：索引你的项目

进入项目根目录，执行：

cd your-project
gitnexus analyze

这个命令会：

扫描所有源代码文件
解析 Python 的 import 关系（也支持 JS/TS/Java/Go 等）
构建函数 / 类之间的调用图
生成知识图谱索引文件

第三步：配置 MCP 接入 AI 编辑器

GitNexus 支持一键配置：

gitnexus setup

这条命令会自动检测你安装了哪些 AI 编辑器，并写入对应的 MCP 配置。

如果想手动配置，以 Claude Code 为例：

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Cursor 则需要编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

第四步：验证

配置完成后，在 AI 编辑器里问一句：

“这个项目有哪些模块？它们之间的依赖关系是怎样的？”

如果 AI 能回答出来，说明 GitNexus 已经生效了。

4.5 也可以用 Web UI（不需要装 CLI）

如果你只是想快速体验，直接访问 gitnexus.vercel.app，拖拽项目文件夹进去，浏览器里就能看到可视化图谱。

不过 Web 版受浏览器内存限制，大型项目建议用 CLI。

4.6 注意事项

大项目首次索引比较慢 —— 代码量越大，首次 analyze 越久，耐心等待。
不会扫描 node_modules 等依赖目录 —— GitNexus 只索引你项目自己的代码。
MCP 配置是全局的 —— 每个编辑器只需要配一次，所有项目共享。
Windows 用户建议用管理员权限运行终端 —— 避免文件写入权限问题。
代码变更后需要重新索引 —— 每次大幅改动后，重新跑 gitnexus analyze。
隐私安全 —— CLI 模式完全本地运行，代码不会上传到任何服务器。

五、三件套组合拳：怎么串联起来

这三个工具不是孤立的，而是互补的。来看一套理想的工作流：

                    ┌──────────────────┐
                    │    OpenSpec      │
                    │  "做什么、怎么做"  │
                    └────────┬─────────┘
                             │ 规范定义
                             ▼
┌──────────────┐    ┌──────────────────┐    ┌──────────────┐
│   GitNexus   │───▶│    AI 编辑器      │◀───│   LingMa     │
│  "代码关系图"  │    │  (Qoder/Cursor)  │    │  "技能包"    │
│              │    │                  │    │              │
│  告诉AI：     │    │  干活前：         │    │  告诉AI：    │
│  谁依赖谁     │    │  1.读OpenSpec规范 │    │  按什么流程  │
│  谁调用谁     │    │  2.查GitNexus关系 │    │  按什么标准  │
│  影响范围     │    │  3.加载LingMa技能 │    │  输出什么格式│
└──────────────┘    └──────────────────┘    └──────────────┘

实际工作流举例：

假设你要给 flask_data_exporter 项目新增一个"导出 PDF"功能：

OpenSpec：先创建变更提案 openspec proposal "新增PDF导出功能"，在提案里写清楚需求、接口格式、文件存储位置。
GitNexus：AI 通过 MCP 查询现有导出逻辑（batch_export_service.py、file_generator.py），搞清楚现有代码的调用链，确保新功能不破坏已有逻辑。
LingMa：AI 加载 api-standard 技能，确保新接口的返回格式和现有接口一致；加载 error-handling 技能，确保异常处理风格统一。
动手写代码，写完归档。

六、总结

工具	一句话	核心价值
OpenSpec	项目的"法律条文"	让 AI 守规矩、改代码有据可查
LingMa Skill	可复用的"技能包"	把经验沉淀下来，一次编写到处使用
GitNexus	代码的"关系地图"	让 AI 看清全局，改代码不炸一片

三个工具加在一起，本质上是把 AI 编程从"碰运气"变成了**“工程化”**——有规范、有流程、有上下文。

现在的 AI 已经很能写代码了，缺的不是能力，而是约束和上下文。这三个工具正好补上了这块拼图。

参考链接：

OpenSpec GitHub：https://github.com/Fission-AI/OpenSpec

通义灵码官网：https://lingma.aliyun.com

GitNexus GitHub：https://github.com/abhigyanpatwari/GitNexus

GitNexus Web UI：https://gitnexus.vercel.app