1. 為什么團(tuán)隊(duì)用 Claude Code 總在重復(fù)踩坑很多人第一次接觸 Claude Code會(huì)覺(jué)得它就是個(gè)能改代碼的聊天框。但真正把它放進(jìn)團(tuán)隊(duì)協(xié)作場(chǎng)景后問(wèn)題會(huì)立刻暴露同一個(gè)倉(cāng)庫(kù)里A 同學(xué)讓 Claude 改接口B 同學(xué)讓 Claude 補(bǔ)測(cè)試C 同學(xué)讓 Claude 重構(gòu)目錄三個(gè)會(huì)話各自為戰(zhàn)改出來(lái)的風(fēng)格完全不一樣。更麻煩的是昨天剛糾正過(guò)的錯(cuò)誤今天新開(kāi)一個(gè)會(huì)話Claude 又犯一遍。這不是模型不行而是缺少項(xiàng)目記憶和任務(wù)邊界。Claude Code 本身提供了幾個(gè)關(guān)鍵機(jī)制來(lái)解決這件事CLAUDE.md 負(fù)責(zé)項(xiàng)目級(jí)記憶Skills 負(fù)責(zé)把重復(fù)流程封裝成可復(fù)用能力Subagents 負(fù)責(zé)把大任務(wù)拆開(kāi)、保持主上下文干凈Plan Mode 負(fù)責(zé)在動(dòng)手前先對(duì)齊方案。這四個(gè)東西組合起來(lái)才是一套能落地的團(tuán)隊(duì)工作流。我試過(guò)在一個(gè)中型前端倉(cāng)庫(kù)里把這套配置跑通最直觀的變化是新人拉下代碼后不需要口頭交接我們這個(gè)項(xiàng)目測(cè)試怎么寫(xiě)、提交信息什么格式Claude 讀完 CLAUDE.md 就知道了。下面按問(wèn)題場(chǎng)景 → 前置準(zhǔn)備 → 可復(fù)制配置 → 驗(yàn)證 → 排錯(cuò) → 下一步的順序展開(kāi)每一步都給到能直接抄的片段。先明確一點(diǎn)Claude Code 的配置核心是文件不是某個(gè)開(kāi)關(guān)。你寫(xiě)進(jìn)倉(cāng)庫(kù)的文件才是團(tuán)隊(duì)真正共享的東西。個(gè)人偏好放本地團(tuán)隊(duì)約定進(jìn)版本庫(kù)這條線要?jiǎng)澢宄?. TaoToken 前置準(zhǔn)備把 Base URL、Key、Model ID 三件套配好在寫(xiě) CLAUDE.md 之前得先讓 Claude Code 能穩(wěn)定連上模型服務(wù)。團(tuán)隊(duì)場(chǎng)景下我建議統(tǒng)一走一個(gè)可控的接入點(diǎn)而不是每個(gè)人各自找渠道。這里用 TaoToken 作為接入層官網(wǎng)是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。配置 Claude Code 時(shí)核心就是三件套Base URL、API Key、Model ID。缺一個(gè)都會(huì)報(bào)錯(cuò)而且報(bào)錯(cuò)信息往往不直觀。你可以先在控制臺(tái)創(chuàng)建 Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 創(chuàng)建完復(fù)制出來(lái)只顯示一次記得存好。Claude Code 讀取配置的方式和環(huán)境變量有關(guān)。最穩(wěn)的做法是在項(xiàng)目根目錄或用戶目錄下維護(hù)配置文件。如果你用的是 Claude Code 的 settings 機(jī)制可以寫(xiě)成 JSON如果走環(huán)境變量就寫(xiě)進(jìn) shell 配置。下面給一個(gè) settings 片段路徑按你實(shí)際安裝位置調(diào)整{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意 Base URL 后面不要多加/v1之類的路徑Claude Code 會(huì)自己拼接。Model ID 要和你賬號(hào)里可用的模型對(duì)齊寫(xiě)錯(cuò)了會(huì)直接 404 或 model not found。Key 不要提交到 git放進(jìn).gitignore或者用環(huán)境變量注入。如果你更習(xí)慣用 Codex 那套auth.json邏輯是一樣的把 base_url 和 api_key 填進(jìn)去即可。團(tuán)隊(duì)里最好統(tǒng)一一種方式否則排錯(cuò)時(shí)每個(gè)人環(huán)境不同很難定位。配好之后先別急著寫(xiě)復(fù)雜配置跑一個(gè)最小驗(yàn)證在終端里啟動(dòng) Claude Code輸入一句列出當(dāng)前目錄的文件看它能不能正常返回。這一步過(guò)了再往下做 CLAUDE.md 和 Skills。如果這一步就報(bào) 401說(shuō)明 Key 或 Base URL 有問(wèn)題先解決這個(gè)別往下堆配置。3. 可復(fù)制配置CLAUDE.md 模板、Skills 目錄與 Subagents 片段這一節(jié)是全文最核心的部分三個(gè)配置文件都能直接抄。3.1 CLAUDE.md 模板CLAUDE.md 放在倉(cāng)庫(kù)根目錄Claude Code 啟動(dòng)時(shí)會(huì)自動(dòng)讀取。它的作用是告訴 Claude這個(gè)項(xiàng)目是什么、怎么跑、有哪些約定。團(tuán)隊(duì)內(nèi)部迭代的原則是——每次 Claude 犯錯(cuò)就把糾正寫(xiě)進(jìn)去讓它下次不再犯。下面是一個(gè)可直接用的模板# 項(xiàng)目說(shuō)明 這是一個(gè) React TypeScript 的前端倉(cāng)庫(kù)包管理用 pnpm。 ## 常用命令 - 安裝依賴pnpm install - 啟動(dòng)開(kāi)發(fā)pnpm dev - 跑測(cè)試pnpm test - 類型檢查pnpm tsc --noEmit - 格式化pnpm lint --fix ## 代碼約定 - 組件用函數(shù)式禁止 class 組件 - 所有導(dǎo)出函數(shù)必須寫(xiě) JSDoc - 提交信息格式type(scope): description - 新增依賴前必須先說(shuō)明理由 ## 目錄結(jié)構(gòu) - src/components通用組件 - src/pages頁(yè)面級(jí)組件 - src/hooks自定義 hooks - src/utils純函數(shù)工具 ## 注意事項(xiàng) - 不要修改 pnpm-lock.yaml 除非確實(shí)新增依賴 - 測(cè)試文件放在同目錄下命名 *.test.ts - 遇到不確定的接口先問(wèn)不要猜這個(gè)模板的關(guān)鍵在最后一段注意事項(xiàng)。團(tuán)隊(duì)里每個(gè)人踩過(guò)的坑都往這里加。比如不要?jiǎng)?lock 文件測(cè)試必須和源碼同目錄這些規(guī)則寫(xiě)進(jìn)去之后Claude 的行為會(huì)明顯收斂。你可以讓 Claude 自己維護(hù)這個(gè)文件每次糾正它之后在提示詞結(jié)尾加一句Update your CLAUDE.md so you dont make that mistake again它會(huì)自己把規(guī)則補(bǔ)進(jìn)去。3.2 Skills 目錄結(jié)構(gòu)Skills 是把重復(fù)流程封裝成可調(diào)用能力。判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果某件事你每天做超過(guò)一次就把它變成 Skill。目錄結(jié)構(gòu)如下.claude/ skills/ techdebt/ SKILL.md context-dump/ SKILL.md analytics/ SKILL.md每個(gè) SKILL.md 里寫(xiě)清楚這個(gè)技能做什么、什么時(shí)候用、怎么執(zhí)行。比如 techdebt 這個(gè)技能用于每次會(huì)話結(jié)束時(shí)查找重復(fù)代碼# techdebt ## 用途 在會(huì)話結(jié)束前掃描本次改動(dòng)找出重復(fù)代碼并消除。 ## 執(zhí)行步驟 1. 對(duì)比本次改動(dòng)涉及的文件 2. 找出重復(fù)的邏輯塊 3. 提取成公共函數(shù)并替換 4. 跑測(cè)試確認(rèn)沒(méi)有破壞行為Skills 提交到 git 之后就變成了團(tuán)隊(duì)共享的機(jī)構(gòu)知識(shí)。新人入職不需要口頭教Claude 讀到 SKILL.md 就知道怎么執(zhí)行。這是復(fù)利效應(yīng)最明顯的地方。3.3 Subagents 配置片段Subagents 解決的是上下文污染問(wèn)題。主會(huì)話負(fù)責(zé)統(tǒng)籌具體任務(wù)分派給子代理子代理干完把結(jié)果匯報(bào)回來(lái)主上下文保持干凈。配置片段如下{ subagents: { enabled: true, agents: [ { name: test-runner, description: 專門負(fù)責(zé)跑測(cè)試并匯報(bào)失敗用例, model: claude-sonnet-4-5 }, { name: code-reviewer, description: 以高級(jí)工程師身份審查計(jì)劃或改動(dòng), model: claude-sonnet-4-5 } ] } }用法上在請(qǐng)求后面追加Use subagents就能觸發(fā)。比如重構(gòu)這個(gè)模塊Use subagentsClaude 會(huì)把任務(wù)拆給子代理執(zhí)行。團(tuán)隊(duì)里常見(jiàn)的三種模式一是追加Use subagents投入更多算力二是把單個(gè)任務(wù)分派出去保持主上下文干凈三是通過(guò) hook 把權(quán)限請(qǐng)求路由到更強(qiáng)的模型做安全掃描。3.4 Plan Mode 的使用Plan Mode 是團(tuán)隊(duì)里每個(gè)人都該用的功能。它的價(jià)值不只是先規(guī)劃再動(dòng)手更重要的是卡住時(shí)重新規(guī)劃。當(dāng)任務(wù)進(jìn)行中出現(xiàn)意外不要硬撐原計(jì)劃切回 Plan Mode 重新對(duì)齊。高級(jí)技巧是讓 Claude 寫(xiě)完計(jì)劃后啟動(dòng)第二個(gè) Claude 以高級(jí)工程師身份審查這個(gè)計(jì)劃挑毛病。這一步能擋掉很多方向性錯(cuò)誤。4. 驗(yàn)證請(qǐng)求逐項(xiàng)確認(rèn)配置真的生效配置寫(xiě)完不代表生效必須逐項(xiàng)驗(yàn)證。下面給一套可執(zhí)行的驗(yàn)證動(dòng)作。第一步驗(yàn)證 CLAUDE.md 被讀取。在 Claude Code 里問(wèn)這個(gè)項(xiàng)目的測(cè)試命令是什么如果它回答pnpm test說(shuō)明 CLAUDE.md 生效了。如果它說(shuō)我不知道檢查文件是否在根目錄、文件名大小寫(xiě)是否正確。第二步驗(yàn)證 Skills 可調(diào)用。輸入/skills或者直接說(shuō)用 techdebt 技能掃描當(dāng)前改動(dòng)看它是否按 SKILL.md 的步驟執(zhí)行。如果提示找不到技能檢查.claude/skills/路徑和 SKILL.md 的命名。第三步驗(yàn)證 Subagents。輸入用 subagents 跑一遍測(cè)試觀察它是否分派了子任務(wù)。如果沒(méi)有任何子代理行為檢查配置里的enabled是否為 true以及 agents 數(shù)組是否寫(xiě)對(duì)。第四步驗(yàn)證 Plan Mode。輸入一個(gè)稍復(fù)雜的任務(wù)比如給用戶模塊加一個(gè)導(dǎo)出功能看它是否先給出計(jì)劃再動(dòng)手。如果直接開(kāi)始改代碼說(shuō)明 Plan Mode 沒(méi)觸發(fā)檢查你的調(diào)用方式。第五步驗(yàn)證模型連通性。這一步回到 TaoToken 的接入。如果前面都正常但請(qǐng)求失敗用模型對(duì)話頁(yè)面單獨(dú)測(cè)一下 Key 是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。能正常對(duì)話說(shuō)明 Key 沒(méi)問(wèn)題問(wèn)題在 Claude Code 的配置層。驗(yàn)證通過(guò)后你會(huì)看到一個(gè)明顯變化Claude 改代碼的風(fēng)格開(kāi)始和團(tuán)隊(duì)約定一致重復(fù)錯(cuò)誤減少大任務(wù)不再把上下文撐爆。這時(shí)候才算真正跑通。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth配置過(guò)程中最容易撞上的幾類報(bào)錯(cuò)逐個(gè)說(shuō)清楚。401 Unauthorized最常見(jiàn)。原因通常是 Key 寫(xiě)錯(cuò)、Key 過(guò)期、或者 Base URL 和 Key 不匹配。排查順序先確認(rèn) Key 是從控制臺(tái)復(fù)制的完整字符串沒(méi)有多余空格再確認(rèn) Base URL 是https://taotoken.net/api沒(méi)有多加路徑最后確認(rèn)這個(gè) Key 對(duì)應(yīng)的賬號(hào)有權(quán)限訪問(wèn)你指定的 Model ID。三件套里任何一個(gè)錯(cuò)位都會(huì) 401。local proxy failed這個(gè)報(bào)錯(cuò)通常出現(xiàn)在網(wǎng)絡(luò)層。Claude Code 嘗試連接時(shí)被本地環(huán)境攔截。檢查你的 shell 里有沒(méi)有設(shè)置沖突的代理變量比如HTTP_PROXY、HTTPS_PROXY。如果有先清掉再試。另外確認(rèn)防火墻沒(méi)有攔截對(duì) API 地址的出站請(qǐng)求。reading choices 相關(guān)報(bào)錯(cuò)這類錯(cuò)誤一般出現(xiàn)在響應(yīng)解析階段說(shuō)明返回的數(shù)據(jù)結(jié)構(gòu)不符合預(yù)期。常見(jiàn)原因是 Model ID 寫(xiě)錯(cuò)服務(wù)端返回了錯(cuò)誤結(jié)構(gòu)而不是正常的 choices 數(shù)組。核對(duì) Model ID 拼寫(xiě)確認(rèn)它在你賬號(hào)的可用列表里。OAuth 相關(guān)報(bào)錯(cuò)如果你用的是需要 OAuth 的接入方式報(bào)錯(cuò)通常和 token 過(guò)期或回調(diào)地址不匹配有關(guān)。團(tuán)隊(duì)場(chǎng)景下我建議直接用 API Key 方式少一層 OAuth 就少一類問(wèn)題。如果必須用 OAuth確認(rèn)回調(diào)地址和配置里的一致。model not foundModel ID 不在可用范圍。去控制臺(tái)確認(rèn)當(dāng)前賬號(hào)能用的模型列表把配置里的 Model ID 換成實(shí)際存在的。排錯(cuò)的核心思路是分層先確認(rèn) Key 和 Base URL 這層通不通再確認(rèn) Model ID 這層對(duì)不對(duì)最后才看 Claude Code 自身的配置。不要一上來(lái)就懷疑代碼大部分問(wèn)題都在接入層。如果自己排查不出來(lái)接入文檔里有更細(xì)的說(shuō)明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 下一步把工作流固化下來(lái)配置跑通之后真正決定團(tuán)隊(duì)效率的是持續(xù)迭代。CLAUDE.md 不是寫(xiě)一次就完事每次 Claude 犯錯(cuò)都要往里加規(guī)則Skills 不是建一次就夠重復(fù)出現(xiàn)的流程要不斷封裝進(jìn)去Subagents 的分工要根據(jù)項(xiàng)目實(shí)際調(diào)整。如果你還在個(gè)人階段先把 CLAUDE.md 和 Plan Mode 用起來(lái)這兩個(gè)投入最小、回報(bào)最快。如果團(tuán)隊(duì)已經(jīng)在用 Claude Code 做長(zhǎng)期編碼和 Agent 任務(wù)可以考慮 Coding Plan 這類更系統(tǒng)的方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要管理多個(gè) Key 和權(quán)限時(shí)控制臺(tái)在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 創(chuàng)建在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。最后給一個(gè)實(shí)用技巧把 CLAUDE.md 當(dāng)成團(tuán)隊(duì)的活文檔每次 code review 發(fā)現(xiàn) Claude 又犯了老毛病別只在 PR 里改順手把規(guī)則補(bǔ)進(jìn) CLAUDE.md。堅(jiān)持兩周你會(huì)發(fā)現(xiàn) Claude 在這個(gè)倉(cāng)庫(kù)里的表現(xiàn)和剛接入時(shí)完全是兩個(gè)水平。這就是復(fù)利工程的意思——規(guī)則越攢越多錯(cuò)誤越來(lái)越少。