夜雨聆风三个月前我在做一个支付模块的重构。
不是什么大项目，四五百个文件，几个核心服务。我把需求描述清楚， Claude Code 开始读代码。它读得很认真 —— 一个文件接一个文件，目录一层层翻， grep 搜了一遍又一遍。
我看着它翻了快十分钟。上下文窗口被系统提示词和工具定义吃掉一大截，剩下那点空间，被它翻过的几十个文件塞得满满当当。它开始"压缩"——把前面的内容自动总结成模糊的摘要。然后基于摘要，改了几行代码。
我当时盯着屏幕想：你连这个项目长什么样都不知道。
不是能力的问题。是它根本没有一张地图。它每次进来，都是从零开始摸黑走路。
你花了几千块买的工具，是个瞎子
这不是我在夸大。 SWE-Pruner 那篇论文里拆过 AI 编程 Agent 的 token 消耗结构： 76.1% 花在探索行为上——读文件、 grep 、看目录。真正写进代码里的改动，不到 12%。
更让人火大的是上下文窗口这件事。 200K token 听起来很大对吧？系统提示词占一块，工具 schema 占一块——有人实测光工具定义本身就能吃掉 57K token——每轮工具调用结果又堆上来。你实际能用的空间不到一半。
上下文窗口不是均匀的。中间区域的信息 AI 最容易忽略。放太深的东西，相当于不存在。
于是你的 AI 助手不停地压缩旧对话。把重要的注释压缩成"这里有一些代码"。把"这个校验不能删"压缩成"有校验"。然后自信地删掉了它。
这不是模型烂。是你让它拄着拐杖过独木桥，然后怪它摔跤。
我搭了一座桥，然后才意识到这东西根本不是工具
意识到这个问题之后，我做了一件事：给项目建了一张代码图谱。
技术上不复杂——一个叫 codebase-memory-mcp 的开源工具， MIT 协议，用 C 写的，纯二进制零依赖。它拿 tree-sitter 语法解析器把你的项目整个扫一遍，自动识别出所有函数、类、接口，以及它们之间的调用、导入、继承关系，存成一张有结构的图。
158 种语言。 Linux 内核 2800 万行代码， 3 分钟索完。 Django 级别的项目， 6 秒。
但这不是重点。
重点是装完之后，我的 Claude Code 变了。它不再一个一个翻文件了。我让它查"谁调用了这个函数"，它查图谱，几十毫秒。让它看看改了 GatewayClient 的签名会影响哪些地方，它沿着调用链一层层查。
五个操作变成了肌肉记忆：get_architecture 看全貌，trace_path 追调用链，search_graph 查调用方，detect_changes 看改动影响，get_code_snippet 只取需要的那几行。
一个数字让我意识到这东西的价值：同样的五个结构查询，直接翻文件要 41 万 token 。查图谱只要 3400 个。省了 120 倍的上下文。省下来的空间不是省 token 费，是让 AI 有精力去想"这段逻辑对不对"，而不是"这行代码在哪个文件里"。
然后再想一件事：你知道有多少人每天在让 AI 盲写代码吗？
地图告诉你"在哪里"，但"为什么"没人替你写
图建好了， AI 能准确地告诉你 handleTimeout 调用了 retryWithBackoff。
但它不知道为什么要重试。不知道第三次重试的超时时间为什么是 30 秒而不是 60 秒。不知道这条规则是上一个同事在凌晨两点上线后发现故障、回滚、排查了四个小时才加上去的。
结构是程序帮你建的。解释必须人写。
我的做法很朴素。项目根目录建一个 knowledge/ 文件夹，全用 Markdown 写：
knowledge/├── architecture.md # 为什么拆成了这些模块├── decisions/ # 关键决策│ └── 支付为什么分两步扣款.md└── gotchas/ # 踩坑记录 └── 用户ID校验不能放网关层.mdAI 整理初稿——它根据代码结构推演出设计意图，我确认和修正。然后跟着代码一起进 Git 。
两层记忆：一层自动生成，负责"哪里是什么"；一层人工维护，负责"为什么是这样"。少了一层， AI 还是可能自信地删掉那个"看起来没必要"的校验。
说实话， AI 编程的下一件事不是更大的模型
这一年 AI 编程工具卷疯了。 Cursor 、 Claude Code 、 Codex 、 TRAE ....
名字换了一茬又一茬。每个都在说自己模型更大、窗口更长、理解更深。
但没人问一个更根本的问题：AI 到底是怎么"看到"你的代码的？
它没看到。它每次来都是从头摸——读 30 个文件，压缩成摘要，再读 30 个，再压缩。你给它 500 个文件，它有效读到的永远是前面那几十个。后面的被压成关键词，关键词被压成"这里有一些逻辑"，然后它基于这个做判断。
这不是模型的问题。是输入方式的问题。你给了它全市的电话本，让它找一条从 A 到 B 的最短路线，但你没给它一张地图。
建图这件事，从下载到索完一个几百文件的项目，从头到尾不超过半个小时。一个二进制文件，一行 JSON 配置，跑一次索引。
但说真的，半小时不是重点。重点是做完之后，你每次打开编辑器， AI 不再是蹲在角落翻文件堆的实习生。它知道这个项目长什么样。
这才是 AI 编程应该有的样子。不是更大的上下文窗口。是一张图。