nexus/wiki/concepts/ThreeTierExplanation.md

title, type, tags, last_updated

title	type	tags	last_updated
ThreeTierExplanation	concept		2026-05-02

Definition

Three-Tier Explanation（三层解释法）是代码库分析和 onboarding 输出的一种分层叙事结构，从极高层次到极深层次渐进展开，帮助不同需求的受众快速获取所需信息。

Three Tiers

Tier 1: One-Line Summary（一句话概述）

• Purpose: 快速建立代码库是什么的基线认知
• Length: 1 句话
• Audience: 需要快速判断是否关注此代码库的人

Tier 2: Five-Minute Explanation（五分钟高层解释）

• Purpose: 构建完整的系统工作方式高层理解
• Content:
  • Primary tasks: 代码做什么
  • Primary inputs: 主输入（HTTP请求、CLI参数、消息、文件、函数参数）
  • Primary outputs: 主输出（响应、数据库写入、文件、事件、渲染UI）
  • Key files: 关键文件及其职责
  • Main code paths: 主代码路径（入口 → 编排 → 核心逻辑 → 输出）
• Audience: 需要了解系统如何运作的开发者

Tier 3: Deep Dive（深度代码流分析）

• Purpose: 支撑精确的技术决策和问题定位
• Content:
  • Type: 系统类型（web app/API/monorepo/CLI/library/hybrid）
  • Primary runtimes: 主运行时环境
  • Entry points: 所有入口点及重要性说明
  • Top-level structure: 顶层结构表
  • Key boundaries: 关键边界（展示层/应用层/持久层/跨领域）
  • Responsibilities by file: 文件级职责映射
  • Detailed code flows: 详细代码流步骤
  • Files inspected: 已检查文件清单
• Audience: 需要进行具体实现或调试的开发者

Usage Context

• CodebaseOnboarding 的核心输出格式
• ExecutionTracing 的结果呈现
• 新代码库探索的标准化报告结构

Related Concepts

• CodebaseOnboarding — 代码库 onboarding 方法论
• ExecutionTracing — 执行路径追踪
• MentalModel — 心智模型构建