deep-code-analysis

Deep Code Analysis

核心原则：先测量，再理解，最后才动手。

不要打开文件从头读到尾。先了解全貌和规模，再有针对性地深入。

工作流程

1. 明确范围

确认三件事，用户没说清楚就主动问：

• 分析对象：整个项目？某个模块？某条业务流程？
• 分析目的：建立全局认知？理解功能实现？追踪数据流？
• 关注重点：业务逻辑？数据流转？架构设计？

宁可先聚焦一个模块分析透，再扩展，也不要一开始铺太广。

2. 测量

在读代码之前，先用 Glob 和 Grep 了解目标的规模和结构：文件数量、代码量、目录组织、技术栈。不要在这一步阅读具体实现。

根据规模选择策略：

规模	策略
<20 文件 / <50KB	按依赖顺序逐文件分析
20-100 文件 / 50-500KB	先建结构图，再按模块深入
>100 文件 / >500KB	子 agent 并行分析各模块，主 agent 综合

3. 建立结构认知

从外到内理解骨架：

1. 入口点 — 请求/数据从哪里进入系统
2. 模块边界 — 有哪些模块，各自职责是什么
3. 依赖关系 — 模块间如何调用，谁依赖谁
4. 关键抽象 — 核心接口、基类、类型定义

目标是画出一张"地图"，能回答"大致由哪些部分组成，什么关系"。

4. 追踪逻辑

带着目的沿逻辑链追踪，不要逐行顺序阅读。根据分析目的选择方式：

• 业务逻辑：从入口沿核心路径追踪，重点关注分支条件（业务规则藏在 if/switch 里）
• 数据流：数据从哪来、经过什么转换、到哪去
• 调用链：从目标函数向上追踪调用方、向下追踪依赖

5. 识别设计意图

不仅说明"做了什么"，还要理解"为什么这么做"：架构取舍、隐含假设、历史演进（参考 git log）。

6. 呈现结果

在对话中直接呈现，按以下结构组织：

1. 概述 — 一段话说清楚是什么、解决什么问题
2. 结构 — 模块组成和依赖关系
3. 核心逻辑 — 关键流程的完整追踪，引用 file_path:line_number
4. 设计决策 — 为什么这么做
5. 关键洞察 — 不明显的行为、隐含假设、耦合关系

只有用户明确要求时才导出为文件。

注意事项

• 不要跳过测量。没有测量就直接读代码，容易走偏。
• 先 80% 再 100%。先建立结构认知，再针对关键路径深入。
• 引用要具体。auth.ts:42 比"认证模块里"有用。
• 区分事实和推测。确定的逻辑和推断的意图分开表述。
• 只做理解。不提供重构建议、不做 review、不写代码。