主题
Claude Code 工作原理
理解 agentic loop、内置工具以及 Claude Code 如何与你的项目交互。
是什么
Claude Code 是运行在终端中的 agentic（智能体）助手。它擅长编码，但也能完成任何你能从命令行做的事：写文档、运行构建、搜索文件、调研主题等。Claude Code 充当围绕 Claude 模型的 agentic harness（智能体外壳），提供工具、上下文管理与执行环境，把一个语言模型变成有能力的编码 agent。
它与只能看到当前文件的内联代码助手不同：因为 Claude 能看到整个项目，所以它可以跨文件工作——搜索相关文件、读取多个文件理解上下文、做协调一致的跨文件编辑、运行测试验证修复，并在你要求时提交更改。
怎么工作
- agentic loop（智能体循环）分三个阶段：gather context（收集上下文）、take action（采取行动）、verify results（验证结果），这些阶段会交织在一起并反复迭代直到任务完成。
- 循环由两个组件驱动：负责推理的 models（模型）和负责行动的 tools（工具）；每次工具调用返回的信息都会反馈进循环，影响 Claude 的下一步决策。
- 你也是循环的一部分：可在任意时刻打断以改变方向、补充上下文或要求换一种方法；Claude 自主工作但对你的输入保持响应。
- 内置工具分为五类：File operations（文件操作）、Search（搜索）、Execution（执行）、Web（网络）、Code intelligence（代码智能，需 code intelligence plugins）。Claude 还有 spawning subagents、向你提问等编排工具。
- 运行 claude 后，Claude Code 可访问：你的项目文件、终端、git 状态、CLAUDE.md、Auto memory，以及你配置的扩展（MCP servers、skills、subagents、Claude in Chrome）。
- 会话（session）以纯文本 JSONL 形式保存在 ~/.claude/projects/ 下，支持 rewind/resume/fork；每个新会话以全新的 context window 启动，不含此前会话历史。
- context window 容纳对话历史、文件内容、命令输出、CLAUDE.md、auto memory、已加载 skills 和系统指令；接近上限时 Claude 先清除较旧的工具输出，必要时再对对话做摘要（compaction），会保留你的请求与关键代码片段。
- 两个安全机制：checkpoints（每次文件编辑前快照，可撤销）与 permissions（控制 Claude 无需询问就能做的事）。
- 可通过 skills、MCP、hooks、subagents 在核心 agentic loop 之上扩展能力。
怎么配置 / 用法
切换模型与权限模式、控制上下文：
text
# 会话中切换模型，或启动时指定
/model
claude --model <name>
# 权限模式：Shift+Tab 循环切换
# Default / Auto-accept edits / Plan mode / Auto mode（research preview）
# 在 .claude/settings.json 中允许特定命令，免去每次询问
# 例如信任 npm test、git status
# 撤销文件更改：按 Esc 两次回退到先前状态
# 打断：按 Esc 立即停止；或输入纠正后回车（不停止当前工具）
# 上下文相关命令
/context # 查看上下文占用
/compact focus on the API changes # 带焦点压缩
/mcp # 查看每个 server 的上下文成本在 CLAUDE.md 中添加 "Compact Instructions" 区段可控制压缩时保留的内容。
什么时候用
- 需要跨多个文件协调修改、运行测试验证并按需提交的编码任务（如 fix the authentication bug）。
- 任何能从命令行完成的工作：写文档、运行构建、搜索文件、调研主题。
- 复杂问题先研究后编码时，用 plan mode（Shift+Tab 两次）先分析代码库再制定计划。
- 想让 Claude 自检工作时，提供测试用例、期望 UI 截图或明确的输出定义。
- 需要在本地、Cloud（Anthropic 托管 VM）或 Remote Control（浏览器控制本机）等不同环境执行时。
限制 / 坑
- checkpoints 仅覆盖文件更改且为会话本地、独立于 git；影响远程系统（数据库、API、部署）的操作无法 checkpoint，因此 Claude 在执行有外部副作用的命令前会询问。
- context 填满时会自动 compaction，早期对话中的详细指令可能丢失；持久规则应放进 CLAUDE.md 而非依赖对话历史。
- 若单个文件或工具输出过大导致每次摘要后上下文立即填满，Claude Code 在数次尝试后会停止 auto-compaction 并报 thrashing error 而非死循环。
- Auto mode 目前为 research preview（研究预览）。
- Code intelligence（查看类型错误、跳转定义、查找引用）需要安装 code intelligence plugins。
硬事实速查（11 条）
- 会话以纯文本 JSONL 文件保存在 ~/.claude/projects/ 下。
- Auto memory：MEMORY.md 的前 200 行或 25KB（以先到者为准）在每次会话开始时加载。
- 可用模型：Sonnet 适合大多数编码任务，Opus 为复杂架构决策提供更强推理；用 /model 切换或 claude --model <name> 启动。
- 权限模式四种：Default、Auto-accept edits（无需询问即可执行 mkdir、mv 等常见文件系统命令）、Plan mode（仅只读工具）、Auto mode（研究预览）。
- Esc 两次回退到先前文件状态；Esc 一次立即停止 Claude 并取消正在运行的工具调用。
- Plan mode 通过 Shift+Tab 两次进入；Shift+Tab 循环切换权限模式。
- 可在 .claude/settings.json 中允许特定命令（如 npm test、git status），权限可从组织级策略到个人偏好分层设置。
- claude --continue 或 claude --resume 在同一 session ID 下恢复并追加消息；--fork-session 或 /branch 复制历史到新 session ID 且不改动原会话。
- /resume picker 默认显示当前 worktree 的会话，可用键盘快捷键扩大到其它 worktree 或 project。
- MCP 工具定义默认 deferred、按需通过 tool search 加载，只有工具名占用上下文；用 /mcp 查看各 server 成本。
- 内置辅助命令：/init 引导创建 CLAUDE.md，/agents 配置自定义 subagents，/doctor 诊断安装问题，/context 查看上下文占用。