| name | create-vibe-project |
| description | Vibe Engineering Discipline v1.0 — 8 principles for disciplined AI-assisted "Vibe Coding". Use this skill when starting a new vibe-coding project, setting ground rules with an AI coding agent, or onboarding a team to structured AI collaboration. |
| metadata | {"author":"woodgaya@gmail.com","version":"1.0.0"} |
Vibe Engineering Discipline v1.0
When to Use
- Starting a new project where AI will do most of the coding
- Setting up guardrails for an AI coding agent (Claude Code, Codex, Cursor, etc.)
- Onboarding a team to structured, disciplined vibe coding
- Reviewing if a project's AI collaboration setup is missing key disciplines
The 8 Principles
原则 1: Think Before Coding
若需求模糊，先列出至少 2 种假设，询问用户后再编码。不得擅自猜测业务逻辑。
- 面对模糊需求时，AI 必须主动提出 2+ 种可能的解释
- 用户确认方向后，才能开始实现
- 禁止"我认为用户想要的是 X……"的猜测式开发
Checklist:
原则 2: Simplicity First
禁用 speculative features。单次逻辑无需抽象，除非已有 3 处重复。优先用语言内置特性，不引入额外库。
- 不写"将来可能会用到"的代码
- 重复 3 次以下不要提取抽象（不要过早抽象）
- 优先用标准库/语言原生特性，第三方库要有充分理由
Checklist:
原则 3: Surgical Changes
单次修改 ≤3 文件。不改未涉及的代码格式、注释、空行。任何重构需用户明确批准。
- 一次提交/一次对话，只改核心逻辑涉及的文件
- 不要顺手格式化、重命名、删注释
- 重构 = 用户说"重构"才算
Checklist:
原则 4: Goal-Driven + Verify
提交前必须运行 npm test 并附结果。提供测试通过的证据（截图/日志）。
- 修改实现后必须跑测试
- 测试结果必须可见（终端输出日志）
- 如果测试失败，先修复再提交
Checklist:
原则 5: Dogfooding (Human Verification)
修改后，用户必须手动走一遍核心流程。AI 应输出「需要人工验证的核心路径清单」。
- AI 完成修改后，输出一份人工验证清单
- 用户必须亲自走一遍核心流程来确认
- 未经验证不得合并/部署
核心路径清单模板：
## 需要人工验证的核心路径
1. [ ] 打开首页，确认页面正常加载
2. [ ] 点击 [功能 X]，确认流程走通
3. [ ] 输入 [异常值]，确认边界处理符合预期
4. [ ] 检查控制台无报错
5. [ ] 其他：___________
Checklist:
原则 6: Context Freshness
每次新对话开始时，自动读取 ARCHITECTURE_GUIDE.md。若上下文超限，主动总结并保存至 session-summary.md。
- 每次新对话自动加载架构文档
- 当 token 使用接近限制时，主动总结当前进度
- 将总结写入
session-summary.md 供下次对话使用
Checklist:
原则 7: Contract as Test
使用 TypeScript 严格模式 + Zod schema。修改公共接口时，同步更新对应的 OpenAPI spec。契约变更必须通过 scripts/verify-contracts.sh。
- TypeScript
strict: true
- 运行时数据验证用 Zod
- 公开 API 接口变更必须同步更新 OpenAPI 文档
- 契约验证脚本必须通过
Checklist:
原则 8: Reversibility & Rollback Anchors
每次独立功能修改后，执行 git tag vibe-$(date +%Y%m%d)-<feature-name>。所有修改必须能在单个 git revert <tag> 内完全撤销。
- 每个功能点完成后打 tag
- tag 命名格式：
vibe-YYYYMMDD-<feature-name>
- 确保一次 revert 就能完全回退，不需要逐个文件处理
Checklist:
项目初始化模板
在项目根目录创建 VIBE_DISCIPLINE.md，写入以下内容：
# Vibe Engineering Discipline v1.0
本项目的 AI 编程遵循以下原则：
| # | 原则 | 核心要求 |
|---|------|---------|
| 1 | Think Before Coding | 模糊需求先列假设，不猜测 |
| 2 | Simplicity First | 禁用 speculative features |
| 3 | Surgical Changes | 单次改 ≤3 文件 |
| 4 | Goal-Driven + Verify | 提交前跑测试 |
| 5 | Dogfooding | 人工验证核心路径 |
| 6 | Context Freshness | 每次读 ARCHITECTURE_GUIDE.md |
| 7 | Contract as Test | TypeScript strict + Zod |
| 8 | Reversibility & Rollback Anchors | 每个功能打 tag |
同时创建 scripts/verify-vibe.sh：
#!/bin/bash
set -euo pipefail
echo "=== Vibe Compliance Check ==="
if [ ! -f "ARCHITECTURE_GUIDE.md" ]; then
echo "[WARN] ARCHITECTURE_GUIDE.md 不存在"
fi
if [ -f "tsconfig.json" ]; then
if grep -q '"strict": true' tsconfig.json 2>/dev/null; then
echo "[OK] TypeScript strict mode enabled"
else
echo "[FAIL] TypeScript strict mode not enabled"
fi
fi
latest_tag=$(git tag -l 'vibe-*' --sort=-version:refname 2>/dev/null | head -1)
if [ -n "$latest_tag" ]; then
echo "[OK] Latest vibe tag: $latest_tag"
else
echo "[WARN] No vibe-* tags found"
fi
echo "=== Done ==="
与 AI Agent 的交互提示
使用 Claude Code / Codex / Cursor 等 AI 编程工具时，在 .claude.md 或项目 prompt 中声明：
This project follows Vibe Engineering Discipline v1.0.
Before each code change, read the 8 principles from VIBE_DISCIPLINE.md.
常见陷阱
- 原则 1 最容易被忽略 — AI 倾向于直接干活而不是先问清楚。需要项目 prompt 中特别强调。
- 原则 2 & 3 相辅相成 — 简单 + 精准修改，两者一起做效果最好。
- 原则 4 容易被跳过 — 如果测试很慢或不稳定，AI 倾向于找借口不跑。可以拆成快慢测试。
- 原则 5 不是可选项 — 这是人类保持对项目控制权的最低保障。跳过此原则 = 失去项目所有权。
- 原则 8 在多人协作时更重要 — 清晰的回滚锚点让整个团队敢于更快地实验。
