graphify 的 CLAUDE.md 常驻规则解析：让 Claude Code 学会先查知识图谱、再读源码

无论你管理的代码库有多大，只要它已经被 graphify 处理过，就会在 graphify-out/ 下沉淀出一份可查询的知识图谱——包含 god nodes（枢纽节点）、社区结构（community structure）与跨文件关系（cross-file relationships）。而 Claude Code 等 AI 编码代理能否高效利用这份图谱，取决于它"潜意识"里遵守的规则。本篇技术指南围绕仓库中 claude-md.md 这份 always-on 指令片段展开，讲解 graphify 如何把这套"查询优先、逐层退避、修改后增量更新"的工作流注入 CLAUDE.md，并结合源码说明 graphify query / path / explain / update 的底层机制与落地前提。读完你将掌握：图谱产出物各有什么用途、何时该用哪个命令、以及为什么 AST 级增量更新可以做到零 API 成本。

一、这是"常驻指令"：从片段到 CLAUDE.md 的生成流水线

claude-md.md 的正文非常短，但它在 graphify 中不是一篇普通文档，而是一份被刻意设计的 always-on 指令块——只在该文档真正"在场"时才有价值。graphify 仓库维护了一套由片段生成交付物、再由校验器防漂移的流水线：

• 编辑源头（single source of truth）：tools/skillgen/fragments/always-on/claude-md.md 是给人编辑的片段文件。
• 渲染产物：graphify/always_on/claude-md.md 是打包进 wheel 的成品 markdown，内容与片段逐字节一致。
• 快照基线：tools/skillgen/expected/graphify__always_on__claude-md.md 是 expected/ 下的防漂移快照。

在 tools/skillgen/gen.py 中可以看到，ALWAYS_ON_BLOCKS 把 claude-md 映射到历史上的常量 _CLAUDE_MD_SECTION，与 agents-md、gemini-md、vscode-instructions、antigravity-rules、kiro-steering 并列，共六个常驻指令块。这些块过去是 graphify/main.py 里的三引号字符串常量，现在被抽取为独立 markdown 文件，模块在加载时读取——graphify claude install 通过 install._always_on("claude-md") 取到这段文本，把它写入用户的 CLAUDE.md（见 graphify/install.py），从而让 Claude Code 在每一个会话都能读到这条规则，实现真正的 always-on。

tools/skillgen/gen.py 的 render_always_on()（tools/skillgen/gen.py）在一次完整渲染中生成这六个块，而 --check 与 expected/ 快照则构成 CI/提交前的防漂移闸门：任何人手工改动已生成的 always_on/*.md，都会被字节级比对拦下（对应 --always-on-roundtrip 校验器）。

二、规则 1：图谱存在时，query 永远优先于裸读源码

片段第一条规则给出了 Claude Code 处理代码库问题的决策顺序：

• 当 graphify-out/graph.json 存在时，代码库问题先执行 graphify query "<question>"；
• 关系类问题用 graphify path "<A>" "<B>"；
• 聚焦某个概念用 graphify explain "<concept>"。

这条规则背后的动机在片段里写得很直白：这些命令返回的是限定范围的子图（scoped subgraph），通常远小于 GRAPH_REPORT.md 或原始 grep 输出。这也与 graphify/skill.md 中描述的 fast path 一致——只要 graph.json 存在且用户问的是关于代码库的自然语言问题，代理应跳过抽取流水线直接进入 query 流程。

query 的底层形态

在 tools/skillgen/fragments/references/query/default.md 中可以读到完整的 query 规范。核心包括：

模式	标志	适用场景
BFS（默认）	无	“X 连接了什么？”——广度上下文，最近邻居优先
DFS	--dfs	“X 如何到达 Y？”——追踪特定调用链或依赖路径

同时支持 --budget 1500 这类 token 上限参数，控制返回子图的规模。值得注意的是，query 的节点匹配机制是大小写折叠的 substring + IDF，本身不做词干还原、不做同义词扩展、不做跨语言匹配——因此规范要求先做"受约束的查询扩展"：从 graph.json 的节点标签中提取词汇表写入 .vocab.txt，再从这份图谱真实词汇里挑选至多 12 个 token 重新拼装查询串。这一设计从源码层面保证了"用户问 auth、图谱写 Guardian"这类措辞错位不会让查询退化为噪声。

path 与 explain 的定位

• graphify path "<A>" "<B>" 走最短路径分析，把两个概念（哪怕隔了多个模块）之间的连接关系拉出来，适合回答“这两块是怎么搭上的”。
• graphify explain "<concept>" 面向单个节点的聚焦讲解，适合在不展开整张图的前提下解释一个符号/模块的职责。

当 graphify query 这个 CLI 不可用时，规则还允许退回到内联 NetworkX 遍历 graphify-out/graph.json——保证即使在未安装 CLI 的环境中，代理仍能遵循"查询优先"的精神。

三、规则 2：wiki/index.md 是广域导航层，优先级高于源码浏览

片段第二条规则：若 graphify-out/wiki/index.md 存在，用它做广域导航（broad navigation），而不要直接翻原始源码。

graphify 的 wiki 由 graphify/wiki.py 生成，to_wiki() 会以社区为单位产出 index.md 汇总页 + 每个社区一篇独立文章，并包含指向 god nodes 的专门条目。配合社区的语义标签与跨社区链接（graphify/wiki.py 中的 _cross_community_links、_index_md），这份 wiki 相当于把整张图"翻译"成人/代理可连续点击阅读的文档树。触发方式是带 --wiki 的构建：

/graphify <path> --wiki    # 生成可被 agent 爬取的 wiki（index.md + 每社区一篇）

它解决的是"该从哪里看起"的问题：当一个问题需要覆盖多个社区、多组文件时，从 index.md 按社区入口进入，比逐文件 grep 的路径规划效率高得多。

四、规则 3：GRAPH_REPORT.md 只在需要全局面时读取

片段第三条规则对 GRAPH_REPORT.md 的使用设了门槛：仅用于宽泛的架构审视，或在 query / path / explain 无法给出足够上下文时才读。

这与 report 的生成定位吻合——graphify/report.py 的 generate() 负责聚合 god nodes、surprising connections（惊喜连接）、社区标签、cohesion 分数与建议问题，最终得到一份面向"人通读"的整体报告。它信息密度高、覆盖全库，因此体量也大；把这类报告当作默认输入会显著拉高每个会话的上下文成本。规则刻意把它降级为"退避选项"，与第一条中"子图优先于整包报告"的思路一脉相承：先取小、按需放大。

五、规则 4：改完代码立即 graphify update .，AST-only、零 API 成本

片段最后一条规则要求代理在修改代码后运行 graphify update .，让图谱保持最新，并特别注明 AST-only, no API cost。

这条规则的底层支撑在 tools/skillgen/fragments/references/shared/update.md 中展开。graphify update（对应 --update 增量模式）走的是增量重抽取而非全量重建：

• 调用 detect_incremental(Path(...))（实现见 graphify/detect.py），只找出新增/变更/删除的文件；
• 若没有变化，直接输出 No files changed since last run 并退出；
• 有变化时，仅对变更子集重新做 AST 抽取，再复用缓存与既有图谱做合并，从而节省 token 与时间；
• 同时产出 .graphify_incremental.json / .graphify_detect.json 供下游建图步骤读取，把"增量后的正确状态"透传给后续阶段。

"零 API 成本"的来源在于：结构性抽取走的是本地、确定性的 tree-sitter AST 解析（对应项目描述中的 "local deterministic AST parsing, no vector store"），不调用任何 LLM。语义抽取（需要 AI 的文档/论文/图片理解）才会消耗 token，而纯代码修改触发的 AST 级更新完全不依赖外部模型——这正是该规则能被设计成"改完就跑、无心理负担"的原因。

六、规则如何真正"常驻"：安装接线与自动化闸门

要理解这套规则为什么有效，需要看清它被注入的机制：

1. CLAUDE.md 即会话记忆。Claude Code 每次会话都会读取项目根目录的 CLAUDE.md（以及 .claude/ 下的设置）。graphify claude install 将 ## graphify 段写入该文件（graphify/install.py），卸载时用 marker 精确剥离（graphify/install.py），做到可重复安装与清理。
2. 片段即单点事实源。这段文本只存在于 tools/skillgen/fragments/always-on/claude-md.md，always_on/ 产物与 expected/ 快照均由它渲染而来；想修改规则，只需改片段并重跑 python -m tools.skillgen。
3. 多个宿主共享语义。同样的"图谱查询优先"原则，graphify 也以 agents-md、gemini-md 等变体注入到 AGENTS.md、GEMINI.md 等文件；claude-md 变体的 hooks 目标是 CLAUDE.md（见 tools/skillgen/gen.py 的 _HOOKS_TARGET 映射）。

七、适用前提与最佳实践小结

场景	推荐动作	依据/文件
问代码库问题且 graph.json 存在	graphify query "<question>"	claude-md.md
追问两个概念间的关系	graphify path "<A>" "<B>"	同上
聚焦单个概念的讲解	graphify explain "<concept>"	同上
需要跨社区的全局面	读 graphify-out/wiki/index.md	同上
深度架构审视/子图不够	读 graphify-out/GRAPH_REPORT.md	report.py
刚修改过代码	graphify update .（AST-only，零 API 成本）	shared/update.md

需要特别说明的前提条件：上述规则的生效依赖 graphify-out/graph.json 位于当前工作目录下（即项目根目录），且图谱曾用 graphify 构建过。对从未建图的新仓库，规则的第一步不会触发，代理会自然走完整抽取流程。这套"常驻指令"的价值在于把图谱从一次性产物升级为持续演进的协作资产——每一次代码改动后的 update，都在用零成本的方式让 AI 代理的"项目认知"与真实源码保持同步。