how

How

根据实际运行代码，建立资深工程师对某个子系统的工作模型。解释架构和运行时流程，但不要把答案写成带注释的源码。

选择模式

• Explain 是回答“这是如何工作的？”这类问题时的默认模式。
• Place 用于回答所有权和分层问题，例如“这应该放在哪里？”。在建议边界前，先梳理相关架构。
• Critique 适用于用户还询问架构上有哪些问题或值得改进之处的情况。先完整解释，再评判设计。

Explain 工作流

1. 明确问题

确定目标、所需深度和可能的入口点。若目标含糊不清，根据对话和仓库上下文说明最合理的理解；只有在不同理解会导致不同调查时才提问。

划分范围：

• 狭窄： 一个模块、工具函数、函数或范围明确的调用路径。
• 广泛： 横跨边界、服务、持久化层或多个独立流程的子系统。

不确定时先从狭窄范围入手，只有在遇到无法解释的边界时才扩大范围。

完成条件： 明确目标、入口点和调查边界。

2. 追踪代码

对于狭窄问题，直接追踪实现。对于广泛问题，将子系统划分为两到四个独立角度，例如状态、请求流、持久化或外部边界。运行时支持独立的只读 Agent 时，并行探索这些角度；否则依次检查。

使用 references/explorer-prompt.md 委派探索。每个角度都必须根据实际符号和调用，从入口追踪到效果，记录读取过的文件，并指出缺口，而不是跨越缺口进行推断。

完成条件： 从触发到可观察效果的每个关键步骤都有代码引用，且列出每个尚未追踪的环节作为待解问题。

3. 综合工作模型

整合不同追踪结果中的重叠内容和矛盾之处。若发现不一致，重新阅读相关代码。无论由负责人撰写答案还是委派撰写，都使用 references/explainer-prompt.md 作为综合约定。

解释仅应涵盖问题所需的部分：

• 概览： 用途和边界。
• 关键概念： 理解流程所需的少数类型或服务。
• 工作原理： 触发、步骤、数据转换、决策和效果。
• 代码位置： 新贡献者应优先查看的文件。
• 注意事项： 令人意外的行为、缺口或容易出错之处。

只有在组件交互或数据转换用图示比文字更清晰时，才加入图示。

完成条件： 不熟悉该领域的资深工程师无需重新打开每个文件，就能找出入口点、追踪主流程并说出子系统的边界。

Placement 工作流

首先追踪提议中的代码会影响的行为和边界。然后根据以下方面比较候选归属位置：

• 领域职责和状态所有权；
• 依赖方向和生命周期；
• 仓库中相似行为的实现模式；
• 验证、错误和副作用所属的边界；
• 可测试性，以及根据仓库证据推断最可能的后续改动。

推荐一个位置，解释它为何拥有该行为，并说明它应导入、暴露哪些内容，以及哪些内容应留在其他位置。指出可信的替代方案，并说明它们为何不那么合适。除非新建一层能消除已证实的耦合或重复复杂性，否则不要新建层。

完成条件： 建议引用现有边界和类似代码，明确指定唯一归属位置，并说明最小集成路径。

Critique 工作流

1. 建立解释

先完成 Explain 工作流。评判现有架构，而非假设中的设计。

2. 收集独立评判意见

结合说明、相关文件以及 references/critique-rubric.md，使用 references/critic-prompt.md。如果运行环境支持并行评审，请使用两名或更多独立评审者，以减少框架偏见；否则，请直接应用评审标准。

此方法不得依赖特定的 Agent 提供方、模型或运行器配置。

**完成标准：**每个拟议问题都引用代码，并说明实际成本，而非仅表达风格偏好。

3. 作出最终判断

对每项发现进行分类：

• **采取行动：**已证实的架构问题，值得立即修复。
• **考虑：**真实存在的顾虑，但其成本或补救措施尚不确定。
• **记录：**优先级较低的权衡或技术债务标记。
• **驳回：**不正确、缺乏依据或仅属偏好。

先呈现说明，再呈现评审意见。若架构合理，则评审意见留空。

**完成标准：**合并重叠的发现，解决分歧或明确呈现分歧，并确保每项保留的建议都有证据、影响说明和恰当的优先级。