一 Key 接入 Claude Code 實(shí)戰(zhàn))
1. 為什么 feature-dev 和 planning-with-files 必須一起用先說結(jié)論feature-dev是執(zhí)行引擎planning-with-files是持久化大腦。單用任何一個(gè)都會(huì)在真實(shí)項(xiàng)目里翻車。我拿一個(gè) Spring Boot 的 OA 系統(tǒng)舉例。需求是「新增請(qǐng)假審批流程」涉及 Camunda BPMN 節(jié)點(diǎn)注冊(cè)、Kafka 消息路由、workflow-worker 到 workflow-service 的分層調(diào)用。你打開 Claude Code讓 Agent 從需求分析一路寫到代碼審查。第一個(gè)坑Agent 做到一半上下文炸了。Phase 2 探索了十幾個(gè)文件Phase 3 你回答了 5 個(gè)邊界問題會(huì)話越來越長(zhǎng)前面的關(guān)鍵決策被截?cái)唷gent 開始「忘記」之前說好的「駁回后回到申請(qǐng)人修改重提」。第二個(gè)坑第二天回來一切歸零。昨天花兩小時(shí)讓 Agent 理解了架構(gòu)分層和可復(fù)用抽象今天新開會(huì)話它完全不記得。你得把需求、架構(gòu)、決策從頭再講一遍。這兩個(gè)坑本質(zhì)是同一件事大模型的上下文窗口是易失性的而功能開發(fā)是跨會(huì)話的持久化工作。feature-dev解決「怎么做」——7 階段結(jié)構(gòu)化流程加并行 Agent 編排planning-with-files解決「怎么不忘記」——把每個(gè)階段的產(chǎn)物寫進(jìn)磁盤文件隨時(shí)可恢復(fù)。維度feature-devplanning-with-files定位執(zhí)行引擎持久化大腦核心能力7 階段流程 并行 Agent 編排三大文件充當(dāng)磁盤記憶 跨會(huì)話恢復(fù)解決什么從需求到代碼的完整流水線每個(gè)階段產(chǎn)物落盤隨時(shí)恢復(fù)持久性上下文丟失則狀態(tài)全丟寫入文件中斷可續(xù)Agent 驅(qū)動(dòng)3 探索 3 架構(gòu) 3 審查并行無 Agent 編排專注記錄錯(cuò)誤管理無結(jié)構(gòu)化錯(cuò)誤追蹤專屬錯(cuò)誤表 三次失敗協(xié)議光有引擎跑不遠(yuǎn)光有油箱動(dòng)不了。這篇就講怎么讓它們打出組合拳并且用 TaoToken 統(tǒng)一 Key 把 Claude Code 的 API 通道接好讓整套流程穩(wěn)定跑起來。適合誰看用 Claude Code 做后端開發(fā)的 Java/Spring Boot 工程師也適合前端、全棧、數(shù)據(jù)工程的同學(xué)因?yàn)閰f(xié)作規(guī)則和語言棧無關(guān)。2. 用 TaoToken 統(tǒng)一 Key 接入 Claude Code 的前置準(zhǔn)備在配置兩個(gè)技能之前先把 API 通道打通。Claude Code 默認(rèn)走 Anthropic 官方通道但很多團(tuán)隊(duì)希望統(tǒng)一 Key 管理、統(tǒng)一計(jì)費(fèi)、統(tǒng)一審計(jì)。TaoToken 提供的就是這樣一個(gè)統(tǒng)一入口一個(gè) Key 覆蓋模型對(duì)話、編碼 Agent、API 調(diào)用。你需要準(zhǔn)備三樣?xùn)|西Base URL、API Key、Model ID。這三件套是后面所有配置的基礎(chǔ)缺一不可。Base URL 用https://taotoken.net/api注意這個(gè)地址不帶任何查詢參數(shù)。API Key 在控制臺(tái)的 API Keys 頁面生成建議按項(xiàng)目或按人分配方便后續(xù)排查用量。Model ID 根據(jù)你用的模型填比如 Claude 系列對(duì)應(yīng)的模型標(biāo)識(shí)。先去控制臺(tái)拿 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content生成 Key 的入口在 API Keys 頁面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后Claude Code 的接入方式有兩種環(huán)境變量方式和配置文件方式。環(huán)境變量適合臨時(shí)驗(yàn)證配置文件適合長(zhǎng)期使用。環(huán)境變量方式在終端里設(shè)置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODEL你的Model IDWindows PowerShell 用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的Key $env:ANTHROPIC_MODEL你的Model ID配置文件方式更推薦因?yàn)橹貑⒔K端不丟。Claude Code 讀取的配置路徑通常在用戶目錄下的.claude文件夾。如果你用的是 Codex 風(fēng)格的auth.json結(jié)構(gòu)類似這樣{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的Model ID }注意Base URL、Key、Model ID 這三件套必須同時(shí)正確。只改 Base URL 不改 Key會(huì)報(bào) 401只改 Key 不改 Model ID可能報(bào)模型不存在。這是后面排障章節(jié)會(huì)重點(diǎn)講的。驗(yàn)證通道是否打通最直接的方式是用模型對(duì)話頁面發(fā)一條測(cè)試消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果模型對(duì)話能正常返回說明 Key 和通道沒問題接下來再配置 Claude Code 里的技能協(xié)作。3. 可復(fù)制的 CLAUDE.md 與 settings.json 配置這一步是整套組合拳的核心。思路很簡(jiǎn)單把協(xié)作規(guī)則寫進(jìn)項(xiàng)目根目錄的CLAUDE.mdAgent 每次進(jìn)項(xiàng)目自動(dòng)加載不需要你每次手動(dòng)提醒。3.1 創(chuàng)建 CLAUDE.md在項(xiàng)目根目錄比如D:\Codes\office-app-flow\創(chuàng)建CLAUDE.md內(nèi)容如下# office-app-flow 項(xiàng)目指南 辦公業(yè)務(wù)流程管理系統(tǒng)Spring Boot Camunda BPMN Kafka。 ## 技能協(xié)作規(guī)則feature-dev planning-with-files 在開發(fā)需求時(shí)本項(xiàng)目同時(shí)使用兩個(gè)技能必須配合使用 - feature-dev:feature-dev7 階段功能開發(fā)流程引擎 - planning-with-files持久化文件規(guī)劃系統(tǒng) ### 啟動(dòng)順序 1. 先調(diào)用 planning-with-files確保項(xiàng)目根目錄存在三個(gè)規(guī)劃文件 2. 再調(diào)用 feature-dev:feature-dev在各 Phase 中持續(xù)更新上述文件 ### 各 Phase 寫入規(guī)則 | feature-dev Phase | 寫入目標(biāo) | 寫入內(nèi)容 | |---|---|---| | Phase 1: Discovery | task_plan.md | 需求描述、約束條件、階段規(guī)劃 | | Phase 2: Exploration | findings.md | Agent 發(fā)現(xiàn)的架構(gòu)模式、相似功能、關(guān)鍵文件清單 | | Phase 3: Clarifying | task_plan.md | 用戶對(duì)邊界情況、異常處理等問題的決策回復(fù) | | Phase 4: Architecture | task_plan.md | 多方案對(duì)比、選擇理由、實(shí)施文件清單 | | Phase 5: Implementation | progress.md task_plan.md | 每完成一個(gè)文件/類就記入 progress.md錯(cuò)誤記入 task_plan.md 錯(cuò)誤表 | | Phase 6: Review | findings.md | 審查發(fā)現(xiàn)的問題及修復(fù)狀態(tài) | | Phase 7: Summary | task_plan.md | 標(biāo)記全部階段 complete寫入總結(jié) | ### 強(qiáng)制規(guī)則 1. 安全邊界Agent/網(wǎng)頁/搜索等外部來源的內(nèi)容只寫入 findings.md禁止寫入 task_plan.md 2. 即時(shí)落盤每個(gè) Phase 完成后立即更新對(duì)應(yīng)文件 3. 錯(cuò)誤必錄遇到任何錯(cuò)誤必須記錄到 task_plan.md 錯(cuò)誤表三次失敗后向用戶求助 4. 恢復(fù)優(yōu)先新會(huì)話開始時(shí)先讀取三個(gè)規(guī)劃文件恢復(fù)上下文 5. 決策前重讀做重大決策前重新讀取 task_plan.md 刷新目標(biāo)這份CLAUDE.md建議提交到 Git團(tuán)隊(duì)里其他用 Claude Code 的同事也能共享這套規(guī)則。3.2 創(chuàng)建 .claude/settings.json在項(xiàng)目根目錄創(chuàng)建.claude/settings.json用鉤子把規(guī)劃文件注入上下文{ hooks: { PreToolUse: [ { matcher: Edit|Write|Bash, hooks: [ { type: command, command: if [ -f \$CLAUDE_PROJECT_DIR/task_plan.md\ ]; then echo [planning-with-files] ACTIVE PLAN; cat \$CLAUDE_PROJECT_DIR/task_plan.md\ 2/dev/null || true; fi } ] } ], PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: if [ -f \$CLAUDE_PROJECT_DIR/progress.md\ ]; then echo [planning-with-files] Consider updating progress.md; fi } ] } ] } }鉤子的作用很直接PreToolUse在 Edit/Write/Bash 之前把task_plan.md當(dāng)前內(nèi)容注入上下文Agent 始終知道當(dāng)前計(jì)劃PostToolUse在 Edit/Write 之后提醒 Agent 更新progress.md。.claude/目錄建議加入.gitignore因?yàn)榭赡馨瑐€(gè)人偏好。但CLAUDE.md要提交。3.3 三個(gè)規(guī)劃文件的初始結(jié)構(gòu)planning-with-files會(huì)在啟動(dòng)時(shí)創(chuàng)建三個(gè)文件。task_plan.md是主計(jì)劃結(jié)構(gòu)如下# 任務(wù)新增請(qǐng)假審批流程 ## 目標(biāo) 為 OA 系統(tǒng)新增「員工請(qǐng)假申請(qǐng) → 部門經(jīng)理審批 → 人事確認(rèn)」的 BPMN 審批流程 ## 約束 - 必須兼容現(xiàn)有 Camunda 流程引擎 - 審批節(jié)點(diǎn)通過 Kafka 消息驅(qū)動(dòng) - 遵循現(xiàn)有 workflow-worker → workflow-service 分層架構(gòu) ## 階段 | # | 階段 | 狀態(tài) | |---|------|------| | 1 | 需求澄清 | complete | | 2 | 代碼探索 | pending | | 3 | 澄清問題 | pending | | 4 | 架構(gòu)設(shè)計(jì) | pending | | 5 | 編碼實(shí)現(xiàn) | pending | | 6 | 質(zhì)量審查 | pending | | 7 | 總結(jié) | pending | ## 關(guān)鍵決策 Phase 3 寫入 ## 錯(cuò)誤記錄 | 錯(cuò)誤 | 嘗試次數(shù) | 解決方案 | |------|---------|---------|findings.md記錄探索和審查發(fā)現(xiàn)progress.md記錄每次會(huì)話的進(jìn)度。這三個(gè)文件就是 Agent 的「磁盤記憶」。4. 組合調(diào)用步驟與端到端驗(yàn)證配置好之后跑一遍完整流程驗(yàn)證組合拳效果。假設(shè)你在一個(gè)新項(xiàng)目里對(duì)話大概是這樣。4.1 啟動(dòng)與需求發(fā)現(xiàn)你輸入「幫我新增一個(gè)請(qǐng)假審批功能」。Agent 先讀CLAUDE.md知道要組合兩個(gè)技能。然后planning-with-files初始化創(chuàng)建task_plan.md、findings.md、progress.md。接著feature-dev進(jìn)入 Phase 1 需求發(fā)現(xiàn)Agent 會(huì)問你我理解你需要新增一個(gè)審批流程。請(qǐng)確認(rèn) 1. 流程節(jié)點(diǎn)申請(qǐng) → 經(jīng)理審批 → 人事確認(rèn) 2. 是否需要支持駁回和撤回 3. 審批人是由前端指定還是后端規(guī)則匹配你回答「節(jié)點(diǎn)是申請(qǐng)→經(jīng)理審批→人事確認(rèn)支持駁回審批人由前端指定」。Agent 把需求和約束寫入task_plan.md。4.2 代碼探索與澄清Phase 2 代碼探索feature-dev并行啟動(dòng) 3 個(gè) code-explorer Agent一個(gè)找相似審批流程實(shí)現(xiàn)一個(gè)分析 Camunda 集成方式一個(gè)分析 Kafka 消息路由。三個(gè) Agent 返回結(jié)果后寫入findings.md包含 6 個(gè)關(guān)鍵文件路徑和 3 個(gè)可復(fù)用模式。注意安全邊界Agent 的輸出只寫入findings.md不寫入task_plan.md。因?yàn)閠ask_plan.md會(huì)被鉤子反復(fù)注入上下文如果混入外部?jī)?nèi)容可能被當(dāng)作指令執(zhí)行這是間接提示注入的風(fēng)險(xiǎn)。Phase 3 澄清問題Agent 基于探索發(fā)現(xiàn)列出模糊點(diǎn)1. 駁回后流程回到申請(qǐng)人還是直接結(jié)束 2. 審批超時(shí)如 48 小時(shí)未處理怎么辦 3. 是否需要審批歷史記錄表你回答「駁回回到申請(qǐng)人修改重提超時(shí)自動(dòng)通過需要?dú)v史記錄」。Agent 寫入task_plan.md關(guān)鍵決策區(qū)。4.3 架構(gòu)設(shè)計(jì)與編碼Phase 4 架構(gòu)設(shè)計(jì)feature-dev并行啟動(dòng) 3 個(gè) code-architect Agent最小改動(dòng)派、清晰架構(gòu)派、務(wù)實(shí)平衡派。三份方案給你選你選務(wù)實(shí)平衡方案Agent 把對(duì)比和理由寫入task_plan.md。Phase 5 編碼實(shí)現(xiàn)Agent 按批準(zhǔn)的架構(gòu)逐步實(shí)現(xiàn)。每完成一個(gè)文件就寫入progress.md## 2026-07-09 會(huì)話 ### 已完成 - [x] WorkflowNodeTypeEnum 新增 LEAVE_APPROVAL 枚舉值 - [x] 新增 LeaveApprovalProcessService繼承 AbstractNodeProcessService - [x] NodeProcessService.java 新增路由分支 - [ ] 單元測(cè)試遇到 NPE待解決 ### 當(dāng)前狀態(tài) - Phase 5 實(shí)現(xiàn)中進(jìn)度 60%遇到錯(cuò)誤寫入task_plan.md錯(cuò)誤表## 錯(cuò)誤記錄 | 錯(cuò)誤 | 嘗試次數(shù) | 解決方案 | |------|---------|---------| | LeaveApprovalProcessService.getFormData() NPE | 1 | 排查中疑似未注入 WorkflowDataOperateService |4.4 跨會(huì)話恢復(fù)驗(yàn)證這是最關(guān)鍵的驗(yàn)證動(dòng)作。假設(shè)你在 Phase 5 編碼到一半下班了。第二天回來運(yùn)行恢復(fù)腳本python .claude/skills/planning-with-files/scripts/session-catchup.py .它會(huì)輸出上次會(huì)話2026-07-09 當(dāng)前階段Phase 5 - 編碼實(shí)現(xiàn)進(jìn)度 60% 已修改文件 - WorkflowNodeTypeEnum.java - LeaveApprovalProcessService.java - LeaveApprovalController.java 待解決錯(cuò)誤 - LeaveApprovalProcessService.getFormData() NPEAgent 基于這些信息無縫接續(xù)你不需要重新描述半個(gè)字。這就是「五問重啟測(cè)試」我在哪里task_plan.md當(dāng)前階段、我要去哪里剩余未完成階段、目標(biāo)是什么task_plan.md目標(biāo)聲明、我學(xué)到了什么findings.md、我做了什么progress.md。端到端驗(yàn)證成功的標(biāo)志新會(huì)話啟動(dòng)后Agent 能準(zhǔn)確說出當(dāng)前階段、已改文件、待解決錯(cuò)誤并直接繼續(xù) Phase 5而不是從頭問你需求。5. 常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth配置過程中最容易踩的坑集中在 API 通道和技能加載兩塊。下面按真實(shí)報(bào)錯(cuò)逐個(gè)排查。5.1 401 Unauthorized報(bào)錯(cuò)長(zhǎng)這樣API Error: 401 {error:{type:authentication_error,message:invalid x-api-key}}原因通常是三件套沒對(duì)齊。檢查順序Base URL 是不是https://taotoken.net/api注意不要多加路徑或參數(shù)API Key 是不是從控制臺(tái)復(fù)制完整有沒有多余空格Model ID 是不是當(dāng)前 Key 有權(quán)限的模型。如果你用的是auth.json確認(rèn)字段名正確{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的Model ID }改完重啟 Claude Code環(huán)境變量方式要重新source或重開終端。5.2 local proxy failed報(bào)錯(cuò)Error: local proxy failed to start這個(gè)通常和本地網(wǎng)絡(luò)配置有關(guān)。先確認(rèn)沒有殘留的代理環(huán)境變量干擾echo $HTTP_PROXY echo $HTTPS_PROXY如果有值且不是你要的清掉unset HTTP_PROXY unset HTTPS_PROXY然后確認(rèn) Base URL 能直連。用 curl 測(cè)一下curl -I https://taotoken.net/api能返回 HTTP 狀態(tài)碼說明通道可達(dá)。如果這里就失敗問題在網(wǎng)絡(luò)層不在 Claude Code 配置。5.3 reading choices 相關(guān)報(bào)錯(cuò)報(bào)錯(cuò)Error: reading choices of undefined這是響應(yīng)結(jié)構(gòu)不符合預(yù)期。常見原因是 Base URL 指向了不兼容的端點(diǎn)或者 Model ID 填錯(cuò)導(dǎo)致返回了錯(cuò)誤結(jié)構(gòu)。確認(rèn) Base URL 是https://taotoken.net/apiModel ID 用控制臺(tái)里列出的準(zhǔn)確標(biāo)識(shí)。如果你在settings.json里同時(shí)配了多個(gè)模型別名檢查別名映射有沒有寫錯(cuò)。5.4 OAuth 相關(guān)報(bào)錯(cuò)報(bào)錯(cuò)OAuth error: invalid_grantClaude Code 某些版本會(huì)走 OAuth 流程。如果你已經(jīng)用 API Key 方式接入需要在配置里明確禁用 OAuth避免它優(yōu)先走 OAuth 導(dǎo)致沖突。檢查settings.json里有沒有殘留的 OAuth 配置項(xiàng)清掉后重啟。5.5 技能沒加載如果 Agent 沒有按CLAUDE.md的規(guī)則組合兩個(gè)技能檢查CLAUDE.md是不是在項(xiàng)目根目錄不是子目錄.claude/settings.json的 JSON 格式有沒有語法錯(cuò)誤用python -m json.tool驗(yàn)證鉤子命令里的$CLAUDE_PROJECT_DIR在你的 shell 里能不能正確展開。驗(yàn)證 JSON 格式python -m json.tool .claude/settings.json沒報(bào)錯(cuò)說明格式正確。排障時(shí)如果懷疑是 Key 或通道問題直接去模型對(duì)話頁面發(fā)一條消息最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文檔里有完整的參數(shù)說明和示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content6. 長(zhǎng)期編碼與 Agent 場(chǎng)景的通道選擇跑通一次組合拳之后接下來要考慮的是長(zhǎng)期使用。如果你只是偶爾驗(yàn)證模型效果模型對(duì)話頁面就夠了。但如果你要把feature-devplanning-with-files當(dāng)成日常開發(fā)流程每天跑多個(gè)需求那通道的穩(wěn)定性和額度管理就很重要。Coding Plan 適合長(zhǎng)期編碼和 Agent 場(chǎng)景因?yàn)樗淳幋a用量?jī)?yōu)化比單次調(diào)用更劃算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你用 Claude Code 的 Anthropic 兼容模式接入文檔里有專門的配置說明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理頁面可以按項(xiàng)目分配不同 Key方便區(qū)分哪個(gè)項(xiàng)目用了多少額度https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制臺(tái)總覽能看到整體用量和余額https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后說一個(gè)我踩過的坑CLAUDE.md不要寫太長(zhǎng)。一份精心編寫的CLAUDE.md通常在 50 到 80 行之間約 1.5K tokens。相比一個(gè)典型開發(fā)會(huì)話 100K tokens 的上下文窗口占比不到 2%但價(jià)值巨大。如果你把項(xiàng)目所有規(guī)范都塞進(jìn)去反而會(huì)擠占 Agent 處理實(shí)際任務(wù)的上下文。規(guī)則寫清楚協(xié)作順序和寫入目標(biāo)就夠了細(xì)節(jié)讓 Agent 在 Phase 里自己探索。三個(gè)規(guī)劃文件和 Git 的關(guān)系也值得注意task_plan.md建議提交它是項(xiàng)目的功能開發(fā)日志findings.md建議提交記錄架構(gòu)理解和審查發(fā)現(xiàn)是隱性知識(shí)顯性化progress.md看團(tuán)隊(duì)偏好如果不想暴露每次會(huì)話細(xì)節(jié)可以.gitignore。換項(xiàng)目或換開發(fā)環(huán)境時(shí)只需要把CLAUDE.md模板復(fù)制到新項(xiàng)目根目錄按技術(shù)棧微調(diào)再把.claude/settings.json復(fù)制過去。兩個(gè)技能本身是全局安裝的不需要重新裝。配置一次后面每個(gè)項(xiàng)目都能直接復(fù)用這套組合拳。 讓 feature-dev 與 planning-with-files 打出組合拳：TaoToken 統(tǒng)一 Key 接入 Claude Code 實(shí)戰(zhàn)
1. 為什么 feature-dev 和 planning-with-files 必須一起用先說結(jié)論feature-dev是執(zhí)行引擎planning-with-files是持久化大腦。單用任何一個(gè)都會(huì)在真實(shí)項(xiàng)目里翻車。我拿一個(gè) Spring Boot 的 OA 系統(tǒng)舉例。需求是「新增請(qǐng)假審批流程」涉及 Camunda BPMN 節(jié)點(diǎn)注冊(cè)、Kafka 消息路由、workflow-worker 到 workflow-service 的分層調(diào)用。你打開 Claude Code讓 Agent 從需求分析一路寫到代碼審查。第一個(gè)坑Agent 做到一半上下文炸了。Phase 2 探索了十幾個(gè)文件Phase 3 你回答了 5 個(gè)邊界問題會(huì)話越來越長(zhǎng)前面的關(guān)鍵決策被截?cái)唷gent 開始「忘記」之前說好的「駁回后回到申請(qǐng)人修改重提」。第二個(gè)坑第二天回來一切歸零。昨天花兩小時(shí)讓 Agent 理解了架構(gòu)分層和可復(fù)用抽象今天新開會(huì)話它完全不記得。你得把需求、架構(gòu)、決策從頭再講一遍。這兩個(gè)坑本質(zhì)是同一件事大模型的上下文窗口是易失性的而功能開發(fā)是跨會(huì)話的持久化工作。feature-dev解決「怎么做」——7 階段結(jié)構(gòu)化流程加并行 Agent 編排planning-with-files解決「怎么不忘記」——把每個(gè)階段的產(chǎn)物寫進(jìn)磁盤文件隨時(shí)可恢復(fù)。維度feature-devplanning-with-files定位執(zhí)行引擎持久化大腦核心能力7 階段流程 并行 Agent 編排三大文件充當(dāng)磁盤記憶 跨會(huì)話恢復(fù)解決什么從需求到代碼的完整流水線每個(gè)階段產(chǎn)物落盤隨時(shí)恢復(fù)持久性上下文丟失則狀態(tài)全丟寫入文件中斷可續(xù)Agent 驅(qū)動(dòng)3 探索 3 架構(gòu) 3 審查并行無 Agent 編排專注記錄錯(cuò)誤管理無結(jié)構(gòu)化錯(cuò)誤追蹤專屬錯(cuò)誤表 三次失敗協(xié)議光有引擎跑不遠(yuǎn)光有油箱動(dòng)不了。這篇就講怎么讓它們打出組合拳并且用 TaoToken 統(tǒng)一 Key 把 Claude Code 的 API 通道接好讓整套流程穩(wěn)定跑起來。適合誰看用 Claude Code 做后端開發(fā)的 Java/Spring Boot 工程師也適合前端、全棧、數(shù)據(jù)工程的同學(xué)因?yàn)閰f(xié)作規(guī)則和語言棧無關(guān)。2. 用 TaoToken 統(tǒng)一 Key 接入 Claude Code 的前置準(zhǔn)備在配置兩個(gè)技能之前先把 API 通道打通。Claude Code 默認(rèn)走 Anthropic 官方通道但很多團(tuán)隊(duì)希望統(tǒng)一 Key 管理、統(tǒng)一計(jì)費(fèi)、統(tǒng)一審計(jì)。TaoToken 提供的就是這樣一個(gè)統(tǒng)一入口一個(gè) Key 覆蓋模型對(duì)話、編碼 Agent、API 調(diào)用。你需要準(zhǔn)備三樣?xùn)|西Base URL、API Key、Model ID。這三件套是后面所有配置的基礎(chǔ)缺一不可。Base URL 用https://taotoken.net/api注意這個(gè)地址不帶任何查詢參數(shù)。API Key 在控制臺(tái)的 API Keys 頁面生成建議按項(xiàng)目或按人分配方便后續(xù)排查用量。Model ID 根據(jù)你用的模型填比如 Claude 系列對(duì)應(yīng)的模型標(biāo)識(shí)。先去控制臺(tái)拿 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content生成 Key 的入口在 API Keys 頁面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后Claude Code 的接入方式有兩種環(huán)境變量方式和配置文件方式。環(huán)境變量適合臨時(shí)驗(yàn)證配置文件適合長(zhǎng)期使用。環(huán)境變量方式在終端里設(shè)置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODEL你的Model IDWindows PowerShell 用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的Key $env:ANTHROPIC_MODEL你的Model ID配置文件方式更推薦因?yàn)橹貑⒔K端不丟。Claude Code 讀取的配置路徑通常在用戶目錄下的.claude文件夾。如果你用的是 Codex 風(fēng)格的auth.json結(jié)構(gòu)類似這樣{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的Model ID }注意Base URL、Key、Model ID 這三件套必須同時(shí)正確。只改 Base URL 不改 Key會(huì)報(bào) 401只改 Key 不改 Model ID可能報(bào)模型不存在。這是后面排障章節(jié)會(huì)重點(diǎn)講的。驗(yàn)證通道是否打通最直接的方式是用模型對(duì)話頁面發(fā)一條測(cè)試消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果模型對(duì)話能正常返回說明 Key 和通道沒問題接下來再配置 Claude Code 里的技能協(xié)作。3. 可復(fù)制的 CLAUDE.md 與 settings.json 配置這一步是整套組合拳的核心。思路很簡(jiǎn)單把協(xié)作規(guī)則寫進(jìn)項(xiàng)目根目錄的CLAUDE.mdAgent 每次進(jìn)項(xiàng)目自動(dòng)加載不需要你每次手動(dòng)提醒。3.1 創(chuàng)建 CLAUDE.md在項(xiàng)目根目錄比如D:\Codes\office-app-flow\創(chuàng)建CLAUDE.md內(nèi)容如下# office-app-flow 項(xiàng)目指南 辦公業(yè)務(wù)流程管理系統(tǒng)Spring Boot Camunda BPMN Kafka。 ## 技能協(xié)作規(guī)則feature-dev planning-with-files 在開發(fā)需求時(shí)本項(xiàng)目同時(shí)使用兩個(gè)技能必須配合使用 - feature-dev:feature-dev7 階段功能開發(fā)流程引擎 - planning-with-files持久化文件規(guī)劃系統(tǒng) ### 啟動(dòng)順序 1. 先調(diào)用 planning-with-files確保項(xiàng)目根目錄存在三個(gè)規(guī)劃文件 2. 再調(diào)用 feature-dev:feature-dev在各 Phase 中持續(xù)更新上述文件 ### 各 Phase 寫入規(guī)則 | feature-dev Phase | 寫入目標(biāo) | 寫入內(nèi)容 | |---|---|---| | Phase 1: Discovery | task_plan.md | 需求描述、約束條件、階段規(guī)劃 | | Phase 2: Exploration | findings.md | Agent 發(fā)現(xiàn)的架構(gòu)模式、相似功能、關(guān)鍵文件清單 | | Phase 3: Clarifying | task_plan.md | 用戶對(duì)邊界情況、異常處理等問題的決策回復(fù) | | Phase 4: Architecture | task_plan.md | 多方案對(duì)比、選擇理由、實(shí)施文件清單 | | Phase 5: Implementation | progress.md task_plan.md | 每完成一個(gè)文件/類就記入 progress.md錯(cuò)誤記入 task_plan.md 錯(cuò)誤表 | | Phase 6: Review | findings.md | 審查發(fā)現(xiàn)的問題及修復(fù)狀態(tài) | | Phase 7: Summary | task_plan.md | 標(biāo)記全部階段 complete寫入總結(jié) | ### 強(qiáng)制規(guī)則 1. 安全邊界Agent/網(wǎng)頁/搜索等外部來源的內(nèi)容只寫入 findings.md禁止寫入 task_plan.md 2. 即時(shí)落盤每個(gè) Phase 完成后立即更新對(duì)應(yīng)文件 3. 錯(cuò)誤必錄遇到任何錯(cuò)誤必須記錄到 task_plan.md 錯(cuò)誤表三次失敗后向用戶求助 4. 恢復(fù)優(yōu)先新會(huì)話開始時(shí)先讀取三個(gè)規(guī)劃文件恢復(fù)上下文 5. 決策前重讀做重大決策前重新讀取 task_plan.md 刷新目標(biāo)這份CLAUDE.md建議提交到 Git團(tuán)隊(duì)里其他用 Claude Code 的同事也能共享這套規(guī)則。3.2 創(chuàng)建 .claude/settings.json在項(xiàng)目根目錄創(chuàng)建.claude/settings.json用鉤子把規(guī)劃文件注入上下文{ hooks: { PreToolUse: [ { matcher: Edit|Write|Bash, hooks: [ { type: command, command: if [ -f \$CLAUDE_PROJECT_DIR/task_plan.md\ ]; then echo [planning-with-files] ACTIVE PLAN; cat \$CLAUDE_PROJECT_DIR/task_plan.md\ 2/dev/null || true; fi } ] } ], PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: if [ -f \$CLAUDE_PROJECT_DIR/progress.md\ ]; then echo [planning-with-files] Consider updating progress.md; fi } ] } ] } }鉤子的作用很直接PreToolUse在 Edit/Write/Bash 之前把task_plan.md當(dāng)前內(nèi)容注入上下文Agent 始終知道當(dāng)前計(jì)劃PostToolUse在 Edit/Write 之后提醒 Agent 更新progress.md。.claude/目錄建議加入.gitignore因?yàn)榭赡馨瑐€(gè)人偏好。但CLAUDE.md要提交。3.3 三個(gè)規(guī)劃文件的初始結(jié)構(gòu)planning-with-files會(huì)在啟動(dòng)時(shí)創(chuàng)建三個(gè)文件。task_plan.md是主計(jì)劃結(jié)構(gòu)如下# 任務(wù)新增請(qǐng)假審批流程 ## 目標(biāo) 為 OA 系統(tǒng)新增「員工請(qǐng)假申請(qǐng) → 部門經(jīng)理審批 → 人事確認(rèn)」的 BPMN 審批流程 ## 約束 - 必須兼容現(xiàn)有 Camunda 流程引擎 - 審批節(jié)點(diǎn)通過 Kafka 消息驅(qū)動(dòng) - 遵循現(xiàn)有 workflow-worker → workflow-service 分層架構(gòu) ## 階段 | # | 階段 | 狀態(tài) | |---|------|------| | 1 | 需求澄清 | complete | | 2 | 代碼探索 | pending | | 3 | 澄清問題 | pending | | 4 | 架構(gòu)設(shè)計(jì) | pending | | 5 | 編碼實(shí)現(xiàn) | pending | | 6 | 質(zhì)量審查 | pending | | 7 | 總結(jié) | pending | ## 關(guān)鍵決策 Phase 3 寫入 ## 錯(cuò)誤記錄 | 錯(cuò)誤 | 嘗試次數(shù) | 解決方案 | |------|---------|---------|findings.md記錄探索和審查發(fā)現(xiàn)progress.md記錄每次會(huì)話的進(jìn)度。這三個(gè)文件就是 Agent 的「磁盤記憶」。4. 組合調(diào)用步驟與端到端驗(yàn)證配置好之后跑一遍完整流程驗(yàn)證組合拳效果。假設(shè)你在一個(gè)新項(xiàng)目里對(duì)話大概是這樣。4.1 啟動(dòng)與需求發(fā)現(xiàn)你輸入「幫我新增一個(gè)請(qǐng)假審批功能」。Agent 先讀CLAUDE.md知道要組合兩個(gè)技能。然后planning-with-files初始化創(chuàng)建task_plan.md、findings.md、progress.md。接著feature-dev進(jìn)入 Phase 1 需求發(fā)現(xiàn)Agent 會(huì)問你我理解你需要新增一個(gè)審批流程。請(qǐng)確認(rèn) 1. 流程節(jié)點(diǎn)申請(qǐng) → 經(jīng)理審批 → 人事確認(rèn) 2. 是否需要支持駁回和撤回 3. 審批人是由前端指定還是后端規(guī)則匹配你回答「節(jié)點(diǎn)是申請(qǐng)→經(jīng)理審批→人事確認(rèn)支持駁回審批人由前端指定」。Agent 把需求和約束寫入task_plan.md。4.2 代碼探索與澄清Phase 2 代碼探索feature-dev并行啟動(dòng) 3 個(gè) code-explorer Agent一個(gè)找相似審批流程實(shí)現(xiàn)一個(gè)分析 Camunda 集成方式一個(gè)分析 Kafka 消息路由。三個(gè) Agent 返回結(jié)果后寫入findings.md包含 6 個(gè)關(guān)鍵文件路徑和 3 個(gè)可復(fù)用模式。注意安全邊界Agent 的輸出只寫入findings.md不寫入task_plan.md。因?yàn)閠ask_plan.md會(huì)被鉤子反復(fù)注入上下文如果混入外部?jī)?nèi)容可能被當(dāng)作指令執(zhí)行這是間接提示注入的風(fēng)險(xiǎn)。Phase 3 澄清問題Agent 基于探索發(fā)現(xiàn)列出模糊點(diǎn)1. 駁回后流程回到申請(qǐng)人還是直接結(jié)束 2. 審批超時(shí)如 48 小時(shí)未處理怎么辦 3. 是否需要審批歷史記錄表你回答「駁回回到申請(qǐng)人修改重提超時(shí)自動(dòng)通過需要?dú)v史記錄」。Agent 寫入task_plan.md關(guān)鍵決策區(qū)。4.3 架構(gòu)設(shè)計(jì)與編碼Phase 4 架構(gòu)設(shè)計(jì)feature-dev并行啟動(dòng) 3 個(gè) code-architect Agent最小改動(dòng)派、清晰架構(gòu)派、務(wù)實(shí)平衡派。三份方案給你選你選務(wù)實(shí)平衡方案Agent 把對(duì)比和理由寫入task_plan.md。Phase 5 編碼實(shí)現(xiàn)Agent 按批準(zhǔn)的架構(gòu)逐步實(shí)現(xiàn)。每完成一個(gè)文件就寫入progress.md## 2026-07-09 會(huì)話 ### 已完成 - [x] WorkflowNodeTypeEnum 新增 LEAVE_APPROVAL 枚舉值 - [x] 新增 LeaveApprovalProcessService繼承 AbstractNodeProcessService - [x] NodeProcessService.java 新增路由分支 - [ ] 單元測(cè)試遇到 NPE待解決 ### 當(dāng)前狀態(tài) - Phase 5 實(shí)現(xiàn)中進(jìn)度 60%遇到錯(cuò)誤寫入task_plan.md錯(cuò)誤表## 錯(cuò)誤記錄 | 錯(cuò)誤 | 嘗試次數(shù) | 解決方案 | |------|---------|---------| | LeaveApprovalProcessService.getFormData() NPE | 1 | 排查中疑似未注入 WorkflowDataOperateService |4.4 跨會(huì)話恢復(fù)驗(yàn)證這是最關(guān)鍵的驗(yàn)證動(dòng)作。假設(shè)你在 Phase 5 編碼到一半下班了。第二天回來運(yùn)行恢復(fù)腳本python .claude/skills/planning-with-files/scripts/session-catchup.py .它會(huì)輸出上次會(huì)話2026-07-09 當(dāng)前階段Phase 5 - 編碼實(shí)現(xiàn)進(jìn)度 60% 已修改文件 - WorkflowNodeTypeEnum.java - LeaveApprovalProcessService.java - LeaveApprovalController.java 待解決錯(cuò)誤 - LeaveApprovalProcessService.getFormData() NPEAgent 基于這些信息無縫接續(xù)你不需要重新描述半個(gè)字。這就是「五問重啟測(cè)試」我在哪里task_plan.md當(dāng)前階段、我要去哪里剩余未完成階段、目標(biāo)是什么task_plan.md目標(biāo)聲明、我學(xué)到了什么findings.md、我做了什么progress.md。端到端驗(yàn)證成功的標(biāo)志新會(huì)話啟動(dòng)后Agent 能準(zhǔn)確說出當(dāng)前階段、已改文件、待解決錯(cuò)誤并直接繼續(xù) Phase 5而不是從頭問你需求。5. 常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth配置過程中最容易踩的坑集中在 API 通道和技能加載兩塊。下面按真實(shí)報(bào)錯(cuò)逐個(gè)排查。5.1 401 Unauthorized報(bào)錯(cuò)長(zhǎng)這樣API Error: 401 {error:{type:authentication_error,message:invalid x-api-key}}原因通常是三件套沒對(duì)齊。檢查順序Base URL 是不是https://taotoken.net/api注意不要多加路徑或參數(shù)API Key 是不是從控制臺(tái)復(fù)制完整有沒有多余空格Model ID 是不是當(dāng)前 Key 有權(quán)限的模型。如果你用的是auth.json確認(rèn)字段名正確{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的Model ID }改完重啟 Claude Code環(huán)境變量方式要重新source或重開終端。5.2 local proxy failed報(bào)錯(cuò)Error: local proxy failed to start這個(gè)通常和本地網(wǎng)絡(luò)配置有關(guān)。先確認(rèn)沒有殘留的代理環(huán)境變量干擾echo $HTTP_PROXY echo $HTTPS_PROXY如果有值且不是你要的清掉unset HTTP_PROXY unset HTTPS_PROXY然后確認(rèn) Base URL 能直連。用 curl 測(cè)一下curl -I https://taotoken.net/api能返回 HTTP 狀態(tài)碼說明通道可達(dá)。如果這里就失敗問題在網(wǎng)絡(luò)層不在 Claude Code 配置。5.3 reading choices 相關(guān)報(bào)錯(cuò)報(bào)錯(cuò)Error: reading choices of undefined這是響應(yīng)結(jié)構(gòu)不符合預(yù)期。常見原因是 Base URL 指向了不兼容的端點(diǎn)或者 Model ID 填錯(cuò)導(dǎo)致返回了錯(cuò)誤結(jié)構(gòu)。確認(rèn) Base URL 是https://taotoken.net/apiModel ID 用控制臺(tái)里列出的準(zhǔn)確標(biāo)識(shí)。如果你在settings.json里同時(shí)配了多個(gè)模型別名檢查別名映射有沒有寫錯(cuò)。5.4 OAuth 相關(guān)報(bào)錯(cuò)報(bào)錯(cuò)OAuth error: invalid_grantClaude Code 某些版本會(huì)走 OAuth 流程。如果你已經(jīng)用 API Key 方式接入需要在配置里明確禁用 OAuth避免它優(yōu)先走 OAuth 導(dǎo)致沖突。檢查settings.json里有沒有殘留的 OAuth 配置項(xiàng)清掉后重啟。5.5 技能沒加載如果 Agent 沒有按CLAUDE.md的規(guī)則組合兩個(gè)技能檢查CLAUDE.md是不是在項(xiàng)目根目錄不是子目錄.claude/settings.json的 JSON 格式有沒有語法錯(cuò)誤用python -m json.tool驗(yàn)證鉤子命令里的$CLAUDE_PROJECT_DIR在你的 shell 里能不能正確展開。驗(yàn)證 JSON 格式python -m json.tool .claude/settings.json沒報(bào)錯(cuò)說明格式正確。排障時(shí)如果懷疑是 Key 或通道問題直接去模型對(duì)話頁面發(fā)一條消息最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文檔里有完整的參數(shù)說明和示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content6. 長(zhǎng)期編碼與 Agent 場(chǎng)景的通道選擇跑通一次組合拳之后接下來要考慮的是長(zhǎng)期使用。如果你只是偶爾驗(yàn)證模型效果模型對(duì)話頁面就夠了。但如果你要把feature-devplanning-with-files當(dāng)成日常開發(fā)流程每天跑多個(gè)需求那通道的穩(wěn)定性和額度管理就很重要。Coding Plan 適合長(zhǎng)期編碼和 Agent 場(chǎng)景因?yàn)樗淳幋a用量?jī)?yōu)化比單次調(diào)用更劃算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你用 Claude Code 的 Anthropic 兼容模式接入文檔里有專門的配置說明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理頁面可以按項(xiàng)目分配不同 Key方便區(qū)分哪個(gè)項(xiàng)目用了多少額度https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制臺(tái)總覽能看到整體用量和余額https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后說一個(gè)我踩過的坑CLAUDE.md不要寫太長(zhǎng)。一份精心編寫的CLAUDE.md通常在 50 到 80 行之間約 1.5K tokens。相比一個(gè)典型開發(fā)會(huì)話 100K tokens 的上下文窗口占比不到 2%但價(jià)值巨大。如果你把項(xiàng)目所有規(guī)范都塞進(jìn)去反而會(huì)擠占 Agent 處理實(shí)際任務(wù)的上下文。規(guī)則寫清楚協(xié)作順序和寫入目標(biāo)就夠了細(xì)節(jié)讓 Agent 在 Phase 里自己探索。三個(gè)規(guī)劃文件和 Git 的關(guān)系也值得注意task_plan.md建議提交它是項(xiàng)目的功能開發(fā)日志findings.md建議提交記錄架構(gòu)理解和審查發(fā)現(xiàn)是隱性知識(shí)顯性化progress.md看團(tuán)隊(duì)偏好如果不想暴露每次會(huì)話細(xì)節(jié)可以.gitignore。換項(xiàng)目或換開發(fā)環(huán)境時(shí)只需要把CLAUDE.md模板復(fù)制到新項(xiàng)目根目錄按技術(shù)棧微調(diào)再把.claude/settings.json復(fù)制過去。兩個(gè)技能本身是全局安裝的不需要重新裝。配置一次后面每個(gè)項(xiàng)目都能直接復(fù)用這套組合拳。