Skip to content

35-claude-md-loading-and-instruction-assembly.md

Latest commit

 

History

History
138 lines (90 loc) · 4.9 KB

35-claude-md-loading-and-instruction-assembly.md

File metadata and controls

138 lines (90 loc) · 4.9 KB

35. CLAUDE.md 加载算法与指令装配

所属专题簇：记忆与上下文算法深挖

建议前读：21. 记忆系统：CLAUDE.md、Session Memory 与 Agent Memory

建议后读：17. 系统提示词与模型决策 或 38. ReadFileState、Context Cache 与 Partial View 机制

研究问题

CLAUDE.md 在 Claude Code 里为什么不是简单的多文件拼接，而是一套正式的指令装配算法？

一句话结论

因为 Claude Code 不只是“把几个 Markdown 读进 prompt”，它还要处理优先级、@include、frontmatter 条件匹配、partial view、外部文件限制和缓存一致性，所以 CLAUDE.md 已经演化成一个小型指令装配器。

这篇讲什么

这一章深挖 src/utils/claudemd.ts：文件发现、优先级、词法级 include、frontmatter paths 过滤、external include 规则，以及这套系统如何进入 getUserContext()。

如果你不看源码，只看这一章，应该记住什么

  • CLAUDE.md 在 Claude Code 里是装配系统，不是单文件。
  • include、路径条件和 partial view 都会改变真正进入上下文的内容。
  • 这套系统既是“记忆层”，也是“工作区指令编译器”。

源码依据

Mermaid 图：CLAUDE.md 装配流程图

flowchart TD
    A["managed / user / project / local files"] --> B["发现与优先级排序"]
    B --> C["parse frontmatter"]
    C --> D["提取 paths globs"]
    C --> E["词法提取 @include"]
    E --> F["递归处理 include"]
    D --> G["按 targetPath / includeExternal 过滤"]
    F --> H["strip comments / truncate / partial view 标记"]
    G --> H
    H --> I["MemoryFileInfo 列表"]
    I --> J["getUserContext"]
Loading

加载顺序只是最外层规则

src/utils/claudemd.ts 顶部注释已经写出四层来源：

  • managed
  • user
  • project
  • local

但这只是装配入口，不是最终算法的全部。真正复杂的是每层内部还要处理：

  • 当前目录向上遍历
  • CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md
  • 条件规则和 include

@include 是词法级提取，不是朴素文本拼接

同一文件里能看到：

  • 使用 marked 的 Lexer
  • extractIncludePathsFromTokens
  • 只在 leaf text node 提取 include
  • code block / code string 不参与 include 解析

这说明 Claude Code 不想让 @path 在代码片段或注释示例中被误识别成真正 include 指令。

external include 是受控的

processMemoryFile()、loadProjectMemoryFiles() 一路都有 includeExternal 参数，说明系统显式区分：

  • 哪些 memory 源允许 include 外部文件
  • 哪些只允许项目内路径

这不是细枝末节，而是工作区指令系统的边界控制。

frontmatter paths 让规则变成条件装配

parseFrontmatterPaths() 和相关过滤逻辑说明：

  • memory file 可以声明只对某些目标路径生效
  • splitPathInFrontmatter() 会把 frontmatter 里的路径规则拆开
  • 后续用 glob 匹配目标 path 决定是否纳入

这意味着 .claude/rules 并不是“总是全部注入”，而可以按文件上下文局部生效。

partial view 是一个重要但容易忽略的概念

MemoryFileInfo 里有：

  • contentDiffersFromDisk
  • rawContent

而注释明确说这用于：

  • HTML comment strip
  • frontmatter strip
  • MEMORY.md truncation

也就是说，模型看到的内容可能是“处理后的视图”，不等于磁盘原文。Claude Code 会显式把这件事记录下来。

这和 readFileState 是连着的

claudemd.ts 中还有：

  • cacheKeys(readFileState)
  • 从 readFileState 汇总 memory files
  • partial view presence in cache

这意味着自动注入过的 memory 文件，不只是“读过一次”，而是会进入会话级文件认知状态。后续 Edit/Write 是否需要显式 Read，和这个状态有关。

为什么它值得单独成章

因为 CLAUDE.md 在 Claude Code 里承担了三重角色：

  • 工作区记忆
  • 局部规则系统
  • 自动上下文装配器

不理解这套算法，很容易误以为它只是“把一个 markdown 附到 prompt 前面”。

你真正应该记住的点

  • CLAUDE.md 的复杂度远高于普通提示词文件。
  • include、frontmatter paths 和 partial view 是三条关键机制。
  • 这套系统体现了 Anthropic 对“工作区指令自动装配”的高度重视。

延伸阅读