一 Key 篇）)
1. 前端 AI 編程助手為什么總寫出“不像你項(xiàng)目”的代碼先說(shuō)結(jié)論AI 編程助手在前端場(chǎng)景里翻車九成不是模型能力問(wèn)題而是上下文供給方式錯(cuò)了。你打開(kāi) Cursor 或 Cline丟一句“幫我寫個(gè)帶權(quán)限控制的動(dòng)態(tài)路由菜單”它給你的代碼可能用了 Redux Toolkit而你的項(xiàng)目早就統(tǒng)一到 Zustand它可能在 TypeScript 里隨手寫any而你的tsconfig開(kāi)了strict它可能把樣式寫成內(nèi)聯(lián)style{{}}而你們團(tuán)隊(duì)規(guī)定只用 Tailwind 的className。這些現(xiàn)象背后是同一個(gè)機(jī)制模型在訓(xùn)練時(shí)見(jiàn)過(guò)海量開(kāi)源代碼它的“默認(rèn)偏好”是互聯(lián)網(wǎng)平均水平而不是你團(tuán)隊(duì)的工程標(biāo)準(zhǔn)。你越是用一段超長(zhǎng) System Prompt 去糾正它越容易觸發(fā)上下文過(guò)載——關(guān)鍵指令被淹沒(méi)Token 成本還一路飆升。我試過(guò)把 3000 字的規(guī)范塞進(jìn)對(duì)話開(kāi)頭結(jié)果模型寫到第三個(gè)組件就開(kāi)始“忘記”前面的約束。后來(lái)?yè)Q成 Rules Skills 的分層結(jié)構(gòu)配合 TaoToken 統(tǒng)一 Key 打通多個(gè)工具才真正穩(wěn)定下來(lái)。這篇就按“問(wèn)題 → 前置 → 配置 → 驗(yàn)證 → 排障 → 分流”的順序把可復(fù)制的目錄結(jié)構(gòu)、配置片段和驗(yàn)證步驟全部交給你。適合誰(shuí)看正在用 Cursor、Cline、Claude Code 做前端開(kāi)發(fā)想讓 AI 輸出符合團(tuán)隊(duì)規(guī)范的工程師以及需要給多人團(tuán)隊(duì)統(tǒng)一 AI 編碼標(biāo)準(zhǔn)的架構(gòu)師和技術(shù) Leader。核心檢索詞先明確AI 編程助手、Rules、Skills、前端、CLAUDE.md。這五個(gè)詞貫穿全文你照著做就能落地。2. TaoToken 統(tǒng)一 Key 與 API 通道的前置準(zhǔn)備多工具協(xié)作的第一個(gè)坑是每個(gè)編輯器都要單獨(dú)配一套 Key 和 Base URL。Cursor 一套、Cline 一套、Claude Code 又一套換模型時(shí)逐個(gè)改團(tuán)隊(duì)里每個(gè)人的配置還不一致。TaoToken 的價(jià)值就在這里它提供統(tǒng)一的 API 通道你只需要一個(gè) Key、一個(gè) Base URL就能讓多個(gè) AI 編程助手走同一條鏈路。官網(wǎng)入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 這個(gè)不加 UTM。注意區(qū)分官網(wǎng)用于注冊(cè)和查看文檔API 地址用于填進(jìn)編輯器的 Base URL 字段。前置準(zhǔn)備分三步都很短第一步拿到 Key。進(jìn)入控制臺(tái)創(chuàng)建 API Key路徑是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 頁(yè)面生成。生成后立刻復(fù)制保存頁(yè)面刷新后不再完整顯示。API Keys 直達(dá)鏈接https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第二步確認(rèn)你要用的模型 ID。前端編碼場(chǎng)景常用的是 Claude 系列和 GPT 系列具體可用列表在文檔里查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Model ID 必須和文檔里寫的完全一致大小寫、連字符都不能錯(cuò)這是后面 401 和reading choices報(bào)錯(cuò)的高發(fā)點(diǎn)。第三步?jīng)Q定你的主力工具。如果你長(zhǎng)期做編碼和 Agent 任務(wù)建議直接上 Coding Plan額度更劃算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。只是想先驗(yàn)證模型對(duì)話效果用模型對(duì)話頁(yè)試https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。這里有個(gè)關(guān)鍵認(rèn)知TaoToken 是 API 通道不是編輯器替代品。你的代碼編輯、文件讀寫、終端執(zhí)行仍然在 Cursor / Cline / Claude Code 里完成TaoToken 只負(fù)責(zé)把模型請(qǐng)求接過(guò)去。所以配置的重點(diǎn)永遠(yuǎn)是三件套——Base URL、Key、Model ID缺一不可。3. 可復(fù)制的 Rules 與 Skills 目錄結(jié)構(gòu)及配置片段這一節(jié)是全文的技術(shù)核心。先給目錄結(jié)構(gòu)再給每個(gè)文件的配置片段路徑和原文保持一致你直接復(fù)制到項(xiàng)目根目錄即可。3.1 目錄結(jié)構(gòu)your-frontend-project/ ├── CLAUDE.md ├── docs/ │ ├── rules/ │ │ ├── react-component-rules.md │ │ ├── api-fetching-rules.md │ │ ├── jest-testing-rules.md │ │ └── test-failing-rules.md │ └── skills/ │ ├── modal-accessibility-skill.md │ └── dynamic-route-skill.md ├── .cursor/ │ └── mcp.json └── .claude/ └── settings.jsonCLAUDE.md是入口路由docs/rules/放禁止性約束docs/skills/放標(biāo)準(zhǔn)實(shí)現(xiàn)方案。.cursor/mcp.json和.claude/settings.json是工具側(cè)配置下面逐個(gè)給。3.2 CLAUDE.md 路由入口# 項(xiàng)目 AI 協(xié)作約定 ## 規(guī)則路由Rules - 編寫 React UI 組件前閱讀 docs/rules/react-component-rules.md - 編寫業(yè)務(wù)數(shù)據(jù)請(qǐng)求邏輯前閱讀 docs/rules/api-fetching-rules.md - 編寫單元測(cè)試前閱讀 docs/rules/jest-testing-rules.md - 運(yùn)行測(cè)試遇到失敗報(bào)錯(cuò)時(shí)優(yōu)先閱讀 docs/rules/test-failing-rules.md ## 技能路由Skills - 遇到彈窗或模態(tài)框需求時(shí)閱讀 docs/skills/modal-accessibility-skill.md - 遇到動(dòng)態(tài)路由或權(quán)限菜單需求時(shí)閱讀 docs/skills/dynamic-route-skill.md ## 全局紅線 - 禁止使用 any類型必須顯式聲明 - 禁止內(nèi)聯(lián) style樣式統(tǒng)一走 Tailwind className - 狀態(tài)管理統(tǒng)一使用 Zustand禁止引入 Redux注意CLAUDE.md只做路由不寫具體規(guī)范細(xì)節(jié)。細(xì)節(jié)全部下沉到docs/rules/和docs/skills/這樣模型按需加載不會(huì)一次性吞掉所有上下文。3.3 規(guī)則文件示例docs/rules/react-component-rules.md# React 組件規(guī)則 - 絕不允許使用 style 屬性編寫行內(nèi)樣式所有樣式必須通過(guò) Tailwind CSS 的 className 實(shí)現(xiàn) - 組件必須使用函數(shù)式寫法禁止 class 組件 - Props 必須定義 TypeScript interface命名以 Props 結(jié)尾 - 副作用統(tǒng)一放 useEffect依賴數(shù)組必須完整docs/rules/api-fetching-rules.md# 數(shù)據(jù)請(qǐng)求規(guī)則 - 服務(wù)端狀態(tài)統(tǒng)一使用 React Query 的 useQuery / useMutation 封裝 - 禁止在組件內(nèi)直接調(diào)用 fetch必須走 src/api/ 下的封裝層 - 請(qǐng)求錯(cuò)誤必須統(tǒng)一走 errorHandler禁止裸 try-catch 吞異常3.4 技能文件示例docs/skills/modal-accessibility-skill.md# 可訪問(wèn)性模態(tài)框技能 ## 標(biāo)準(zhǔn)實(shí)現(xiàn)路徑 1. 必須使用 radix-ui/react-dialog 作為底層 headless 組件 2. 必須包含屏幕閱讀器可見(jiàn)的 DialogTitle 和 DialogDescription 3. 樣式覆蓋必須遵循 tailwind.config.js 中的定制設(shè)計(jì)系統(tǒng) 4. 關(guān)閉按鈕必須有 aria-label ## 禁止事項(xiàng) - 禁止引入 antd Modal 等重型組件庫(kù) - 禁止手寫 focus trap 邏輯3.5 工具側(cè)配置片段Cursor 的 MCP 配置.cursor/mcp.json{ mcpServers: { taotoken: { url: https://taotoken.net/api, headers: { Authorization: Bearer YOUR_TAOTOKEN_KEY } } } }Claude Code 的.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: YOUR_TAOTOKEN_KEY, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Cline 在編輯器設(shè)置里填三件套Base URL 填https://taotoken.net/apiAPI Key 填你的 TaoToken KeyModel ID 填文檔里確認(rèn)過(guò)的模型名。Codex 用戶如果走auth.json結(jié)構(gòu)是{ base_url: https://taotoken.net/api, api_key: YOUR_TAOTOKEN_KEY, model: claude-sonnet-4-20250514 }三件套 Base URL Key Model ID 在任何工具里都不能少。CC Switch 切換配置時(shí)也是改這三個(gè)字段別只改 Key 忘了 Base URL。4. 驗(yàn)證規(guī)則生效與技能觸發(fā)的具體操作配置寫完不代表生效必須驗(yàn)證。下面給三個(gè)可復(fù)現(xiàn)的驗(yàn)證動(dòng)作每個(gè)都有明確的預(yù)期結(jié)果。4.1 驗(yàn)證 Rules 是否被讀取在 Cursor 或 Cline 里新建一個(gè)測(cè)試組件文件src/components/TestButton.tsx然后輸入提示幫我寫一個(gè)帶 hover 效果的按鈕組件如果 Rules 生效模型輸出里不應(yīng)該出現(xiàn)style{{}}而應(yīng)該用className配合 Tailwind。同時(shí)它應(yīng)該主動(dòng)聲明 Props interface。如果它寫了內(nèi)聯(lián)樣式說(shuō)明CLAUDE.md的路由沒(méi)被讀到檢查文件是否在項(xiàng)目根目錄、文件名大小寫是否正確。4.2 驗(yàn)證 Skills 是否被觸發(fā)輸入提示幫我實(shí)現(xiàn)一個(gè)確認(rèn)刪除的彈窗預(yù)期結(jié)果是模型先讀取docs/skills/modal-accessibility-skill.md然后按 Radix UI 路徑實(shí)現(xiàn)包含DialogTitle和DialogDescription。如果它直接引入 antd 的 Modal說(shuō)明技能路由沒(méi)命中檢查CLAUDE.md里技能路由的關(guān)鍵詞是否覆蓋了“彈窗”“模態(tài)框”這類觸發(fā)詞。4.3 驗(yàn)證 API 通道是否連通在終端里直接發(fā)一個(gè)請(qǐng)求確認(rèn) TaoToken 通道正常curl https://taotoken.net/api/v1/messages \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 只回復(fù) OK}] }返回里能看到content字段且文本是OK說(shuō)明 Key、Base URL、Model ID 三件套全部正確。這一步過(guò)了編輯器里的報(bào)錯(cuò)基本都能排除通道問(wèn)題。4.4 驗(yàn)證多工具一致性同一個(gè) Key 分別配到 Cursor 和 Claude Code用同一個(gè)提示詞跑一遍對(duì)比輸出風(fēng)格是否一致。如果 Cursor 遵守了 Tailwind 規(guī)則而 Claude Code 沒(méi)有說(shuō)明 Claude Code 的settings.json沒(méi)讀到項(xiàng)目級(jí)CLAUDE.md檢查工作目錄是否在項(xiàng)目根。5. 本篇常見(jiàn)報(bào)錯(cuò)與排查對(duì)照這一節(jié)按真實(shí)報(bào)錯(cuò)來(lái)每條都給現(xiàn)象、原因、修法。401 Unauthorized最常見(jiàn)。現(xiàn)象是請(qǐng)求直接被拒。原因通常是 Key 復(fù)制不完整、Key 前后有空格、或者用了官網(wǎng)地址當(dāng) Base URL。修法重新在 API Keys 頁(yè)面生成確認(rèn) Base URL 是https://taotoken.net/api而不是官網(wǎng)首頁(yè)。local proxy failed出現(xiàn)在 Cline 或 Cursor 的 MCP 配置里。原因是mcp.json里的url字段寫錯(cuò)或者網(wǎng)絡(luò)層攔截。修法確認(rèn)url是https://taotoken.net/api不要帶多余路徑檢查Authorization頭的Bearer前綴有沒(méi)有漏。reading choices 報(bào)錯(cuò)通常是響應(yīng)結(jié)構(gòu)不符合預(yù)期根因是 Model ID 寫錯(cuò)模型返回了非標(biāo)準(zhǔn)格式。修法回到文檔頁(yè)核對(duì) Model ID 的完整拼寫注意日期后綴和連字符。OAuth 相關(guān)報(bào)錯(cuò)Claude Code 首次啟動(dòng)時(shí)可能走 OAuth 流程。如果你已經(jīng)用settings.json配了ANTHROPIC_API_KEY需要在啟動(dòng)參數(shù)里顯式跳過(guò) OAuth或者確認(rèn)環(huán)境變量?jī)?yōu)先級(jí)高于登錄態(tài)。修法檢查settings.json的env塊是否被正確加載必要時(shí)在終端export一次再啟動(dòng)。規(guī)則不生效但通道正?，F(xiàn)象是模型能回復(fù)但無(wú)視 Rules。原因是CLAUDE.md不在工作目錄根或者文件名被改成了claude.md。修法確認(rèn)文件名全大寫CLAUDE.md位置在項(xiàng)目根。技能觸發(fā)不穩(wěn)定有時(shí)觸發(fā)有時(shí)不觸發(fā)。原因是CLAUDE.md里的觸發(fā)詞太窄。修法把觸發(fā)詞寫寬一點(diǎn)比如“彈窗 / 模態(tài)框 / dialog / modal”都列上。排查順序建議固定為先 curl 驗(yàn)通道 → 再驗(yàn)CLAUDE.md是否被讀 → 最后驗(yàn)技能觸發(fā)。這樣能快速定位是通道問(wèn)題還是上下文問(wèn)題。6. 把統(tǒng)一 Key 與 Rules/Skills 固化成團(tuán)隊(duì)資產(chǎn)走到這里你已經(jīng)有了可復(fù)制的目錄結(jié)構(gòu)、可粘貼的配置片段、可復(fù)現(xiàn)的驗(yàn)證步驟和排障對(duì)照表。剩下的事是把它變成團(tuán)隊(duì)資產(chǎn)而不是個(gè)人技巧。具體做法把CLAUDE.md、docs/rules/、docs/skills/提交進(jìn) Git 倉(cāng)庫(kù)作為項(xiàng)目腳手架的一部分。新同學(xué)拉下代碼配好 TaoToken 三件套R(shí)ules 和 Skills 自動(dòng)生效不需要口口相傳。團(tuán)隊(duì)里誰(shuí)發(fā)現(xiàn) AI 犯了新錯(cuò)誤就把它寫成一條新規(guī)則或新技能走 PR 評(píng)審合并。這樣規(guī)范會(huì)隨項(xiàng)目一起生長(zhǎng)。定期做一次“水療日”審查docs/rules/和docs/skills/合并重復(fù)條目刪除過(guò)時(shí)約束確保CLAUDE.md的路由顆粒度足夠細(xì)。上下文冗余是 Rules/Skills 體系最大的敵人保持精簡(jiǎn)比不斷堆砌更重要。需要長(zhǎng)期跑編碼和 Agent 任務(wù)的團(tuán)隊(duì)直接上 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入過(guò)程中遇到通道或配置問(wèn)題先查接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 再對(duì)照 API Keys 頁(yè)面確認(rèn) Key 狀態(tài)https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先驗(yàn)證模型輸出風(fēng)格用模型對(duì)話頁(yè)試一輪https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后一句實(shí)操建議先把CLAUDE.md和兩個(gè)規(guī)則文件建起來(lái)跑通第 4 節(jié)的三個(gè)驗(yàn)證動(dòng)作再逐步補(bǔ) Skills。不要一上來(lái)就寫二十個(gè)文件上下文過(guò)載會(huì)讓效果反而變差。 徹底駕馭前端 AI 編程助手：基于 Rules 與 Skills 的提效核心法則（TaoToken 統(tǒng)一 Key 篇）
1. 前端 AI 編程助手為什么總寫出“不像你項(xiàng)目”的代碼先說(shuō)結(jié)論AI 編程助手在前端場(chǎng)景里翻車九成不是模型能力問(wèn)題而是上下文供給方式錯(cuò)了。你打開(kāi) Cursor 或 Cline丟一句“幫我寫個(gè)帶權(quán)限控制的動(dòng)態(tài)路由菜單”它給你的代碼可能用了 Redux Toolkit而你的項(xiàng)目早就統(tǒng)一到 Zustand它可能在 TypeScript 里隨手寫any而你的tsconfig開(kāi)了strict它可能把樣式寫成內(nèi)聯(lián)style{{}}而你們團(tuán)隊(duì)規(guī)定只用 Tailwind 的className。這些現(xiàn)象背后是同一個(gè)機(jī)制模型在訓(xùn)練時(shí)見(jiàn)過(guò)海量開(kāi)源代碼它的“默認(rèn)偏好”是互聯(lián)網(wǎng)平均水平而不是你團(tuán)隊(duì)的工程標(biāo)準(zhǔn)。你越是用一段超長(zhǎng) System Prompt 去糾正它越容易觸發(fā)上下文過(guò)載——關(guān)鍵指令被淹沒(méi)Token 成本還一路飆升。我試過(guò)把 3000 字的規(guī)范塞進(jìn)對(duì)話開(kāi)頭結(jié)果模型寫到第三個(gè)組件就開(kāi)始“忘記”前面的約束。后來(lái)?yè)Q成 Rules Skills 的分層結(jié)構(gòu)配合 TaoToken 統(tǒng)一 Key 打通多個(gè)工具才真正穩(wěn)定下來(lái)。這篇就按“問(wèn)題 → 前置 → 配置 → 驗(yàn)證 → 排障 → 分流”的順序把可復(fù)制的目錄結(jié)構(gòu)、配置片段和驗(yàn)證步驟全部交給你。適合誰(shuí)看正在用 Cursor、Cline、Claude Code 做前端開(kāi)發(fā)想讓 AI 輸出符合團(tuán)隊(duì)規(guī)范的工程師以及需要給多人團(tuán)隊(duì)統(tǒng)一 AI 編碼標(biāo)準(zhǔn)的架構(gòu)師和技術(shù) Leader。核心檢索詞先明確AI 編程助手、Rules、Skills、前端、CLAUDE.md。這五個(gè)詞貫穿全文你照著做就能落地。2. TaoToken 統(tǒng)一 Key 與 API 通道的前置準(zhǔn)備多工具協(xié)作的第一個(gè)坑是每個(gè)編輯器都要單獨(dú)配一套 Key 和 Base URL。Cursor 一套、Cline 一套、Claude Code 又一套換模型時(shí)逐個(gè)改團(tuán)隊(duì)里每個(gè)人的配置還不一致。TaoToken 的價(jià)值就在這里它提供統(tǒng)一的 API 通道你只需要一個(gè) Key、一個(gè) Base URL就能讓多個(gè) AI 編程助手走同一條鏈路。官網(wǎng)入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 這個(gè)不加 UTM。注意區(qū)分官網(wǎng)用于注冊(cè)和查看文檔API 地址用于填進(jìn)編輯器的 Base URL 字段。前置準(zhǔn)備分三步都很短第一步拿到 Key。進(jìn)入控制臺(tái)創(chuàng)建 API Key路徑是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 頁(yè)面生成。生成后立刻復(fù)制保存頁(yè)面刷新后不再完整顯示。API Keys 直達(dá)鏈接https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第二步確認(rèn)你要用的模型 ID。前端編碼場(chǎng)景常用的是 Claude 系列和 GPT 系列具體可用列表在文檔里查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Model ID 必須和文檔里寫的完全一致大小寫、連字符都不能錯(cuò)這是后面 401 和reading choices報(bào)錯(cuò)的高發(fā)點(diǎn)。第三步?jīng)Q定你的主力工具。如果你長(zhǎng)期做編碼和 Agent 任務(wù)建議直接上 Coding Plan額度更劃算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。只是想先驗(yàn)證模型對(duì)話效果用模型對(duì)話頁(yè)試https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。這里有個(gè)關(guān)鍵認(rèn)知TaoToken 是 API 通道不是編輯器替代品。你的代碼編輯、文件讀寫、終端執(zhí)行仍然在 Cursor / Cline / Claude Code 里完成TaoToken 只負(fù)責(zé)把模型請(qǐng)求接過(guò)去。所以配置的重點(diǎn)永遠(yuǎn)是三件套——Base URL、Key、Model ID缺一不可。3. 可復(fù)制的 Rules 與 Skills 目錄結(jié)構(gòu)及配置片段這一節(jié)是全文的技術(shù)核心。先給目錄結(jié)構(gòu)再給每個(gè)文件的配置片段路徑和原文保持一致你直接復(fù)制到項(xiàng)目根目錄即可。3.1 目錄結(jié)構(gòu)your-frontend-project/ ├── CLAUDE.md ├── docs/ │ ├── rules/ │ │ ├── react-component-rules.md │ │ ├── api-fetching-rules.md │ │ ├── jest-testing-rules.md │ │ └── test-failing-rules.md │ └── skills/ │ ├── modal-accessibility-skill.md │ └── dynamic-route-skill.md ├── .cursor/ │ └── mcp.json └── .claude/ └── settings.jsonCLAUDE.md是入口路由docs/rules/放禁止性約束docs/skills/放標(biāo)準(zhǔn)實(shí)現(xiàn)方案。.cursor/mcp.json和.claude/settings.json是工具側(cè)配置下面逐個(gè)給。3.2 CLAUDE.md 路由入口# 項(xiàng)目 AI 協(xié)作約定 ## 規(guī)則路由Rules - 編寫 React UI 組件前閱讀 docs/rules/react-component-rules.md - 編寫業(yè)務(wù)數(shù)據(jù)請(qǐng)求邏輯前閱讀 docs/rules/api-fetching-rules.md - 編寫單元測(cè)試前閱讀 docs/rules/jest-testing-rules.md - 運(yùn)行測(cè)試遇到失敗報(bào)錯(cuò)時(shí)優(yōu)先閱讀 docs/rules/test-failing-rules.md ## 技能路由Skills - 遇到彈窗或模態(tài)框需求時(shí)閱讀 docs/skills/modal-accessibility-skill.md - 遇到動(dòng)態(tài)路由或權(quán)限菜單需求時(shí)閱讀 docs/skills/dynamic-route-skill.md ## 全局紅線 - 禁止使用 any類型必須顯式聲明 - 禁止內(nèi)聯(lián) style樣式統(tǒng)一走 Tailwind className - 狀態(tài)管理統(tǒng)一使用 Zustand禁止引入 Redux注意CLAUDE.md只做路由不寫具體規(guī)范細(xì)節(jié)。細(xì)節(jié)全部下沉到docs/rules/和docs/skills/這樣模型按需加載不會(huì)一次性吞掉所有上下文。3.3 規(guī)則文件示例docs/rules/react-component-rules.md# React 組件規(guī)則 - 絕不允許使用 style 屬性編寫行內(nèi)樣式所有樣式必須通過(guò) Tailwind CSS 的 className 實(shí)現(xiàn) - 組件必須使用函數(shù)式寫法禁止 class 組件 - Props 必須定義 TypeScript interface命名以 Props 結(jié)尾 - 副作用統(tǒng)一放 useEffect依賴數(shù)組必須完整docs/rules/api-fetching-rules.md# 數(shù)據(jù)請(qǐng)求規(guī)則 - 服務(wù)端狀態(tài)統(tǒng)一使用 React Query 的 useQuery / useMutation 封裝 - 禁止在組件內(nèi)直接調(diào)用 fetch必須走 src/api/ 下的封裝層 - 請(qǐng)求錯(cuò)誤必須統(tǒng)一走 errorHandler禁止裸 try-catch 吞異常3.4 技能文件示例docs/skills/modal-accessibility-skill.md# 可訪問(wèn)性模態(tài)框技能 ## 標(biāo)準(zhǔn)實(shí)現(xiàn)路徑 1. 必須使用 radix-ui/react-dialog 作為底層 headless 組件 2. 必須包含屏幕閱讀器可見(jiàn)的 DialogTitle 和 DialogDescription 3. 樣式覆蓋必須遵循 tailwind.config.js 中的定制設(shè)計(jì)系統(tǒng) 4. 關(guān)閉按鈕必須有 aria-label ## 禁止事項(xiàng) - 禁止引入 antd Modal 等重型組件庫(kù) - 禁止手寫 focus trap 邏輯3.5 工具側(cè)配置片段Cursor 的 MCP 配置.cursor/mcp.json{ mcpServers: { taotoken: { url: https://taotoken.net/api, headers: { Authorization: Bearer YOUR_TAOTOKEN_KEY } } } }Claude Code 的.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: YOUR_TAOTOKEN_KEY, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Cline 在編輯器設(shè)置里填三件套Base URL 填https://taotoken.net/apiAPI Key 填你的 TaoToken KeyModel ID 填文檔里確認(rèn)過(guò)的模型名。Codex 用戶如果走auth.json結(jié)構(gòu)是{ base_url: https://taotoken.net/api, api_key: YOUR_TAOTOKEN_KEY, model: claude-sonnet-4-20250514 }三件套 Base URL Key Model ID 在任何工具里都不能少。CC Switch 切換配置時(shí)也是改這三個(gè)字段別只改 Key 忘了 Base URL。4. 驗(yàn)證規(guī)則生效與技能觸發(fā)的具體操作配置寫完不代表生效必須驗(yàn)證。下面給三個(gè)可復(fù)現(xiàn)的驗(yàn)證動(dòng)作每個(gè)都有明確的預(yù)期結(jié)果。4.1 驗(yàn)證 Rules 是否被讀取在 Cursor 或 Cline 里新建一個(gè)測(cè)試組件文件src/components/TestButton.tsx然后輸入提示幫我寫一個(gè)帶 hover 效果的按鈕組件如果 Rules 生效模型輸出里不應(yīng)該出現(xiàn)style{{}}而應(yīng)該用className配合 Tailwind。同時(shí)它應(yīng)該主動(dòng)聲明 Props interface。如果它寫了內(nèi)聯(lián)樣式說(shuō)明CLAUDE.md的路由沒(méi)被讀到檢查文件是否在項(xiàng)目根目錄、文件名大小寫是否正確。4.2 驗(yàn)證 Skills 是否被觸發(fā)輸入提示幫我實(shí)現(xiàn)一個(gè)確認(rèn)刪除的彈窗預(yù)期結(jié)果是模型先讀取docs/skills/modal-accessibility-skill.md然后按 Radix UI 路徑實(shí)現(xiàn)包含DialogTitle和DialogDescription。如果它直接引入 antd 的 Modal說(shuō)明技能路由沒(méi)命中檢查CLAUDE.md里技能路由的關(guān)鍵詞是否覆蓋了“彈窗”“模態(tài)框”這類觸發(fā)詞。4.3 驗(yàn)證 API 通道是否連通在終端里直接發(fā)一個(gè)請(qǐng)求確認(rèn) TaoToken 通道正常curl https://taotoken.net/api/v1/messages \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 只回復(fù) OK}] }返回里能看到content字段且文本是OK說(shuō)明 Key、Base URL、Model ID 三件套全部正確。這一步過(guò)了編輯器里的報(bào)錯(cuò)基本都能排除通道問(wèn)題。4.4 驗(yàn)證多工具一致性同一個(gè) Key 分別配到 Cursor 和 Claude Code用同一個(gè)提示詞跑一遍對(duì)比輸出風(fēng)格是否一致。如果 Cursor 遵守了 Tailwind 規(guī)則而 Claude Code 沒(méi)有說(shuō)明 Claude Code 的settings.json沒(méi)讀到項(xiàng)目級(jí)CLAUDE.md檢查工作目錄是否在項(xiàng)目根。5. 本篇常見(jiàn)報(bào)錯(cuò)與排查對(duì)照這一節(jié)按真實(shí)報(bào)錯(cuò)來(lái)每條都給現(xiàn)象、原因、修法。401 Unauthorized最常見(jiàn)。現(xiàn)象是請(qǐng)求直接被拒。原因通常是 Key 復(fù)制不完整、Key 前后有空格、或者用了官網(wǎng)地址當(dāng) Base URL。修法重新在 API Keys 頁(yè)面生成確認(rèn) Base URL 是https://taotoken.net/api而不是官網(wǎng)首頁(yè)。local proxy failed出現(xiàn)在 Cline 或 Cursor 的 MCP 配置里。原因是mcp.json里的url字段寫錯(cuò)或者網(wǎng)絡(luò)層攔截。修法確認(rèn)url是https://taotoken.net/api不要帶多余路徑檢查Authorization頭的Bearer前綴有沒(méi)有漏。reading choices 報(bào)錯(cuò)通常是響應(yīng)結(jié)構(gòu)不符合預(yù)期根因是 Model ID 寫錯(cuò)模型返回了非標(biāo)準(zhǔn)格式。修法回到文檔頁(yè)核對(duì) Model ID 的完整拼寫注意日期后綴和連字符。OAuth 相關(guān)報(bào)錯(cuò)Claude Code 首次啟動(dòng)時(shí)可能走 OAuth 流程。如果你已經(jīng)用settings.json配了ANTHROPIC_API_KEY需要在啟動(dòng)參數(shù)里顯式跳過(guò) OAuth或者確認(rèn)環(huán)境變量?jī)?yōu)先級(jí)高于登錄態(tài)。修法檢查settings.json的env塊是否被正確加載必要時(shí)在終端export一次再啟動(dòng)。規(guī)則不生效但通道正?，F(xiàn)象是模型能回復(fù)但無(wú)視 Rules。原因是CLAUDE.md不在工作目錄根或者文件名被改成了claude.md。修法確認(rèn)文件名全大寫CLAUDE.md位置在項(xiàng)目根。技能觸發(fā)不穩(wěn)定有時(shí)觸發(fā)有時(shí)不觸發(fā)。原因是CLAUDE.md里的觸發(fā)詞太窄。修法把觸發(fā)詞寫寬一點(diǎn)比如“彈窗 / 模態(tài)框 / dialog / modal”都列上。排查順序建議固定為先 curl 驗(yàn)通道 → 再驗(yàn)CLAUDE.md是否被讀 → 最后驗(yàn)技能觸發(fā)。這樣能快速定位是通道問(wèn)題還是上下文問(wèn)題。6. 把統(tǒng)一 Key 與 Rules/Skills 固化成團(tuán)隊(duì)資產(chǎn)走到這里你已經(jīng)有了可復(fù)制的目錄結(jié)構(gòu)、可粘貼的配置片段、可復(fù)現(xiàn)的驗(yàn)證步驟和排障對(duì)照表。剩下的事是把它變成團(tuán)隊(duì)資產(chǎn)而不是個(gè)人技巧。具體做法把CLAUDE.md、docs/rules/、docs/skills/提交進(jìn) Git 倉(cāng)庫(kù)作為項(xiàng)目腳手架的一部分。新同學(xué)拉下代碼配好 TaoToken 三件套R(shí)ules 和 Skills 自動(dòng)生效不需要口口相傳。團(tuán)隊(duì)里誰(shuí)發(fā)現(xiàn) AI 犯了新錯(cuò)誤就把它寫成一條新規(guī)則或新技能走 PR 評(píng)審合并。這樣規(guī)范會(huì)隨項(xiàng)目一起生長(zhǎng)。定期做一次“水療日”審查docs/rules/和docs/skills/合并重復(fù)條目刪除過(guò)時(shí)約束確保CLAUDE.md的路由顆粒度足夠細(xì)。上下文冗余是 Rules/Skills 體系最大的敵人保持精簡(jiǎn)比不斷堆砌更重要。需要長(zhǎng)期跑編碼和 Agent 任務(wù)的團(tuán)隊(duì)直接上 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入過(guò)程中遇到通道或配置問(wèn)題先查接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 再對(duì)照 API Keys 頁(yè)面確認(rèn) Key 狀態(tài)https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先驗(yàn)證模型輸出風(fēng)格用模型對(duì)話頁(yè)試一輪https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后一句實(shí)操建議先把CLAUDE.md和兩個(gè)規(guī)則文件建起來(lái)跑通第 4 節(jié)的三個(gè)驗(yàn)證動(dòng)作再逐步補(bǔ) Skills。不要一上來(lái)就寫二十個(gè)文件上下文過(guò)載會(huì)讓效果反而變差。