Vibe Coding Standards

一套经过一线生产项目验证的 AI 编码规范，适用于 Cursor（.cursor/rules/）和 Claude Code（.claude/rules/），帮助 AI 像靠谱的工程师一样写代码。

背景：在一个 15 天 10 万行代码、95% 由 AI 生成的真实项目中沉淀出来。核心理念——不是教 AI 写代码，而是告诉 AI 什么不能做。

快速开始

Cursor 用户

1. 将 rules/ 目录下的 .mdc 文件复制到你项目的 .cursor/rules/ 目录
2. 将 skills/ 目录复制到你的 ~/.cursor/skills/ 目录（全局生效）
3. 根据你的项目修改 project-architecture-template.mdc（这是唯一需要大改的文件）
4. 开始和 AI 对话——它会自动遵守这些规范

cp -r rules/ your-project/.cursor/rules/
cp -r skills/ ~/.cursor/skills/

Claude Code 用户

Claude Code 的 .claude/rules/ 只识别 .md 文件，需要将 .mdc 改为 .md 后缀：

# 复制并重命名后缀
mkdir -p your-project/.claude/rules/
for f in rules/*.mdc; do cp "$f" "your-project/.claude/rules/$(basename "${f%.mdc}.md")"; done

# Skills 复制到全局目录
cp -r skills/ ~/.claude/skills/

同样需要修改 project-architecture-template.md（注意后缀变了）。

Cursor 用 .mdc，Claude Code 用 .md——内容完全一样，只是文件后缀不同。.mdc 本质就是 Markdown，改后缀即可。

Frontmatter 差异：Cursor 用 globs 做条件匹配，Claude Code 用 paths。本仓库中仅 java-spring-conventions 使用了 globs: "**/*.java"，Claude Code 用户需改为 paths: "**/*.java"。其余文件设置了 alwaysApply: true，两边通用无需改动。

文件说明

三层结构

rules/
├── development-workflow.mdc         # 通用层 — Leader-Worker-Judge 工作流
├── design-principles.mdc            # 通用层 — 设计原则（红线 + 传统工程原则）
├── java-spring-conventions.mdc      # 技术栈层 — Java/Spring 编码规范 + 静态分析
└── project-architecture-template.mdc # 项目层 — 域边界表 + 数据访问分层（需自定义）

层级	文件	谁能用	需要改吗
通用层	development-workflow.mdc	前端/后端/客户端/全栈	基本不用改，工作流细节可以自行调整
通用层	design-principles.mdc	前端/后端/客户端/全栈	代码示例可换成你的语言
技术栈层	java-spring-conventions.mdc	Java/Spring Boot 后端	按团队规范微调
项目层	project-architecture-template.mdc	你的具体项目	必须根据项目填写

各文件核心内容

development-workflow.mdc — 最关键的一份

通过关键词触发 AI 在三个角色间切换：

• Leader（分析需求 方案设计 定接口）：多问少做，输出设计文档和 API 骨架
• Worker（开始开发 写代码 写测试）：按方案执行，一次一个功能点
• Judge（review 跑测试 能部署了吗）：跑测试、跑静态检查、给出证据再下结论
• BugFix（修bug fix）：定位→改码→补测试→跑通，四步闭环

design-principles.mdc — 红线 + 传统工程原则

4 条红线（违反即 Judge 不通过）：

1. 逻辑收口 — 同一职责只有一个归属
2. 复用优先 — 先找再写
3. 禁止循环依赖 — 传递依赖链至少查 3 跳
4. 禁止魔法值 — 枚举/常量统一

9 条重要原则：模块化、幂等性、防御性编程、副作用可预测、优雅降级、可测试性、日志有效性、开闭原则、设计模式问题驱动。

附带 8 项自检清单，每次开发新功能前过一遍。

java-spring-conventions.mdc — Java 技术栈专用

• 依赖注入：构造器注入，禁止 @Autowired 字段注入
• 异常处理：统一 BizException + ResultCode
• 返回类型：统一 Result<T>
• 静态分析工具矩阵：Enforcer / CheckStyle / PMD / CPD / SpotBugs

project-architecture-template.mdc — 需要你填的

• 域边界表：告诉 AI 每个业务域有哪些 Service、DAO，改哪个域的代码该找哪个类
• 数据访问分层：Controller → Service（编排/领域）→ Repository → DAO 的职责和规则
• 模块职责：哪个模块放什么，禁止什么

核心理念

为什么 AI 需要 Rules？

人类工程师的经验（单一职责、幂等性、不循环依赖）是内化的，AI 没有。你不说，它不知道。

写 Rules 的三个原则

1. 写"禁止"比写"建议"有效 10 倍 — AI 对"必须/禁止"的遵从度远高于"建议/推荐"
2. 带正反代码示例 — AI 看 ✅ 和 ❌ 比看文字描述理解快
3. 项目层必须有域边界表 — 没有这张表，AI 不知道代码该放哪

配套文档建议

除了 Rules，建议在项目中维护：

docs/
├── plans/          # 技术方案（Leader 输出）
├── flow/           # API 交互流程（Leader 输出）
└── database/       # DB Schema 文档
    ├── mysql-all-tables.sql
    └── mongodb-indexes.js

这些文档是 AI 的"长期记忆"——新开窗口时，AI 可以快速检索上下文。

Skills — AI 的"工作方法论"

除了 Rules（告诉 AI 什么能做什么不能做），Skills 告诉 AI 怎么做。Skills 是可复用的工作方法论，当 AI 遇到特定场景时自动激活。

Skills 来源

本仓库的 Skills 基于两个优秀的开源项目，移除了 git 操作相关部分并做了适配：

• 开发工作流 Skills（12 个）— 基于 obra/superpowers
• 上下文工程 Skills（7 个）— 基于 muratcankoylan/Agent-Skills-for-Context-Engineering

Skills 目录

skills/
├── 开发工作流（基于 superpowers）
│   ├── brainstorming/               # 需求头脑风暴，创意工作前必用
│   ├── writing-plans/               # 编写实施计划
│   ├── executing-plans/             # 按计划分批执行
│   ├── subagent-driven-development/ # 子 Agent 驱动开发（含 prompt 模板）
│   ├── dispatching-parallel-agents/ # 并行派发多个 Agent
│   ├── test-driven-development/     # TDD 红绿重构
│   ├── systematic-debugging/        # 系统化调试（含根因追溯技术）
│   ├── requesting-code-review/      # 请求代码审查
│   ├── receiving-code-review/       # 接收代码审查反馈
│   ├── verification-before-completion/ # 完成前必须验证
│   ├── finishing-a-development-branch/ # 开发分支收尾
│   └── using-superpowers/           # Skills 调度入口
│
├── 上下文工程（基于 Agent-Skills-for-Context-Engineering）
│   ├── context-fundamentals/        # 上下文工程基础
│   ├── context-degradation/         # 上下文退化模式
│   ├── context-compression/         # 上下文压缩策略
│   ├── context-optimization/        # 上下文优化技术
│   ├── filesystem-context/          # 文件系统上下文管理
│   ├── multi-agent-patterns/        # 多 Agent 架构模式
│   └── tool-design/                 # Agent 工具设计

关键 Skills 简介

Skill	一句话说明	何时触发
brainstorming	把模糊想法变成清晰设计方案	做任何创造性工作之前
writing-plans	把需求拆成 TDD 友好的执行步骤	有需求/设计稿，准备动手之前
systematic-debugging	四阶段调试：根因→模式→假设→修复	遇到任何 Bug
test-driven-development	先写测试，看到红，再写代码	实现任何功能
verification-before-completion	没跑过验证命令不许说"完成了"	声称工作完成之前
context-fundamentals	理解上下文窗口和注意力机制	设计 Agent 系统架构
context-compression	长对话压缩，不丢关键信息	Agent 会话超出上下文限制
multi-agent-patterns	多 Agent 协作的三种架构模式	设计多 Agent 系统

适配其他技术栈

目前 java-spring-conventions.mdc 是 Java/Spring Boot 专用。如果你用其他技术栈：

• 前端（React/Vue/Next.js）：development-workflow.mdc 和 design-principles.mdc 直接可用，另写一份前端编码规范替换 Java 那份
• Go / Python / Node.js：同上，替换技术栈层的编码规范
• 客户端（iOS/Android/Flutter）：同上

通用层的两份文件（工作流 + 设计原则）不需要改，直接用。

致谢

• obra/superpowers — 开发工作流 Skills 的原始来源
• muratcankoylan/Agent-Skills-for-Context-Engineering — 上下文工程 Skills 的原始来源

License

MIT