1. 为什么代码规划总在“业务上下文”这一步卡住你可能已经习惯了让 Claude Code 读本地文件、跑 grep、生成实现计划但真正落到业务决策时问题往往不在代码本身。比如你手里有一份TECH_DEBT.md列了 12 条技术债两周只能做 3 到 4 条怎么排优先级光看代码根本判断不出来——哪条影响付费客户、哪条和 Q1 路线图对齐、哪条在错误日志里高频出现这些信息散落在 Elasticsearch 的多个索引里Claude Code 默认的工具链看不到。这就是 subagents 与 Elastic Agent Builder 组合要解决的问题让 Claude Code 在进入代码规划之前先通过一个专门的 retrieval subagent 去 Elasticsearch 检索业务上下文把“错误频率、客户层级、工单量、工程规范、路线图”这些外部知识拉回来再交给 planning agent 制定计划。整个过程不需要你把数据复制到本地也不需要主对话窗口被一堆原始 JSON 塞满。subagents 的核心价值在于上下文隔离。每个 subagent 有自己的上下文窗口完成任务后只把结果返回给主 agent执行过程不污染主对话。它还有四个原则上下文保留、专业化能力、可复用性、灵活访问控制。你可以限制某个 subagent 只能访问特定工具比如只允许它调用 Elasticsearch 的 MCP 工具不允许它写文件。在 Claude Code 里subagent 用一段带 frontmatter 的 Markdown 定义schema 大致是这样--- name: your-sub-agent-name description: Description of when this subagent should be invoked tools: tool1, tool2, tool3 model: sonnet permissionMode: default skills: skill1, skill2 --- Your subagents system prompt goes here.tools字段不写就继承主 agent 的所有工具包括 MCP 工具。model可以指定别名或inherit。调用方式有两种隐式调用比如你说“I want to plan my new functionality”Claude 会自动判断该用哪个 subagent显式调用直接说“Use the planning subagent to plan my new functionality”。subagent 还是有状态的第一次调用后会生成一个 agentId下次可以用Resume agent abc123继承之前的上下文agentId 也能在~/.claude/projects/{project}/{sessionId}/subagents/里找到。编排模式上常见的有三种顺序模式chaining一个 subagent 的输出传给下一个像 Linux 管道并行模式多个 subagent 同时跑独立任务主 agent 负责汇总中心辐射模式hub-and-spoke主 agent 当协调者把业务信息收集交给 retrieval agent同时让 explore agent 看本地文件、planning agent 出计划。本文要落地的就是 hub-and-spoke。什么时候该用 agent什么时候一条 ES|QL 就够了如果你只想要单个聚合比如“访问量最高的页面是哪个”直接跑查询。但当问题需要多个查询互相依赖、跨索引推理、消解歧义、综合定量与定性信息时agent 才有价值。技术债优先级排序恰好四个都占读TECH_DEBT.md知道有哪 12 条对每条查error_logs拿错误频率跨索引参考customer_data看客户层级查support_tickets看投诉量读knowledge里的工程规范和 Q1 路线图最后综合成建议。单条查询做不到因为“最重要的技术债”这个判断依赖前面每一步的结果。2. TaoToken 统一 Key 与前置准备把 endpoint 和 auth.json 写对在把 Elastic Agent Builder 接进 Claude Code 之前先把模型侧的访问统一掉。TaoToken 提供统一的 API endpointClaude Code、Codex、Cline 这些工具都可以指向同一个 Base URL用同一个 Key省得每个工具各配一套。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。Claude Code 侧的配置有两种常见写法。一种是通过环境变量在 shell 里设置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoTokenKey另一种是写进 Claude Code 的 settings 文件。如果你用的是项目级配置路径是.claude/settings.json用户级则是~/.claude/settings.json。内容大致如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey } }如果你同时用 Codex它的凭据文件在~/.codex/auth.json写法是{ OPENAI_API_KEY: sk-你的TaoTokenKey, OPENAI_BASE_URL: https://taotoken.net/api }这里有个容易踩的坑Base URL 末尾不要多加/v1或/anthropic不同客户端对路径拼接的处理不一样多写一段可能导致 404。统一用https://taotoken.net/api这个根路径客户端会自己补全。Elasticsearch 侧的前置条件有三条Claude Code 2.0.76 及以上、Elasticsearch 9.2、一个 Elasticsearch API key。Agent Builder 已经正式发布你可以在 Elastic Cloud 上开一个 trial 来跑通本文的流程。Kibana 的地址记作${KIBANA_URL}API key 记作${API_KEY}后面创建 agent 和配置 MCP 都要用到。先把测试数据集准备好。我们需要四个索引knowledge内部文档、工程规范、路线图、error_logs按模块统计的生产错误频率、support_tickets客户投诉及紧急标记、customer_data客户层级、MRR。在 Kibana Dev Tools 里创建 mapping 并批量索引数据以customer_data为例PUT customer_data { mappings: { properties: { user_id: { type: keyword }, customer_tier: { type: keyword }, company_name: { type: text }, mrr: { type: float }, joined_at: { type: date } } } } POST customer_data/_bulk {index:{}} {user_id:enterprise_user_01,customer_tier:enterprise,company_name:Acme Corp,mrr:2500.00,joined_at:2023-01-15} {index:{}} {user_id:enterprise_user_02,customer_tier:enterprise,company_name:GlobalTech Inc,mrr:4200.00,joined_at:2022-08-20} {index:{}} {user_id:user_045,customer_tier:pro,company_name:SmallBiz LLC,mrr:49.00,joined_at:2024-01-10}其余三个索引按同样方式建好。本地项目里再放两个 Markdown 文件TECH_DEBT.md列出 12 条技术债每条带模块、症状、预估工时REQUIREMENTS.md写 Q1 2025 的需求。这两个文件是 planning agent 的本地输入和 Elasticsearch 里的业务数据交叉参考。3. 可复制配置Agent Builder 创建 agent MCP 接入 Claude Code先在 Kibana 侧用 API 创建一个 retrieval agent。这个 agent 的职责是用 ES|QL 跑分析查询同时能搜索 knowledge 索引里的非结构化文本。用内置工具就够了它们覆盖了对任意索引的搜索和分析Agent Builder 也支持自定义工具来做更专业的操作比如限定索引范围或加 ES|QL 动态参数这里先不展开。创建 agent 的 curl 请求如下注意把${KIBANA_URL}和${API_KEY}替换成你自己的curl -X POST https://${KIBANA_URL}/api/agent_builder/agents \ -H Authorization: ApiKey ${API_KEY} \ -H kbn-xsrf: true \ -H Content-Type: application/json \ -d { id: tech-debt-advisor, name: Tech Debt Prioritization Agent, description: I help prioritize technical debt by analyzing error logs, support tickets, customer impact, and aligning with engineering standards and roadmap priorities., avatar_color: #BFDBFF, avatar_symbol: TD, configuration: { instructions: This agent helps prioritize technical debt items. Use the following indices:\n\n- knowledge: Engineering standards, policies, and roadmap priorities\n- error_logs: Production error frequency by module\n- support_tickets: Customer complaints and their urgency\n- customer_data: Customer tier information (enterprise, pro, free)\n\nWhen analyzing tech debt:\n1. Check error frequency in error_logs\n2. Cross-reference affected users with customer_data to understand tier impact\n3. Count support tickets and note urgency markers\n4. Check knowledge base for relevant policies and Q1 priorities\n5. Synthesize findings into prioritized recommendations, tools: [ { tool_ids: [ platform.core.search, platform.core.list_indices, platform.core.get_index_mapping, platform.core.get_document_by_id, platform.core.execute_esql, platform.core.generate_esql ] } ] } }返回体里会带上id、type、name等字段说明 agent 创建成功。这个 agent 在 Kibana 里也能直接聊天测试。接下来把它暴露的 MCP server 加到 Claude Code。命令是claude mcp add --transport http agentbuilder https://${KIBANA_URL}/api/agent_builder/mcp --header Authorization: ApiKey ${API_KEY}加完之后用claude mcp get agentbuilder检查连接状态。如果状态正常说明 MCP 通道通了。然后在 Claude Code 里创建 subagent。输入/agents选 Create new agentscope 选 Project只在本项目可用避免 agent 溢出生成方式选 Generate with Claude。描述填Agent that analyzes technical debt by querying Elasticsearch for error logs, support tickets, customer data, and engineering knowledge base. Use this agent when you need to prioritize tech debt items based on business impact.在 Select tools 里选 Advanced options勾选刚才 agent 创建时定义的六个工具platform.core.search、platform.core.list_indices、platform.core.get_index_mapping、platform.core.get_document_by_id、platform.core.execute_esql、platform.core.generate_esql它们都挂在agentbuilder这个 MCP server 下。模型选 Opusplanning 类任务对推理能力要求高。Claude 会根据描述自动给 subagent 命名比如tech-debt-analyzer。这里三件套要写全Base URL 是https://${KIBANA_URL}/api/agent_builder/mcpKey 是 Elasticsearch 的${API_KEY}Model ID 在 subagent 定义里通过model: opus指定。三者缺一MCP 调用就会失败。4. 验证请求用一次真实检索确认上下文注入生效配置完成后别急着让它出计划先用一个需要多步推理的问题验证 retrieval subagent 是否真的把 Elasticsearch 数据拉回来了。在 Claude Code 里输入Based on TECH_DEBT.md, which items should we prioritize for our 2-week sprint? Use the tech-debt-analyzer agent to check error frequency, customer impact, support ticket volume, and alignment with engineering standards.观察执行过程。正常情况下你会看到 subagent 依次协调多个查询先读本地TECH_DEBT.md拿到条目列表然后对每条去error_logs查错误频率跨索引参考customer_data看受影响用户的层级分布查support_tickets统计投诉量和紧急标记最后读knowledge里的工程规范和 Q1 路线图。这些查询不是一次完成的而是前一步的结果影响后一步——比如某条技术债在error_logs里频率高才会进一步去customer_data确认它影响的是不是 enterprise 客户。返回的结果应该是一份结合了本地文件和 Elasticsearch 数据的优先级建议。关键验证点是建议里是否出现了只有 Elasticsearch 才有的信息比如“AUTH-001 影响 3 个 enterprise 客户MRR 合计 9800”“EXPORT-002 在 support_tickets 里有 7 条投诉其中 2 条标记 urgent”。如果这些数字出现了说明上下文注入生效如果建议只基于TECH_DEBT.md的文本说明 MCP 工具没被调用。你还可以用/context查看每个 MCP tool 定义和 subagent prompt 占用了多少上下文。这一步在创建 subagents 时值得做因为工具定义本身有开销挂太多工具会挤占有效上下文。验证通过后再进入正式规划Based on our requirements defined in REQUIREMENTS.md, use the planning agent to create a detailed implementation plan, prioritizing tasks according to business impact. Use the tech-debt-analyzer agent to query about internal company knowledge and make analytical queries about error patterns and customer impact.这时 Claude 会按 hub-and-spoke 模式并行运行一边让 retrieval agent 查 Elasticsearch一边让 explore agent 读本地文件最后 planning agent 汇总。你拿到的计划是基于实际业务数据而非假设的可以直接交给 coding agent 逐步执行。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞上的几类报错逐个说清楚。401 Unauthorized。两种可能一是 TaoToken 的 Key 写错或过期检查ANTHROPIC_AUTH_TOKEN是否以sk-开头、有没有多余空格二是 Elasticsearch 的${API_KEY}没正确传入 MCP header。用claude mcp get agentbuilder看连接状态如果显示 failed多半是 header 里的Authorization: ApiKey ${API_KEY}没替换成真实值。注意 Elasticsearch 用的是ApiKey前缀不是Bearer。local proxy failed。这个报错通常出现在 Base URL 配置有误时。检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/v1或带了多余路径。统一用https://taotoken.net/api让客户端自己拼接。如果你在 settings.json 和 shell 环境变量里都设了以哪个为准取决于客户端加载顺序建议只保留一处避免冲突。reading choices 相关报错。这类错误一般出现在响应体解析阶段常见原因是模型返回了非预期格式或者 Base URL 指向了一个不兼容的 endpoint。确认你用的是 TaoToken 的 API 地址而不是官网首页地址。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 是 https://taotoken.net/api 两者不要混用。OAuth 相关报错。Claude Code 某些版本会尝试走 OAuth 流程如果你用的是 API Key 模式需要在配置里明确禁用 OAuth 或确保ANTHROPIC_AUTH_TOKEN优先。检查~/.claude/settings.json里有没有残留的 OAuth 配置项清掉后重启 Claude Code。MCP 工具调用返回空结果。如果 subagent 跑了但没拿到 Elasticsearch 数据先确认 agent 创建时的tool_ids和 subagent 里勾选的工具一致。六个工具要全部勾上少一个都可能导致某类查询失败。另外确认索引名拼写正确knowledge、error_logs、support_tickets、customer_data大小写敏感。subagent 没被调用。如果你显式说了“Use the tech-debt-analyzer agent”但它没触发检查 subagent 的description是否足够明确。description 是 Claude 判断何时调用它的依据写得太泛会导致它被忽略。另外确认 scope 选的是 Project如果选成 User 级别在某些项目里可能不生效。6. 把业务上下文接进代码规划之后走到这一步你的 Claude Code 已经能在规划阶段同时看到三类信息本地文件TECH_DEBT.md、REQUIREMENTS.md、源码、互联网search、fetch、内部业务数据Elasticsearch 的四个索引。retrieval subagent 负责把第三类拉回来planning agent 负责综合coding agent 负责执行。实际用下来有几个经验值得记一下。第一subagent 的 prompt 要具体到文件名和索引名别说“review the code”要说“review the changes to src/auth/index.ts, focusing on JWT token validation”。精确的指令决定它是直接用 read 读文件还是用 grep 大范围搜索后者浪费时间和 token。第二工具要限制在必要范围内只做分析的 agent 给 Read、Grep、Glob 就够需要改代码的再加 Edit、Write。第三长时间任务可以让 agent 写一个 Markdown 清单记录进度然后/clear清对话下一个 agent 从清单继续这样不会丢初始指令。Agent Builder 的 MCP 能力让 retrieval subagent 能访问 Elasticsearch 数据但它的价值不在简单查询而在需要基于前置结果做多步推理、整合多来源信息的时候。技术债优先级排序只是其中一个场景同样的模式可以套到故障排查、客户影响分析、合规检查等需要跨索引综合判断的任务上。如果你还没配 TaoToken 的统一 Key可以从 API Keys 页面拿一个再对照接入文档把 Base URL 和 auth.json 写对。想先验证模型连通性用模型对话跑一轮如果打算长期在编码和 Agent 场景里用Coding Plan 会更合适。
1. 为什么代码规划总在“业务上下文”这一步卡住你可能已经习惯了让 Claude Code 读本地文件、跑 grep、生成实现计划但真正落到业务决策时问题往往不在代码本身。比如你手里有一份TECH_DEBT.md列了 12 条技术债两周只能做 3 到 4 条怎么排优先级光看代码根本判断不出来——哪条影响付费客户、哪条和 Q1 路线图对齐、哪条在错误日志里高频出现这些信息散落在 Elasticsearch 的多个索引里Claude Code 默认的工具链看不到。这就是 subagents 与 Elastic Agent Builder 组合要解决的问题让 Claude Code 在进入代码规划之前先通过一个专门的 retrieval subagent 去 Elasticsearch 检索业务上下文把“错误频率、客户层级、工单量、工程规范、路线图”这些外部知识拉回来再交给 planning agent 制定计划。整个过程不需要你把数据复制到本地也不需要主对话窗口被一堆原始 JSON 塞满。subagents 的核心价值在于上下文隔离。每个 subagent 有自己的上下文窗口完成任务后只把结果返回给主 agent执行过程不污染主对话。它还有四个原则上下文保留、专业化能力、可复用性、灵活访问控制。你可以限制某个 subagent 只能访问特定工具比如只允许它调用 Elasticsearch 的 MCP 工具不允许它写文件。在 Claude Code 里subagent 用一段带 frontmatter 的 Markdown 定义schema 大致是这样--- name: your-sub-agent-name description: Description of when this subagent should be invoked tools: tool1, tool2, tool3 model: sonnet permissionMode: default skills: skill1, skill2 --- Your subagents system prompt goes here.tools字段不写就继承主 agent 的所有工具包括 MCP 工具。model可以指定别名或inherit。调用方式有两种隐式调用比如你说“I want to plan my new functionality”Claude 会自动判断该用哪个 subagent显式调用直接说“Use the planning subagent to plan my new functionality”。subagent 还是有状态的第一次调用后会生成一个 agentId下次可以用Resume agent abc123继承之前的上下文agentId 也能在~/.claude/projects/{project}/{sessionId}/subagents/里找到。编排模式上常见的有三种顺序模式chaining一个 subagent 的输出传给下一个像 Linux 管道并行模式多个 subagent 同时跑独立任务主 agent 负责汇总中心辐射模式hub-and-spoke主 agent 当协调者把业务信息收集交给 retrieval agent同时让 explore agent 看本地文件、planning agent 出计划。本文要落地的就是 hub-and-spoke。什么时候该用 agent什么时候一条 ES|QL 就够了如果你只想要单个聚合比如“访问量最高的页面是哪个”直接跑查询。但当问题需要多个查询互相依赖、跨索引推理、消解歧义、综合定量与定性信息时agent 才有价值。技术债优先级排序恰好四个都占读TECH_DEBT.md知道有哪 12 条对每条查error_logs拿错误频率跨索引参考customer_data看客户层级查support_tickets看投诉量读knowledge里的工程规范和 Q1 路线图最后综合成建议。单条查询做不到因为“最重要的技术债”这个判断依赖前面每一步的结果。2. TaoToken 统一 Key 与前置准备把 endpoint 和 auth.json 写对在把 Elastic Agent Builder 接进 Claude Code 之前先把模型侧的访问统一掉。TaoToken 提供统一的 API endpointClaude Code、Codex、Cline 这些工具都可以指向同一个 Base URL用同一个 Key省得每个工具各配一套。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。Claude Code 侧的配置有两种常见写法。一种是通过环境变量在 shell 里设置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoTokenKey另一种是写进 Claude Code 的 settings 文件。如果你用的是项目级配置路径是.claude/settings.json用户级则是~/.claude/settings.json。内容大致如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey } }如果你同时用 Codex它的凭据文件在~/.codex/auth.json写法是{ OPENAI_API_KEY: sk-你的TaoTokenKey, OPENAI_BASE_URL: https://taotoken.net/api }这里有个容易踩的坑Base URL 末尾不要多加/v1或/anthropic不同客户端对路径拼接的处理不一样多写一段可能导致 404。统一用https://taotoken.net/api这个根路径客户端会自己补全。Elasticsearch 侧的前置条件有三条Claude Code 2.0.76 及以上、Elasticsearch 9.2、一个 Elasticsearch API key。Agent Builder 已经正式发布你可以在 Elastic Cloud 上开一个 trial 来跑通本文的流程。Kibana 的地址记作${KIBANA_URL}API key 记作${API_KEY}后面创建 agent 和配置 MCP 都要用到。先把测试数据集准备好。我们需要四个索引knowledge内部文档、工程规范、路线图、error_logs按模块统计的生产错误频率、support_tickets客户投诉及紧急标记、customer_data客户层级、MRR。在 Kibana Dev Tools 里创建 mapping 并批量索引数据以customer_data为例PUT customer_data { mappings: { properties: { user_id: { type: keyword }, customer_tier: { type: keyword }, company_name: { type: text }, mrr: { type: float }, joined_at: { type: date } } } } POST customer_data/_bulk {index:{}} {user_id:enterprise_user_01,customer_tier:enterprise,company_name:Acme Corp,mrr:2500.00,joined_at:2023-01-15} {index:{}} {user_id:enterprise_user_02,customer_tier:enterprise,company_name:GlobalTech Inc,mrr:4200.00,joined_at:2022-08-20} {index:{}} {user_id:user_045,customer_tier:pro,company_name:SmallBiz LLC,mrr:49.00,joined_at:2024-01-10}其余三个索引按同样方式建好。本地项目里再放两个 Markdown 文件TECH_DEBT.md列出 12 条技术债每条带模块、症状、预估工时REQUIREMENTS.md写 Q1 2025 的需求。这两个文件是 planning agent 的本地输入和 Elasticsearch 里的业务数据交叉参考。3. 可复制配置Agent Builder 创建 agent MCP 接入 Claude Code先在 Kibana 侧用 API 创建一个 retrieval agent。这个 agent 的职责是用 ES|QL 跑分析查询同时能搜索 knowledge 索引里的非结构化文本。用内置工具就够了它们覆盖了对任意索引的搜索和分析Agent Builder 也支持自定义工具来做更专业的操作比如限定索引范围或加 ES|QL 动态参数这里先不展开。创建 agent 的 curl 请求如下注意把${KIBANA_URL}和${API_KEY}替换成你自己的curl -X POST https://${KIBANA_URL}/api/agent_builder/agents \ -H Authorization: ApiKey ${API_KEY} \ -H kbn-xsrf: true \ -H Content-Type: application/json \ -d { id: tech-debt-advisor, name: Tech Debt Prioritization Agent, description: I help prioritize technical debt by analyzing error logs, support tickets, customer impact, and aligning with engineering standards and roadmap priorities., avatar_color: #BFDBFF, avatar_symbol: TD, configuration: { instructions: This agent helps prioritize technical debt items. Use the following indices:\n\n- knowledge: Engineering standards, policies, and roadmap priorities\n- error_logs: Production error frequency by module\n- support_tickets: Customer complaints and their urgency\n- customer_data: Customer tier information (enterprise, pro, free)\n\nWhen analyzing tech debt:\n1. Check error frequency in error_logs\n2. Cross-reference affected users with customer_data to understand tier impact\n3. Count support tickets and note urgency markers\n4. Check knowledge base for relevant policies and Q1 priorities\n5. Synthesize findings into prioritized recommendations, tools: [ { tool_ids: [ platform.core.search, platform.core.list_indices, platform.core.get_index_mapping, platform.core.get_document_by_id, platform.core.execute_esql, platform.core.generate_esql ] } ] } }返回体里会带上id、type、name等字段说明 agent 创建成功。这个 agent 在 Kibana 里也能直接聊天测试。接下来把它暴露的 MCP server 加到 Claude Code。命令是claude mcp add --transport http agentbuilder https://${KIBANA_URL}/api/agent_builder/mcp --header Authorization: ApiKey ${API_KEY}加完之后用claude mcp get agentbuilder检查连接状态。如果状态正常说明 MCP 通道通了。然后在 Claude Code 里创建 subagent。输入/agents选 Create new agentscope 选 Project只在本项目可用避免 agent 溢出生成方式选 Generate with Claude。描述填Agent that analyzes technical debt by querying Elasticsearch for error logs, support tickets, customer data, and engineering knowledge base. Use this agent when you need to prioritize tech debt items based on business impact.在 Select tools 里选 Advanced options勾选刚才 agent 创建时定义的六个工具platform.core.search、platform.core.list_indices、platform.core.get_index_mapping、platform.core.get_document_by_id、platform.core.execute_esql、platform.core.generate_esql它们都挂在agentbuilder这个 MCP server 下。模型选 Opusplanning 类任务对推理能力要求高。Claude 会根据描述自动给 subagent 命名比如tech-debt-analyzer。这里三件套要写全Base URL 是https://${KIBANA_URL}/api/agent_builder/mcpKey 是 Elasticsearch 的${API_KEY}Model ID 在 subagent 定义里通过model: opus指定。三者缺一MCP 调用就会失败。4. 验证请求用一次真实检索确认上下文注入生效配置完成后别急着让它出计划先用一个需要多步推理的问题验证 retrieval subagent 是否真的把 Elasticsearch 数据拉回来了。在 Claude Code 里输入Based on TECH_DEBT.md, which items should we prioritize for our 2-week sprint? Use the tech-debt-analyzer agent to check error frequency, customer impact, support ticket volume, and alignment with engineering standards.观察执行过程。正常情况下你会看到 subagent 依次协调多个查询先读本地TECH_DEBT.md拿到条目列表然后对每条去error_logs查错误频率跨索引参考customer_data看受影响用户的层级分布查support_tickets统计投诉量和紧急标记最后读knowledge里的工程规范和 Q1 路线图。这些查询不是一次完成的而是前一步的结果影响后一步——比如某条技术债在error_logs里频率高才会进一步去customer_data确认它影响的是不是 enterprise 客户。返回的结果应该是一份结合了本地文件和 Elasticsearch 数据的优先级建议。关键验证点是建议里是否出现了只有 Elasticsearch 才有的信息比如“AUTH-001 影响 3 个 enterprise 客户MRR 合计 9800”“EXPORT-002 在 support_tickets 里有 7 条投诉其中 2 条标记 urgent”。如果这些数字出现了说明上下文注入生效如果建议只基于TECH_DEBT.md的文本说明 MCP 工具没被调用。你还可以用/context查看每个 MCP tool 定义和 subagent prompt 占用了多少上下文。这一步在创建 subagents 时值得做因为工具定义本身有开销挂太多工具会挤占有效上下文。验证通过后再进入正式规划Based on our requirements defined in REQUIREMENTS.md, use the planning agent to create a detailed implementation plan, prioritizing tasks according to business impact. Use the tech-debt-analyzer agent to query about internal company knowledge and make analytical queries about error patterns and customer impact.这时 Claude 会按 hub-and-spoke 模式并行运行一边让 retrieval agent 查 Elasticsearch一边让 explore agent 读本地文件最后 planning agent 汇总。你拿到的计划是基于实际业务数据而非假设的可以直接交给 coding agent 逐步执行。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞上的几类报错逐个说清楚。401 Unauthorized。两种可能一是 TaoToken 的 Key 写错或过期检查ANTHROPIC_AUTH_TOKEN是否以sk-开头、有没有多余空格二是 Elasticsearch 的${API_KEY}没正确传入 MCP header。用claude mcp get agentbuilder看连接状态如果显示 failed多半是 header 里的Authorization: ApiKey ${API_KEY}没替换成真实值。注意 Elasticsearch 用的是ApiKey前缀不是Bearer。local proxy failed。这个报错通常出现在 Base URL 配置有误时。检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/v1或带了多余路径。统一用https://taotoken.net/api让客户端自己拼接。如果你在 settings.json 和 shell 环境变量里都设了以哪个为准取决于客户端加载顺序建议只保留一处避免冲突。reading choices 相关报错。这类错误一般出现在响应体解析阶段常见原因是模型返回了非预期格式或者 Base URL 指向了一个不兼容的 endpoint。确认你用的是 TaoToken 的 API 地址而不是官网首页地址。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 是 https://taotoken.net/api 两者不要混用。OAuth 相关报错。Claude Code 某些版本会尝试走 OAuth 流程如果你用的是 API Key 模式需要在配置里明确禁用 OAuth 或确保ANTHROPIC_AUTH_TOKEN优先。检查~/.claude/settings.json里有没有残留的 OAuth 配置项清掉后重启 Claude Code。MCP 工具调用返回空结果。如果 subagent 跑了但没拿到 Elasticsearch 数据先确认 agent 创建时的tool_ids和 subagent 里勾选的工具一致。六个工具要全部勾上少一个都可能导致某类查询失败。另外确认索引名拼写正确knowledge、error_logs、support_tickets、customer_data大小写敏感。subagent 没被调用。如果你显式说了“Use the tech-debt-analyzer agent”但它没触发检查 subagent 的description是否足够明确。description 是 Claude 判断何时调用它的依据写得太泛会导致它被忽略。另外确认 scope 选的是 Project如果选成 User 级别在某些项目里可能不生效。6. 把业务上下文接进代码规划之后走到这一步你的 Claude Code 已经能在规划阶段同时看到三类信息本地文件TECH_DEBT.md、REQUIREMENTS.md、源码、互联网search、fetch、内部业务数据Elasticsearch 的四个索引。retrieval subagent 负责把第三类拉回来planning agent 负责综合coding agent 负责执行。实际用下来有几个经验值得记一下。第一subagent 的 prompt 要具体到文件名和索引名别说“review the code”要说“review the changes to src/auth/index.ts, focusing on JWT token validation”。精确的指令决定它是直接用 read 读文件还是用 grep 大范围搜索后者浪费时间和 token。第二工具要限制在必要范围内只做分析的 agent 给 Read、Grep、Glob 就够需要改代码的再加 Edit、Write。第三长时间任务可以让 agent 写一个 Markdown 清单记录进度然后/clear清对话下一个 agent 从清单继续这样不会丢初始指令。Agent Builder 的 MCP 能力让 retrieval subagent 能访问 Elasticsearch 数据但它的价值不在简单查询而在需要基于前置结果做多步推理、整合多来源信息的时候。技术债优先级排序只是其中一个场景同样的模式可以套到故障排查、客户影响分析、合规检查等需要跨索引综合判断的任务上。如果你还没配 TaoToken 的统一 Key可以从 API Keys 页面拿一个再对照接入文档把 Base URL 和 auth.json 写对。想先验证模型连通性用模型对话跑一轮如果打算长期在编码和 Agent 场景里用Coding Plan 会更合适。
