用 CodeGraph 读代码，用 Anti-Defensive Writing 写清楚

本文最后更新于：2026年10月31日晚上

用 AI 辅助开发时，我比较关心两件事：分析代码时，能不能把相关模块和调用关系找全；整理结果时，能不能把结论、依据和适用条件讲清楚。

CodeGraph 和 Anti-Defensive Writing 分别对应这两个环节。前者提供代码结构查询，后者提供文字修改规则。把它们放在一起，可以形成一条很实用的工作流：先找到源码依据，完成修改和验证，再把结果整理成读得懂的技术说明。

这篇记录安装、接入和日常使用方法。CodeGraph 命令按本机 1.6.2 的帮助信息核对，项目文档查阅于 2026 年 10 月 31 日。

先分清两个工具各自负责什么

工具	放在什么环节	主要产出
CodeGraph	阅读项目、追踪调用、评估改动范围	相关源码、符号关系、调用路径
Anti-Defensive Writing	修改技术说明、实验记录和博客草稿	观点明确、条件具体的文字

CodeGraph 通过 CLI 或 MCP 提供代码查询能力。Anti-Defensive Writing 的核心是一份 SKILL.md，由 Agent 在写作任务中读取并应用。

实际使用时，可以先拿 CodeGraph 回答一个具体的代码问题，再把查到的事实交给写作 Skill 整理。这样更容易看出两者分别带来了什么帮助。

CodeGraph：安装、接入和初始化分三步

安装命令行工具

这里采用项目 README 提供的 npm 安装方式，适合已经有 npm 的环境：

1 2	`npm install -g @colbymchenry/codegraph codegraph --version`

macOS 上也可以使用这套命令。若机器上已经能运行 codegraph，先查看版本即可，避免重复安装。

接下来运行安装向导：

1	`codegraph install`

在向导里选择自己使用的 Agent，例如 Codex 或 Claude Code，再选择安装范围。这个步骤负责把 CodeGraph 接到 Agent 的工具配置中。

在需要分析的仓库里建立索引

进入实际项目根目录，再执行：

1
2
3

cd /path/to/your-project
codegraph init
codegraph status

init 会创建项目本地的 .codegraph/ 目录，并构建初始索引。status 用来查看索引状态和统计信息。

安装 CLI、接入 Agent、初始化项目，是三件分别完成的事。安装过工具以后，每个需要使用 CodeGraph 的仓库仍要单独建立索引。

.codegraph/ 保存本地索引和相关运行状态。如果团队选择让每个人在本地生成索引，可以在 .gitignore 中加入：

1	`.codegraph/`

是否把索引或相关配置纳入版本管理，按项目约定处理。

确认 Agent 真正在使用它

接入后，可以在 Codex 或 Claude Code 中提出一个范围明确的问题：

1
2
3

请使用 CodeGraph 分析当前项目的查询入口。
列出关键函数、调用路径，以及对应的文件和行号。
把源码直接支持的事实与仍需验证的推断分开说明。

检查执行过程里是否调用了 CodeGraph 工具，并查看返回的源码和路径。MCP 查询入口主要是 codegraph_explore；终端里对应的是 codegraph explore。

如果只需要检查 Codex 的手动配置格式，可以让当前安装版本输出配置片段：

1	`codegraph install --print-config codex`

这样得到的参数与本机版本对应，接入时优先使用安装向导生成的配置。

日常读代码，我会从一个具体问题开始

与其一开始就让 Agent 概括整个仓库，更容易检查的起点是一个明确入口：某个请求从哪里进入，经过哪些函数，最后在哪里形成返回值。

下面用 Index::search 作为示例符号，实际使用时替换成项目里的真实名称：

1	`codegraph explore "Index::search 的输入、调用链和结果返回路径"`

需要进一步检查调用方或改动范围时，再查询：

1 2	`codegraph callers "Index::search" codegraph impact "Index::search"`

读返回结果时，我会先抓住三个信息：入口在哪里、关键处理经过哪些模块、哪些调用方可能受到修改影响。然后回到对应源码，核对参数、分支和数据流。

图谱提供的是组织代码关系的线索。对于反射、复杂动态分发或工具尚未解析出的边，仍需结合源码和运行结果确认。性能判断则交给实际测试：调用路径能帮助找到检查位置，耗时需要通过测量得到。

在 AGENTS.md 里约定查询顺序

如果一个仓库已经建立了索引，可以给 Agent 加一段简短的项目约定：

## 代码阅读

- 根目录存在 .codegraph/ 时，优先使用 codegraph_explore
  或 codegraph explore 查询相关源码与调用关系。
- 查询时写明文件、符号或需要追踪的路径，并核对返回的行号。
- 没有索引时，使用已有的文本搜索和文件读取工具。

这段约定规定工具的使用时机。索引由项目维护者决定是否建立，Agent 根据当前仓库状态选择查询方式。

修改代码后，索引怎么更新？

CodeGraph 的自动同步依赖正在运行、并监视该项目的服务。日常通过 MCP 使用时，文件变化可以触发增量同步；离线修改、切换分支，或者对索引状态有疑问时，可以手动同步并检查：

1 2	`codegraph sync codegraph status`

维护时记住三个命令就够了：

命令	作用
`codegraph sync`	增量同步项目变化
`codegraph index`	重新构建完整索引
`codegraph upgrade`	升级 CodeGraph 程序

索引更新和程序升级对应不同的操作。平时修改业务代码，先关注同步状态；需要更新工具版本时，再执行程序升级。

Anti-Defensive Writing：把结果直接写出来

技术内容写完以后，另一种常见问题是正文里塞进了太多保护性措辞：一段话还没讲清结果，就先说“只是初步尝试”“可能有一定帮助”“仍有很大局限”。读者看完，反而不容易找到真正的信息。

Anti-Defensive Writing 会检查这些句子的作用，把没有增加信息的谦辞、重复免责声明和层层保留删掉，再围绕观点重新组织段落。

这份 Skill 的规则里，有个很实用的原则：结论的力度跟着证据走。 有测量结果，就写清条件和数值；原因还没确认，就说明当前观察；适用前提影响读者判断时，把前提留下来。

安装到技能目录

它可以只安装一个 SKILL.md。首次安装到 Codex 的用户级目录，可以执行：

mkdir -p ~/.agents/skills/anti-defensive-writing
curl -fsSL \
  https://raw.githubusercontent.com/Kiterlin/anti-defensive-writing/main/SKILL.md \
  -o ~/.agents/skills/anti-defensive-writing/SKILL.md

安装后结构如下：

1
2
3

~/.agents/skills/
└── anti-defensive-writing/
    └── SKILL.md

上面的下载命令会写入目标文件。如果已经有同名 Skill，先检查现有版本，再决定是否替换。

Claude Code 可以把同一个文件放到 ~/.claude/skills/anti-defensive-writing/SKILL.md。需要随项目共享时，分别使用项目内的 .agents/skills/ 或 .claude/skills/ 目录。

按OpenAI 官方技能文档，Codex 会自动检测技能变化；如果选择器里仍未出现，可以重启。首次使用时显式点名调用，比较方便确认它是否加载成功。

在任务里明确调用

在 Codex CLI 或 IDE 扩展中，可以这样写：

$anti-defensive-writing

请修改下面的技术说明：
先说清主要发现，删去重复的自我限定。
保留实验条件、原始指标和必要的不确定性。
事实不足的位置请指出，不补造结果。

[粘贴草稿]

Claude Code 中，项目给出的调用方式是：

1	`/anti-defensive-writing 修改下面的技术说明，保留事实和必要条件。`

把输入范围说清楚也很有帮助。例如“只修改摘要”“保持命令和参数不变”“将这份实验记录整理成博客”，比笼统地要求“写得更专业”更容易得到可用的结果。

看一个技术记录的改写例子

下面使用一组假设数据演示写法：在相同数据集和并发度下，方案的 P95 延迟从 18 ms 降到 14 ms，Recall@10 从 0.960 变为 0.958。

比较含糊的写法是：

这次只是做了一些初步优化，可能在一定程度上改善了性能。不过召回率也有所下降，因此仍有很多不足，效果还需要进一步研究。

可以整理成：

在相同数据集和并发度下，方案将 P95 延迟从 18 ms 降至 14 ms，Recall@10 从 0.960 变为 0.958。该结果记录了本轮配置下的延迟与召回率变化。

修改后，读者能直接看到测试条件、收益和代价。实验只覆盖了哪些数据、还需要验证哪些负载，可以在对应的实验说明中具体交代。

改写时尤其要检查数字有没有变化、相关性有没有被写成因果，以及尚未测量的效果有没有被补进正文。文字的清晰度来自信息组织，新的结论仍需要新的证据。

把两者放进一次完整任务

例如，要修改查询流程并写一份技术记录，可以按下面的顺序推进：

查看 CodeGraph 索引状态，定位入口、调用链和相关实现。
核对源码，明确参数、分支和需要保持的接口约束。
完成修改，运行与改动相关的构建、功能测试和性能测试。
整理已确认的改动、测试条件、指标与待验证问题。
使用 Anti-Defensive Writing 修改说明，让每一段围绕一个具体结论展开。

交给 Agent 的任务描述可以写成：

先使用 CodeGraph 分析查询入口与扫描模块的调用关系，
给出相关文件和行号，再说明需要核对的实现细节。

完成改动后，按项目要求运行构建和测试，记录实际结果。

最后使用 Anti-Defensive Writing 整理技术说明：
写清改动、验证条件和观测结果，保留有依据的限制。
尚未验证的推断单独列出，指标只使用实际测试数据。

这种组合适合代码阅读笔记、PR 说明、实验记录和技术博客。前面的步骤负责积累依据，最后的写作步骤把这些依据组织成读者能够理解和检查的内容。

使用时，从一个具体问题开始就够了：追清一条调用链，核对一次改动，再写一小段结果说明。用顺以后，再把查询习惯和写作要求逐步整理进项目约定。

参考资料

工具

#CodeGraph #Codex #Agent Skills #写作

用 CodeGraph 读代码，用 Anti-Defensive Writing 写清楚

https://zzmes.github.io/2026/10/31/codegraph-anti-defensive-writing/

作者

Zzmes

发布于

2026年10月31日

许可协议

给 Jetson Orin Nano 增加 16 GiB Swap 下一篇