一套为 AI 辅助开发（vibe coding）量身打造的工程纲领。 让 AI 在你的项目里"按规矩办事"——更规范、更高效、更准确。
在任意项目根目录执行一行命令(任何电脑、跨 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 的助手）会在每次进入项目时自动加载顶层约定，并按文档套件中的工作流和规范执行任务。
| 形态 | 利 | 弊 | 是否采用 |
|---|---|---|---|
| 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 环境):
git clone https://github.com/mllt992/vibe-coding-rules.git- 把
template/CLAUDE.md和template/docs/复制到目标项目根目录 - 把
template/.claude/skills/workflow-*复制到~/.claude/skills/(用户级)或<项目>/.claude/skills/(项目级)
两种方式接入后必做:
- 编辑
CLAUDE.md第 0 节，补充本项目的：技术栈、业务领域、代码目录、运行方式 - 浏览
docs/00_通用规范/，按本项目实际情况删/改/补示例（通用规范是技术栈无关的，但项目里通常需要写实例） - 提交到版本库——规范从此成为项目契约
如果项目已有 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 不至于改个按钮颜色都先发需求分析文档。
- AI 是同事而不是工具 —— 给清楚的工作流和规范，让它独立完成、自我审查
- 方案先于代码 —— 任何超过 10 分钟的任务，先写方案再写代码
- 禁止猜测 —— 业务规则有歧义时优先问人
- 反例驱动 —— 避坑清单比"应该怎么做"更有效
- 强制归档 —— 文档不入库 = 工作未完成
- 技术栈无关 —— 规范用抽象语言写，示例按需补充
✓ 任何 AI 辅助开发的项目（Web、移动、后端、CLI、库） ✓ 任何技术栈（JS / Python / Go / Java / Rust / ...） ✓ 个人项目 / 团队项目 ✓ Claude Code / Cursor / 其他读取项目级 Markdown 上下文的 AI 工具
✗ 不适用：纯 prompt 工程项目、不涉及代码工程化的纯研究脚本
发现工作流漏洞、规范缺失、避坑案例？直接编辑对应文档，在 docs/文档更新日志.md 加一条变更记录即可。
规范是活的——它应该随着项目踩过的坑不断长出新的条目。