how

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

How

How(工作原理)

Build a senior-engineer working model of a subsystem from the code that runs it. Explain the architecture and runtime flow without turning the answer into annotated source.
基于实际运行该 subsystem 的代码,建立资深工程师级的工作模型。解释架构和 runtime 流程,但不要把答案变成逐行注释的源码讲解。

Choose a mode

选择模式

  • Explain is the default for “how does this work?” questions.
  • Place answers ownership and layering questions such as “where should this live?” Trace the relevant architecture before recommending a boundary.
  • Critique applies when the user also asks what is architecturally wrong or worth improving. Complete the explanation before judging the design.
  • Explain 是“它是如何工作的?”这类问题的默认模式。
  • Place 用于回答“代码应该放在哪里?”之类的所有权和分层问题。在建议边界之前,先梳理相关架构。
  • Critique 适用于用户同时询问架构上有哪些问题或哪些地方值得改进的情况。先完成解释,再评价设计。

Explain workflow

Explain 工作流

1. Frame the question

1. 界定问题

Identify the target, desired depth, and likely entry point. For an ambiguous target, state the best interpretation from the conversation and repository context; ask only when different interpretations would require different investigations.
Classify the scope:
  • Narrow: one module, utility, function, or contained call path.
  • Broad: a subsystem spanning boundaries, services, persistence, or several independent flows.
Start narrow when uncertain and widen only when an unexplained boundary requires it.
Complete when: the target, entry point, and investigation boundary are explicit.
明确目标、期望深度和可能的入口。对于含糊的目标,根据对话和 repository 上下文说明最佳理解;只有当不同理解需要不同的调查路径时才提问。
判断范围:
  • Narrow: 单个 module、utility、function,或范围受限的调用路径。
  • Broad: 跨越边界、service、persistence 或多个独立流程的 subsystem。
不确定时先从 Narrow 开始,仅当出现尚未解释的边界时再扩大范围。
完成条件: 目标、入口和调查边界均已明确。

2. Trace the code

2. 追踪代码

For a narrow question, trace the implementation directly. For a broad question, divide the subsystem into two to four independent angles, such as state, request flow, persistence, or external boundaries. Explore those angles in parallel when the runtime supports independent read-only agents; otherwise inspect them sequentially.
Use references/explorer-prompt.md for delegated exploration. Each angle must follow actual symbols and calls from entry to effect, record files read, and name gaps rather than infer across them.
Complete when: every material step from trigger to observable effect has a code citation, and every untraced edge is listed as an open question.
对于 Narrow 问题,直接追踪实现。对于 Broad 问题,将 subsystem 分成二到四个独立角度,例如状态、请求流程、persistence 或外部边界。如果 runtime 支持相互独立的只读 Agent,则并行探索这些角度;否则依次检查。
委托探索时使用 references/explorer-prompt.md。每个角度都必须沿着实际的 symbols 和 calls,从入口追踪到最终效果,记录已读取的文件,并明确指出信息缺口,而不是跨缺口进行推断。
完成条件: 从触发条件到可观察效果的所有关键步骤都有代码引用,并且每条未追踪的调用边都被列为 open question。

3. Synthesize the working model

3. 综合形成工作模型

Reconcile overlap and contradictions across the traces. Re-read code where findings disagree. Use references/explainer-prompt.md as the synthesis contract whether the lead writes the answer or delegates it.
The explanation should cover only the sections the question needs:
  • Overview: purpose and boundary.
  • Key concepts: the few types or services needed to follow the flow.
  • How it works: trigger, steps, data transformations, decisions, and effects.
  • Where things live: the files a new contributor should open first.
  • Gotchas: surprising behavior, gaps, or sharp edges.
Include a diagram only when component interaction or data transformation is clearer visually than in prose.
Complete when: a senior engineer unfamiliar with the area could identify the entry point, trace the main path, and name the subsystem's boundaries without reopening every file.
协调不同追踪结果之间的重叠和矛盾。发现结论不一致时,重新阅读相关代码。无论由主 Agent 编写答案还是委派答案,都将 references/explainer-prompt.md 作为综合规范。
解释只需涵盖问题所需的章节:
  • 概述: 目的和边界。
  • 关键概念: 理解流程所需的少量 types 或 services。
  • 工作方式: 触发条件、步骤、数据转换、决策和效果。
  • 代码位置: 新贡献者应首先打开的文件。
  • 注意事项: 令人意外的行为、信息缺口或不易察觉的边缘问题。
仅当图示比文字更清晰地表达组件交互或数据转换时,才加入 diagram。
完成条件: 即使不熟悉该领域,资深工程师也能识别入口、追踪主要路径,并说明 subsystem 的边界,而无需重新查看每个文件。

Placement workflow

Place 工作流

First trace the behavior and boundaries that the proposed code will affect. Then compare candidate owners against:
  • domain responsibility and state ownership;
  • dependency direction and lifecycle;
  • repository patterns for similar behavior;
  • the boundary where validation, errors, and side effects belong;
  • testability and the likely next change supported by repository evidence.
Recommend one location, explain why it owns the behavior, and state what it should import, expose, and leave elsewhere. Name credible alternatives and why they fit less well. Avoid creating a new layer unless it removes demonstrated coupling or repeated complexity.
Complete when: the recommendation cites current boundaries and analogous code, assigns one clear owner, and describes the smallest integration path.
首先追踪拟议代码会影响的行为和边界。然后根据以下方面比较候选归属方:
  • 领域职责和状态所有权;
  • 依赖方向和生命周期;
  • repository 中处理类似行为的既有模式;
  • validation、error 和 side effect 应归属的边界;
  • 可测试性,以及 repository 证据所支持的潜在后续变更。
推荐一个明确位置,解释为什么该位置拥有这些行为,并说明它应该 import 和 expose 什么,以及哪些内容应留在其他位置。列出可信的替代方案,并解释为什么它们不如推荐方案合适。除非新 layer 能消除已证实存在的耦合或重复复杂度,否则不要创建它。
完成条件: 推荐方案引用当前边界和类似代码,指定一个清晰的归属方,并描述最小的集成路径。

Critique workflow

Critique 工作流

1. Establish the explanation

1. 建立解释

Complete the explain workflow first. Critique the architecture that exists, not an assumed design.
先完成 Explain 工作流。批判实际存在的架构,而不是假设的设计。

2. Gather independent judgments

2. 收集独立判断

Use references/critic-prompt.md with the explanation, relevant files, and references/critique-rubric.md. When the runtime supports parallel reviewers, use two or more independent critics to reduce framing bias; otherwise apply the rubric directly.
The method must not depend on a particular agent provider, model, or runner configuration.
Complete when: every proposed issue cites the code and states a practical cost rather than a style preference.
将解释、相关文件、references/critique-rubric.md 与 references/critic-prompt.md 一并使用。如果 runtime 支持并行 reviewers,则使用两个或更多独立 critics,以减少框架偏差;否则直接应用 rubric。
该方法不得依赖特定的 Agent provider、model 或 runner 配置。
完成条件: 每项提出的问题都引用了代码,并说明实际成本,而不是仅表达风格偏好。

3. Make the lead judgment

3. 作出最终判断

Classify each finding:
  • Act on: a demonstrated architectural problem worth fixing now.
  • Consider: a real concern whose cost or remedy remains uncertain.
  • Noted: a low-priority trade-off or debt marker.
  • Dismissed: incorrect, unsupported, or merely preferential.
Present the explanation first, followed by the critique. Keep an empty critique when the architecture is sound.
Complete when: overlapping findings are merged, disagreements are resolved or exposed, and every retained recommendation has evidence, impact, and an appropriate priority.
对每项发现进行分类:
  • Act on: 已证实存在且值得立即修复的架构问题。
  • Consider: 确实存在的隐患,但其成本或解决方案仍不确定。
  • Noted: 低优先级的 trade-off 或技术债务标记。
  • Dismissed: 不正确、缺乏依据,或仅仅出于个人偏好。
先呈现解释,随后呈现 critique。若架构合理,critique 部分保持为空。
完成条件: 合并重叠的发现,解决或明确呈现分歧,并且每项保留的建议都有证据、影响说明和适当的优先级。