别再手写了！让 AI 开工前先扫一眼代码"存货"

一个真实的翻车现场

我做哲哲的成长树项目，前端纯静态、插件越加越多。一开始很自然地写了一份"插件功能清单"，贴在 README 里，写着"当前 18 个插件"。

问题来了：项目在长，插件在加，那份清单没人改。等我再数源码，实际已经 26 个了——8 个偷偷冒出来，清单还停在 18。更要命的是，规则文档里写着"加插件前先查这张表"。AI 很听话，真去查了那张过期的表，结果要么重复造轮子，要么和已有数据文件撞车。

根因不是"忘了更新"，而是清单和源码本来就是两份东西。你补表、加注册、加注解，只是把腐烂推迟，还多出一个会漂移的来源。

解法：让代码自己报数

思路很简单：别让 AI 读人写的功能清单，让它在动手前跑一条命令，从源码现场扫出"已经实现了什么"，扫完直接复用。

我把这叫"能力地图打法"。核心就一句话——唯一真源是源码，清单只是派生物。

之前是"人写清单 → AI 读清单"。现在改成"源码 → 只读 CLI 扫 → 现场输出给 AI"。新建一个文件，下次扫描自动出现，零登记、零注册改造、零清单文件。

它到底怎么扫的

脚本不执行代码、不做 AST、不猜语义。它只读文本，用几组正则抓"字面量"：

• 全局对象 window.X / export / public class
• 路由 route('GET','/api/x') / @GetMapping / @app.route
• CLI 参数 --flag
• 数据文件 *.json、文件头那行 xxx.js — 做什么 的注释

因为只认字面量，它零依赖、还能跨语言。同一个脚本，在 Node、Java Spring（@GetMapping）、Python Flask（@app.route）、ES Module 上都能抽到能力，不用换脚本。

三步落地，改的是习惯不是代码

模板就两个文件：capabilities-cli.js + capabilities.config.json。迁移只要 5 步，但真正的成败在第四步——把一段"固定指令"贴进项目的 AGENTS.md / README / 会话开场白，让 AI 养成"开工前先 --prompt"的习惯。

常用三条命令：

• --prompt：给 AI 看的完整清单（有哪些域、文件、能力、硬约束、门禁）
• --selftest：自检扫得全不全，CI 和交付前跑
• --init：自动探测项目里有哪些域和语言，生成配置（保持 domains: "auto"，以后加目录零维护）

注意：它不联网、不写文件、不碰数据目录。--init 和 --selftest-new 是仅有的两个会写文件的例外，而且限定输出位置。

边界：别被"自动收录"骗了

最容易被坑的是这一条：清单自动收录 ≠ 服务已经上线。

比如新增一个后端插件、新加一条路由，能力地图能扫到文件，但服务端可能要重启才挂载、工具页可能要在登记表加一行才能访问。拿"清单里有了"当上线证据，是要出事的。

另外，动态拼接的路由、写在配置里的端点，字面量扫不到。这时别回头去补手写清单——直接读源码。

为什么 AI 不能像 IDEA 那样秒级拿骨架？

聊到这，你可能会问：IDEA 跳转到定义、查找引用、看调用链，都是瞬时的，为啥 AI 不行？

因为 IDEA 有常驻工程模型：它一次性把整个项目的 PSI / AST / 符号表建好，常驻内存，你边写它边用增量编译保持热，所以全量语义天然可见。

而 LLM Agent 是会话制、没有持续索引。它"知道代码"的唯一方式是靠工具读文件、把内容塞进上下文窗口。窗口有限，把整个项目的 AST 全塞进去会爆；而且跨会话不记忆结构，下次来还得重读。建一份全量 PSI 太贵、又不持久，安全上也不该让 AI 直接持有整份工程模型。

所以能力地图不是要替代 IDE，而是给"没有 IDE 的 Agent"一张靠谱的目录级地图：不回答语义细节，只回答"有什么、在哪、契约是什么"。它够轻、可移植、跨项目直接复用——你已经踩过的坑，下一个项目别再踩。

结语

说白了，能力地图打法就是用一条命令，把"人维护会腐烂的清单"换成"源码自己报数"。它治的是 AI 开发里最隐蔽的浪费：明明已经实现了，却因为信息过时又造了一遍。

如果你也在用 AI 攒项目、模块越堆越多，不妨试试：下次开工前，先让它跑一条 --prompt。