轻量级 Vibe Coding 规范驱动开发框架 — 让 AI 编码助手从"凭感觉写代码"进化到"按规范生成代码"

不侵入业务 · Go 单二进制 · 按需组合 · 多 Agent 适配

当你使用 AI 编码助手（Cursor、Claude Code、Copilot、Windsurf）时，它们并不了解你的项目规范——编码风格、架构约束、安全规则、设计模式……结果就是不断手动纠正 AI 生成的代码。

VibeSpec 用一套 spec（约束）+ skill（技能）+ knowledge（知识） 三层规范体系解决这个问题：

  Spec（约束）          Skill（技能）         Knowledge（知识）
  MUST / SHALL         HOW-TO / PATTERN     CONTEXT / REFERENCE
  ──────────           ──────────           ──────────────
  编码规范              设计模式              业务术语表
  架构约束              代码模板              API 参考
  安全规则              工作流程              架构决策记录

          └──── 按 技术栈 + 业务域 按需组合安装 ────┘

特性	VibeSpec	OpenSpec	SpecKit	Rules Files
三层规范体系	spec+skill+knowledge	仅 spec	仅 spec	扁平规则
按需安装	按技术栈/业务域匹配	—	—	—
零侵入	.vibespec/ 目录	.openspec/	较多文件	根目录文件
无运行时依赖	Go 单二进制	Node.js	Python/uv	纯文件
多 Agent 支持	自动生成各 IDE 规则	支持	支持	需手动维护
版本管理	semver + lock 文件	—	—	—
包之间可依赖	支持	—	—	—

# macOS / Linux 一键安装
curl -fsSL https://get.vibespec.dev | sh

# Go install
go install github.com/vibespec/cli/cmd/vibespec@latest

# Homebrew
brew install vibespec/tap/vibespec

# 1. 初始化项目（自动检测技术栈，推荐匹配的规范包）
cd my-project
vibespec init

# 2. 安装规范包
vibespec install --auto            # 自动匹配安装
vibespec install @vibespec/go-api  # 或手动指定

# 3. 生成 AI 助手规则文件
vibespec compose --link

完成后，你的 AI 编码助手就会自动遵循安装的规范来生成代码。

my-project/
├── .vibespec/                    # 所有规范文件（零侵入）
│   ├── vibespec.yaml             # 项目配置
│   ├── vibespec.lock             # 版本锁文件
│   ├── specs/                    # 约束规范（MUST/SHALL）
│   ├── skills/                   # 技能模式（SHOULD/RECOMMEND）
│   ├── knowledge/                # 领域知识（CONTEXT）
│   └── compose/                  # 自动生成的 Agent 规则文件
│       ├── .cursorrules
│       ├── CLAUDE.md
│       ├── .github/copilot-instructions.md
│       └── .windsurfrules
├── .cursorrules → .vibespec/compose/.cursorrules     # 符号链接（可选）
├── CLAUDE.md → .vibespec/compose/CLAUDE.md
└── ... 你的业务代码（不受影响）

命令	说明
vibespec init	初始化项目，自动检测技术栈并推荐规范包
vibespec install [包名]	安装规范包（支持 --auto、--only specs 等）
vibespec update	更新已安装的规范包（支持 --check 检查更新）
vibespec compose	组合生成各 AI 助手的规则文件（支持 --link 创建符号链接）
vibespec list	查看已安装的规范包
vibespec search <关键词>	搜索可用的规范包
vibespec create <类型> <名称>	创建自定义规范文件（spec / skill / knowledge）
vibespec validate	校验规范文件格式
vibespec doctor	诊断环境配置问题

VibeSpec 可为以下 AI 工具自动生成对应格式的规则文件：

AI 助手	生成文件
Cursor	.cursorrules
Claude Code	CLAUDE.md
GitHub Copilot	.github/copilot-instructions.md
Windsurf	.windsurfrules
通用格式	AGENTS.md

vibespec init 会自动识别你的项目：

• 语言：Go、Node.js、Python、Rust、Java
• 框架：Gin、Echo、Fiber、Chi、Gorm、React、Vue、Next.js 等
• 基础设施：PostgreSQL、MySQL、Redis、MongoDB、Kafka（通过 docker-compose.yaml）
• AI 工具：Cursor、Claude Code、Copilot、Windsurf

并根据检测结果推荐安装最匹配的规范包。

VibeSpec 使用基于 Git 的注册表分发规范包，无需部署服务器。

在 .vibespec/vibespec.yaml 中配置：

registries:
  # 官方注册表
  - name: official
    type: git
    url: https://github.com/vibespec/registry.git

  # 公司内部私有注册表
  - name: company
    type: git
    url: https://github.com/mycompany/vibespec-registry.git

包名	说明
@vibespec/go-api	Go API 开发规范（编码风格、错误处理、安全、设计模式）
@vibespec/git-vcs	Git 提交规范

更多规范包持续添加中。

vibespec create spec my-coding-style
vibespec create skill my-logging-pattern
vibespec create knowledge my-domain-glossary

规范文件采用带 YAML frontmatter 的 Markdown 格式：

---
id: my-coding-style
type: spec
tags: [go, api, style]
version: 1.0.0
priority: 100
---

# My Coding Style

## 命名规范
- 函数名 MUST 使用驼峰命名
- 包名 MUST 全小写且不含下划线

## 错误处理
- MUST NOT 忽略 error 返回值
- MUST 使用 fmt.Errorf 包装错误并添加上下文

vibespec pack ./my-specs             # 打包
vibespec publish ./my-specs.tar.gz   # 发布到注册表

或直接通过 Git 发布到自己的注册表仓库。详见 vibespec-registry/README.md。

vibespec/
├── vibespec-kit/                  # 核心工具集
│   ├── cli/                       # CLI 工具（Go）
│   ├── registry-server/           # 可选的 HTTP 注册表服务器（Go + Gin）
│   ├── examples/                  # 示例规范包 & 项目演示
│   └── DESIGN.md                  # 详细设计文档
└── vibespec-registry/             # 官方 Git 规范包注册表
    ├── packages/                  # 已发布的规范包
    └── index.yaml                 # 包索引

组件	说明	技术栈
CLI	核心命令行工具，单二进制分发	Go 1.22 + Cobra
Registry Server	可选的 HTTP 注册表服务	Go 1.22 + Gin
Registry	Git-based 规范包仓库	Git + YAML

# 构建 CLI
cd vibespec-kit/cli
go build -o vibespec ./cmd/vibespec

# 构建 Registry Server（可选）
cd vibespec-kit/registry-server
go build -o registry-server ./cmd/registry-server
# 或使用 Docker
docker compose up -d

• 零侵入：所有规范文件集中在 .vibespec/ 目录，不改动业务代码结构
• 单二进制：Go 编译，无 Python / Node.js 依赖，一条命令安装
• 按需组合：像 npm 包一样按技术栈和业务域匹配安装，不安装用不到的规范
• 三层分离：约束（必须遵守）、技能（推荐实践）、知识（背景上下文）各司其职
• 多 Agent 适配：一份规范，自动生成各 AI 工具的原生规则文件

详细设计文档：vibespec-kit/DESIGN.md

MIT