Vibe-Spec-Sync Skill

by @qingni in Tools

# Install this skill:

npx skills add qingni/vibe-spec-sync

Or install specific skill: npx add-skill https://github.com/qingni/vibe-spec-sync

# Description

这是一个用于保持 Vibe Coding 变更与 Spec 文档同步的 Skill。当检测到代码变更时，自动分析变更类型并提示更新相关 spec 文档。

# SKILL.md

Vibe-Spec-Sync Skill

概述

这是一个用于保持 Vibe Coding 变更与 Spec 文档同步的 Skill。当检测到代码变更时，自动分析变更类型并提示更新相关 spec 文档。

⚠️ 重要提醒: Spec-First 是推荐的工作方式，本 Skill 是在已发生 Vibe Coding 后的补救措施。
请先阅读变更规模与流程匹配指南了解何时应该走完整的 Spec-First 流程。

适用场景

在使用本 Skill 之前，请先判断变更规模：

变更规模	推荐做法	是否使用本 Skill
微小修复	直接提交	❌ 不需要
小型 Bug	直接改 + 补 Change Log	⚡ 可选使用
中型功能	应该先更新 Spec	✅ 如已 Vibe Coding，使用本 Skill 补救
大型重构	必须先写 ADR + Spec	✅ 如已 Vibe Coding，使用本 Skill 补救

详细分层标准见：workflow-guide.md

触发条件

当以下情况发生时，自动触发此 Skill：
- 完成一次 Vibe Coding 修复或功能调整
- 用户明确请求同步 spec
- 检测到代码文件有实质性变更

工作流程

Step 1: 检测上下文

获取当前 Git 分支名称
自动检测对应的 spec 目录（规则：specs/{分支名}/）
读取 spec 目录下的核心文件：
spec.md - 主需求文档
tasks.md - 任务列表
data-model.md - 数据模型（如存在）
api.md - API 定义（如存在）

Step 2: 分析变更

根据以下分类分析本次变更的类型：

变更类型	标识	说明	Spec 更新点
Bug 修复	`BUG_FIX`	修复现有逻辑的错误	在 Change Log 中记录
行为变更	`BEHAVIOR_CHANGE`	改变了功能的行为方式	更新 spec.md 相关章节
数据结构	`DATA_STRUCTURE`	修改了数据模型/Schema	更新 data-model.md
API 变更	`API_CHANGE`	修改了接口定义	更新 api.md
性能优化	`PERFORMANCE`	优化性能但不改变行为	在 Change Log 中记录
紧急修复	`HOTFIX`	紧急生产问题修复	在 Change Log 中记录，标注优先级

Step 3: 生成 Spec 更新

根据变更类型，生成相应的 spec 更新内容：

3.1 Change Log 更新（所有变更必须）

在 spec.md 末尾的 ## Change Log 章节添加记录：

## Change Log

| 日期 | 类型 | 变更内容 | 影响需求 |
|------|------|----------|----------|
| YYYY-MM-DD | {变更类型} | {变更描述} | {影响的需求编号或"无"} |

3.2 需求更新（BEHAVIOR_CHANGE / DATA_STRUCTURE / API_CHANGE）

定位到 spec.md 中受影响的需求章节
使用 ~~原内容~~ 标记废弃内容
添加新内容并标注 [Updated: YYYY-MM-DD]

Step 4: ADR 决策

对于以下类型的变更，询问用户是否需要创建 ADR：

BEHAVIOR_CHANGE - 推荐创建
DATA_STRUCTURE - 推荐创建
API_CHANGE - 推荐创建
BUG_FIX - 如果修复揭示了设计缺陷，可选创建
PERFORMANCE - 如果涉及架构权衡，可选创建

ADR 文件存放位置：specs/{分支名}/decisions/ADR-{序号}-{描述}.md

Step 5: 输出同步总结

完成同步后，输出总结报告：

## 📋 Spec 同步报告

**分支**: {分支名}
**变更类型**: {类型}
**同步时间**: {时间戳}

### 更新内容
- [x] spec.md Change Log 已更新
- [ ] data-model.md 已更新（如适用）
- [ ] api.md 已更新（如适用）
- [ ] ADR 已创建（如适用）

### 变更摘要
{简要描述本次变更}

Spec 目录自动检测规则

当前分支: 002-doc-chunking-opt
  ↓
查找目录: specs/002-doc-chunking-opt/
  ↓
如果不存在，尝试模糊匹配（去除数字前缀）
  ↓
如果仍不存在，提示用户手动指定

注意事项

保持原子性: 每次只更新与本次变更相关的内容
可追溯性: 所有变更必须记录在 Change Log 中
最小侵入: 只修改必要的部分，不要重写整个文档
确认优先: 在实际修改 spec 文件前，先向用户展示将要做的更改
Vibe 标记: 如果是事后补救，在 Change Log 中添加 [VIBE] 标记

参考文档

变更规模与流程匹配指南 - 何时使用 Spec-First vs Vibe Coding
变更类型分类指南 - 如何判断变更类型
ADR 模板 - 架构决策记录模板

# README.md

Vibe-Spec-Sync

🔄 让 Vibe Coding 变更与 Spec 文档保持同步的 AI Skill

特性 • 安装 • 使用方法 • 工作流程 • 参考文档 • 许可证

简介

Vibe-Spec-Sync 是一个专为 AI 辅助编程设计的 Skill，用于解决 Vibe Coding（即兴编程）后 Spec 文档与实际代码不同步的问题。

当你在 AI 助手的帮助下快速修复 Bug 或调整功能后，这个 Skill 会自动分析变更类型，并帮助你更新相关的 Spec 文档，保持文档与代码的一致性。

⚠️ 重要提醒: Spec-First 是推荐的工作方式，本 Skill 是在已发生 Vibe Coding 后的补救措施。

特性

🔍 自动检测: 根据 Git 分支名自动定位对应的 Spec 目录
📊 智能分类: 自动识别变更类型（Bug 修复、行为变更、API 变更等）
📝 增量更新: 最小侵入式更新，只修改必要的文档部分
📋 Change Log: 自动维护变更日志，保证可追溯性
🏗️ ADR 支持: 对重大变更推荐创建架构决策记录

安装

将此 Skill 添加到你的 AI 编程助手中：

# 克隆仓库
git clone https://github.com/your-username/vibe-spec-sync.git

# 将 SKILL.md 添加到你的项目或 AI 工具配置中

使用方法

适用场景

在使用本 Skill 之前，请先判断变更规模：

变更规模	推荐做法	是否使用本 Skill
微小修复	直接提交	❌ 不需要
小型 Bug	直接改 + 补 Change Log	⚡ 可选使用
中型功能	应该先更新 Spec	✅ 如已 Vibe Coding，使用本 Skill 补救
大型重构	必须先写 ADR + Spec	✅ 如已 Vibe Coding，使用本 Skill 补救

触发方式

当以下情况发生时，可触发此 Skill：

完成一次 Vibe Coding 修复或功能调整
明确请求同步 Spec
检测到代码文件有实质性变更

变更类型

变更类型	标识	说明	Spec 更新点
Bug 修复	`BUG_FIX`	修复现有逻辑的错误	在 Change Log 中记录
行为变更	`BEHAVIOR_CHANGE`	改变了功能的行为方式	更新 spec.md 相关章节
数据结构	`DATA_STRUCTURE`	修改了数据模型/Schema	更新 data-model.md
API 变更	`API_CHANGE`	修改了接口定义	更新 api.md
性能优化	`PERFORMANCE`	优化性能但不改变行为	在 Change Log 中记录
紧急修复	`HOTFIX`	紧急生产问题修复	在 Change Log 中记录，标注优先级

工作流程

┌─────────────────────────────────────────────────────────────┐
│                    Vibe-Spec-Sync 工作流                      │
└─────────────────────────────────────────────────────────────┘

     ┌──────────────┐
     │  Vibe Coding │
     │   完成变更    │
     └──────┬───────┘
            │
            ▼
     ┌──────────────┐
     │ Step 1:      │
     │ 检测上下文    │  ──→ 获取分支名，定位 Spec 目录
     └──────┬───────┘
            │
            ▼
     ┌──────────────┐
     │ Step 2:      │
     │ 分析变更类型  │  ──→ BUG_FIX / BEHAVIOR_CHANGE / ...
     └──────┬───────┘
            │
            ▼
     ┌──────────────┐
     │ Step 3:      │
     │ 生成Spec更新  │  ──→ Change Log + 需求更新
     └──────┬───────┘
            │
            ▼
     ┌──────────────┐
     │ Step 4:      │
     │ ADR 决策     │  ──→ 重大变更推荐创建 ADR
     └──────┬───────┘
            │
            ▼
     ┌──────────────┐
     │ Step 5:      │
     │ 输出同步总结  │  ──→ 生成同步报告
     └──────────────┘

目录结构

vibe-spec-sync/
├── README.md              # 本文件
├── SKILL.md               # Skill 定义文件
├── LICENSE                # MIT 许可证
├── references/            # 参考文档
│   ├── workflow-guide.md  # 变更规模与流程匹配指南
│   ├── change-types.md    # 变更类型分类指南
│   └── adr-template.md    # ADR 模板
└── scripts/               # 辅助脚本

参考文档

变更规模与流程匹配指南 - 何时使用 Spec-First vs Vibe Coding
变更类型分类指南 - 如何判断变更类型
ADR 模板 - 架构决策记录模板

最佳实践

Spec-First 优先: 尽量在编码前先更新 Spec
及时同步: Vibe Coding 后立即运行 Skill 同步
保持原子性: 每次只同步与本次变更相关的内容
添加 VIBE 标记: 事后补救的变更在 Change Log 中添加 [VIBE] 标记

许可证

本项目采用 MIT 许可证。

Made with ❤️ for better documentation

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.

Vibe-Spec-Sync Skill

# Description

# SKILL.md

Vibe-Spec-Sync Skill

概述

适用场景

触发条件

工作流程

Step 1: 检测上下文

Step 2: 分析变更

Step 3: 生成 Spec 更新

3.1 Change Log 更新（所有变更必须）

3.2 需求更新（BEHAVIOR_CHANGE / DATA_STRUCTURE / API_CHANGE）

Step 4: ADR 决策

Step 5: 输出同步总结

Spec 目录自动检测规则

注意事项

参考文档

# README.md

Vibe-Spec-Sync

简介

特性

安装

使用方法

适用场景

触发方式

变更类型

工作流程

目录结构

参考文档

最佳实践

许可证

# Related Skills

# Supported AI Coding Agents

Confirm

Submit a Skill