Codebase Analyzer

Codebase Analyzer — 项目调研 Skill

你的任务

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

报告要同时回答两个问题：

1. 它做什么 —— 项目定位、核心功能、用户与价值。
2. 它怎么实现 —— 架构、技术栈、关键路径、运行方式。

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

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

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

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 步：自顶向下信息采集

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

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

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

基于第 1 步采集到的依赖、入口、目录结构（看证据，不看名字），判断项目属于哪一类，然后按 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-standard.md：9 个主干章节，条件章节无关就一行带过，不为凑满硬撑。
• 深度报告 → references/template-deep.md：严格走完整 10 章 + 附录，每章都要保留标题，没内容就写"未搞清楚 / 不适用（原因）"，不省略。

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

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

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

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

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

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

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

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

输出格式约束

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

反例（不要这样做）

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

相关参考

报告模板（按输出深度档三选一）：

• references/template-quick.md —— 快速概览档骨架（半屏，1 分钟看懂）
• references/template-standard.md —— 标准调研档骨架（默认，9 主干章节）
• references/template-deep.md —— 深度报告档骨架（完整 10 章 + 附录）

通用清单：

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