# Codebase Analyzer

> 对一个软件项目或源码仓库进行全面调研，输出一份结构化的中文调研报告，让对项目不熟悉的人能够同时理解"它做什么"和"它怎么实现"。当用户说"调研这个项目 / 分析这个代码库 / 给我一份项目分析报告 / 我要全面理解这个项目 / 帮我看看这个仓库 / onboarding 一下 / 这个项目的整体架构是什么 / 给我梳理下这个源码"等等，或者把一个不熟悉的代码目录交给你并希望你给出全局认识时，必须使用本 skill。即使用户没有显式说"调研报告"，只要意图是"帮我搞懂一个完整的代码库 / 项目"，就应当触发。但本 skill 仅针对"全局理解 / 架构调研 / onboarding"场景：若用户只是要做 code review、定位某个 bug、评审某处具体实现、做性能或安全诊断，不要触发本 skill。

- Skill: `rollrollroll/codebase-analyzer` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add rollrollroll/codebase-analyzer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rollrollroll/codebase-analyzer/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: RollRollRoll (https://skillmd.com/u/rollrollroll)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/rollrollroll/codebase-analyzer

---


# Codebase Analyzer — 项目调研 Skill

## 你的任务

调研用户指定（或当前工作目录下）的软件项目，产出一份**结构化的中文调研报告**，目标读者是"对项目不熟悉但需要快速建立完整心智模型"的工程师。报告的**详尽程度按下文"输出深度"选档**，不是任何情况都套完整模板。

报告要同时回答两个问题：
1. **它做什么** —— 项目定位、核心功能、用户与价值。
2. **它怎么实现** —— 架构、技术栈、关键路径、运行方式。

## 输出深度（先选档，再调研）

不同诉求需要的报告厚度差别很大，**动手前先判断该用哪一档**，避免"快速 onboarding"被一份巨型报告淹没。**三份输出模板中只读对应那一份**（通用的 investigation-checklist / project-type-checklists 仍按需读取）：

- **快速概览（轻）**：半屏到一屏，一句话定义 + 技术栈 + 目录地图 + 一条核心流程简述。适合"快速看看 / 简单了解 / 大概是啥"。模板：[references/template-quick.md](references/template-quick.md)
- **标准调研（默认）**：建立完整心智模型但不堆砌，9 个主干章节，条件章节无关就一行带过。模板：[references/template-standard.md](references/template-standard.md)
- **深度报告（重）**：严格、完整走全部 10 章 + 附录，一项不省。适合"完整报告 / 详细调研 / 全面分析 / 交付文档"。模板：[references/template-deep.md](references/template-deep.md)

**选档规则**：
- 用户明确要"完整 / 详细 / 全面"报告 → 深度报告。
- 用户说"快速 / 简单 / 大概 / 扫一眼" → 快速概览。
- **没有明确说明时，默认标准调研**——既不敷衍也不过载。
- 拿不准时，先按标准调研产出，并在结尾一句话告诉用户"需要更深可展开为深度报告，需要更轻可只看快速概览"。

> 项目大小与输出深度**正交**：大项目也可以只要快速概览（见下文"大项目策略"）。下文的"工作流程"以**标准调研 / 深度报告**为基准描述；选了快速概览时，只做第 1 步采集 + 按 template-quick 产出即可，第 2~3 步按需精简。

## 核心原则（不要违反）

1. **自顶向下，不要逐文件通读**
   - 先抓大局（README / 入口 / 配置 / 依赖 / 目录），再深入实现。
   - 不要 cat 每一个源文件。读"足够回答问题"的内容即可。
   - **默认跳过这些目录 / 文件**，不计入扫描范围：`.git`、`node_modules`、`.venv` / `venv`、`dist`、`build`、`out`、`target`、`coverage`、`__pycache__`、`.next` / `.nuxt` 等构建产物，以及代码生成目录（`generated/`、`*.pb.go`、`*_pb2.py` 等）。大型 lock / bundle 文件（`package-lock.json`、`yarn.lock`、`*.min.js`）**默认不读**，仅在需要确认依赖版本时按需查看对应条目。

2. **不确定就标注，不要猜；但要分清"不适用"和"未搞清楚"**
   - 凡是没读到、推断不出、需要业务侧确认的内容，写在 "## 未搞清楚的部分 / 假设" 章节里。
   - 不要用合理猜测填补未知，那会污染读者的心智模型。
   - **"不适用" ≠ "未搞清楚"**：一个简单 CLI 没有认证机制，是"不适用（原因：本项目不涉及用户身份）"，而不是"没搞清楚认证在哪"。前者是确定的结论，后者是盲区。把两者混为一谈会误导读者。
   - 条件章节（认证安全 / 可观测性 / 外部系统 / 部署基础设施等）若与本项目无关，**一行写明"不适用（原因）"即可**，不必硬撑出小标题和占位内容。

3. **结论必须有源码证据，可核对**
   - 每个重要结论都要尽量对应到**具体源码路径（含行号）**，例如"这是入口"、"这是核心算法"、"这条路径会落库"后面跟上 `path:line`，让用户能 jump-to-source 验证。
   - **不准凭项目名或 README 描述断言功能**。README 说有的能力，要去源码里找到对应实现再确认；找不到实现就当作"声称但未在源码验证"。
   - 源码里**没有证据**支撑的结论，必须显式写明"不确定 / 未在源码确认"，并放到 "## 未搞清楚的部分 / 假设" 章节，不要含糊带过。

4. **追代表性流程，不追全部**
   - 选 1~2 条最能体现项目核心价值的端到端流程（例如最典型的请求、最核心的 CLI 命令），把它从入口到输出**完整串起来**。这是最有信息密度的章节。
   - 其他次要流程可以一句话带过。

5. **大项目分阶段产出**
   - 如果项目体量大到一次输出报告会丢失全局，**先输出"全局概览 + 目录地图"**，再按模块逐步深入。具体策略见 [references/parallel-strategy.md](references/parallel-strategy.md)。

6. **敏感配置最小读取，报告不得泄露凭据**
   - 默认**不读取真实环境文件或疑似凭据文件的内容**，包括 `.env`、`.env.*`（排除 `.env.example` / `.env.sample`）、`secrets.*`、`credentials.*`、`.npmrc`、`.pypirc`、`.netrc`、`*.key`、`*.pem` 及云厂商凭据文件。也不运行 `env` / `printenv` 等会倾倒当前环境的命令。需要判断是否误提交时，只检查文件名、跟踪状态与忽略规则。
   - 配置调研只读 `.env.example`、`.env.sample`、`config.example.*` 和配置加载代码；即使是示例文件，遇到疑似真实 token、密码、密钥也停止展开并标记为敏感。
   - 报告环境变量时只写**变量名、用途、是否必填和加载位置**，不复制运行环境中的值。配置代码里的公开非敏感默认值可按需说明；凭据类默认值一律写为 `[已脱敏]`，不得原样输出。
   - 该约束同样适用于子 agent 简报、中间进度、代码片段和最终落盘报告。

## 工作流程

### 第 0 步：确认调研对象与输出深度档

先确认要调研的目录路径。如果用户没指定，默认就是当前工作目录。如果当前目录是空的或明显不是代码项目，停下来问用户。

同时按"输出深度"小节**定下用哪一档**（快速概览 / 标准调研 / 深度报告）——这决定第 4 步读哪个模板文件。用户没明说就默认**标准调研**。

### 第 1 步：自顶向下信息采集

按以下顺序快速扫读，不要乱序，也不要跳过：

| 顺序 | 看什么 | 看出来什么 |
|---|---|---|
| ① | 根目录 `ls`、`README*`、`docs/`、`CHANGELOG*` | 项目是什么、面向谁、怎么用 |
| ② | 依赖清单：`package.json` / `pyproject.toml` / `requirements*.txt` / `go.mod` / `pom.xml` / `Cargo.toml` / `build.gradle` / `composer.json` 等 | 语言、框架、关键三方库 |
| ③ | 配置 / 部署：`.env.example` / `.env.sample`、`config.example.*`、配置加载代码、`Dockerfile*`、`docker-compose*`、`Makefile`、`.github/`、`k8s/`、`helm/`、`terraform/` | 变量名与加载来源、部署方式、CI/CD；跳过真实 `.env` 与疑似凭据文件内容 |
| ④ | 程序入口：`main.*`、`index.*`、`app.*`、`cmd/`、`bin/`、`manage.py`、框架约定的入口（如 Spring 的 `@SpringBootApplication`、Next.js 的 `pages/` `app/`） | 启动从哪开始执行 |
| ⑤ | 顶层目录结构 | 模块划分 |
| ⑥ | 数据模型：`models/`、`entities/`、`schema.*`、`migrations/`、ORM 定义 | 核心实体与关系 |
| ⑦ | 对外接口：路由表、controller、API 定义文件（OpenAPI / proto / GraphQL schema） | 暴露的能力 |
| ⑧ | 测试目录、CI 配置 | 工程实践 |

不要把所有文件都 Read 一遍——绝大多数模块**只需要看入口、目录索引、关键类名**就够了，深入读源码只在追端到端流程时进行。

### 第 2 步：识别项目类型并追加专项分析

基于第 1 步采集到的依赖、入口、目录结构（**看证据，不看名字**），判断项目属于哪一类，然后按 [references/project-type-checklists.md](references/project-type-checklists.md) 对应小节追加专项分析。常见类型：

- **CLI 项目**、**Web 服务**、**Library / SDK**、**Agent 项目**、**MCP Server**、**DevTool / Workflow 工具**、**Agent 编程工具插件 / 扩展（Claude Code / Codex）**

要点：

- 一个项目可能同时命中多类（如 "Web 服务 + 运维 CLI"），命中几类就各做一份专项分析，并分别给出判断依据。
- 判不出明确类型时，写明"未匹配到专项类型"，只做通用调研即可，不要硬套。
- 专项分析的每条结论同样要落到源码路径，不确定就标注。

### 第 3 步：选 1~2 条端到端流程并完整追踪

挑最能代表项目核心价值的流程（例如：典型 HTTP 请求处理、最核心 CLI 命令、定时任务的一次执行、消息消费的一条流水）。从**入口**开始，沿着调用链一路走到**最终的输出 / 副作用**（响应、落库、写文件、发消息），记录每一跳：

- 经过哪个文件 / 函数（带路径）
- 关键的转换 / 决策点是什么
- 数据形状如何变化
- 外部依赖在哪一步被调用

这部分是报告里**信息密度最高**的章节，读者通过这一节就能掌握项目的"气脉"。

### 第 4 步：按对应档模板组织输出

**按第 0 步选定的输出深度档，读取并填充对应的模板文件**——三个模板各自独立，不要混用：

- **快速概览** → [references/template-quick.md](references/template-quick.md)：半屏到一屏，一句话定义 + 技术栈 + 目录地图 + 一条核心流程。
- **标准调研（默认）** → [references/template-standard.md](references/template-standard.md)：9 个主干章节，条件章节无关就一行带过，不为凑满硬撑。
- **深度报告** → [references/template-deep.md](references/template-deep.md)：严格走完整 10 章 + 附录，每章都要保留标题，没内容就写"未搞清楚 / 不适用（原因）"，不省略。

> 三档都遵循同一套硬约束：结论给源码路径、不凭名字猜、区分"不适用 / 未搞清楚"。区别只在**覆盖范围与详尽度**。大项目分阶段时（见下文"大项目策略"），阶段 1 的"全局概览 + 目录地图"是临时产物，不受任何模板的完整性约束。

调研每个章节时的具体追问点见 [references/investigation-checklist.md](references/investigation-checklist.md)。第 2 步识别出的项目类型专项分析，写入模板里的"项目类型专项分析"章节（快速概览档可省略此章）。

> **深度档 + 大项目提速**：深度报告档调研大项目时，可把描述性章节（第 1/2/3/4/6/7/8 章）拆给子 agent 并行起草、气脉章节（一页纸概览与第 5/9/10 章）主 agent 亲自写，并分阶段流式输出，缩短撰写墙钟、给出进度感。详见 [references/parallel-strategy.md](references/parallel-strategy.md) 的「按报告章节并行起草」。

### 第 5 步：自检

输出前按"通用项 + 所选档专项"过一遍。**只跑你这一档的清单**，不要拿深度档的标准去要求快速概览，否则会把概览硬扩写成大报告。

**通用项（三档都要）**：
- [ ] 输出深度选档对不对？（默认标准调研；用户要"完整"才上深度报告，要"快速"就给概览）
- [ ] 关键论断是不是都附上了文件路径 / 行号？源码里没有证据的结论，是否都标了"不确定"？没凭名字 / README 猜？
- [ ] 是否跳过了真实 `.env` / 疑似凭据文件内容？报告与中间产物中是否只有变量名、用途、是否必填和来源，没有真实值、token、密码、密钥或敏感默认值？
- [ ] 全文是不是中文？
- [ ] 输出前问过目的地了吗？（终端 / 文件 / 两者）选"文件 / 两者"时处理了同名覆盖吗？

**🟢 快速概览档**：
- [ ] 是否控制在半屏到一屏？有没有不小心扩写成标准报告？
- [ ] 一句话定义 + 技术栈 + 精简目录地图 + **一条核心流程的简述**齐了吗？（注意：是简述，不需要逐跳；**不需要**专项分析和综合评价）

**🟡 标准调研档**：
- [ ] 一页纸概览能让读者扫一眼抓住大局吗？
- [ ] 报告开头（一页纸概览前）放了「## 目录」章节目录吗？目录条目与各 ## 章节真实标题一一对应、可点击跳转？（这是 TOC，与第 4 章的"目录地图 / 项目目录树"不是一回事）
- [ ] 目录地图是"标注重点"而非罗列全部？
- [ ] 有没有 1~2 条端到端流程，每一跳给了文件路径？
- [ ] 识别了项目类型并做了专项分析？（判不出写"未匹配"）综合评价（含项目亮点）给了吗？
- [ ] 不确定的点是否单列在 "未搞清楚" 章节，且与"不适用"区分开？

**🔴 深度报告档**：
- [ ] 模板全部章节都在、没有省略标题？空章节写了"未搞清楚 / 不适用（原因）"？
- [ ] 标准档的全部检查项是否也都满足？（深度档是标准档的超集）
- [ ] 配置/环境变量、可观测性、安全等深度档独有章节是否完整填写或标注不适用？
- [ ] 综合评价章（第 9 章）是否给出**项目亮点**，且每条落到 `path:line`（不是泛泛"架构清晰"）？
- [ ] 若命中 **DevTool / Workflow 工具**：是否按「意图 → 入口 → 流程」**穷举了工作场景全景**？
- [ ] 若命中 **Agent 编程工具插件 / 扩展**：是否区分 Claude Code / Codex 信号、**逐条画像 + 画了整体装配图**？条目多时是否用了并行（或注明未启用）？
- [ ] 若启用了**按报告章节并行起草**：是否做了逐章聚合 / 统一术语 / **跨章一致性核对**？一页纸概览是否先出、章节是否边就绪边推？无子 agent 工具或项目偏小时是否退化为串行并注明"未启用章节并行"？

### 第 6 步：询问输出目的地

报告在对话中产出、且第 5 步自检通过后，**先不要把全文贴出来**，而是问用户希望报告输出到哪里。默认**不自动写盘**——按用户选择决定。

- **询问方式**：当前环境提供交互式选择工具时使用它（如 Claude Code 的 AskUserQuestion 或 Codex 当前会话暴露的用户输入能力）；不可用就用纯文本询问，让用户回一个。
  - **终端**：把报告全文输出在对话里，不写文件。
  - **文件**：写入文件，对话里只回 `✅ 已写入 <路径>` + 报告的**一页纸概览**，不刷全文。
  - **两者**：报告全文输出在对话里，**同时**写入文件。
- **一页纸概览的来源**（选"文件"时终端要留的那段）：标准 / 深度档直接摘报告里的 `## 一页纸概览` 章节；快速概览档没有该章节，摘它的"一句话定义 + 核心价值"两三行。
- **选"文件"或"两者"时的写盘细节**：把刚产出的那一档报告**原文**（中文、Markdown）写入文件：
  - **默认位置**：被调研项目的根目录。
  - **默认文件名**：`<项目名>-调研报告-<YYYYMMDD>.md`——`<项目名>` 取被调研目录名，`<YYYYMMDD>` 取当天日期，例如 `codebase-analyzer-调研报告-20260603.md`。
  - 用户若指定了自己的路径 / 文件名，以用户的为准。
  - 写盘前若发现**同名文件已存在**，先提示用户确认覆盖还是改名，不要静默覆盖。
  - 写入内容就是对话里那份报告，不要为落盘重新精简或扩写。
- **选完不再二次追问**：选"终端"就只输出在对话里、不存盘；想存又想终端看全文的，一开始就选"两者"。
- **大项目分阶段产出时**：等全部模块 / 章节聚合、形成完整报告后再问目的地，落定的是最终完整版而非阶段 1 的过渡概览；流式过程中只向终端推进度 + 概要、过程成稿不逐份贴终端（见 [references/parallel-strategy.md](references/parallel-strategy.md) 的「分阶段输出节奏」）。

## 大项目策略（项目较大时启用）

判断"大"的粗略指标：源文件 > 500、顶层模块 > 10、或一次性写完报告会超过单次输出能力。

> **大小与输出深度是两个独立维度**：项目大不等于用户想要详细报告。若用户对一个大项目只要"快速概览"，就直接产出一页纸概览 + 目录地图 + 一条核心流程即可，**不必启动下面的分阶段并行深入**。下述分阶段流程主要服务于**标准调研 / 深度报告**档。

满足任一条件、且用户需要标准或深度档时：

1. **先只输出"全局概览 + 目录地图"** 给用户看，告诉用户："项目较大，我先给出全局概览和目录地图，然后按模块逐个深入，你可以在任何时候打断或调整顺序。"
2. **按模块并行调研**：若当前环境提供子 agent 工具（Claude Code 可用 `Agent` + `subagent_type=Explore`；Codex 可用只读 `explorer` 或等价 agent thread），把"调研模块 X"作为独立任务派出去，多个模块并行。详见 [references/parallel-strategy.md](references/parallel-strategy.md)。**若该工具在当前环境不可用，则退化为顺序调研，并在报告里说明"未启用并行"。**
3. **聚合**：等子 agent 返回后，由你统一按报告模板拼装，并消除模块间冲突 / 重复 / 不一致。拼装的详尽程度**按选定的输出深度档**决定（深度报告写满全部章节，标准调研抓主干），阶段 1 的概览只是过渡。深度档还可在此基础上**按报告章节并行起草**（描述性章节派子 agent、气脉章节主 agent 自己写），详见 [references/parallel-strategy.md](references/parallel-strategy.md) 的「按报告章节并行起草」。

## 输出格式约束

- **整篇报告必须使用中文**（包括代码片段中的注释，原文代码保持不变）。
- 输出报告时章节顺序**遵循所选档的模板**（[template-quick](references/template-quick.md) / [template-standard](references/template-standard.md) / [template-deep](references/template-deep.md)）：深度报告写满全部章节，标准调研覆盖主干，快速概览半屏内（详见"输出深度"）。大项目阶段 1 的临时概览不受模板约束（见上文第 4 步）。
- 文件路径用反引号包裹，例如 `src/server/router.ts:42`。
- 涉及代码片段使用带语言标识的 fenced code block。
- 结构化对照数据（模块职责、环境变量、对外接口、外部系统等）**用表格**——这类多列、需对齐的数据正是表格的用武之地。正文叙述、长说明、连贯逻辑**不要**塞进表格，用列表或段落更易读。
- 环境变量表只列变量名、用途、是否必填和加载位置；不要为填表去读取或复制真实值。
- 重点用 **粗体**，避免大段斜体。

## 反例（不要这样做）

❌ "这个项目大概是一个 web 应用，应该用了 Express。" —— 没看依赖文件就猜。
❌ 把每个文件都 Read 一遍后再开始写报告 —— 浪费上下文，且大概率丢失全局。
❌ "认证相关的逻辑在 auth 模块里。" —— 没给路径，读者无法核对。
❌ 端到端流程只写"请求进来，处理，返回"——没追到具体文件 / 函数。
❌ 直接输出整篇巨型报告，没有先给概览。
❌ 用英文输出，或中英混杂。
❌ 为了补全配置章节读取真实 `.env` / 私钥 / 凭据文件，或把 token、密码、密钥及敏感默认值写进报告。
❌ 没问过目的地就把整篇报告刷满终端，或擅自把报告写进项目目录。本 skill 要求**产出后、输出前先问目的地**（终端 / 文件 / 两者），再按用户选择输出。

## 相关参考

报告模板（按输出深度档三选一）：
- [references/template-quick.md](references/template-quick.md) —— 快速概览档骨架（半屏，1 分钟看懂）
- [references/template-standard.md](references/template-standard.md) —— 标准调研档骨架（默认，9 主干章节）
- [references/template-deep.md](references/template-deep.md) —— 深度报告档骨架（完整 10 章 + 附录）

通用清单：
- [references/investigation-checklist.md](references/investigation-checklist.md) —— 每个章节的具体追问点
- [references/project-type-checklists.md](references/project-type-checklists.md) —— 按项目类型（CLI / Web / SDK / Agent / MCP / DevTool / Claude Code / Codex 扩展）的专项分析清单
- [references/parallel-strategy.md](references/parallel-strategy.md) —— 大项目分阶段 / 并行调研策略（含"按扩展条目并行""按报告章节并行起草"两个变体）