how

如何

探索代码库，回答“X 是如何工作的？”这类问题。提供清晰的架构说明，深度应达到资深工程师入职并熟悉某个子系统所需的水平。内容应足以帮助读者建立有效的心智模型，而不是对源代码逐行注释。

有两种模式：

1. 说明（默认）。探索代码库并给出清晰的说明
2. 评审。先进行说明，然后启动多个模型，分别找出架构问题

说明模式

步骤 1：理解问题并评估复杂度

解析用户的问题：

• “限流器是如何工作的？”，一个子系统
• “我们如何处理按需使用的计费？”，一个功能流程
• “认证服务是如何构建的？”，一个架构概览
• “带我了解用户提交表单后会发生什么”，一次运行时跟踪

确定范围。如果问题含糊不清，先说明你认为最可能的理解，再开始探索。不要提问。如果理解有偏差，让用户纠正即可。

评估复杂度，决定采用哪种方式：

• 简单（单个模块、小型工具，或“函数 X 是如何工作的？”这类范围较窄的问题）：跳过探索 Agent，由讲解者一次性完成探索和说明。转到步骤 2b。
• 复杂（涉及多个文件或服务的子系统、横切功能、完整架构概览）：先并行启动探索 Agent，再移交给讲解者。转到步骤 2a。

如有疑问，优先按简单问题处理。如果讲解者遇到困难，随时可以启动探索 Agent。

步骤 2a：探索（仅限复杂问题）

将问题拆分为 2 到 4 个并行探索方向，每个方向对应子系统中一个独立部分，避免探索者重复工作。例如，针对“限流器是如何工作的？”可以这样拆分：

• 探索者 1：数据模型和状态管理
• 探索者 2：请求路径和执行限制
• 探索者 3：配置和指标基础设施

具体拆分方式取决于问题。自行判断。范围较窄的问题：2 个探索者即可。范围较广的子系统：最多 4 个。

在一条消息中启动所有探索者：

• subagent_type：generalPurpose
• model：你配置的 how-explorer 模型（默认 composer-2.5-fast）
• readonly：true

每个探索者都会收到 references/explorer-prompt.md 中的相同基础提示词，以及一段指定探索方向、说明其负责部分的提示词。每个探索者都应：

• 从整体入手：使用 Glob 查找相关目录，使用 Grep 查找关键类型、接口和类名
• 顺着调用链追踪：从入口点出发，追踪调用链（调用方、被调用方、数据流、类型定义）
• 阅读实际代码，不要根据文件名猜测
• 只有能够清楚描述从输入到输出（或从触发到效果）的完整路径，没有任何含糊之处时，才停止探索
• 记录令人意外、非显而易见或新手容易误解的内容

每个探索者都会返回结构化的发现：找到的组件、追踪到的流程、阅读过的文件，以及任何非显而易见的内容。探索者之间有重叠也没关系，讲解者会整合这些发现。

然后进入步骤 3。

步骤 2b：直接说明（简单问题）

启动一个 Task 子 Agent，一次性完成探索和说明：

• subagent_type：generalPurpose
• model：你配置的 how-explainer 模型（默认 claude-opus-4-8-thinking-xhigh）
• readonly：true

该 Agent 自行探索（Glob、Grep、Read），并直接撰写说明。阅读 references/explainer-prompt.md，了解沟通风格和输出格式。结构相同，只是不需要将探索者的发现作为输入。

进入步骤 4。

步骤 3：综合（仅限复杂问题）

所有探索者返回后，启动一个 Task 子 Agent，将他们的发现综合成一份连贯的说明：

• subagent_type：generalPurpose
• model：你配置的 how-explainer 模型（默认为 claude-opus-4-8-thinking-xhigh）
• readonly：true

说明者会获取所有探索者的发现，并撰写面向用户的说明（输出格式如下）。完整的提示词模板请阅读 references/explainer-prompt.md。说明者会协调重叠的发现、解决矛盾，并将各部分融汇成一个统一的整体。

步骤 4：呈现

向用户呈现说明者的输出。你可以稍作润色以提升清晰度，或补充对话中的背景信息，但不要大幅改写。说明者的内容就是最终交付成果。

输出格式

根据问题调整并遵循此结构。并非每个问题都需要所有部分。

概述。 1–2 段。说明它是什么、有什么作用以及为何存在。提供足够信息，让读者决定是否继续阅读。

关键概念。 介绍重要的类型、服务或抽象概念，并简要定义。无需面面俱到，只需涵盖理解其余内容所需的部分。

工作原理。 说明的核心部分。按步骤介绍整个流程：是什么触发了流程、每一步会发生什么、数据流向何处，以及有哪些决策点。使用自然语言，不要写伪代码。引用具体文件和函数，方便读者查阅，但除非确有必要，否则不要贴出代码块。

文件位置。 简要列出相关文件或目录，帮助读者着手处理此部分。无需罗列所有文件，只列出入门所需的文件即可。

注意事项。 介绍容易忽略或出乎意料之处、可能让人困惑的历史背景，以及已知的风险点。

批评模式

当用户询问架构问题、问题或改进建议，而不只是想了解系统时触发。

步骤 1：先解释

完整执行上述说明流程（步骤 1–4）。批评之前，必须先理解架构。

步骤 2：启动评审者

说明完成后，根据你配置的 how-critics 列表（默认为 claude-opus-4-8-thinking-xhigh、gpt-5.5-high-fast、composer-2.5-fast）中的每个模型启动一名架构评审者，并在一条消息中同时启动。

对于每位评审者：

• subagent_type：generalPurpose
• model：how-critics 配置列表中的一个模型。这些是最低推理能力要求。若架构需要更深入的分析，主导者应升级模型。
• readonly：true

阅读 references/critic-prompt.md 获取提示词模板。每位评审者会获得：

1. 步骤 1 中的说明（无需重新探索）
2. 相关文件路径（以便查阅实际代码）
3. references/critique-rubric.md 中的架构评审标准

步骤 3：主导者判断

遵循 interrogate 技能中的相同框架。你应以务实的主导者身份进行判断，而不是简单汇总。

对发现进行分类：

• 采取行动。 值得立即修复的架构问题
• 考虑。 确实存在顾虑，但成本效益尚不明确
• 记录。 有效的观察，但优先级较低
• 驳回。 结论有误、缺少背景信息或只是风格偏好

先呈现说明（来自步骤 1），再在下方给出评审结论。说明应能独立成立，让只想了解系统的人无需先读完评审内容。