外观
Claude Code 运行机制与工程优化：运行机制篇
分册导航： 当前是“运行机制篇”，聚焦概念边界、Agent Loop、权限沙箱、上下文生命周期与项目文件；工程优化、项目实践、竞品评测和面试训练见 工程实践篇。
目录
1. 学习目标
- 理解 Claude Code 不是单一模型，而是“模型 + Agent Harness + 工具环境 + 安全控制 + 会话状态”的系统；
- 能从启动、上下文装配、模型推理、工具执行、Observation 回灌、验证和终止完整解释一次运行；
- 能说明
CLAUDE.md、.claude/settings*.json、Rules、Skills、Agents、.mcp.json、Worktree、Session 与 Auto Memory 等主要文件的职责、加载时机和 Git 边界； - 能说明 Prompt Caching、Compaction、延迟加载、Subagent、Hooks、LSP、Checkpoint 和 Worktree 分别优化什么；
- 能把“为什么强”拆成模型、上下文、工具、验证、安全、恢复和人机协作七个可评测维度；
- 能识别上下文污染、压缩丢信息、Prompt Injection、错误验证、并行冲突、缓存失效和远程副作用等风险；
- 能在面试中诚实区分官方事实、公开证据推断和闭源内部未知。
2. 面试结论
2.1 30 秒回答
Claude Code 本质上不是“会写代码的 Claude 聊天框”，而是围绕 Claude 模型构建的 Agentic Coding Harness：它把仓库指令、会话历史和工具定义装入上下文，让模型在“读取—搜索—编辑—执行—观察—验证”的循环中动态决定下一步，运行时负责权限、沙箱、状态、并发和恢复。它的竞争力通常来自强模型与成熟 Harness 的乘法效应，尤其是上下文分层、按需加载、真实终端闭环、可中断和可回滚；但它不是所有场景都最强，结论必须在同一仓库、预算、权限和验收测试下与竞品实测。
2.2 一分钟复述版
我会把 Claude Code 分成五层。第一层是 Claude 模型，负责理解目标、选择工具和根据结果修正计划；第二层是 Harness，负责组装 Prompt、维护 Agent Loop、调度工具和结束任务；第三层是上下文系统，把 System Prompt、CLAUDE.md、Auto Memory、Skill、MCP 工具、文件内容和历史结果按不同生命周期加载；第四层是执行系统，直接使用文件工具、Shell、Git、Web 和 LSP 在真实仓库中行动；第五层是控制系统，用 Permission、Sandbox、Checkpoint、Hook 和 Managed Settings 限制副作用。
它做得好的地方不是某一个“神奇 Prompt”，而是把多轮软件工程中的找证据、改代码、跑测试、看失败、继续修正串成低摩擦闭环，并针对上下文成本做 Prompt Cache、自动压缩、工具 Schema 延迟加载和 Subagent 隔离。不过 Claude Code 完整运行时不是开源参考实现，精确 System Prompt、内部压缩策略、调度启发式和训练方法无法从公开资料确认；而 Codex、Gemini CLI、GitHub Copilot Agent 等产品也在快速补齐相同原语，所以“更强”只能是条件性结论。
2.3 一句话技术判断
Claude Code 的核心优势不是“模型能生成代码”，而是把模型的概率性决策嵌入一个能获取真实上下文、执行真实工具、验证真实结果并限制真实副作用的工程闭环。
3. 面试官为什么问
- 概念区分：能否区分 Claude 模型、Claude Code 产品和 Claude Agent SDK；
- Agent 原理：是否真正理解 Tool Use 只是动作表达，Harness 才负责循环、权限、状态和终止；
- Context Engineering：能否解释为什么长上下文不等于有效上下文，以及缓存、压缩、按需加载怎样协同；
- 工程能力：是否关注测试、回滚、并行冲突、缓存命中、Token、延迟和可观测性；
- 安全意识：是否知道
CLAUDE.md是上下文而不是强制策略，Checkpoint 也不能回滚数据库和部署； - 方案权衡：能否把“我觉得更好用”变成可重复的竞品评测协议；
- 事实纪律：面对闭源产品，能否明确说出哪些公开可证、哪些只能推断、哪些不知道。
4. 概念、边界与证据等级
4.1 Claude Code 是什么
按 Anthropic 官方定义，Claude Code 是围绕 Claude 模型提供工具、上下文管理和执行环境的 Agentic Harness。它可以读取和修改文件、搜索代码、运行 Shell 与 Git、调用 Web 和代码智能工具，并把每次工具结果重新交给模型，直到模型给出最终结果或运行时因权限、预算、错误或用户输入而停止。
从系统职责看，可以拆成：
| 层次 | 核心职责 | 典型内容 | 决定性边界 |
|---|---|---|---|
| 模型决策层 | 理解目标、选择动作、修正计划 | Claude 模型、推理强度、Tool Use | 输出具有概率性，不能直接当权限或事实 |
| Harness 控制层 | 组织请求、循环和消息流 | Agent Loop、任务状态、Tool Result、终止 | 完整内部实现未公开 |
| Context 层 | 决定模型当前能看到什么 | System Prompt、CLAUDE.md、Memory、Skill、历史 | 窗口有限，相关性比总量更重要 |
| Execution 层 | 对真实环境产生可观测结果 | Read/Edit/Bash/Git/Web/LSP/MCP | 会产生本地或远程副作用 |
| Safety 层 | 限制动作并提供恢复 | Permission、Sandbox、Checkpoint、Policy | 不是绝对安全保证，覆盖范围不同 |
| Extension 层 | 注入领域能力或并行工作 | Skills、Hooks、Subagents、Agent Teams、Plugins | 会增加配置、Token、供应链和协调成本 |
4.2 它不是什么
- 不是 Claude 模型本身；同一模型放进不同 Harness，实际完成率可能不同；
- 不是普通聊天 UI；它的主要输出可能是仓库中的代码和测试结果，而不只是最后一段文字；
- 不是只调用一次函数的 Tool Calling；运行时会把 Observation 回灌并继续循环；
- 不是确定性编译器；模型仍可能读错文件、选错工具、过度修改或错误宣称完成；
- 不是安全边界本身；Prompt 指令不能替代 OS Sandbox、服务端授权和人工审批；
- 不是所有 Coding Agent 的唯一实现；Codex CLI、Gemini CLI 和 Copilot Agent 也采用相近的 Agent Loop 与工具执行范式。
4.3 三类证据必须分开
| 标记 | 含义 | 本文示例 |
|---|---|---|
| 官方可验证事实 | Anthropic 文档、工程博客、SDK 文档或公开仓库明确说明 | 会话写入本地 JSONL、文件编辑前建立快照、只读工具可并行、MCP Schema 默认延迟加载 |
| 基于证据的架构推断 | 多条公开行为能支持，但官方未公开精确实现 | 模型、默认 Coding Prompt、工具语义和 Harness 很可能经过联合迭代，形成协同优势 |
| 当前无法确认 | 没有足够公开证据，不应补造 | 完整 System Prompt 文本、Tool 选择内部打分、Compaction 使用的精确 Prompt/模型、内部训练数据和竞品控制实验 |
事实红线： Claude Agent SDK 暴露
claude_codeSystem Prompt Preset，并说明其中包含工具、编码风格、安全和环境指导；这证明存在完整预设，不等于公开了预设全文或所有运行时启发式。Anthropic 的 Claude Code 公共仓库采用“保留所有权利”的许可，也不能当作完整开源运行时源码阅读。
来源定位： Modifying system prompts；Claude Code LICENSE（访问日期：2026-07-10）。
4.4 “更强”的正确问题
不要问“Claude Code 是否绝对最强”，而应问：
- 在什么任务上：单文件补全、跨模块改造、调试、Issue 到 PR、代码审查还是云端异步任务？
- 使用什么模型、推理强度、版本、上下文和扩展？
- 是否给予同等 Shell、网络、MCP、依赖和仓库指令权限？
- 预算是 Token、费用、墙钟时间还是人工干预次数？
- 结果由谁验收：模型自述、编译器、测试、静态分析、隐藏测试还是人工 Review？
只有这些条件固定后，“强”才从体验判断变成工程结论。
4.5 小白直觉：新工程师进入“项目作战室”
小林第一天接手支付仓库，目标是修复“退款偶发失败”。冲突在于：他既不知道项目怎么启动，也不能碰生产数据库，更不能把个人测试账号提交进 Git。组长没有把整间公司的资料都堆到他桌上，而是按用途给了他一套作战室：
- 进门先读团队长期维护的项目手册，知道架构、构建命令和验收方式；
- 走到支付目录时，墙上才亮起支付模块专属规则；
- 需要排查数据库时，再取出数据库诊断手册，或请独立的数据库专家去查；
- 调用外部监控前，先从服务目录找到连接方式，再由门禁判断能否执行；
- 个人测试地址只写在自己的便笺里，修复过程和文件快照则保存在本机工作记录中。
最后，小林没有靠记住所有材料完成任务，而是让“该常驻的常驻、该按需的按需、该强制的由门禁强制、该留痕的落到本机记录”。这正是 Claude Code 项目文件分层的直觉。
| 作战室中的对象 | Claude Code 对应物 | 解决的问题 |
|---|---|---|
| 项目总手册 | CLAUDE.md | 每个相关会话都需要的架构、命令和团队约定 |
| 进入某部门才显示的 SOP | .claude/rules/*.md | 模块化规则，以及按路径延迟加载 |
| 临时取用的专业手册 | .claude/skills/<name>/SKILL.md | 可复用但不必永久占据 Context 的知识与流程 |
| 在独立房间工作的专家 | .claude/agents/*.md | 用独立 Context、工具和权限完成子任务 |
| 外部服务通讯录 | .mcp.json | 声明团队共享的 MCP Server 连接配置 |
| 门禁与自动检查 | .claude/settings.json 中的 Permission、Sandbox 与 Hooks | 约束工具、副作用和生命周期动作 |
| 个人便笺 | CLAUDE.local.md、settings.local.json、Auto Memory | 保存个人或本机范围的偏好与经验 |
| 工作录像与文件快照 | Session JSONL、file-history/ | Resume、审计和直接文件编辑的恢复 |
回到专业机制：这些文件并不是同一优先级的一包 Prompt。CLAUDE.md 与 Rules 影响模型可见上下文，Settings 和组织策略控制客户端行为，Skill 与 Agent 决定能力怎样按需装入或隔离，Session 与 Checkpoint 则保存运行轨迹和恢复材料。分层的价值是减少无关 Context、降低配置泄漏，并把自然语言建议与确定性控制分开。
类比边界： 作战室类比能解释“文件分工和加载时机”，但不能把模型想成会稳定遵守手册的人。CLAUDE.md 不是 IAM，Auto Memory 不是可信业务数据库，Session 不是远程审计系统，Checkpoint 也不能撤销 Bash、数据库、API、部署或消息发送产生的外部副作用。
5. 运行机制深度剖析
5.1 从一次 API 调用到持续 Agent Loop
LLM 在两次 API 请求之间不会自行保存会话状态。Claude Code 每一轮都要把当前有效上下文重新提交给模型：稳定的 System Prompt 与工具定义、项目上下文、此前对话和 Tool Result，再加本轮新输入。模型返回普通文本或一个/多个 Tool Use；如果是工具调用，Harness 校验并执行，再把结果追加为新 Observation，重新请求模型。
可以抽象为：
其中：
是用户目标； 是第 轮模型可见上下文； 是 Claude 模型产生动作的策略； 是回答、读取、搜索、编辑、命令、委派或请求用户等动作； 是当前权限、沙箱、预算和组织策略； 是受策略约束的工具与环境执行器；其返回仍可能受网络、进程和外部状态影响； 是真实环境返回的 Observation； 是追加、裁剪、压缩和持久化上下文的运行时逻辑。
公式不是 Claude Code 源码，也不假设各模块实现公开；它表达的是官方文档可观察到的控制关系：模型提议，权限与调度规则由运行时裁决，工具在真实环境执行，结果再影响下一轮。
来源定位： How the agent loop works（消息类型、Tool Result 回灌、结束条件与工具调度，访问日期：2026-07-10）。
5.1.1 技术清单
| 技术点 ID | 技术点/环节 | 类型 | 采用方案 | 链路职责 | 版本/证据边界 |
|---|---|---|---|---|---|
| TP-CLAUDE-CONTEXT | 上下文装配与续航 | 运行时/配置 | CLAUDE.md、Rules、Skill/MCP 延迟加载、Prompt Cache、Compaction 与 Auto Memory | 把稳定规则、按需能力和增长历史分层送入模型，并在窗口压力下压缩续航 | 公开文档可验证行为与配置；核心 Harness 实现、训练细节和内部排序算法未完整公开 |
| TP-CLAUDE-EXECUTION | 工具调度与安全执行 | Runtime/基础设施 | Claude Code Harness + Tool Use + Permission + 可选 OS Sandbox + Hook | 将模型动作转换成 Read、Edit、Bash、LSP、Web 或 MCP 执行，并在真实副作用前裁决权限 | Permission 与 Sandbox 能力以当前平台和组织策略为准；模型不能绕过服务端授权 |
| TP-CLAUDE-RECOVERY | 会话、文件与并行恢复 | 存储/版本控制 | Session JSONL + Resume/Fork + File Checkpoint + Git/Worktree | 保存会话轨迹、支持分叉与文件级回退，并隔离并行 Writer | Checkpoint 不覆盖 Bash、数据库、部署和消息等外部副作用；远程状态仍需幂等、对账与补偿 |
5.2 启动阶段：先建立“可工作的世界模型”
新会话大致需要形成三层稳定前缀和一层增长历史：
- System Prompt 层：Claude Code 的 Coding 指令、输出方式、工具使用与安全指导，以及当前可用的内置工具定义；
- Project Context 层：项目根和层级中的
CLAUDE.md、Auto Memory、非路径限定规则等； - Extension Metadata 层：Skill 简短描述、MCP 工具名称及其他可发现能力；完整内容尽量按需加载；
- Conversation 层：用户消息、模型响应、文件读取结果、命令输出、Tool Use 和 Tool Result，随循环持续增长。
如果是 /resume，Harness 会恢复已保存会话；如果是新会话，则不会自动继承旧对话，只能依靠 CLAUDE.md、Auto Memory 或外部项目产物获得跨会话知识。官方文档说明，本地会话消息、工具调用和结果写入 ~/.claude/projects/ 下的 JSONL；Auto Memory 则以仓库为范围保存可复用学习。
图：架构｜Claude Code Harness 的上下文、执行与恢复组件边界
替代文本： 用户请求进入 Claude Code Harness；Harness 将稳定 System Prompt、项目指令和按需扩展与增长中的会话历史组装后交给 Claude 模型。模型提出工具动作，权限引擎先裁决，Bash 再受 OS 沙箱约束；文件、终端、Git、Web、LSP 或 MCP 返回 Observation，写入会话并进入下一轮。Checkpoint 和 JSONL 会话分别支持文件回滚与会话恢复。
图表加载中…
读图结论： Claude Code 的“智能”来自模型，但可持续工作的能力来自 Harness 把上下文、工具反馈、安全裁决和恢复机制闭成一条环；模型不能绕过运行时权限与沙箱边界直接修改世界。
5.3 一轮执行：模型不是直接运行 Shell
一次典型修复可能经历：
- 用户提出“修复失败测试”；
- 模型选择 Bash 运行目标测试；
- Permission Engine 根据 allow/ask/deny、权限模式和组织策略决定是否允许；
- 若是 Bash，命令及子进程在启用时还受文件系统与网络 Sandbox 限制；
- Harness 执行命令，捕获 stdout、stderr、退出码或拒绝原因；
- Tool Result 进入上下文，模型根据真实错误搜索文件；
- 模型调用 Read/Grep/LSP 获取局部证据，再提出 Edit；
- 文件修改前建立 Checkpoint；
- 修改后再次执行测试或读取 LSP 诊断；
- 模型认为验收条件满足后返回最终消息，否则继续循环。
图：技术调用流程｜Claude Code 从失败测试到验证修复的时序
替代文本： 用户请求后，Claude 模型先让 Harness 执行测试；权限裁决通过，且启用 Sandbox 时相关边界检查通过，工具才返回失败信息。模型再搜索、读取和编辑，Harness 在编辑前快照文件，随后 LSP 和测试返回新证据。默认在模型不再请求工具时结束；配置外置验收后还可因验收失败继续。
图表加载中…
读图结论： 高质量 Coding Agent 的关键不是第一次生成正确 Patch，而是先尊重权限裁决，再让真实执行结果或拒绝原因成为下一步输入，持续迭代到外部验证通过。
权限返回“允许”时才能直接执行；返回“请求批准”时 Harness 必须等待用户，返回“拒绝”时则把拒绝原因作为 Tool Result 交还模型。模型可以据此改用只读证据或调整方案，但不能把拒绝解释成命令已经运行。
5.4 工具调度：安全并行，而不是所有动作并发
Claude Agent SDK 文档明确说明：同一轮中的只读工具，例如 Read、Glob、Grep 和标记为只读的 MCP 工具，可以并发执行；Edit、Write、Bash 等有状态或可能产生冲突的工具顺序执行。这个决策兼顾了两点：
- 并行读取能降低大型仓库探索的墙钟时间；
- 顺序写入避免两个动作基于过期状态同时修改同一文件或环境。
自定义工具如果想并发，需要显式提供只读语义。由此可见，工具注解不只是给模型看的描述，也会影响 Harness 的调度与安全性；错误标记有副作用的工具为只读，可能造成竞态和重复副作用。
来源定位： Agent SDK - Tool execution（只读并发、有状态工具顺序执行，访问日期：2026-07-10）。
5.5 权限与沙箱：两个互补控制面
Permission 和 Sandbox 不能混为一谈：
- Permission 适用于 Bash、Read、Edit、WebFetch、MCP 等工具，决定允许、询问还是拒绝；
- Sandbox 是 OS 级执行约束，主要限制 Bash 命令及其子进程的文件系统和网络访问；
- Managed Settings 可以从组织层强制限制规则、MCP、Hook、Plugin 与绕过模式；
- Protected Paths 对
.git、Shell 配置和关键配置提供额外保护； - Checkpoint 在文件编辑前保存本地文件版本，但不能撤销数据库、API、部署、发送消息或 Git Remote 等外部副作用。
Anthropic 的沙箱工程文章说明其 macOS 使用 Seatbelt、Linux 使用 Bubblewrap，并同时做文件系统与网络隔离。文章还报告 Anthropic 内部使用中权限提示减少 84%；这是厂商内部测量，能说明设计目标和内部结果，不能直接外推为所有仓库的独立基准。
来源定位： Permissions；Sandboxing；Claude Code sandboxing engineering note（访问日期：2026-07-10）。
5.6 上下文生命周期：工作记忆、持久规则与会话存档不是一回事
| 载体 | 生命周期 | 适合内容 | 不适合内容 |
|---|---|---|---|
| System Prompt | 会话级稳定前缀 | 工具、安全、Coding 行为 | 项目不断变化的细节 |
CLAUDE.md | 每个相关会话加载 | 构建命令、架构、团队约定、硬性工作流程 | 大段偶用 API 文档、秘密、可执行权限 |
| Path Rules | 命中路径时加载 | 特定语言或目录规则 | 全局都必须知道的约束 |
| Skill | 描述常驻、正文按需 | 可复用专项知识与操作流程 | 真正的 IAM 或不可绕过策略 |
| Auto Memory | 跨会话、仓库范围 | 反复出现的构建经验、调试规律和偏好 | 未验证事实、秘密、必须强制执行的规则 |
| Conversation | 当前会话持续增长 | 当前目标、证据、工具结果和决策 | 永久规则和完整日志仓库 |
| Session JSONL | 本地持久化 | 恢复、分叉、审计当前工作 | 自动进入新会话的长期知识 |
| 外部 Artifact | 跨窗口和跨 Agent | 计划、进度、测试证据、设计决策 | 未版本化的临时猜测 |
官方文档明确指出，CLAUDE.md 是在 System Prompt 后作为项目上下文提供给模型，并不是强制配置；模糊、冲突或过长的指令仍可能不被遵循。Auto Memory 的入口只在会话开始时加载前 200 行或 25KB，详细主题文件按需读取。这些限制体现了一条重要原则：持久化不等于全部常驻上下文，常驻也不等于强制执行。
来源定位： Memory and CLAUDE.md；Prompt caching layers（访问日期：2026-07-10）。
5.7 结束、恢复和分叉
一次 Loop 可以因以下条件结束：
- 模型产生最终回答；
- 工具权限被拒绝且没有替代路径；
- 需要用户确认、补充信息或纠偏；
- 达到模型、Token、费用、时间或工具限制；
- 发生不可恢复错误；
- 用户按 Escape 中断。
会话 JSONL 让用户恢复或分叉对话，文件快照让用户回退本地修改，Git 则承担版本协作和持久提交。三者职责不同：Conversation Rewind 回退可见对话历史，File Checkpoint 回退文件，Git Commit/Worktree 管理长期版本与并行分支。远程系统必须另外设计幂等、对账和补偿。
5.8 扩展面：每种机制只解决一种主要问题
| 扩展 | 主要解决什么 | Context 成本 | 典型误用 |
|---|---|---|---|
CLAUDE.md | 每轮都需要的项目规则 | 已加载的根/祖先内容进入稳定项目上下文；子目录内容可按访问路径延迟加载 | 塞入所有文档，导致噪声和遵循下降 |
| Skill | 按需专业知识和可复用流程 | 描述常驻，正文调用时加载 | 把权限策略写成自然语言 Skill |
| MCP | 外部系统的工具和数据接口 | 工具名先加载，Schema 尽量延迟 | 一次连接大量不用的工具和秘密 |
| Hook | 模型外的生命周期自动化与策略 | Hook 代码在模型外执行；返回文本、拒绝原因或 Additional Context 可进入上下文 | 用 Prompt 代替本应强制执行的程序化 Hook |
| Subagent | 隔离高噪声子任务和专门角色 | 默认非 Fork 使用独立窗口并返回摘要 | 任务强依赖主对话却仍委派，丢失细节 |
| Agent Team | 独立会话协作与直接通信 | 多份完整上下文，成本较高 | 细小任务也开团队，协调成本超过收益 |
| LSP | 精确符号导航和编辑后诊断 | 通常低，可减少广泛文件读取 | 未安装语言插件却假设已有语义索引 |
| Worktree | 隔离并行文件修改 | 主要是磁盘与 Git 成本 | 多 Agent 共享同一工作树同时写入 |
这套扩展体系的成熟之处在于“按生命周期分工”：总是需要的放 CLAUDE.md，偶尔需要的放 Skill，外部能力放 MCP，必须强制的程序化规则放 Permission 或命令型 Hook，高噪声任务交给 Subagent，并行写入用 Worktree 隔离。把所有问题都交给一个超长 Prompt，通常会更贵、更不稳定，也更难排障。
5.9 Claude Code 项目主要文件与用途
先说明范围：Claude Code 核心 Runtime 不是完整开源参考实现，因此不能依据公共仓库诚实地画出“内部源码模块树”。本节解释的是一个普通代码仓库接入 Claude Code 后，团队真正会维护和排查的主要文件，以及仓库外由 Claude Code 在本机生成的状态文件。
图：Claude Code 项目文件的共享、本地与运行时职责
替代文本： 仓库根目录中的 CLAUDE.md、.claude 配置、.mcp.json 和 .worktreeinclude 构成可提交的团队层；CLAUDE.local.md 与 settings.local.json 构成当前项目的个人层；用户目录中的全局配置、Session JSONL、Auto Memory 与文件快照构成本机层；.claude/worktrees 是运行时生成的隔离工作目录。
图表加载中…
读图结论： 团队事实应落在可审查、可版本化的仓库文件中；个人偏好和含源码轨迹的运行数据留在本机；是否进入 Context、是否强制执行、是否用于恢复是三个不同维度。
5.9.1 团队最常维护的核心文件
| 文件或目录 | 主要用途 | 何时加载或使用 | Git 建议 | 关键边界 |
|---|---|---|---|---|
CLAUDE.md 或 .claude/CLAUDE.md | 项目架构、构建/测试命令、编码规范、常用工作流 | 当前目录及祖先目录中的文件在会话启动时完整加载；子目录文件在 Claude 读取该目录内容时加载 | 提交 | 作为 System Prompt 之后的项目上下文影响行为，不是权限强制层；官方建议保持精炼 |
CLAUDE.local.md | 当前项目的个人 URL、测试数据或工作偏好 | 与同级 CLAUDE.md 一起加载，并排在其后 | 不提交，手工创建时加入 .gitignore | 只存在当前工作树；多个 Worktree 不会自动共享 |
.claude/rules/**/*.md | 把测试、安全、API 等规则拆成主题文件 | 无 paths Frontmatter 时启动加载；有 paths 时读取匹配文件后加载 | 提交 | 适合持续规则；一次性、多步骤流程更适合 Skill |
.claude/settings.json | 团队共享的 Permission、Hook、环境变量、Sandbox、模型默认值和 Plugin 设置 | 启动时按配置作用域与优先级合并 | 提交，但不能写密钥 | Settings 可参与确定性控制；CLAUDE.md 只能给行为指导 |
.claude/settings.local.json | 当前机器、当前项目的个人覆盖项或实验配置 | Local Scope 优先于 Project 与 User Scope | 不提交；Claude Code 创建时会配置 Git Ignore，手工创建时需自行忽略 | 不是团队配置事实源，也不应依赖他人的机器路径 |
.claude/skills/<name>/SKILL.md | 可复用的领域知识、模板、脚本和操作流程 | 启动时主要发现名称与描述；用户调用或 Claude 判断相关时加载正文 | 项目 Skill 提交 | 适合渐进式披露；需要强制执行的安全规则不能只写在 Skill |
.claude/agents/*.md | 定义自定义 Subagent 的 Prompt、模型、工具、权限、Skills、Memory 或 Worktree 隔离 | 被显式选择或主 Agent 委派时创建独立执行上下文 | 项目 Agent 提交 | 非 Fork Agent 不继承主对话全文；委派消息和预载内容必须足够 |
.mcp.json | 声明项目级、团队共享的 MCP Server | 项目被信任且用户批准该 Server 后建立连接和暴露工具 | 可提交配置，密钥通过环境变量注入 | 不要提交 Token；Local/User MCP 状态保存在 ~/.claude.json，不是本文件 |
.worktreeinclude | 用 .gitignore 语法列出创建 Worktree 时要复制的本地文件 | Claude Code 创建 Worktree 时处理 | 提交 | 只复制“匹配且已经被 Git 忽略”的文件；自定义 WorktreeCreate Hook 会接管该流程 |
5.9.2 可选扩展和兼容文件
| 文件或目录 | 用途 | 使用建议 |
|---|---|---|
.claude/commands/*.md | 兼容旧式单文件自定义命令 | 仍可使用，但新能力优先写成包含 SKILL.md 的 Skill |
.claude/output-styles/*.md | 定义角色、语气和输出格式 | 只负责表达风格，不应承载项目架构或安全策略 |
.claude/agent-memory/<name>/ | 为特定 Subagent 保存持久 Memory | 只有确实需要跨会话专家记忆时使用；提交前审查事实与敏感信息 |
.claude/workflows/*.js | 保存可复用的 Dynamic Workflow 脚本 | 属于版本变化较快的高级能力，使用前核对当前版本和运行边界 |
.claude/hooks/ | 团队可自行约定的 Hook 脚本存放目录 | 不是自动发现的特殊目录；Hook 必须在 Settings 的 hooks 字段注册，脚本也可以放在其他位置 |
.claude/worktrees/<name>/ | claude --worktree 默认创建的隔离工作目录 | 运行时产物，不是配置源，不应提交；用 Git/Claude Code 的 Worktree 生命周期管理 |
5.9.3 仓库外的个人配置与运行数据
| 本机路径 | 用途 | 安全与生命周期 |
|---|---|---|
~/.claude/CLAUDE.md | 个人跨项目指令 | 不提交；项目规则仍应放项目内 |
~/.claude/settings.json | 个人跨项目设置、工具和 Plugin 偏好 | 不提交；Managed、CLI、Local、Project、User 之间存在优先级 |
~/.claude.json | App 状态、OAuth、UI 开关和个人/本地 MCP 配置 | 由 Claude Code 管理，不提交，也不应复制给他人 |
~/.claude/projects/<project>/<session>.jsonl | 完整会话、消息、Tool Call 与 Tool Result，支持 Resume/Fork | 明文且可能含源码、命令输出或秘密；默认按 cleanupPeriodDays 清理，不应把内部 JSONL Schema 当稳定 API |
~/.claude/projects/<project>/memory/MEMORY.md | Auto Memory 的简短索引；同一 Git 仓库的子目录和 Worktree 共享 | 启动加载前 200 行或 25KB 中先达到的上限，主题文件按需读取；它是可编辑笔记，不是可信数据库 |
~/.claude/file-history/<session>/ | Claude 直接编辑文件前的 Checkpoint 快照 | 只覆盖 Claude 文件工具捕获的修改；不覆盖 Bash、数据库、API、部署与其他远程副作用 |
5.9.4 AGENTS.md 和普通工程文件怎么处理
Claude Code 原生读取 CLAUDE.md，不会自动读取 AGENTS.md。如果仓库已经用 AGENTS.md 服务多个 Coding Agent，可在项目 CLAUDE.md 中显式写：
markdown
@AGENTS.md
## Claude Code
- Run the authoritative test command before reporting completion.也可以在不需要 Claude 专属内容时建立符号链接。/init 能参考现有 AGENTS.md 生成 CLAUDE.md，但这不等于后续会话会原生加载 AGENTS.md。
README.md、package.json、pyproject.toml、Makefile、测试配置、.github/workflows/*、源码和测试仍然是项目真正的工程事实源；Claude Code 只会在读取、搜索或被 @import 后获得其内容。CLAUDE.md 最好记录“权威命令和事实源在哪里”，不要把这些文件整份复制进去，否则会制造重复、过期和 Context 浪费。
一个实用的最小结构是：先用 CLAUDE.md 固定全局事实和验收命令，再按需要增加 rules/、skills/、agents/、settings.json 与 .mcp.json；个人差异只进入 Local 文件，运行轨迹留在 ~/.claude。排障时可运行 /memory 确认实际加载了哪些 CLAUDE.md、Local 文件和 Rules，再检查 Settings Scope、工具批准与 Session 证据。
来源定位： Explore the .claude directory、Memory and CLAUDE.md、Settings、Skills、Subagents、MCP、Hooks、Worktrees（访问日期：2026-07-11）。
总结
一句话记忆： Claude Code 运行机制的核心，是由 Harness 把 Claude 的概率性决策、真实工具反馈、权限控制、上下文治理和恢复状态组织成可持续验证的 Agent Loop。
- 模型负责提出动作，Harness 负责上下文装配、工具执行、Observation 回灌与终止控制；
- System Prompt、项目规则、按需扩展和会话历史具有不同加载时机，长上下文不能替代上下文治理；
- Permission、Sandbox 与 Checkpoint 分别约束动作许可、操作系统边界和文件恢复，不能互相替代；
CLAUDE.md、Rules、Settings、Skills、Agents、MCP、Session 与 Memory 应按上下文、控制、扩展和状态职责分层；- 公开资料可以验证产品行为，但完整 System Prompt、私有调度策略和内部训练方法仍应明确标注为未知。