Vibe-Coding-Universal Vibe-Coding-Universal

一、核心概念1. Core Concepts

1.1 什么是 Vibe Coding？1.1 What is Vibe Coding?

Vibe Coding 是 AI 辅助编程的新范式，强调「提示词先行」（Prompt First）。传统开发中常遇到的问题：Vibe Coding is a new paradigm for AI-assisted programming, emphasizing "Prompt First". Common problems in traditional development:

• AI 猜错需求：你只说了一句"做个记账 App"，AI 就开始瞎写AI guesses wrong: You only said "make a记账 App", and AI starts writing randomly
• 代码难以维护：没有规划，AI 写出来的代码像面条一样缠绕Code hard to maintain: No planning, AI code becomes spaghetti
• 重复踩坑：同样的问题，每次开发都要重新给 AI 解释Repeated pitfalls: Same problems, need to explain to AI every time

1.2 本项目的独特价值1.2 Unique Value

二、三层架构设计2. Three-Layer Architecture

┌─────────────────────────────────────────────────────────┐
│ 第一层：认知层 (SKILL.md)  —— 🧠 大脑                    │
│   • 7 轮结构化调研逻辑                                  │
│   • 文档生成模板                                        │
│   • 非侵入式规范                                        │
├─────────────────────────────────────────────────────────┤
│ 第二层：记忆层 (vibe_memory.py) —— 💾 记忆              │
│   • 存储历史：项目归档到 .vibe/history/                 │
│   • 检索经验：自动查找历史项目                          │
│   • 格式化导出：转换为 Claude Code / Codex 格式         │
├─────────────────────────────────────────────────────────┤
│ 第三层：执行层 (AGENTS.md) —— 🤖 手臂                   │
│   • 纯执行，不关心需求怎么调研出来的                    │
│   • 只关心 AGENTS.md 里的指令                           │
└─────────────────────────────────────────────────────────┘

三、7 轮深度调研方法论3. 7-Round Deep Survey

3.1 调研流程3.1 Survey Flow

每次只问 1 个问题，等用户回答后再问下一个：Ask only 1 question at a time, wait for user's answer before asking the next:

3.2 AI 自主决策规则3.2 AI Self-Decision Rules

• 用户回答模糊时 → 主动追问具体细节Unclear answer → Proactively ask for details
• 用户说"随便"或"你决定" → 记录为 AI 自主决策，并在文档中标注User says "whatever" or "you decide" → Mark as AI self-decision
• 用户中途跳过 → 标记为 ⏭️ 跳过，继续下一个User skips → Mark as ⏭️ skipped

3.3 生成《开发指导书》3.3 Generate Development Guide

调研完成后，AI 自动生成标准化 guide.md，包含 8 个章节：After survey, AI generates standardized guide.md with 8 chapters:

1. 需求定义：Must Have + Nice to Have + Out of Scope
2. 技术架构：技术栈选型 + 项目结构 + 关键依赖
3. UI/UX 规范：设计风格 + 响应式要求
4. 开发计划：分步执行，每步 10-30 分钟可完成
5. 开发约束：铁律 + 编码规范 + 特殊约束
6. 历史经验：相似项目参考 + 已知坑点
7. 变更记录：记录所有变更
8. AI 决策记录：供用户审查

四、Memory Bank 记忆系统4. Memory Bank System

4.1 目录结构（非侵入式）4.1 Directory Structure (Non-Invasive)

project/
├── .vibe/                      # 本技能的工作目录（隔离的）
│   ├── guide.md                # 统一开发指导文档
│   ├── client-profile.md       # 客户长期偏好
│   ├── history/                # 历史项目归档
│   │   └── 2026-04-21_记账app/
│   └── session-log.md          # 当前会话的调研记录
├── memory-bank/                # Claude Code 专用格式
├── AGENTS.md                   # Claude Code 入口文件
└── ... (用户原有的项目文件)     # 本技能绝不触碰

4.2 相似项目检索算法4.2 Similar Project Retrieval

使用纯 Python 实现的零依赖检索：Zero-dependency retrieval using pure Python:

# Recall: query 中有多少比例的词出现在目标文档中
intersection = query_tokens & content_tokens
recall = len(intersection) / len(query_tokens)
jaccard = len(intersection) / len(query_tokens | content_tokens)
score = recall * 0.7 + jaccard * 0.3

4.3 跨项目客户画像4.3 Cross-Project Client Profile

client-profile.md 记录用户的长期偏好，跨项目复用，包括技术偏好、UI 偏好、历史统计等。client-profile.md records long-term user preferences for cross-project reuse, including tech preferences, UI preferences, and historical stats.

五、与 Hermes Agent 的结合5. Integration with Hermes Agent

5.1 兼容平台5.1 Compatible Platforms

六、与其他框架的对比6. Comparison with Other Frameworks

6.1 vs DeerFlow6.1 vs DeerFlow

6.2 核心差异6.2 Core Differences

Vibe-Coding-Universal 的优势's Advantages：

• 更轻量：纯 Markdown + 零依赖 PythonLighter: Pure Markdown + Zero-dependency Python
• 更专注：聚焦于"写代码前"的需求澄清More focused: On requirements clarification before coding
• 更通用：任何 AI 都能加载使用More universal: Any AI can load and use

七、关键洞察与实践建议7. Key Insights & Recommendations

7.1 核心价值7.1 Core Value

1. Prompt First：在写代码前强制进行需求调研，避免"AI 瞎写"Force requirements survey before coding
2. Single Source of Truth：一份 guide.md 作为开发唯一真理来源One guide.md as the single source of truth
3. 记忆复用：跨项目复用客户偏好和历史经验Cross-project preference and experience reuse
4. 零门槛：任何 AI 都能加载使用Zero threshold, any AI can use

7.2 实践建议7.2 Recommendations

• 新项目启动：先加载 SKILL.md，再描述需求New project: Load SKILL.md first, then describe requirements
• 需求澄清：认真回答 7 轮调研，减少 AI 猜测Requirements: Answer the 7 rounds carefully
• 经验积累：完成项目后归档，充实记忆库Experience: Archive completed projects to enrich memory
• 定期回顾：检查 guide.md 的变更记录，持续优化Review: Check guide.md changes regularly

八、相关资源8. Resources

• GitHub: https://github.com/mage0535/vibe-coding-universal
• 相关项目:
  • EnzeD/vibe-coding - Memory Bank 核心理念Core Concept
  • tukuaiai/vibe-coding-cn - 四阶段×十二原则方法论4-Phase × 12-Principle Methodology