0 token 就能画出代码库结构图？这个 AST 神器让我直接省出一杯咖啡钱

每次让 Claude Code 帮我熟悉一个陌生 repo,它都要先把整个目录读一遍才能告诉我「这个项目是干啥的、模块怎么分」。看着 token 一路狂烧,我心里就在滴血——直到我刷到 darthmolen 的 codebase-mapper 这个 Skill,才反应过来:原来代码库的架构图根本不需要 LLM 自己读代码,用 AST 静态解析 就行,AI 只负责「消化总结」,而「扫描」这件事直接交给脚本。

它到底做了啥

简单说,这是一款专门给 CLAUDE.md 用的「代码库结构生成器」。它支持 Python / C# / TypeScript 三大主流语言,内部跑的是 AST 解析脚本(纯 Python 脚本,不消耗 AI token),自动抽出命名空间、类、方法、继承关系、依赖导入,最后把一份精炼的架构摘要塞回 CLAUDE.md 的标记区间。

四个阶段也很直白:

• DETECT — 自动识别项目语言和源码根目录
• PARSE — 调用对应语言的 AST mapper 脚本生成结构图
• MERGE — 把结构图用 <!-- CODEBASE-MAP-START --> / <!-- CODEBASE-MAP-END --> 标记插入到 CLAUDE.md,不覆盖 你手写的其他内容
• REPORT — 打印摘要和 token 计数

为什么我觉得它值得装

之前我用过的几个「文档生成器」类 Skill,基本都靠 LLM 读源码再总结,项目一大就慢、要不就乱。而这个 Skill 的关键差异点是 「deterministic + 0 AI token」:

• 同样的代码 → 永远生成同样的输出,可版本化、可回滚
• 扫描阶段 不消耗 AI token,只在 MERGE 之后让 AI 把结构图写进文档时才花 token
• 用 marker 划定区间,只动它管的那一段,不会误删你项目说明里写的「历史背景」「部署注意事项」

我自己把它装进一个 80+ Python 文件的 FastAPI 项目试了下:扫描大概 5 秒,生成的架构图清清楚楚列出了每个 router、service、model,后面再让 Claude Code 改代码时,它第一句就不再问「这个项目是怎么组织的」 了——直接开工,效率肉眼可见。

适用场景

• 接手新项目、需要快速建立 mental model
• 维护大型 monorepo,定期刷新 CLAUDE.md 让 AI 助手不迷路
• Code Review 之前,先看一眼结构、定位改动模块
• 团队新人 Onboarding,直接丢一份结构化文档过去

怎么装

git clone https://github.com/darthmolen/ai-plugins-and-skills
mkdir -p ~/.claude/skills
cp -r ai-plugins-and-skills/skills/codebase-mapper ~/.claude/skills/

然后在 Claude Code 里直接说「帮我生成这个项目的架构图」,它就会自动跑起来。

老实说,这种「让 AI 做它擅长的、把机械活交给脚本」的 Skill 设计思路,我觉得才是 Agent Skill 真正能落地的方向——不是所有事都要让大模型从头干一遍。

📦 GitHub: https://github.com/darthmolen/ai-plugins-and-skills/tree/main/skills/codebase-mapper

GitHub: https://github.com/darthmolen/ai-plugins-and-skills/tree/main/skills/codebase-mapper