1. 為什么 Vibe Coding 需要一份 AGENTS.mdVibe Coding 的核心是「用自然語言描述意圖讓 AI 補(bǔ)齊實現(xiàn)細(xì)節(jié)」。聽起來很爽但真正落到一個多文件項目里問題馬上暴露AI 不知道你的目錄約定不知道你用的是 Next.js App Router 還是 Pages Router不知道樣式走 Tailwind 還是 CSS Module于是它生成的代碼「能跑但不對味」——文件放錯位置、命名風(fēng)格打架、技術(shù)?；煊?。我試過在一個 React FastAPI 的項目里連續(xù)讓 AI 改三次首頁每次它都新建一個components/Home.tsx而項目里其實早就有src/app/page.tsx。這不是模型笨是我沒給它「項目使用手冊」。AGENTS.md 就是這份手冊。Cursor 和 Claude Code 都會自動讀取項目根目錄下的 AGENTS.md把它當(dāng)作長期上下文。你寫清楚目錄結(jié)構(gòu)、技術(shù)棧、代碼風(fēng)格、常用命令A(yù)I 生成的代碼就會自動落在正確的文件里、遵循你的命名習(xí)慣、用對依賴庫。這一章我們就把 Vibe Coding 的工作流固定下來AGENTS.md 定義腳手架約定Prompt 骨架驅(qū)動生成TaoToken 統(tǒng)一提供模型通道。適合誰看已經(jīng)在用 Cursor / Claude Code / Cline 這類工具但生成結(jié)果總需要大改的開發(fā)者或者剛接觸 Vibe Coding想一次性把工作流搭對的人。讀完你能拿到一份可直接復(fù)制的 AGENTS.md 骨架、一份 settings.json / config.toml 配置片段以及一套驗證通道是否生效的動作。2. 前置準(zhǔn)備TaoToken 通道與項目基線在寫 AGENTS.md 之前先把模型通道接好。Vibe Coding 的工作流里AI 工具會頻繁發(fā)起請求補(bǔ)全、對話、Agent 循環(huán)如果每個工具各配一套 Key管理起來很亂。TaoToken 的思路是提供一個統(tǒng)一的 API 入口兼容 OpenAI 與 Anthropic 兩種協(xié)議風(fēng)格你只需要維護(hù)一個 Key。先拿到 Key打開 https://taotoken.net/api-keys 登錄后在控制臺創(chuàng)建 API Key復(fù)制保存。注意 Key 只在創(chuàng)建時完整顯示一次丟了就重新建一個。然后確認(rèn)你的項目基線。以本章貫穿的 markdown-flow-playground 為例它是一個前后端分離項目層技術(shù)棧關(guān)鍵目錄后端Python FastAPI markdown-flowbackend/app/前端React Next.js TypeScript Tailwind CSS 4frontend/src/頁面庫markdown-flow-ui、remark-flow、shadcn/uifrontend/src/components/前后端協(xié)作流程是前端把用戶輸入的 MarkdownFlow 文本 POST 給后端/api/render后端用 markdown-flow 解析成結(jié)構(gòu)化 JSON 返回前端用 markdown-flow-ui 渲染成交互式頁面。理解這條鏈路你才知道 AI 改前端時不該去動后端解析邏輯。提示如果你的項目還沒有 AGENTS.md直接在項目根目錄新建一個空文件即可AI 工具會自動識別。文件名必須全大寫AGENTS.md放在倉庫根目錄。3. 可復(fù)制的 AGENTS.md 骨架一份高質(zhì)量的 AGENTS.md 有三個原則結(jié)構(gòu)化清晰、提供上下文、示例驅(qū)動。下面這份骨架你可以直接改項目名后使用我按「AI 讀得懂」的順序組織而不是按人類文檔的習(xí)慣。# AGENTS.md ## 項目概述 markdown-flow-playground一個用自然語言控制 AI 輸出交互式內(nèi)容的 Playground。 用戶輸入 MarkdownFlow 文本前端渲染為可交互頁面。 ## 技術(shù)棧 - 前端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 - 可復(fù)用組件放 frontend/src/components/文件名用 PascalCase - 工具函數(shù)放 frontend/src/lib/文件名用 camelCase - 后端路由放 backend/app/routers/每個模塊一個文件 - 不要新建 src/pages/ 目錄本項目使用 App Router ## 代碼風(fēng)格 - 組件使用函數(shù)式寫法 具名導(dǎo)出不用 default export - 樣式一律用 Tailwind 原子類不寫?yīng)毩?.css 文件 - 類型定義就近放在使用處跨模塊共享的放 src/types/ - 提交前必須通過 pnpm lint 和 pnpm typecheck ## 常用命令 - 前端啟動pnpm dev端口 3000 - 后端啟動uv run uvicorn app.main:app --reload端口 8000 - 前端構(gòu)建pnpm build - 類型檢查pnpm typecheck ## 禁止事項 - 不要修改 backend/app/core/ 下的解析核心邏輯 - 不要引入新的 UI 庫優(yōu)先用 shadcn/ui 已有組件 - 不要用 any 類型必要時用 unknown 類型守衛(wèi)這份骨架的關(guān)鍵在于「禁止事項」和「目錄約定」兩節(jié)。AI 最容易犯的錯就是亂建目錄、亂引依賴你把紅線寫清楚它就會收斂。寫完保存然后在 AI 工具里問一句「這個項目的首頁組件在哪個文件」如果它能答對說明 AGENTS.md 已經(jīng)被讀取。4. 配置片段settings.json 與 config.toml不同工具讀取配置的方式不一樣。Claude Code 走settings.json一些基于 OpenAI 協(xié)議的工具走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 協(xié)議的工具比如某些 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兩個配置的差別只在協(xié)議路徑Anthropic 風(fēng)格用https://taotoken.net/apiOpenAI 風(fēng)格用https://taotoken.net/api/v1。auto_apply false建議先關(guān)掉讓 AI 生成后你手動確認(rèn)再應(yīng)用避免它一口氣改十幾個文件。注意Key 不要提交到 Git。把settings.json和config.toml加進(jìn).gitignore或者用環(huán)境變量注入。團(tuán)隊協(xié)作時每人本地配自己的 Key。5. Prompt 骨架五要素驅(qū)動生成配置好了接下來是 Prompt。高質(zhì)量 Prompt 有五個要素背景、目標(biāo)、約束、示例、驗收標(biāo)準(zhǔn)。我把它做成一個可復(fù)用的骨架你每次填內(nèi)容即可?！颈尘啊?項目markdown-flow-playground 當(dāng)前狀態(tài)首頁 src/app/page.tsx 只有編輯器和預(yù)覽區(qū)沒有歡迎引導(dǎo) 技術(shù)棧Next.js App Router Tailwind CSS 4 shadcn/ui 【目標(biāo)】 在首頁頂部添加歡迎區(qū)域包含歡迎文案和一個「快速開始」按鈕 點擊按鈕后編輯器自動加載示例文檔。 【約束】 - 歡迎區(qū)域放在頁面最頂部用 flexbox 居中對齊 - 按鈕用 Tailwindbg-blue-500 hover:bg-blue-600 text-white rounded-lg - 不影響現(xiàn)有編輯器和預(yù)覽區(qū)功能 - 組件具名導(dǎo)出不用 default export 【示例】 示例文檔內(nèi)容 ?[%{{name}}... Whats your name?] --- Hello {{name}}! Welcome to MarkdownFlow Playground. 【驗收標(biāo)準(zhǔn)】 - 首頁顯示歡迎文案 - 有可見的「快速開始」按鈕 - 點擊后編輯器加載示例文檔 - 其他功能不受影響涉及文件明確寫出來frontend/src/app/page.tsx是首頁組件frontend/src/components/Welcome.tsx是新建的歡迎組件。把文件路徑寫進(jìn) PromptAI 就不會亂建目錄。生成之后進(jìn)入審查環(huán)節(jié)。不滿意就帶著具體問題繼續(xù)對話比如「按鈕點擊后沒有加載文檔檢查一下 onClick 里的狀態(tài)更新邏輯」?jié)M意就應(yīng)用代碼。應(yīng)用后跑一次pnpm dev手動點一下按鈕確認(rèn)示例文檔真的進(jìn)了編輯器。測試通過這個任務(wù)才算完成。6. 驗證通道跑一次生成任務(wù)確認(rèn)生效配置和 Prompt 都就位后必須做一次端到端驗證確認(rèn)模型請求真的走了 TaoToken。最簡單的辦法是讓 AI 執(zhí)行一個明確的小任務(wù)然后看結(jié)果。在 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導(dǎo)出一個顯示文本的徽章組件用 Tailwind 圓角和藍(lán)色背景生成后檢查文件是否落在frontend/src/components/Badge.tsx樣式是否是 Tailwind 類。如果文件位置和風(fēng)格都對說明 AGENTS.md 通道配置整體生效。如果報 401 或連接錯誤回到第 4 節(jié)檢查 Key 和 base_url。想更直觀地確認(rèn)模型可用可以直接在 https://taotoken.net/api 的模型對話頁面發(fā)一條測試消息看是否正常返回。這一步能快速區(qū)分是「Key 問題」還是「工具配置問題」。7. 本篇常見錯排查報錯一AI 生成的代碼放錯目錄。九成是 AGENTS.md 沒寫目錄約定或者寫了但沒被讀取。先確認(rèn)文件名是AGENTS.md且在倉庫根目錄再確認(rèn)工具版本支持自動讀取。Cursor 需要在設(shè)置里開啟 Rules 讀取。報錯二401 Unauthorized。Key 錯了或沒生效。檢查ANTHROPIC_AUTH_TOKEN是否完整復(fù)制有沒有多余空格。OpenAI 協(xié)議的工具注意 base_url 要帶/v1Anthropic 協(xié)議不帶。報錯三模型名不識別。不同工具對模型名的寫法不同有的要claude-sonnet-4-5有的要帶日期后綴。先用模型對話頁面確認(rèn)可用模型名再填進(jìn)配置。報錯四AI 一次改太多文件。把a(bǔ)uto_apply設(shè)為 false并在 Prompt 的約束里寫明「只修改指定文件」。Agent 模式下它容易順手重構(gòu)明確邊界能壓住。報錯五生成結(jié)果風(fēng)格不一致。在 AGENTS.md 的代碼風(fēng)格一節(jié)補(bǔ)上具體例子比如「具名導(dǎo)出export function Welcome() {}」示例驅(qū)動比抽象描述有效得多。8. 把工作流固定下來到這里Vibe Coding 的工作流就閉環(huán)了AGENTS.md 定義腳手架約定settings.json / config.toml 接入統(tǒng)一通道五要素 Prompt 驅(qū)動生成人工審查后應(yīng)用最后跑一次驗證確認(rèn)通道生效。這套流程的價值在于可復(fù)用——換一個項目你只需要重寫 AGENTS.md 和 Prompt 骨架通道配置不用動。長期做編碼和 Agent 任務(wù)的話可以看看 Coding Plan它按周期提供額度比單次調(diào)用更適合高頻的 Agent 循環(huán)https://taotoken.net/coding-plan 。接入文檔在 https://taotoken.net/doc 里面有各工具的詳細(xì)配置說明。Key 管理統(tǒng)一在 https://taotoken.net/api-keys 建議給不同項目建不同的 Key方便排查問題時定位來源。下一篇我們會在這個腳手架上加「多輪迭代」的工作流如何讓 AI 記住上一輪的改動、如何用 diff 審查代替全量重寫。