Vibe 编程蓝图

一种以文档为驱动的 AI 编程方法论。AI 就像一位“能力极强但偶尔粗心的新员工”。你的角色是架构师与决策者——而非监工。

• AI 负责高速产出代码
• 你负责判断、决策与根因诊断
• 方向盘始终掌握在你手中

核心理念

AI 代码生成能力强大，但十分脆弱。若缺乏结构化约束，它产出的代码可能仅能“一次性运行成功”，却会随时间推移迅速变得难以维护。本方法论通过以文档作为记忆来解决该问题——构建一套自引用的文档系统，使 AI 可在任意状态中断后恢复工作，且不丢失上下文。

工作流

阶段 0：检查项目文档状态

重要提示：每次对话开始时，须首先确认项目是否已存在文档：

1. 检查 docs/README.md 是否存在
2. 检查 docs/ARCHITECTURE.md 是否存在
3. 检查 docs/PROJECT_STRUCTURE.md 是否存在
4. 检查主源码目录下是否包含 FOLDER.md 文件

若检测到文档存在：

检测到项目文档：
- docs/README.md
- docs/ARCHITECTURE.md
- docs/PROJECT_STRUCTURE.md
- [FOLDER.md 文件列表]

我将优先阅读这些文档，以充分理解项目上下文，再开始后续工作。

若未发现任何文档：

未检测到文档结构。
请选择：
A) 初始化文档（推荐）——生成完整的文档结构
B) 跳过初始化——不依赖文档直接开始开发

请选择 [A/B]：

阶段 1：蓝图 —— 首先设计架构

目标：在脑中完整构思整个系统架构，随后将其输出为正式文档。

步骤：

1. 明确系统要解决的核心问题
2. 拆解核心模块
3. 绘制数据流向及关键依赖关系
4. 输出至 docs/ARCHITECTURE.md

输出文件： docs/ARCHITECTURE.md

阶段 2：建立分形式文档结构

目标：构建一套自引用的文档系统，确保 AI 可随时回到任一历史状态并持续工作。

三层文档体系

第一层 —— 根级文档

docs/
├── README.md              # 根文档，声明文档更新机制
├── ARCHITECTURE.md       # 系统架构概览
├── PROJECT_STRUCTURE.md   # 项目结构指南（快速导航）
└── superpowers/
    └── DAILY.md           # 日常变更日志

第二层 —— 目录级文档（每个文件夹一个 FOLDER.md，≤3 行）

# [文件夹名称] 架构

**角色：** [单行描述]
**包含：** [文件名] - [功能]，[文件名] - [功能]

> ⚠️ 若该文件夹内容发生变更，请同步更新此文档

第三层 —— 代码文件头部注释（3 行）

// input:  [该文件对外部的依赖]
// output: [该文件向其他模块提供的能力]
// pos:    [该文件在本地系统中的定位]
// ⚠️ 修改该文件时，请同步更新其头部注释及父级 FOLDER.md

自引用机制：局部变更向上同步至全局；全局变更向下传导至局部。任一文件发生变更，均自动触发整条文档链的同步更新。

阶段 3：按模块渐进开发（核心循环）

每个功能模块均遵循以下步骤：

步骤 1：先设计，再编码（Plan-Before-Code）

切勿立即编写代码。请先让 AI 输出技术实现方案，由你审阅并调整。

提示词模板：

在实现 [模块名称] 前，请先输出技术实现方案：
1. 数据模型设计（表结构或类型定义）
2. 核心接口（函数名、参数、返回值）
3. 对其他模块的依赖关系
4. 关键实现细节
5. 潜在风险点

我将审阅并确认后，你再开始编码。

你（人类）的责任：

• 评估方案是否合理
• 调整权限与边界设计
• 确认技术栈选型
• 补充遗漏的边界场景

步骤 2：拆解为小型任务

将模块拆分为彼此独立、可单独完成的小任务。

每个小任务需包含：

• ✅ 明确的目标
• ✅ 技术路径
• ✅ 实施步骤
• ✅ 验证方式

步骤 3：逐个实现小型任务

实施顺序：基础设施 → 业务逻辑 → UI 层

每完成一个小任务后，立即执行以下操作：

1. 更新代码文件的头部注释
2. 更新其父目录下的 FOLDER.md
3. 执行验证（单元测试、演示页面或手动测试）

提示词模板（验证通过后）：

验证通过。请现在执行：
1. 更新 [文件名] 的头部注释（若实现逻辑有变更）
2. 更新 docs/[文件夹]/FOLDER.md（若接口有变更）
3. 若涉及跨文件夹依赖，请同步关联文档

步骤 4：端到端集成

所有模块开发完成后，执行端到端测试。

阶段 4：调试（人类主导时刻）

最重要原则：当同一问题经 2–3 轮尝试仍未修复时，必须立即停止。这表明模型已陷入错误的认知框架中。

调试步骤

步骤 1：识别危险信号

• 模型已对同一问题修改 2–3 次以上，仍未解决
• 修复一处导致另一处出错（补丁叠补丁）
• 代码质量持续恶化，而非逐步改善

步骤 2：人类进行根因诊断

• 阅读错误信息，但不止步于表层现象
• 借助日志、断点与代码追踪，定位真实原因
• 追问：问题发生在哪个模块？为何发生？根本原因是什么？

步骤 3：向模型明确陈述根因

❌ 不要说：这里有个 bug，请修复
✅ 应说：你之前的假设是错误的。真实问题是：[对根因的具体描述，含原因分析]。请基于这一正确认知重新实现。

步骤 4：让模型基于正确理解重新生成

阶段 5：迭代

人机职责对照表

常见 AI 陷阱与应对方案

1. API 幻觉（API Hallucination）

AI 编造了不存在的 API、库函数或接口。

应对方案：在提示词中强调“仅使用官方文档中列出的 API”。必要时，人工核对官方文档。

2. 基于错误假设的重复修补

AI 在错误的基础假设上反复修改代码，导致问题加剧。

应对方案：由你亲自诊断根因，并明确告知 AI 其错误假设所在。

3. 过度工程化（Over-Engineering）

AI 引入大量设计模式、工厂函数与装饰器，造成不必要的复杂性。

应对方案：在代码审查中自由删减。坚持简洁至上。

4. 遗漏边界场景

AI 仅实现主流程（happy path），忽略空值检查、异常处理与并发控制等。

应对方案：在提示词中预先枚举边界场景；或在测试阶段主动补充。

提示词模板库

启动新项目

我想启动一个新项目：[项目描述]
请先帮我输出项目架构文档：
1. 核心模块划分
2. 数据流向关系
3. 技术栈建议

我确认后，你再搭建文档结构并开始编码。

添加新功能

我想在 [现有模块] 中添加 [新功能]。
请先输出技术实现方案。
我确认后再开始编码。

调试请求

我遇到了一个问题：
- 表象：[问题描述]
- 期望行为：[预期结果]
- 实际行为：[实际结果]

我已尝试：[目前已做的尝试]

请先分析可能成因。我将告知你根因，之后我们一起修复。

更新后同步文档

[模块名称] 已完成。请同步：
1. [文件名] 的头部注释（若接口有变更）
2. docs/[文件夹]/FOLDER.md
3. docs/ARCHITECTURE.md（若有重大变更）
4. docs/PROJECT_STRUCTURE.md（若新增模块）

为已有项目初始化文档

这是一个尚无文档的既有项目，请为其初始化文档结构。

注意：初始化过程从真实项目结构出发进行探索（不预设如 src/ 等特定布局），所生成的文档严格匹配项目实际结构。

效率目标

若严格遵循本方法论，你真正需要亲手编写的部分应 < 5%：

• 少量措辞微调
• 根因分析与问题诊断
• 边界场景决策
• 代码审查与架构调整

其余 95% 由 AI 承担：重体力劳动、重复性工作、高速代码生成。