Vibe Coding 开发规范套件

一套为 AI 辅助开发（vibe coding）量身打造的工程纲领。 让 AI 在你的项目里"按规矩办事"——更规范、更高效、更准确。

🚀 一键接入（npx，推荐）

在任意项目根目录执行一行命令(任何电脑、跨 Win/Mac/Linux):

npx vibe-coding-rules

也可以用 scope 别名 npx @xrilang/vibe-coding-rules,两者内容完全一致。

脚本会:

• 📄 写入 CLAUDE.md + docs/(已有 CLAUDE.md 时让你当场选合并策略)
• 🛠 询问 7 个 workflow skill 装到用户级(~/.claude/skills/,所有项目共用)还是项目级(./.claude/skills/)
• 📝 打印下一步提示

零运行时依赖,Node ≥ 18 即可。

也可以手动 git clone 整个仓库使用——见下文。

这是什么

一套项目级别的文档套件，不是插件、不是 MCP、不是 Skill 文件。

把它整个复制进你的项目根目录后，AI 工具（Claude Code / Cursor / 其他读取 CLAUDE.md 的助手）会在每次进入项目时自动加载顶层约定，并按文档套件中的工作流和规范执行任务。

为什么是文档套件而不是 Skill / MCP

| 形态 | 利 | 弊 | 是否采用 | |---|---|---|---| | Claude Code Skill (SKILL.md) | 按需加载 | 需要安装、跨工具不通用、承载多工作流偏臃肿 | ✗ | | MCP Server | 能力强 | 跑服务、需依赖、严重过度工程 | ✗ | | 文档套件（本方案） | 零安装、跨工具、可版本化、可裁剪、CLAUDE.md 自动加载 | 需要 AI 阅读力（现代 LLM 都满足） | ✓ |

核心洞察：vibe coding 的关键是"AI 自动知道规矩"，而 CLAUDE.md 正好满足这点——它会被自动塞进 AI 的上下文，无需任何调用动作。

套件结构

.
├── CLAUDE.md                       # 顶层协作纲领（AI 自动加载，精简）
├── README.md                       # 本文件
└── docs/
    ├── 索引.md                     # 完整文档地图与场景查表
    ├── 文档更新日志.md             # 文档变更总账
    ├── 00_通用规范/                # 改代码前必读（9 篇）
    ├── 01_需求分析/                # 需求文档归档区
    ├── 02_功能设计/                # 方案文档归档区
    ├── 03_问题记录/                # BUG / 技术债
    │   └── 技术债.md
    ├── 04_代码审查/                # 审查报告归档区
    ├── 05_回归用例/                # 回归用例永久库（按模块）
    ├── 10_工作流程/                # 5 个核心工作流
    ├── 12_用户手册/                # 面向最终用户
    ├── 11_字典/                    # 系统字典 + 错误码字典
    ├── 20_模板/                    # 交付物模板 + 已填写样例
    └── 90_最佳实践/                # 5 篇协作 / 避坑指南

完整索引见 docs/索引.md。

使用方法

一、首次接入新项目

方式 A — npx(推荐):

# 在目标项目根目录
npx vibe-coding-rules
# 或: npx @xrilang/vibe-coding-rules (scope 别名，内容一致)

方式 B — 手动复制(无 Node 环境):

1. git clone https://github.com/mllt992/vibe-coding-rules.git
2. 把 template/CLAUDE.md 和 template/docs/ 复制到目标项目根目录
3. 把 template/.claude/skills/workflow-* 复制到 ~/.claude/skills/(用户级)或 <项目>/.claude/skills/(项目级)

两种方式接入后必做:

1. 编辑 CLAUDE.md 第 0 节，补充本项目的：技术栈、业务领域、代码目录、运行方式
2. 浏览 docs/00_通用规范/，按本项目实际情况删/改/补示例（通用规范是技术栈无关的，但项目里通常需要写实例）
3. 提交到版本库——规范从此成为项目契约

二、与已有 CLAUDE.md 合并

如果项目已有 CLAUDE.md：

• 把本套件的 CLAUDE.md 改名为 CLAUDE_纲领.md 放到根目录
• 在项目原有 CLAUDE.md 顶部加一行：本项目协作纲领见 ./CLAUDE_纲领.md
• 或者把本套件 CLAUDE.md 内容并入原文件，保留路由表和铁律

三、日常使用

发指令时用工作流意图关键词，AI 会自动路由：

"做个用户角色管理功能"        → 100 新功能开发
"列表页查询太慢，优化一下"     → 101 优化升级
"导出按钮报 500，修一下"      → 102 BUG 修复
"帮我审一下这个 PR"           → 103 代码审查
"给这个功能补测试用例"        → 104 测试

意图模糊时 AI 会反问，鼓励它问而不是猜。

四、裁剪建议

• 小型项目：可只保留 CLAUDE.md + 10_工作流程/ + 90_最佳实践/
• 后端纯后端项目：可删除 04_前端开发规范.md
• 个人项目无 Code Review：可删 103_代码审查工作流程.md
• 核心铁律不要删（CLAUDE.md 第 1 节）

五、任务规模分级（重要）

不是每个任务都要走完整工作流。CLAUDE.md §2 把任务分四档：

• 微改动（typo / 改颜色 / 单行）：直接做，无需文档
• 小任务（单模块 / < 100 行）：跳过方案文档，仍做自审 + 测试
• 标准任务：走完整工作流
• 高风险任务（资金 / 鉴权 / DB 迁移）：标准 + 强制预审 + 回滚预案

发指令时主动给定级会让 AI 不至于改个按钮颜色都先发需求分析文档。

设计哲学

1. AI 是同事而不是工具 —— 给清楚的工作流和规范，让它独立完成、自我审查
2. 方案先于代码 —— 任何超过 10 分钟的任务，先写方案再写代码
3. 禁止猜测 —— 业务规则有歧义时优先问人
4. 反例驱动 —— 避坑清单比"应该怎么做"更有效
5. 强制归档 —— 文档不入库 = 工作未完成
6. 技术栈无关 —— 规范用抽象语言写，示例按需补充

适用范围

✓ 任何 AI 辅助开发的项目（Web、移动、后端、CLI、库） ✓ 任何技术栈（JS / Python / Go / Java / Rust / ...） ✓ 个人项目 / 团队项目 ✓ Claude Code / Cursor / 其他读取项目级 Markdown 上下文的 AI 工具

✗ 不适用：纯 prompt 工程项目、不涉及代码工程化的纯研究脚本

反馈与迭代

发现工作流漏洞、规范缺失、避坑案例？直接编辑对应文档，在 docs/文档更新日志.md 加一条变更记录即可。 规范是活的——它应该随着项目踩过的坑不断长出新的条目。