1. 为什么 Vibe Coding 需要一份 AGENTS.mdVibe Coding 的核心是「用自然语言描述意图让 AI 补齐实现细节」。听起来很爽但真正落到一个多文件项目里问题马上暴露AI 不知道你的目录约定不知道你用的是 Next.js App Router 还是 Pages Router不知道样式走 Tailwind 还是 CSS Module于是它生成的代码「能跑但不对味」——文件放错位置、命名风格打架、技术栈混用。我试过在一个 React FastAPI 的项目里连续让 AI 改三次首页每次它都新建一个components/Home.tsx而项目里其实早就有src/app/page.tsx。这不是模型笨是我没给它「项目使用手册」。AGENTS.md 就是这份手册。Cursor 和 Claude Code 都会自动读取项目根目录下的 AGENTS.md把它当作长期上下文。你写清楚目录结构、技术栈、代码风格、常用命令AI 生成的代码就会自动落在正确的文件里、遵循你的命名习惯、用对依赖库。这一章我们就把 Vibe Coding 的工作流固定下来AGENTS.md 定义脚手架约定Prompt 骨架驱动生成TaoToken 统一提供模型通道。适合谁看已经在用 Cursor / Claude Code / Cline 这类工具但生成结果总需要大改的开发者或者刚接触 Vibe Coding想一次性把工作流搭对的人。读完你能拿到一份可直接复制的 AGENTS.md 骨架、一份 settings.json / config.toml 配置片段以及一套验证通道是否生效的动作。2. 前置准备TaoToken 通道与项目基线在写 AGENTS.md 之前先把模型通道接好。Vibe Coding 的工作流里AI 工具会频繁发起请求补全、对话、Agent 循环如果每个工具各配一套 Key管理起来很乱。TaoToken 的思路是提供一个统一的 API 入口兼容 OpenAI 与 Anthropic 两种协议风格你只需要维护一个 Key。先拿到 Key打开 https://taotoken.net/api-keys 登录后在控制台创建 API Key复制保存。注意 Key 只在创建时完整显示一次丢了就重新建一个。然后确认你的项目基线。以本章贯穿的 markdown-flow-playground 为例它是一个前后端分离项目层技术栈关键目录后端Python FastAPI markdown-flowbackend/app/前端React Next.js TypeScript Tailwind CSS 4frontend/src/页面库markdown-flow-ui、remark-flow、shadcn/uifrontend/src/components/前后端协作流程是前端把用户输入的 MarkdownFlow 文本 POST 给后端/api/render后端用 markdown-flow 解析成结构化 JSON 返回前端用 markdown-flow-ui 渲染成交互式页面。理解这条链路你才知道 AI 改前端时不该去动后端解析逻辑。提示如果你的项目还没有 AGENTS.md直接在项目根目录新建一个空文件即可AI 工具会自动识别。文件名必须全大写AGENTS.md放在仓库根目录。3. 可复制的 AGENTS.md 骨架一份高质量的 AGENTS.md 有三个原则结构化清晰、提供上下文、示例驱动。下面这份骨架你可以直接改项目名后使用我按「AI 读得懂」的顺序组织而不是按人类文档的习惯。# AGENTS.md ## 项目概述 markdown-flow-playground一个用自然语言控制 AI 输出交互式内容的 Playground。 用户输入 MarkdownFlow 文本前端渲染为可交互页面。 ## 技术栈 - 前端Next.js 15 (App Router) React 19 TypeScript Tailwind CSS 4 - 页面库markdown-flow-ui、remark-flow、shadcn/ui - 后端Python 3.11 FastAPI markdown-flow - 包管理前端 pnpm后端 uv ## 目录约定 - 页面组件放 frontend/src/app/route/page.tsx - 可复用组件放 frontend/src/components/文件名用 PascalCase - 工具函数放 frontend/src/lib/文件名用 camelCase - 后端路由放 backend/app/routers/每个模块一个文件 - 不要新建 src/pages/ 目录本项目使用 App Router ## 代码风格 - 组件使用函数式写法 具名导出不用 default export - 样式一律用 Tailwind 原子类不写独立 .css 文件 - 类型定义就近放在使用处跨模块共享的放 src/types/ - 提交前必须通过 pnpm lint 和 pnpm typecheck ## 常用命令 - 前端启动pnpm dev端口 3000 - 后端启动uv run uvicorn app.main:app --reload端口 8000 - 前端构建pnpm build - 类型检查pnpm typecheck ## 禁止事项 - 不要修改 backend/app/core/ 下的解析核心逻辑 - 不要引入新的 UI 库优先用 shadcn/ui 已有组件 - 不要用 any 类型必要时用 unknown 类型守卫这份骨架的关键在于「禁止事项」和「目录约定」两节。AI 最容易犯的错就是乱建目录、乱引依赖你把红线写清楚它就会收敛。写完保存然后在 AI 工具里问一句「这个项目的首页组件在哪个文件」如果它能答对说明 AGENTS.md 已经被读取。4. 配置片段settings.json 与 config.toml不同工具读取配置的方式不一样。Claude Code 走settings.json一些基于 OpenAI 协议的工具走config.toml。下面给出两份可直接用的片段把模型通道指向 TaoToken。Claude Code 的~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是走 OpenAI 协议的工具比如某些 CLI Agent用config.toml[model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken密钥 model gpt-4o [agent] max_turns 20 auto_apply false两个配置的差别只在协议路径Anthropic 风格用https://taotoken.net/apiOpenAI 风格用https://taotoken.net/api/v1。auto_apply false建议先关掉让 AI 生成后你手动确认再应用避免它一口气改十几个文件。注意Key 不要提交到 Git。把settings.json和config.toml加进.gitignore或者用环境变量注入。团队协作时每人本地配自己的 Key。5. Prompt 骨架五要素驱动生成配置好了接下来是 Prompt。高质量 Prompt 有五个要素背景、目标、约束、示例、验收标准。我把它做成一个可复用的骨架你每次填内容即可。【背景】 项目markdown-flow-playground 当前状态首页 src/app/page.tsx 只有编辑器和预览区没有欢迎引导 技术栈Next.js App Router Tailwind CSS 4 shadcn/ui 【目标】 在首页顶部添加欢迎区域包含欢迎文案和一个「快速开始」按钮 点击按钮后编辑器自动加载示例文档。 【约束】 - 欢迎区域放在页面最顶部用 flexbox 居中对齐 - 按钮用 Tailwindbg-blue-500 hover:bg-blue-600 text-white rounded-lg - 不影响现有编辑器和预览区功能 - 组件具名导出不用 default export 【示例】 示例文档内容 ?[%{{name}}... Whats your name?] --- Hello {{name}}! Welcome to MarkdownFlow Playground. 【验收标准】 - 首页显示欢迎文案 - 有可见的「快速开始」按钮 - 点击后编辑器加载示例文档 - 其他功能不受影响涉及文件明确写出来frontend/src/app/page.tsx是首页组件frontend/src/components/Welcome.tsx是新建的欢迎组件。把文件路径写进 PromptAI 就不会乱建目录。生成之后进入审查环节。不满意就带着具体问题继续对话比如「按钮点击后没有加载文档检查一下 onClick 里的状态更新逻辑」满意就应用代码。应用后跑一次pnpm dev手动点一下按钮确认示例文档真的进了编辑器。测试通过这个任务才算完成。6. 验证通道跑一次生成任务确认生效配置和 Prompt 都就位后必须做一次端到端验证确认模型请求真的走了 TaoToken。最简单的办法是让 AI 执行一个明确的小任务然后看结果。在 Claude Code 里输入claude 读取 AGENTS.md告诉我这个项目的首页组件路径和样式方案如果返回的是frontend/src/app/page.tsx和 Tailwind CSS说明 AGENTS.md 被正确读取。如果它答成src/pages/index.tsx说明文件没被识别检查文件名和位置。再验证模型通道。让 AI 生成一个最小改动claude 在 frontend/src/components/ 下新建一个 Badge.tsx导出一个显示文本的徽章组件用 Tailwind 圆角和蓝色背景生成后检查文件是否落在frontend/src/components/Badge.tsx样式是否是 Tailwind 类。如果文件位置和风格都对说明 AGENTS.md 通道配置整体生效。如果报 401 或连接错误回到第 4 节检查 Key 和 base_url。想更直观地确认模型可用可以直接在 https://taotoken.net/api 的模型对话页面发一条测试消息看是否正常返回。这一步能快速区分是「Key 问题」还是「工具配置问题」。7. 本篇常见错排查报错一AI 生成的代码放错目录。九成是 AGENTS.md 没写目录约定或者写了但没被读取。先确认文件名是AGENTS.md且在仓库根目录再确认工具版本支持自动读取。Cursor 需要在设置里开启 Rules 读取。报错二401 Unauthorized。Key 错了或没生效。检查ANTHROPIC_AUTH_TOKEN是否完整复制有没有多余空格。OpenAI 协议的工具注意 base_url 要带/v1Anthropic 协议不带。报错三模型名不识别。不同工具对模型名的写法不同有的要claude-sonnet-4-5有的要带日期后缀。先用模型对话页面确认可用模型名再填进配置。报错四AI 一次改太多文件。把auto_apply设为 false并在 Prompt 的约束里写明「只修改指定文件」。Agent 模式下它容易顺手重构明确边界能压住。报错五生成结果风格不一致。在 AGENTS.md 的代码风格一节补上具体例子比如「具名导出export function Welcome() {}」示例驱动比抽象描述有效得多。8. 把工作流固定下来到这里Vibe Coding 的工作流就闭环了AGENTS.md 定义脚手架约定settings.json / config.toml 接入统一通道五要素 Prompt 驱动生成人工审查后应用最后跑一次验证确认通道生效。这套流程的价值在于可复用——换一个项目你只需要重写 AGENTS.md 和 Prompt 骨架通道配置不用动。长期做编码和 Agent 任务的话可以看看 Coding Plan它按周期提供额度比单次调用更适合高频的 Agent 循环https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 里面有各工具的详细配置说明。Key 管理统一在 https://taotoken.net/api-keys 建议给不同项目建不同的 Key方便排查问题时定位来源。下一篇我们会在这个脚手架上加「多轮迭代」的工作流如何让 AI 记住上一轮的改动、如何用 diff 审查代替全量重写。
