上下文系统解析：Git、CLAUDE.md 与系统提示词注入

Claude Code 之所以能表现出对项目“深度理解”的能力，核心并不在于模型本身的智商突变，而在于其底层的 context.ts 上下文系统。该系统在对话启动前主动完成高价值信息的采集、压缩与结构化治理，并将 Git 工作区状态、CLAUDE.md 项目约束等关键背景精准注入系统提示词，从而为后续的主循环交互奠定坚实的工程上下文基础。

从源码逻辑来看，getSystemContext() 负责处理一类至关重要的项目级信息：Git 状态。它通过并行执行命令，主动采集以下核心数据：

• 当前分支与默认主分支
• 工作区变更状态（脏/洁）
• 最近提交记录
• Git 用户配置信息

对应源码片段

const [branch, mainBranch, status, log, userName] = await Promise.all([
  getBranch(),
  getDefaultBranch(),
  execFileNoThrow(gitExe(), ['--no-optional-locks', 'status', '--short'], {
    preserveOutputOnError: false,
  }).then(({ stdout }) => stdout.trim()),
  execFileNoThrow(
    gitExe(),
    ['--no-optional-locks', 'log', '--oneline', '-n', '5'],
    {
      preserveOutputOnError: false,
    },
  ).then(({ stdout }) => stdout.trim()),
  execFileNoThrow(gitExe(), ['config', 'user.name'], {
    preserveOutputOnError: false,
  }).then(({ stdout }) => stdout.trim()),
])

这段代码揭示了 Claude Code 的上下文构建逻辑：它并非被动等待用户输入，而是通过并行收集迅速锁定仓库当前的工程语境。模型据此能立即掌握仓库是否处于“脏”状态、当前所在分支以及近期代码演进方向，这对后续的工程任务推演与风险判断至关重要。

原始工程数据往往极其庞杂：仓库文件数量庞大、Git 状态流转频繁、本地记忆缓存可能堆积。context.ts 的核心作用并非盲目地将所有内容原样塞入上下文窗口，而是执行“上下文压缩”——精准提炼出信噪比最高、最值得注入的高价值信号。

除了底层仓库状态，getUserContext() 负责处理用户级与项目级的记忆文件（如 CLAUDE.md），并同步注入当前日期信息。 CLAUDE.md 可视为项目的工程工作说明书，涵盖：

• 编码规范与架构设计约束
• 仓库目录结构规则
• 团队定制命令与工作流约定
• 明确禁止的操作红线

通过固化这些约束，Claude Code 在处理同一项目时能保持高度一致的行为模式。

对应源码片段

const shouldDisableClaudeMd =
  isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS) ||
  (isBareMode() && getAdditionalDirectoriesForClaudeMd().length === 0)

const claudeMd = shouldDisableClaudeMd
  ? null
  : getClaudeMds(filterInjectedMemoryFiles(await getMemoryFiles()))

setCachedClaudeMdContent(claudeMd || null)

💡 关键逻辑：CLAUDE.md 的注入并非无条件触发。系统会优先检查环境变量 CLAUDE_CODE_DISABLE_CLAUDE_MDS 及当前运行模式（如 bare mode），确认符合条件后再进行解析与缓存，确保上下文加载的精准性与安全性。

表面上看，这只是在系统提示词末尾追加文本片段。但站在系统工程的角度，其本质是一套严密的上下文治理机制，重点解决以下问题：

• 筛选机制：明确哪些信息值得长期注入，哪些应当过滤或降级。
• 生命周期管理：对高频变动的数据执行缓存策略，避免重复计算与性能损耗。
• 模式适配：在不同运行模式下动态跳过或限制加载路径。
• 防环与节流：规避循环依赖风险，严格控制提示词总长度以防窗口溢出。

对应源码片段

return {
  ...(gitStatus && { gitStatus }),
  ...(feature('BREAK_CACHE_COMMAND') && injection
    ? {
        cacheBreaker: `[CACHE_BREAKER: ${injection}]`,
      }
    : {}),
}

这段返回值逻辑清晰表明：上下文不再是散落在代码各处的临时字符串，而是被统一封装为结构化上下文对象，再安全、有序地传递给后续的主循环迭代。

开发者往往低估了实时 Git 状态的价值。对于工程代理而言，它是划定任务边界与评估风险的关键信号：

• 工作区是干净还是已被修改？
• 是否存在未提交的冲突或遗漏？
• 当前处于功能分支还是主干保护区域？
• 近期提交记录是否与当前任务产生交集？

Claude Code 将这些动态指标纳入系统级上下文，意味着它并非将代码视为静态文本块，而是将版本库视为持续演进的动态资产。

该文件的核心意义在于将项目经验从“依赖人类沟通与临时口述”转化为可复用、可注入的系统知识。其直接收益体现在：

• 代码生成输出风格与架构决策高度一致；
• 修改操作严格遵循仓库既定规范，减少人工审查成本；
• 大幅降低因记忆缺失或沟通断层导致的重复性错误。

得益于这套上下文系统，Claude Code 在真实工作流中会表现出更强的“本地化”特征：它能更精准地遵守仓库约定、主动规避与工作区状态冲突的风险，并深刻理解特定任务背后的工程动因。这也是同一基础模型在独立聊天框与 Claude Code 环境中体验差异巨大的根本原因。

上下文注入属于能力增强器而非“全知解药”，其表现仍受限于客观物理边界：

• 系统提示词存在硬性长度限制，长尾信息或超大文件仍会被截断；
• Git 状态仅为采集瞬间的快照，不会在会话周期内自动持续刷新；
• CLAUDE.md 等记忆文件的质量、维护及时性与规范性直接决定了行为上限。

• 主动注入而非被动等待：AI 编程工具的核心优势不在于模型凭空更聪明，而在于底层的上下文采集器在对话启动前已自动准备好该知道的项目背景。
• 高信噪比压缩与缓存：通过并行抓取 Git 状态、条件化加载 CLAUDE.md，系统实现了复杂工程数据的提炼与防溢出管理。
• 规范即记忆：将团队约定与编码标准固化为机器可读文件，使 AI 行为从“随机应变”转向稳定可控的工程执行。
• 快照机制的客观局限：需明确上下文注入仅是增强器而非万能钥匙，实时状态一致性仍需依赖开发者手动触发或外部 CI/CD 工具链配合。