老代码库新人上手套件 — 10 年祖传代码不再劝退

这个 pack 给谁用

你刚入职。代码库 8 到 12 年了，几十万行，三个半死不活的微服务，命名约定相互冲突，唯一懂全栈的那个人两个月前走了。没有 ARCHITECTURE.md。README 还在引用 Python 2。Wiki 在某个谁也找不着 URL 的 Confluence 上。

这种情境下，一套精心编排的 AI 工具链才真正解决问题 — 不是替你读代码，而是给你一张能用的地图，让入职第一周从「绝望」变成「真正出活」。

这个 pack 对顺序有强烈观点。链条上每个工具产出的工件，是下一个工具的输入。乱装一通你只会得到噪音；按顺序装完，周五之前你就能在脑中跑出整个系统的可工作模型。

推荐安装顺序

1. Codebase Memory MCP — 先建索引。持久化的代码知识图谱，支持 MCP 的 agent（Claude Code / Cursor / Windsurf）可以直接查。第一天就跑起来，后面所有问题都是查真实索引，而不是 grep 猜。
2. Claude Code Agent: Codebase Explorer — 宏观地图。扫一遍仓库，输出模块/服务清单：入口在哪、谁调用谁、测试目录长什么样。
3. Claude Code Agent: Codebase Pattern Finder — 重复模式。挖出重复的写法、自定义的封装、老员工在标准库之上盖的「内部方言」。这里你能学到团队的本地黑话。
4. ast-index — 快速结构化搜索。基于 Tree-sitter 的 CLI，做 AST 级查询（「找出所有以 Y 形参调用 X 的地方」）。要的是结构而不是文本时用它替代 ripgrep。
5. CodeGraphContext — 调用图变 MCP。把函数和类的关系建成可查图。agent 能回答谁调了它、改这个签名会断什么，用的是 edge 不是凭感觉。
6. Graphify — 仓库级依赖图。在调用图之上叠加模块到模块、文件到文件的 edge。那张你巴不得五年前有人画过的架构图，五分钟生成出来。
7. Claude Code Agent: Legacy Modernizer — 模块级摘要。读每个模块（配合前面那两张图），写一段话：做什么的、谁在调它、依赖谁、哪里看着不对。存成 docs/modules/*.md，全队会感谢你。
8. Claude Code Agent: Technical Debt Manager — 死代码和债务。交叉调用图 + git blame + 测试覆盖率，标出不可达代码、关键路径没测试、从 2019 年起没人动过的模块。输出是待 triage 清单，不是 delete 脚本。
9. Claude Code CLAUDE.md — Best Practices Template — 写下团队一直没有的那份文件。用前面的清单 + 摘要 + 债务表，起草一份 CLAUDE.md（外加一份内容相同的 AGENTS.md 给非 Claude 的 agent），告诉下一个新人「雷在哪儿」。
10. Claude Code Agent: Architect Reviewer — 你的第一个 PR。真开 PR 前，先让 architect-reviewer agent 跑一遍 diff。它会抓出你不知道存在的约定、你不小心穿过的层、你重命名时打破的公共 API。

这条链怎么产出价值

Codebase Memory MCP  ──┐
                       ├── 共享索引
ast-index ─────────────┤
                       │
Codebase Explorer ─────┤───►  模块/服务清单
Pattern Finder ────────┤───►  团队专属写法
                       │
CodeGraphContext ──────┤───►  调用 edge
Graphify ──────────────┤───►  模块 edge
                       │
Legacy Modernizer ─────┴───►  每模块摘要 (docs/modules/*.md)
Technical Debt Manager ────►  triage 清单 (docs/debt.md)
                            │
                            ▼
        CLAUDE.md  +  AGENTS.md  ◄── 你来写
                            │
                            ▼
         第一个 PR + Architect Reviewer 把关

关键洞察：第 1-6 步补齐结构化上下文 — 团队多年缺的就是这块。第 7-8 步把上下文变成可读散文 + triage 表。第 9 步是真正会被后面工程师（和后面 agent）依赖的写作产出。第 10 步保证你的第一个 PR 不丢人。

你会遇到的取舍

• 全量索引 vs 增量索引 — Codebase Memory MCP 和 CodeGraphContext 都需要第一次全量索引。百万行仓库首次跑 30-90 分钟很正常。挂夜里跑，剩下一周都是亚秒级查询。
• MCP server vs CLI — ast-index 本身是 CLI 可独立用；CodeGraphContext 和 Codebase Memory MCP 在 MCP-aware agent 里发挥最大价值。卡在不支持 MCP 的工具上就走 CLI；agent 支持 MCP 就走 MCP。
• 自动生成文档 vs 手写文档 — Legacy Modernizer 出的模块摘要是初稿不是定稿。当成可编辑的起点，别当成权威。
• 死代码：标记 vs 删除 — 永远不要让 agent 在 legacy 仓库里删死代码。静态分析会漏 cron 调度的调用方、动态派发和反射。先标，找老员工 review，再人工删。
• CLAUDE.md vs AGENTS.md — Claude Code 读 CLAUDE.md，通用 agent 读 AGENTS.md。两份文件内容相同两个文件名（软链或单源生成），多工具团队就不会 fork。

常见踩坑

• 跳过索引步骤 — 后面每个工具都会退化成 grep 质量的输出。别跳。
• 100% 相信调用图 — 反射、依赖注入、YAML 配的路由对静态分析全部不可见。重构热路径前先用 runtime trace 验证。
• 只用 agent 输出写 CLAUDE.md — 定稿前花 30 分钟找一个老员工聊。他会告诉你三个图永远看不见的雷。
• 没搞懂就先现代化 — Legacy Modernizer 的名字有挑衅性。先用它做摘要，长远再考虑改造。入职第一周就重写代码 = 必被 revert 的姿势。
• 第一个 PR 跳过 Architect Reviewer — 第一印象很重要。10 分钟跑一遍 reviewer 抓出的约定问题，能省你三天 code-review 撕逼。