用途:在阅读大量文件之前,把代码库侦察工作委派给一个或多个只读 explorer 子 Agent,让主对话专注于协调、决策、实现与验证,由子 Agent 吸收冗长的搜索结果与文件读取。
适用信号:任务位于陌生仓库或子系统;预计需阅读约 10 个以上文件;任务横跨 API、数据库、UI、测试、文档或构建工具等多个独立区域;用户要求理解架构、追踪功能、重构、迁移、根因分析或大范围评审;编辑前需要一次全新的只读梳理。若只是已知文件的小范围定向修改,则跳过委派。
工作流:先简短说明正在使用 explorer 子 Agent 做侦察;划分独立研究切片,代码库较广时优先 2-4 个切片;在环境与策略允许时启动子 Agent,每个只给狭窄的只读任务,默认推理强度为 low,仅在架构复杂、含糊、高风险或存在多条易混淆相似代码路径时提升到 medium 或 high;子 Agent 运行期间,主对话不得读取目标代码库,只做协调、等待或无关任务;收集输出并综合后再自行读取大文件;产出关键文件表,作为下一步阅读地图。
子 Agent 提示模板:声明只读、不得编辑文件;给出目标、范围;要求找出最相关文件与符号、各部分如何衔接、哪些代码路径是活跃/主要/遗留/实验性/未使用、应保留的既有模式、相关测试与配置文档、变更按关注点分组的方式、风险与后续阅读;只返回简洁报告,含发现、关键文件表(File / Why it matters / Relevant symbols or sections / Confidence)、建议后续阅读。
切片方式:按垂直功能路径(前端、API 路由、服务层、持久化、测试)、分层架构(UI、领域逻辑、数据模型、集成、构建运行配置)、问题假设(根因区域、复现路径、邻近实现)或 monorepo 中的独立包划分。避免“探索一切”这类模糊提示。
综合要求:子 Agent 完成后先汇总有用发现,并在大范围读取或编辑前给出 File / Role / Read next? / Reason / Source 表格,优先只读标记为 Yes 的文件;用户询问功能改动位置时附简短 Change Map(Change type / Primary files / Notes)。存在多个相似实现时,明确标注 primary、legacy、experimental、generated 或 unclear,并说明依据。
护栏:探索是侦察而非实现;只要求摘要与文件引用,不要完整文件转储;除非用户明确要求委派编辑且环境允许,提示保持只读;仅当切片独立时并行;子 Agent 读取目标代码库期间,主 Agent 不得对同一目标执行本地搜索、读取或结构扫描;若子 Agent 不可用,则用 rg、rg --files 在本地按同一流程执行并仍产出关键文件表;发现冲突时,编辑前先本地验证最小相关文件集;不要把某次调查的项目特定结论固化进技能,只保留可复用规则与输出形态。
设计说明:该工作流把 Claude Code 的 Explore Agent 模式适配到 Codex,将高容量代码搜索隔离在独立上下文中,只返回相关摘要,并通过关键文件表让交接具体化。更新技能或解释设计时,可阅读 references/claude-explore-agent-research.md。