夜雨聆风大部分开发任务，我还是让 Coding Agent 直接读源码。图个省事儿，读代码 AI 也能理解业务逻辑，只要模型好点，写的代码质量也还不错，就是 Token 花的多点，但我也能接受。
但任务一复杂，痛点就出来了：改一个状态字段，Agent 找到了 Service，却可能漏掉 Mapper、消息消费者、配置和测试；这次好不容易补齐，换个会话，下次还要重新摸一遍。
麻烦的不是 Agent 找不到源码，而是它每次都要重新拼上下文，还可能拼不完整。
顺着这个问题，我拆了 5 个热门项目：
源码才是最终事实，为什么还要额外维护 Wiki 和 CodeGraph？它们解决的到底是时间、空间，还是上下文问题？
拆完这 5 个项目，我得出了结论：源码负责验真，Wiki 复用解释，CodeGraph 追踪关系。 默认直接读源码；同类解释反复出现才做 Wiki，跨模块遗漏反复出现才加 CodeGraph。没有版本、来源和失效规则的派生知识，宁可不用。
1. 源码能读，问题是上下文找不全
换个任务或会话，Agent 又要搜索入口、追调用关系、补配置和测试，再拼一张临时地图。源码没变，理解成本却重新付了一次。
先把这笔成本拆开：
这些方案都把一部分理解提前保存下来，有点像数据库的物化视图：后面查询更快，但底层一变，派生结果就可能失效。真正的区别，是提前保存了什么。
搜索索引预计算“词和位置”； Wiki 预计算“这个系统是什么意思、为什么这样设计”； CodeGraph 预计算“符号之间如何连接、变化会沿哪条边传播”。
这不只是“空间换时间”。空间和预计算是手段，选对上下文、减少遗漏才是目的。
源码、配置、测试和运行记录仍然负责裁决当前事实。Wiki 和 Graph 负责缩小候选范围，不负责替它们下最终结论。
2. 知识库、Wiki、CodeGraph 有什么区别
很多人会把知识库、Wiki、CodeGraph 当成一条升级路线。其实不是，它们在同一套系统里的有着不同的位置：
所以这不是升级路线。 如果没有反复出现的关系查询，知识库里已经有源码和 Wiki，也没必要再补 CodeGraph。
FSoft CodeWiki 就是个直接例子：它先生成依赖 Graph，再据此划分模块、生成 Wiki。Graph 可以是 Wiki 的底层结构，不是谁替代谁。
3. CodeWiki 和 CodeGraph 解决的问题不同
CodeWiki 和 CodeGraph 名字很像，做的事不一样。CodeWiki 先分析代码关系，再把结果写成 Wiki；CodeGraph 保留这张关系索引，供 Agent 随时查询“谁调用了谁、改动会影响哪里”。
以 colbymchenry/codegraph 为例，它用 Tree-sitter 分析源码，把类、函数和调用关系存进本地 SQLite。查询时，索引负责定位，Agent 仍然读取当前源码。它保存的是地图，不是另一份源码。
Graphify 的范围更大：除了代码，还能把 SQL、Markdown、PDF 和图片放进同一个 Graph。它适合追跨材料关系，但模型推断出来的关系仍要回到原文件验证。
所以我不会把这些项目按“新旧”排序，而会按问题选择：
我的默认入口还是搜索；问题变成系统解释、调用关系或混合材料追踪时，再切换工具。
4. Wiki 和 Graph 如何生成、更新
要把 Wiki 和 Graph 用于真实开发，我会补齐下面这条更新链。这是我建议的可靠性门禁，不代表几个项目都已经完整实现：
这里只讲核心思路。具体怎么接进项目，文末都有地址，照着项目说明跑起来不难，我就不重复废话了。
以 CodeGraph 为例：第一次解析源码，保存符号和调用关系；文件变化后，由监听器增量更新索引，更新完成前明确提示结果可能陈旧。Wiki 类工具通常更新受影响页面，混合 Graph 则会比较文件哈希。实现不同，核心都是四步：绑定版本、发现变化、只更新受影响部分、过期时回到源码。
解析器会漏语法，静态分析看不到部分运行时行为，模型也可能补出一条貌似合理的关系。所以我最看重三个字段：版本、来源、置信度。一条关系如果说不清基于哪个提交、来自哪个文件、是抽取还是推断，就不能直接拿来改代码。
我之前在 Graphify v0.9.29、Petclinic 提交 f182358d 上做过一组复现：它能从 OwnerRepository 找到相关 Controller 和测试，也出现过输入漏收和 INFERRED 推断边。原始产物没有完整保留下来，所以这里不报精确覆盖率，只保留一个提醒：命中关键关系，不代表覆盖了整个仓库。
5. 我的四步使用方法
建议不要一上来就同时搭 Wiki、CodeGraph 和向量库。我的使用顺序只有四步：
5.1 第一步：先用搜索和源码
已知符号、单模块修改、小仓库任务，先用搜索、LSP、源码和测试，只确认 Agent 能否稳定完成最基本的上下文选择：
找到实现入口； 找到直接调用方和被调用方； 找到相关配置； 找到应该运行的测试； 在修改前列出预期改动范围。
如果这里已经稳定，Wiki 和 CodeGraph 都是可选优化。不要为了做知识基础设施，先给简单任务增加一条维护链。
5.2 第二步：重复出现的解释放进 Wiki
适合沉淀的内容包括：
模块职责与边界； 核心业务流程； 设计决策和替代方案； 不容易从单个文件看出的业务约束； 跨多个仓库或文档才能拼出的概念。
不适合沉淀的是逐函数复述源码。函数一改，页面就旧；而读者从页面获得的信息并没有比直接打开源码更多。
每个 Wiki 页面至少要带源码入口、生成或校验方式、最后验证的提交版本。没有这些字段，它只是容易被误信的长文本。
5.3 第三步：反复漏掉跨模块关系时再加 CodeGraph
典型信号包括 Agent 经常漏掉数据传输对象（DTO）、接口实现、数据访问层（Repository）、配置、路由或受影响测试。
日常编码以源码结构为主，优先选 CodeGraph 这类能持续同步、直接返回当前代码和调用路径的工具。
如果问题横跨代码、SQL、ADR、PDF、架构图，而且需要把产物离线交给另一个环境，再考虑 Graphify。
默认只选一个。两个工具都接入，并不会自动得到更完整的上下文，反而会增加重复索引、版本判断和路由成本。
5.4 第四步：修改前回源码验证
Agent 使用 Wiki / Graph 之前，先比较派生版本与当前提交（HEAD）和工作区状态。 每份派生产物至少记录：生成器及版本、基准提交、输入文件或哈希、生成时间、来源，以及关系类型或置信度。
基准提交不一致，或者工作区存在未提交修改时，先把 Wiki / Graph 降级为线索，只读当前源码；不能确认来源的关系不进入修改计划。
查询结果要区分：
语法或配置直接抽取； 静态分析推导； 启发式关系； LLM 生成解释。
真正修改之前，仍要打开源码和配置，列出涉及文件与测试，再用测试验证结果。
涉及动态分派、反射、依赖注入、约定式路由、消息主题和运行时配置时，静态 CodeGraph 只能给候选范围。线上问题还要看日志和一次请求的运行链路（Trace），不能从 CodeGraph 直接推断实际执行路径。
下面这段是我会放进项目规则里的最小版本：
markdown## 可直接复制的项目规则1. 已知符号、文件名或错误文本：先用搜索/LSP。2. 询问模块职责、核心流程、设计理由：查 Wiki。3. 询问调用路径、跨模块依赖、影响范围：查 CodeGraph。4. Wiki / Graph 只用于缩小候选范围，不作为最终事实。5. 派生产物必须记录生成器版本、基准 commit、输入/hash、生成时间和来源。6. 基准 commit 不同或工作区有未提交修改：降级回当前源码。7. 每个关键结论必须回到 file:line、配置或测试验证。8. 修改前列出必改文件、可能受影响文件和要运行的测试。9. 对动态分派、反射、依赖注入、配置、消息关系做额外验证。6. 用 8～12 个真实任务验证效果
Wiki 和 Graph 都需要维护。是否值得保留，不该看演示效果，也不该先看占了多少磁盘。
我会从真实待办里挑 8～12 个任务，在同一提交、同一模型、同一权限下，对比 source-only 与 source + 当前候选视图。Wiki 和 Graph 分开测试，一次只增加一种，才知道收益来自哪里。
记录 4 个门槛指标，再看 2 个效率指标：
前四项是门槛，后两项才看效率。 如果只是少读几个文件，却漏掉配置、测试，或者识别不了旧视图，这个优化就不成立。
最后我保留的是一条证据链：搜索找位置，Wiki 复用解释，CodeGraph 追关系；源码、配置、测试和运行记录负责验真。
只把那些反复发生、又容易遗漏的理解过程，做成有来源、有版本、能更新的 Wiki 或 CodeGraph。
7. 参考资料
Google Code Wiki：https://codewiki.google/
CodeWiki 论文：https://aclanthology.org/2026.findings-acl.288/
FSoft CodeWiki：https://github.com/FSoft-AI4Code/CodeWiki
CodeGraph：https://github.com/colbymchenry/codegraph
Graphify：https://github.com/Graphify-Labs/graphify
👉 推荐阅读：