用途
codebase-exploration-loop 用于在陌生代码库中建立可用的心智模型。它是 loop-controller 的一个配置:loop-controller 提供循环机制(原语选择、完整护栏、状态外化),本技能补充理解代码库特有的三件事——种子问题证明(默认失败的提问清单,只有代码引用才能翻转)、只读并行铺开以映射子系统、以及针对剩余理解缺口的循环至枯竭停止条件。该循环耗费 token,每轮会铺开一批子代理,因此设计为用户驱动,需显式输入 /codebase-exploration-loop 并附带问题,而不是在普通提问时静默启动探索。
五部分契约
- 触发:面对陌生仓库出现“我不理解 X”,如上手、逆向工程,或显式调用 /codebase-exploration-loop 并给出种子问题清单。
- 动作:一轮 = 读取缺口清单 → 并行铺开只读子代理(每个开放子系统或问题一个,限制并行度)→ 每个返回发现与 file:line 引用 → 汇总为架构摘要 → 标记已回答问题,暴露新发现的缺口。
- 证明:架构摘要回答每个种子问题,每个答案引用代码中的 path:line(或符号),且没有开放的“我不理解 X”缺口。默认失败:每个问题初始 answered: false,只有出现引用才翻转。
- 记忆:seed-questions.json(默认失败的问题清单及每轮发现的新缺口)与 ARCHITECTURE-SUMMARY.md(不断增长的汇总),跨轮持久,不依赖对话记忆。
- 停止:每个问题都 answered: true 且有引用;或循环至枯竭(某轮既无新答案也无新缺口);或达到轮次/迭代上限;或连续 2 轮无进展;或达到预算上限。
使用方式(三个步骤)
- 捕获种子问题(默认失败):在任何铺开之前,把种子问题写入 seed-questions.json,全部 answered: false。问题应是用户自己的问题,如“请求从哪里进入”“鉴权如何实施”“数据模型是什么”“构建配置在哪”,而非通用清单。用户给出问题时逐字采用,否则提出起始问题集并确认。清单会增长:当某轮揭示你以为理解但其实没理解的内容时,追加为新的默认失败条目。只有清单全部为真且不再增长时循环才结束。JSON 模式与缺口发现规则在 references/exploration.md。
- 只读铺开子代理(限制并行度):每个开放子系统或问题一个子代理,并行派发,仅授予 Read/Grep/Glob/Bash 检查权限——无 Write/Edit、无网络。只读映射者不会意外改动正在研究的代码,且新的子代理会报告实际存在的内容而非期望存在的内容。每个返回带 path:line 引用的简短发现备忘。每轮并行宽度默认约 4-6 并发,更多并行读取者不等于更快理解,只会带来难以调和的汇总和无法预测的预算。派发说明及与 /deep-research 的区别见 references/exploration.md。
- 汇总,然后寻找下一个缺口:把本轮备忘合并进 ARCHITECTURE-SUMMARY.md,按子系统更新章节,将每条引用挂到它回答的问题上,并把这些问题翻转为 answered: true。然后执行关键步骤——通读摘要,问自己还有哪些无法解释。回答“X 如何工作”的子系统备忘通常会暴露“……但谁调用 X,它的数据从哪来?”这些成为新的默认失败条目。这就是循环至枯竭的引擎:直到某轮既无新答案也无新缺口为止。
与相邻工具的区别
- 对比 repo-deep-dive:后者是一次性重量级交付物,为整个仓库生成 12-14 份综合参考文档系列,基于预跑深度研究 markdown。本循环是更轻量、迭代、由种子问题驱动的路径,问题回答完即停止,可能永远不会记录你没问的子系统。用户需要完整系列时应移交 repo-deep-dive(边界与移交触发见 references/exploration.md),不要自行长成它。
- 对比 project-profiler:后者按标准模板产出固定的一次性产物(CLAUDE.md + profile.yaml)。本循环的交付物是问答摘要加循环纪律。它可以为 project-profiler 提供输入(根据循环所学刷新 CLAUDE.md),但剖析不是它的证明。
- 对比 deep-research:同样是铺开 → 验证 → 汇总的形状,但 deep-research 走向网络并引用来源;本循环走向本地代码并引用 path:line,只读、无网络。如果仍觉得像“本地代码上的 deep-research”,那正是重点:真正贡献在于直到种子问题被回答的收敛与只读铺开纪律,而非新的文档格式。
特有护栏
继承 loop-controller → references/safety.md 的完整栈。本循环设置的上限:
- 轮次/迭代上限:默认约 6-8 轮(若设置则从 .claude/profile.yaml 读取)。触达时应停止并报告仍未回答的问题,而不是无引用地把问题标为 true。
- 无进展检测:若某轮未回答任何新问题且未暴露新缺口,循环已枯竭——停止。若同一缺口连续 2 轮无新引用,提交给人类;有些问题需要代码作者而非第三次铺开。
- 预算上限:每轮子代理铺开会成倍增加 token 消耗;按 loop-controller 执行终止循环的上限,并保持每轮宽度受限(见步骤 2)。
只读是边界。映射子代理没有 Write/Edit 与网络权限——仅此而已。本循环研究代码,不修改代码。刷新 CLAUDE.md 是单独的、显式的 project-profiler 调用,不是映射者在轮内做的事。循环内没有不可逆操作,因此在只读边界内可安全无人值守运行。
绝不作弊通过证明:没有真实代码引用就不要把问题翻转为 answered: true,也不要为了清空清单而删掉难题。靠含糊其辞“回答”的摘要是发现,不是理解。
驱动原语选择
按 loop-controller 步骤 1,这是动态工作流/铺开循环,而非 /goal 终点冲刺——每轮是一次并行派发:
- 默认——动态工作流/铺开(本地代码上的 /deep-research 引擎):每轮将只读映射者铺开到各子系统,再汇总。想以带显式 token 预算的工作流管理铺开时,与编排器的 Workflow 模式组合。
- /goal 可驱动外层收敛——条件:“seed-questions.json 每项 answered: true 且有引用,或 N 轮后停止”——每回合做一轮铺开并汇总。记住 /goal 没有原生预算,需嵌入轮次上限。
参考文件
references/exploration.md——seed-questions.json 模式与默认失败/缺口发现规则、只读铺开派发模式(以及它与 /deep-research 的区别)、移交 repo-deep-dive 的边界。