vibe-coding-prompt-template：用三份文档解决AI编程的上下文丢失问题

Andrej Karpathy 在2025年初分享了一种被他称为 Vibe Coding 的新型编程方式。他描述自己几乎不碰键盘，完全依靠 Cursor Composer 与 Claude 进行对话来生成代码，遇到错误就直接把报错信息复制粘贴回去，很少审查代码差异。

这条推文迅速走红，但许多开发者尝试后发现效果不佳。问题的核心在于：你与 AI 的对话缺乏上下文。AI 并不清楚你正在构建项目的具体细节、技术选型或已有约定，因此只能基于最通用的模式进行猜测和生成。

这正是 GitHub 上名为 vibe-coding-prompt-template 的开源项目（作者 KhazP）试图解决的问题。该项目旨在通过一套结构化的文档模板，为 AI 编程工具提供持久的“项目记忆”。

Vibe Coding 的典型痛点

当前，使用 AI 工具编码的常见流程是：打开 Cursor 或 Cline，用一两句话描述需求，然后等待结果。初期几轮对话通常很顺利，但当对话进行到第5轮、第10轮时，问题开始涌现：

• AI 可能开始添加你并未要求的功能。
• 之前约定好的命名规范被悄悄修改。
• 修复一个 bug 时，AI 可能动了好几个不相关的文件。
• 一旦更换模型或切换 IDE，之前所有的“口头约定”全部失效。

这些问题的根源在于：AI 缺乏持久化的项目记忆，每次对话的上下文都是临时的、易失的。解决方案很直观：将所有的项目约定、设计和需求写成文件，存放在项目中，并在每次与 AI 对话时让它先读取这些文件。 vibe-coding-prompt-template 做的就是这件事。

项目结构：三份核心文档

这套工作流围绕三类文档展开，它们构成了一个清晰的流水线：

第一步：PRD（产品需求文档）

对应仓库中的 templates/part2-prd-mvp.md。

PRD 的作用是将“我想做什么”转化为 AI 能理解的结构化信息。它包括：

• 项目概述：一句话描述项目。
• 用户画像与用户故事：以“作为[用户]，我希望[功能]，以便[目的]”的格式编写，并附带验收标准。
• 功能列表：明确区分 MVP（最小可行产品）阶段必须实现的功能与未来规划的功能，这一点至关重要，能防止 AI “过度热心”。
• UI/UX 指南：视觉风格、配色偏好等。
• 数据模型：核心数据实体及其关系。

关键操作：完成 PRD 后，将其保存为项目根目录下的 PRD.md。

第二步：TechDesign（技术设计文档）

对应 templates/part3-tech-design-mvp.md。

如果说 PRD 回答了“做什么”，那么 TechDesign 就回答“怎么做”。一份好的技术设计文档包含：

• 技术栈：明确具体，例如“Next.js + Tailwind + Supabase + NextAuth”。
• 架构：描述系统分层与模块职责。
• API 与集成：列出核心端点及需要接入的第三方服务。
• 数据库模式：具体的表结构、字段类型和关系。
• 实施路线图：将开发计划拆分为清晰的阶段。

跳过这一步的代价是让 AI 在无约束状态下自行选型，结果可能与你期望的架构（如函数式组件）背道而驰。

关键操作：完成技术设计后，保存为项目根目录下的 TechDesign.md。

第三步：AGENTS.md（AI Agent 指令文档）

这是整个方案的核心，也是该项目区别于普通“提示词合集”的关键。AGENTS.md 的设计理念源于行业正在推动的 Agent 配置规范，本质上是一份专门给 AI 阅读的项目 README。

模板文件是 templates/part4-notes-for-agent.md。生成的 AGENTS.md 通常包含以下章节：

## Project Overview
[项目的一句话描述，供AI快速定位上下文]

## Setup Commands
pnpm install
pnpm dev

## Build & Test Commands
pnpm build
pnpm test --watch

## Code Style & Conventions
- 使用 TypeScript，禁止 any 类型
- 优先使用函数组件，禁止类组件
- 文件命名：kebab-case，组件命名：PascalCase
- 样式仅使用 Tailwind，禁止内联 style

## Security
- 禁止提交 `.env` 文件
- 所有 API 密钥必须通过环境变量读取
- 禁止在客户端组件中直接调用需要鉴权的 API

## PR & Commit Instructions
- Commit 信息格式：feat/fix/refactor: 描述
- 每个 PR 只做一件事

将这份文件置于项目根目录后，每次在 Cursor 或 Cline 中开始新对话时，第一条指令就是让 AI 先读取它。这能确保 AI 在整个开发周期中都遵循你的项目规则，无需每次重新“教导”。

工具兼容性：从 Cursor 到 Claude Code

这套模板支持主流 AI 编程工具，通常只需调整配置文件名或存放位置：

工具	配置文件名
Cursor	.cursorrules 或 AGENTS.md
Windsurf	.windsurfrules
Cline (VS Code)	AGENTS.md
Claude Code CLI	CLAUDE.md
Aider	.aider.conf.yml + AGENTS.md
Lovable / v0 / Bolt.new	直接粘贴 PRD 内容

实践中，你可以用同一份 AGENTS.md 驱动 Cursor 和 Claude Code CLI。项目文档提供了一个实用的命令来创建软链接，避免维护两份配置：

ln -s AGENTS.md CLAUDE.md

Vibe Coding Webapp：可视化文档生成

自 v2.3.0 起，项目还提供了一个 Web 界面：vibeworkflow.app。你可以在页面上描述项目想法并选择技术偏好，系统会调用 AI 自动生成 PRD 和 TechDesign 的草稿，支持在线编辑和导出。这对于不习惯从空白 Markdown 文件开始的人来说是个很好的入门方式。

Claude Code Skills 与 Git Hooks

对于使用 Claude Code CLI 的开发者，项目还提供了一些增强功能：

• Claude Code Skills：预配置的任务模板。例如，review-pr 让 Claude 以高级工程师视角审查 PR；write-tests 根据 AGENTS.md 定义的框架自动补充测试用例。
• Git Hooks：在 git commit 前自动运行的脚本，用于检查是否误提交了 .env 文件或遗忘了 console.log 等调试代码。

实战上手：从零开始的完整流程

Step 1: 用模板创建仓库
访问 KhazP/vibe-coding-prompt-template，点击“Use this template”创建你的新仓库，然后克隆到本地。

git clone https://github.com/你的用户名/你的项目名.git
cd 你的项目名

Step 2: 生成 PRD.md
打开你常用的 AI 对话工具（如 Claude.ai），将 templates/part2-prd-mvp.md 的内容粘贴进去，然后描述你的项目。根据 AI 的追问完善细节，最后将生成的完整 PRD 保存为项目根目录下的 PRD.md。

Step 3: 生成 TechDesign.md
在同一个对话中（或上传 PRD.md 开启新对话），粘贴 templates/part3-tech-design-mvp.md 的内容。让 AI 基于你的 PRD 推荐技术栈，经你确认或调整后，生成并保存 TechDesign.md。

Step 4: 生成 AGENTS.md
将 PRD.md 和 TechDesign.md 的内容一并提供给 AI，并给出指令：“请根据这两份文档，帮我生成一份 AGENTS.md，包括项目概述、安装命令、代码风格规范和安全要求。” 生成后放入项目根目录。如果使用 Claude Code，执行软链接命令：

ln -s AGENTS.md CLAUDE.md

Step 5: 开始 Vibe Coding
打开 Cursor 或你使用的 AI IDE，在聊天框中输入：

“请先读取 AGENTS.md、PRD.md 和 TechDesign.md，理解项目目标，然后列出 Phase 1 的开发计划，等我确认后开始执行。”

待 AI 列出计划并得到你的确认后，就可以进入“说需求-看结果”的协作模式了。

关键实践建议

1. 在 PRD 中明确“不要什么”：除了描述功能，务必给出负向约束，例如“不要使用 Redux”、“第一版不添加国际化支持”，这能有效防止 AI 自由发挥。
2. 让 AI 先计划，再执行：在开始一项较大任务前，要求 AI 先列出打算改动的文件及原因，经你确认后再执行。这个习惯能大幅减少“AI 乱改代码”的情况。
3. 将 AGENTS.md 视为活文档：每当发现 AI 重复犯同一类错误，就将对应的规则加入 AGENTS.md。久而久之，这份文件就成了你项目的“AI 使用手册”。
4. 根据任务分工选用工具：UI 原型设计可以交给 Lovable 或 v0 等工具快速完成；涉及后端逻辑、数据库的部分则交给 Cursor 或 Claude Code。两者都遵循同一份 AGENTS.md，能保持一致性。

写在最后

Vibe Coding 并不神秘，它本质上是与 AI 协作方式的演进。Karpathy 描述的是他从零开始的小项目场景，上下文简单。但对于大多数涉及技术选型、团队规范和遗留代码的中等复杂度项目，“凭感觉”是远远不够的。

vibe-coding-prompt-template 所做的工作，就是将“凭感觉”转变为“有依据的协作”。它通过三份结构化的 技术文档，将项目上下文固化下来，让 AI 在明确的规则边界内发挥创造力。该项目获得的数千星标，并非源于技术突破，而是因为它将一套行之有效的实践经验模板化，帮助开发者避开了许多重复的坑。

项目地址：https://github.com/KhazP/vibe-coding-prompt-template

如果你对这类提升开发效率的实践和工具感兴趣，欢迎来 云栈社区 与更多开发者交流探讨。