codebase-explorer

Codebase Explorer

用于理解陌生代码的实地手册。生成可导航的系统行为图，而非文件内容摘要。

核心原则

文件树用于存储，而非理解。目录结构反映了团队如何组织各类产物。逻辑追踪揭示代码为何存在以及它的作用。当两者冲突时，相信追踪结果。

理解不是“我读过代码”。理解是“我能告诉你 X 发生变化时会怎样”。

你不可能理解整个系统。应构建一组纵向切片——从输入到输出的完整路径，让你能够预测有限区域内的行为。

---

适用对象

这项技能对不同受众有不同价值。应根据用户的角色调整深度和术语。

受众	他们需要什么	重点
接手代码的开发者	从哪里开始，哪些内容可以安全修改	纵向切片、共享命运组、隐式契约
技术负责人 / 架构师	风险图谱、耦合分析、重构目标	异味、共享命运组、底层约束
工程经理	变更成本估算、团队协作需求	风险概况、共享命运组、未知项
产品经理	哪些内容难以修改、哪些容易修改，瓶颈在哪里	风险概况（以业务术语描述）、底层约束
安全审计员	攻击面、数据流、信任边界	I/O 边界图、隐式契约、数据沿袭
新员工入职培训	系统工作方式的心智模型	流程 / 架构图、整体氛围、纵向切片
顾问 / 承包商	变更前快速熟悉系统	快速评估模板、架构类型分类
尽职调查审查人员	代码质量信号、技术债清单	异味、活跃度热图、未知项

当用户的角色不明确时，默认采用开发者视角，但应包含风险概况和未知项部分——这些内容对所有人都有用。

---

这项技能最能发挥作用的场景

在以下情况下，这项技能最能发挥价值：

• 继承的代码库缺少或没有文档
• 多服务架构中，没有任何一个人了解整个系统
• 重写前评估——在决定替换什么之前，先了解现有内容
• 对陌生系统进行事件响应——快速识别影响范围
• 开源贡献——提交 PR 前了解项目
• 收购后评估——评估代码质量和技术债
• 合规 / 安全审计——绘制数据流和信任边界
• 入职培训——为新团队成员提供可导航的心智模型

---

工作流

探索分为四个阶段。完成当前阶段后再进入下一阶段。

阶段 0：架构类型检测（前 2 分钟）

在阅读任何业务逻辑之前，先确定代码库的架构类型。架构类型决定应采用哪种垂直切片策略、优先关注哪些异味，以及主要输出产物应是什么。

检测方法：检查根目录中的特征文件。

特征文件	架构类型
template.yaml / serverless.yml / statemachine/ / stepfunctions/	无服务器管道
Dockerfile + 路由处理程序（app.py、server.js、main.go）	后端 API
包含 React/Vue/Svelte/Next 且有 src/components/ 的 package.json	前端应用程序
dags/ / pipeline/ / airflow.cfg / dbt_project.yml	数据管道
具有库结构、没有主入口点的 setup.py / pyproject.toml	库 / SDK
没有 Lambda 代码的 main.tf / *.tf / cdk.json / CloudFormation	基础设施即代码
CLI 入口点（__main__.py、bin/、作为主要接口的 Makefile）	CLI 工具
train.py / model/ / notebooks + 含 ML 库的 requirements.txt	ML 系统

如果多个特征匹配，请根据代码量最多的部分选择主要架构类型。注明次要架构类型。

输出：架构类型分类及置信度。此结果将作为所有后续阶段的依据。

---

阶段 1：概览

在阅读业务逻辑之前，回答有关系统形态的四个问题。每个问题都要生成指定的输出产物。

Q1：污点在哪里？

绘制 I/O 边界图，标出系统与外部世界交互的位置。

1. 识别入口点（主函数、路由处理程序、事件监听器、导出的 API）
2. 对每个入口点，找出第一个外部调用
3. 标记函数：○ 纯函数（无 I/O）· ● 非纯函数（触及外部世界）· ◐ 混合
4. 绘制边界：标出数据从哪里进入、从哪里离开

信号：fetch/axios/http → 网络 · fs/readFile → 文件系统 · query/execute/find/save → 数据库 · Date.now()/Math.random() → 非确定性 · process.env/config.get → 环境耦合

输出：I/O 边界图

Q2：底层约束是什么？

识别硬性限制——内存、负载大小、超时、速率限制——这些限制决定了代码实际能做到什么。

1. 检查依赖清单中的运行时约束
2. 查找配置文件并记录限制：maxPayloadSize、timeout、poolSize、maxRetries
3. 对于 Web 应用：测量初始负载大小和请求数量
4. 搜索内存处理模式：流、分页、游标、分块——缺少这些是异味

信号：硬编码的整数字超时（30000、60000）· 列表端点缺少分页 · 同步读取用户提供的路径 · 无限制地累积数组

输出：约束清单及合规性说明

Q3：隐式契约有哪些？

找出魔法值——未命名却承载业务语义的字面量。

1. 搜索条件语句中的字符串字面量：if (x === "some_string")
2. 搜索除 -1、0、1、2 以外的数字字面量
3. 对每个值进行判断：如果数据的_含义_改变，这会不会出问题？
4. 标记那些假定数据库或外部系统中存在特定值的字面量

区分：配置值（端口、批次大小）是调优参数，不是魔法值。魔法值承载的是_语义_：状态码、类型判别符、通过字符串匹配的业务逻辑。

输出：脆弱性清单

Q4：注意力流向何处？

使用 Git 历史映射组织记忆。在投入详细分析之前，先运行一条探测命令。

步骤 1 — 探测：先运行 git log --oneline -1。如果失败（孤儿分支、没有提交），则跳到备用信号。

步骤 2a — 如果存在历史记录：

1. git log --oneline -100 — 近期活动主题
2. git log --format='%H' --since='6 months ago' | wc -l — 活跃度
3. 对关键文件运行：git log --oneline -10 <file> — 变更新近程度
4. 找出 12 个月以上没有提交记录的文件

信号：3 个月内有 50 次以上提交 → 热点区域 · 2 年以上没有变化 → 冻结 · 近期集中出现“fix”/“hotfix”/“revert” → 不稳定 · 单一作者维护的文件 → 知识孤岛

步骤 2b — 如果不存在历史记录（孤儿分支、新仓库、提取出的代码）：

1. 检查 git status — 已暂存与未跟踪文件可揭示开发意图
2. 检查 git remote -v — 是否存在远程仓库可揭示部署成熟度
3. 检查 git branch -a — 孤儿分支或缺少 main 表示尚未进行首次提交
4. 查看暂存区中的已删除文件（AD 前缀）— 可揭示已被替换的先前架构
5. 使用 ls -lt 检查关键目录中文件的修改时间

输出：活动热力图（基于 Git 历史）或成熟度评估（基于备用信号）。说明使用了哪种信号来源。

---

阶段 2：垂直切片（价值线索）

不要全面检查整个系统。从系统一端到另一端，追踪一个可观察的值。一个完整的垂直切片，胜过对所有内容进行浅尝辄止的调查。

切片策略取决于阶段 0 中检测到的项目类型。

---

策略 A：前端应用 — 追踪可见值

步骤 1 — 选择一个值：选择具体且可见的内容。“绿色标记。”“页眉中的数字 63。”

步骤 2 — 向上游追踪（渲染 → 逻辑）：找到生成该值的代码。你要找的是 渲染位置。

步骤 3 — 追踪数据（逻辑 → 状态）：沿着赋值反向追踪。你要找的是 决策点。

步骤 4 — 追踪来源（状态 → 输入）：找到数据的来源 — API、数据库、用户输入。你要找的是 边界。

步骤 5 — 记录：入口点、决策点、渲染位置，以及沿途的非纯调用。

---

策略 B：管道 — 追踪记录经过各个阶段

管道没有“渲染位置”。数据在流动过程中会不断转换。自然的切片方式是：从输入到最终输出，追踪一个实体。

步骤 1 — 选择一个实体：管道处理的具体数据对象。“一篇 arXiv 论文。”“一笔客户订单。”

步骤 2 — 向前追踪（输入 → 输出）：在每个阶段，回答以下问题：

• 此阶段读取哪些字段？
• 此阶段添加、修改或移除哪些字段？
• 会进行哪些外部调用？
• 结果会落在哪个存储位置？
• 与下一阶段之间存在什么隐式约定？

步骤 3 — 映射架构演变：实体的结构在每个阶段如何变化？这才是管道的真实架构。

步骤 4 — 确定阶段间约定：对于每次交接：

• 序列化格式（JSON、JSONL、Parquet）
• 存储位置约定（硬编码还是通过配置指定）
• 下一阶段假定存在的字段
• 是否在边界处进行校验

步骤 5 — 记录：生成一份数据血缘图：阶段 → 转换 → 输出位置 → 下一阶段。在每个边界标明约定类型。

这是管道代码库的主要产物。

---

策略 C：后端 API — 追踪请求

步骤 1 — 选择一个请求：选择一个会经过多个层级的具体端点。

步骤 2 — 向内追踪：路由 → 中间件 → 处理程序 → 服务 → 持久化。

步骤 3 — 追踪响应：数据如何整理后返回？错误在哪里捕获？

步骤 4 — 记录：路由 → 中间件链 → 处理程序 → 服务调用 → 数据访问 → 响应整理。

---

策略 D：库 / SDK——追踪公共 API

步骤 1 — 选择一个导出的函数：使用最多的公共 API（查看 README 或测试）。

步骤 2 — 向内追踪：公共接口 → 内部模块 → 核心逻辑。

步骤 3 — 梳理抽象层：库在哪些地方隐藏了复杂性？

步骤 4 — 记录：公共 API → 内部调度 → 核心逻辑 → 边缘情况处理。

---

策略 E：基础设施即代码——追踪资源依赖关系

步骤 1 — 选择一个核心资源：其他资源最依赖的资源。

步骤 2 — 追踪依赖它的资源：如果它发生变化，哪些内容会出问题？追踪 Ref、!GetAtt、depends_on。

步骤 3 — 确定影响范围：哪些内容必须一起部署？

步骤 4 — 记录：资源 → 依赖它的资源 → 影响范围 → 部署顺序。

---

通用指导

重复此过程，分析 3–5 个切片。通常这些切片足以揭示系统的真实架构。

有关高级技巧（处理追踪汇聚、识别死代码），请参阅 references/advanced-techniques.md。

---

第 3 阶段：异味检测

扫描架构异味——表明存在结构性问题的模式。优先关注与已识别架构类型相符的异味。

请阅读 references/smell-catalog.md，了解完整目录、信号、风险和验证流程。

通用异味（无论架构类型如何都应检查）：

异味	信号	风险
隐藏的 Schema	条件语句中按字符串匹配值	数据迁移时容易出错
静默溢出	未设置大小限制的无界迭代	规模扩展失败
上帝对象	1000+ 行的文件、包含 20+ 个方法的类	理解能力崩溃
孤立错误	空的 catch 块、记录日志后忽略	静默失败
定时炸弹	硬编码年份、固定日期比较	可预见的未来故障

流水线特有异味（针对数据流水线 / 无服务器流水线优先检查）：

异味	信号	风险
漂移的重复项	同一配置值出现在多个阶段	静默不一致
隐式阶段间契约	在边界处未进行 Schema 验证便访问 Dict	上游变更时静默失效
以路径约定作为 Schema	每个阶段都硬编码存储路径	重命名需要查找所有阶段
未经验证的组装	最终阶段组装 N 个输入，却未检查其完整性	不完整的输出被当作完整结果发布
共享实用工具单点故障	一个函数被 50% 以上的阶段导入	单个缺陷导致整个流水线故障

---

第 4 阶段：风险概况与未知项

这是让探索结果变得可执行的阶段。综合发现，转化为读者可以据此做出的决策。

风险概况——具体说明，避免含糊：

• 不要说“复杂”，而要说：“更改 User 模型需要迁移 + API 更新 + 前端更新。”
• 不要说“有风险”，而要说：“此函数有 8 个调用方，且没有测试。这里的缺陷会导致所有论文的评分出错。”

未知项——明确标出尚未探索的内容及其原因。未说明的假设会变成错误认知。

验证提示——针对每个高风险区域，记录优先测试的内容。验证流程请参阅 references/advanced-techniques.md。

---

输出文档

请阅读 references/documentation-templates.md 获取完整模板。根据架构类型和受众选择模板。

选择合适的模板

情况	模板
全面探索，任意架构类型	全面探索报告
全面探索，管道架构类型	管道探索报告
时间有限或范围较窄	快速评估
追踪单个值	垂直切片记录
管道数据流	数据血缘图
针对性健康检查	异味报告
面向非技术利益相关者的简报	利益相关者简报

输出原则

绘制地图，而非罗列清单。 按共同命运对代码分组——会一起故障、一起变更，或依赖同一外部资源的组件。

说明决策，而非描述情况。 每个部分都应帮助读者做出决策：去哪里查看、要改什么、要避免什么、需要与谁协调。

使用适合受众的语言。 面向技术受众时，使用文件路径和函数名称。面向项目经理和管理者时，将内容转化为业务影响：“这个组件很脆弱” → “修改评分算法需要更新两个未关联的文件——如果有人更新其中一个，却忘了另一个，电子报的质量就会在不知不觉中下降。”

---

快速参考

阶段 0：架构类型 → 策略映射

架构类型	切片策略	主要产物
前端应用	A：追踪可见值	渲染站点追踪
数据／无服务器管道	B：追踪记录经过各个阶段	数据血缘图
后端 API	C：追踪请求	请求生命周期追踪
库／SDK	D：追踪公共 API	抽象层映射
基础设施即代码	E：追踪资源依赖关系	影响范围图
CLI 工具	D（调整后）：追踪命令	命令执行追踪
ML 系统	B（调整后）：追踪训练数据	数据与模型血缘图

定位检查清单

问题	输出
这是什么？（阶段 0）	架构类型分类
脏东西在哪里？	I/O 边界图
底层基础是什么？	约束清单
有哪些隐式契约？	脆弱性清单
注意力流向哪里？	活动热力图或成熟度评估

价值追踪步骤（按架构类型）

前端（A）：选择值 → 渲染站点 → 决策点 → 输入边界 → 记录

管道（B）：选择实体 → 追踪其经过的阶段 → 映射架构演变 → 识别契约 → 数据血缘图

后端 API（C）：选择请求 → 向内追踪 → 追踪响应 → 记录

库（D）：选择公共 API → 向内追踪 → 映射抽象层 → 记录

IaC（E）：选择资源 → 追踪依赖项 → 确定影响范围 → 记录