VibeCoding 从 MD 开始

Vibe Coding（氛围编程）是 AI 编程领域主流的协作范式：开发者用自然语言描述想要的效果，由 AI 编码工具直接生成实现代码，而不是逐行手写。这种范式的起点往往是一份结构清晰、人机皆可读的 Markdown 文档。本教程从 Markdown 出发，讲解如何在 Vibe Coding 工作流中用它写好需求、提示词与项目上下文，让 AI 准确理解你的意图并产出可用的代码。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

VSCode的安装与基本使用教程，VSCode 是编写 Markdown 文档与运行 AI 编码工具的推荐编辑器。
Claude Code安装及配置国内大模型完整教程，Claude Code 是贯穿本教程的 AI 编码工具。
Prompt概念详解及应用教程，理解提示词原理有助于写好驱动 AI 的需求文档。

1. 认识 Vibe Coding 与 Markdown 的角色

1.1 什么是 Vibe Coding

Vibe Coding 由 Andrej Karpathy 在 2025 年提出，指开发者用自然语言描述产品意图，由大语言模型驱动的编码工具生成代码的开发方式。它与传统编程的本质区别在于关注点的转移：

维度	传统编程	Vibe Coding
关注点	语法、算法、实现细节	意图、约束、验收标准
主要输入	逐行手写代码	自然语言描述需求
调试方式	阅读源码定位问题	反馈错误信息让 AI 修复
文档角色	事后补充	驱动开发的起点

Vibe Coding 并不意味着"不用懂编程"，而是把精力从"怎么写"转移到"写什么"：你需要更清楚地描述需求、约束与验收标准，而这正是 Markdown 擅长的事情。

1.2 为什么从 Markdown 开始

在 Vibe Coding 工作流中，Markdown 是人与 AI 之间的通用语言：

人机皆可读：人类读起来结构清晰，AI 同样能理解标题、列表与表格的语义。
表达力足够：标题、列表、表格、代码块、引用块覆盖了需求描述所需的绝大多数表达。
无处不在：README、GitHub Issue、提示词、项目配置文件都以 Markdown 为核心格式。
可版本化：Markdown 是纯文本，天然适合 Git 管理，文档随代码一起演进。

Markdown 之于 Vibe Coding，相当于注释之于传统编程——它把"你想让 AI 做什么"讲清楚，是意图传递的载体。

1.3 Vibe Coding 中的文档驱动工作流

一个典型的 Vibe Coding 项目以 Markdown 文档为起点和终点，形成闭环：

graph LR A[需求文档.md] --> B[AI 编码工具] B --> C[生成代码] C --> D[运行与验证] D -->|发现问题时| B C --> E[README 与文档.md] E --> A

从需求文档出发，经过 AI 编码、验证迭代，最终把实现沉淀回文档。后续章节将逐一讲解这个闭环中 Markdown 的每个用途。

2. Markdown 作为与 AI 沟通的语言

Vibe Coding 要求你写出 AI 能"看懂"的 Markdown。本节讲解 AI 编程场景下最常用的 Markdown 语法及其沟通价值。

2.1 标题与文档结构

标题让 AI 快速识别文档的层级与主题：# 一级标题代表核心主题，## 二级标题代表主要章节，### 三级标题代表子问题。

# 待办事项应用需求

## 1. 功能需求

### 1.1 任务管理

- 新增任务
- 修改任务

### 1.2 标签功能

- 按标签筛选

沟通价值：清晰的标题层级相当于给 AI 一份文档目录，让它先了解整体结构，再定位具体需求。

2.2 列表与任务清单

无序列表列举平级需求点，有序列表描述有先后顺序的步骤，任务清单 - [ ] 则是 AI 编程中最常用的进度标记。

- [x] 搭建项目骨架
- [ ] 实现用户注册功能
- [ ] 实现登录鉴权

沟通价值：任务清单把大需求拆解为可逐项完成的子任务，AI 可以按清单顺序实现，你也能量化地看到进度。

2.3 代码块与语言标注

给 AI 的示例代码必须标注语言类型，AI 才能按正确语言实现。在提示词中说明目标语言，并给出带标注的示例：

def read_csv(path):
    import csv
    with open(path, encoding="utf-8") as f:
        return list(csv.DictReader(f))

沟通价值：语言标注消除了歧义，避免 AI 用错误的语言或框架实现需求。

2.4 表格

表格是描述结构化需求的最佳方式——字段定义、接口参数、配置项、方案对比都适合用表格表达。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 任务名称 |
| due_date | string | 否 | 截止日期 |
| done | boolean | 否 | 是否完成 |

沟通价值：AI 对表格的解析非常准确，字段级需求描述能让 AI 一次性生成正确的数据结构。

2.5 引用块与链接

引用块 > 用于强调约束、注意事项与边界条件，链接用于引导 AI 查看参考资源。

> 注意：接口必须兼容现有 v1 版本，不能破坏已有调用方。

参考现有实现：[用户模块接口文档](api/user.md)

沟通价值：约束条件往往是 AI 最容易忽略的部分，用引用块单独强调能显著提升实现质量。

2.6 Mermaid 图表

在 Markdown 中使用 Mermaid 绘制流程图与结构图，让 AI 理解复杂的架构与流程。

graph LR User[用户] -->|输入| API[API 接口] API --> DB[(数据库)] API --> Cache[(缓存)]

沟通价值：架构图能把数据流向、模块关系这类难以用文字描述的信息精确传达给 AI。

3. 用 Markdown 写好需求与提示词

3.1 需求文档模板

一份好的需求文档是 Vibe Coding 的第一份输入。推荐包含以下区块：

# 项目需求文档

## 1. 背景与目标

一句话说明要解决什么问题、达到什么效果。

## 2. 功能需求

### 2.1 功能名称

- 功能描述：...
- 输入：...
- 输出：...

## 3. 技术约束

- 技术栈：Python 3.10 + FastAPI
- 数据库：MySQL
- 兼容要求：...

## 4. 验收标准

- [ ] 功能可以正常使用
- [ ] 性能达到预期
- [ ] 文档完整

3.2 提示词的 Markdown 结构

发给 AI 的单次提示词同样可以用 Markdown 结构化，比一句"帮我写个登录功能"有效得多：

请实现用户登录功能。

## 需求描述
基于现有 FastAPI 项目，新增登录接口，使用 JWT 鉴权。

## 输入输出
- 请求：POST /api/login，参数 username、password
- 响应：{ "token": "..." }

## 约束
- 密码使用 bcrypt 加密
- 失败返回 401 状态码

## 参考
现有用户表结构见 database/schema.sql

要点：把"需求""输入输出""约束""参考"分块，AI 就能逐块理解并落实，而不是靠猜测。

3.3 示例：用 MD 提示词创建功能

假设要让 AI 为笔记应用新增"标签筛选"功能：

请为笔记应用新增标签筛选功能。

## 需求描述
在笔记列表页支持按标签筛选，可同时选择多个标签。

## 输入输出
- 输入：GET /api/notes?tags=a,b
- 输出：匹配标签的笔记列表

## 约束
- 标签匹配采用 AND 逻辑
- 无标签时返回全部笔记

## 验收标准
- [ ] 单标签筛选生效
- [ ] 多标签同时筛选生效
- [ ] 空标签返回全部

把这份文档交给 AI 编码工具，通常一次就能得到符合要求的实现；不满足的地方，在对话中继续补充即可。

4. 项目上下文：CLAUDE.md 与 README

4.1 CLAUDE.md 项目上下文

CLAUDE.md 是 AI 编码工具（如 Claude Code）自动读取的项目级上下文文件，会进入 AI 的初始上下文，让 AI 在编码时遵循项目约定。

# CLAUDE.md

## 项目简介

待办事项 API 服务。

## 技术栈

- 后端：FastAPI
- 数据库：MySQL

## 编码约定

- 注释使用简洁风格
- 数据库名统一使用 ai_ml_tutorial
- 依赖使用 requirements.txt 锁定版本

## 常用命令

- 启动服务：python main.py
- 运行测试：pytest

沟通价值：把项目规范写进 CLAUDE.md，AI 每次生成代码都会自动遵守，无需重复提示。

4.2 README 驱动的开发

README 是项目说明书，也是给 AI 看的项目总纲——它描述项目是什么、如何运行、如何扩展。

# 待办事项 API

基于 FastAPI 的待办事项管理接口。

## 运行

\`\`\`bash
uv pip install -r requirements.txt
python main.py
\`\`\`

## 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/todos | 获取列表 |
| POST | /api/todos | 新增任务 |
| DELETE | /api/todos/{id} | 删除任务 |

沟通价值：AI 新增功能时先读 README，就能理解项目现状，避免重复造轮子或破坏已有接口。

4.3 把对话沉淀为文档

Vibe Coding 的对话是临时的，文档是持久的。完成一个功能后，把关键决策记录到文档，后续 AI 才能基于真实记录工作。

## 决策记录

- 2026-08-10：登录功能改用 JWT 方案，弃用 Session
- 2026-08-10：数据表增加 soft_delete 字段

5. Vibe Coding 实战工作流

5.1 从零开始一个项目

结合前文，完整的 Vibe Coding 项目流程如下：

graph LR A[编写需求文档] --> B[创建 CLAUDE.md] B --> C[让 AI 搭建骨架] C --> D[逐个功能实现] D --> E[运行验证] E -->|通过| F[更新 README] E -->|失败| D

写需求文档：用第 3 节的模板描述目标、功能与验收标准。
建 CLAUDE.md：声明技术栈与编码约定，让 AI 从一开始就按规范工作。
搭建骨架：让 AI 生成项目结构、依赖清单与启动脚本。
逐个功能实现：每个功能对应一个文档块，一次只推进一个。
运行验证：执行 AI 生成的启动命令，观察报错并反馈给 AI 修复。
更新 README：功能稳定后更新 README，形成新的文档基线。

5.2 迭代与验证循环

Vibe Coding 的日常是"描述-实现-验证-修正"的小循环：

步骤	输入	输出
描述	需求文档片段	明确的实现指令
实现	提示词	AI 生成的代码
验证	运行日志、测试结果	是否满足验收标准
修正	错误信息、差异描述	新的提示词

关键是把验证结果准确反馈给 AI：报错日志、期望与实际的差异，都比笼统的"不对，再改改"有效。

5.3 常见误区与最佳实践

常见误区：

只描述结果，不描述约束：AI 自由发挥，生成的代码往往不符合项目约定。
文档与代码脱节：AI 改完代码，文档没更新，下一轮协作又回到原点。
一次性塞入过多需求：上下文过长时 AI 容易遗漏细节，应分块推进。

最佳实践：

需求、约束、验收标准三要素齐全后再交给 AI。
每个功能完成后立即沉淀到 CLAUDE.md 或决策记录。
用任务清单跟踪进度，让 AI 明确当前该做哪一步。

6. 总结

6.1 核心要点回顾

Vibe Coding 是用自然语言描述意图、由 AI 生成代码的编程范式，Markdown 是传递意图的载体。
Markdown 语法服务于沟通：标题定结构、列表拆任务、代码块定语言、表格定义字段、引用块强调约束、Mermaid 描述架构。
三类核心文档：需求文档（表达要做什么）、CLAUDE.md（表达项目规范）、README（表达项目现状）。
工作流闭环：需求文档 → AI 编码 → 验证迭代 → 文档沉淀。

6.2 常见问题与解答

问：Vibe Coding 是不是不用懂编程了？

答：不是。你仍然需要理解需求、架构与验收标准，只是不必逐行写实现。正因为要把需求描述清楚，你需要比传统开发更严谨的文档能力，这正是 Markdown 的价值所在。

问：AI 生成的代码不符合预期怎么办？

答：先检查文档是否写清了约束与验收标准，多数偏差源于需求含糊。把差异具体化（"字段名应为 x，接口应返回 y"）后再次提交，比笼统的"不对"有效。

问：提示词和需求文档有什么区别？

答：需求文档是持久的、面向整个项目的输入；提示词是一次性的、面向单个任务的输入。正式项目中两者结合：需求文档沉淀规范，提示词驱动具体功能。

问：CLAUDE.md 在团队项目中怎么维护？

答：CLAUDE.md 是团队约定，由熟悉项目的人维护，写入公共规范。修改时应像代码评审一样走评审流程，避免个人偏好影响整个团队。