企业官网建设流程全解析

1. 为什么 Vibe Coding 需要一份 AGENTS.md

Vibe 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 为例，它是一个前后端分离项目：

前后端协作流程是：前端把用户输入的 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/api，OpenAI 风格用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 居中对齐 - 按钮用 Tailwind：bg-blue-500 hover:bg-blue-600 text-white rounded-lg - 不影响现有编辑器和预览区功能 - 组件具名导出，不用 default export 【示例】 示例文档内容： ?[%{{name}}... What's your name?] --- Hello {{name}}! Welcome to MarkdownFlow Playground. 【验收标准】 - 首页显示欢迎文案 - 有可见的「快速开始」按钮 - 点击后编辑器加载示例文档 - 其他功能不受影响

涉及文件明确写出来：frontend/src/app/page.tsx是首页组件，frontend/src/components/Welcome.tsx是新建的欢迎组件。把文件路径写进 Prompt，AI 就不会乱建目录。

生成之后进入审查环节。不满意就带着具体问题继续对话，比如「按钮点击后没有加载文档，检查一下 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 要带/v1，Anthropic 协议不带。

报错三：模型名不识别。不同工具对模型名的写法不同，有的要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 审查代替全量重写。