# Claude Code 工作原理与扩展地图

> Claude Code 的 agentic loop、模型、工具、上下文加载、执行环境、扩展能力和 5 分钟/1 小时缓存影响。

URL: https://docs.passion8.cc/docs/claude-code/how-it-works
Language: zh-CN
Publisher: Passion8

这页把官方 Overview、How Claude Code works 和 Extend Claude Code 合成一张结构图。先理解 Claude Code 怎么工作,再决定该写 `CLAUDE.md`、Skill、Subagent、MCP、Hook 还是 Plugin。




Claude Code 不是普通聊天窗口。它是围绕 Claude 模型的一层 agentic harness:负责加载项目上下文、暴露工具、执行命令、管理权限、保存会话,并把每一步结果反馈给模型继续决策。




## Agentic loop

Claude Code 的核心循环是三步,但真实任务会反复穿插:

| 阶段 | Claude 做什么 | 你怎么配合 |
| --- | --- | --- |
| Gather context | 读文件、搜索符号、查看 git 状态、加载 `CLAUDE.md`、rules、skills 和 MCP 信息 | 给目标、目录、日志、截图和边界 |
| Take action | 编辑文件、运行命令、调用 MCP、派发 subagent、写计划或生成产物 | 控制权限模式,及时打断错误方向 |
| Verify results | 跑测试、lint、build、查看 diff、用浏览器或 GUI 验证 | 给验收命令和失败证据 |

这个循环不是固定脚本。模型会根据上一轮工具结果决定下一步,可能先查代码,再改文件,再跑测试,再根据失败回头修。

## 模型和工具分工

| 部分 | 作用 | 典型配置 |
| --- | --- | --- |
| 模型 | 理解代码、拆任务、判断下一步、解释结果 | `/model`、`--model`、`/effort`、fast mode、fallback model |
| 工具 | 让 Claude 真正行动,例如读文件、改代码、跑命令、访问网页、调用外部系统 | permissions、MCP、Hooks、tool search、sandbox |
| Harness | 负责会话、上下文、权限、工具调用、checkpoint、transcript、状态栏和 UI | settings、`CLAUDE_CONFIG_DIR`、`~/.claude/projects` |

模型切换和 effort 切换会进入 prompt cache key。中途频繁 `/model` 或 `/effort` 会让 5m/1h TTL 都失去意义,因为缓存不能跨不同模型配置复用。

## 内置能力地图

| 能力类别 | Claude 能做什么 | 本地文档 |
| --- | --- | --- |
| 文件操作 | Read、Edit、Write、MultiEdit、检查 diff | [工具参考](https://docs.passion8.cc/docs/claude-code/tools) |
| 搜索 | Glob、Grep、代码结构探索、history 搜索 | [大型代码库与 Monorepo](https://docs.passion8.cc/docs/claude-code/large-codebases) |
| 执行 | Bash、测试、构建、git、后台 Bash、Monitor | [交互模式与终端体验](https://docs.passion8.cc/docs/claude-code/interactive-terminal) |
| Web 与浏览器 | WebFetch、WebSearch、Chrome、Computer Use | [Chrome 与 Computer Use](https://docs.passion8.cc/docs/claude-code/chrome-computer-use) |
| 外部系统 | MCP、Channels、GitHub、Slack、数据库、工单 | [MCP 工具接入](https://docs.passion8.cc/docs/claude-code/mcp) |
| 自动化 | Headless、Routines、/loop、CI、Code Review | [Headless 自动化](https://docs.passion8.cc/docs/claude-code/headless) |

## 执行入口

| 入口 | 代码在哪里运行 | Provider 和缓存边界 |
| --- | --- | --- |
| Terminal CLI | 本机工作目录 | 最容易接 Passion8,缓存和本地配置可控 |
| VS Code / JetBrains | IDE 管理的 Claude Code 进程 | 要确认 IDE 继承 Base URL、Token、代理和证书 |
| Desktop | Desktop 管理的本地或组织环境 | 取决于登录方式和组织策略 |
| Web / Slack / cloud review | Anthropic 云端环境 | 通常不继承本机 Passion8 env 和本地 prompt cache |
| Agent SDK | 你的服务启动 `claude` 子进程 | 每个 worker/session 要自己规划状态、隔离和缓存 |

如果从本地 CLI 切到 web/cloud review,不要假设会共享 5m/1h 缓存。它们通常是不同 session、不同 provider、不同执行环境。

## 上下文加载顺序

Claude Code 会自动加载多类上下文。越靠前、越稳定的内容,越容易成为 prompt cache 的可复用前缀。

| 来源 | 何时加载 | 缓存影响 |
| --- | --- | --- |
| System prompt 和工具定义 | 会话开始和能力变化时 | 最关键的缓存前缀 |
| `CLAUDE.md` | 启动时加载当前目录及父级,子目录按需加载 | 改后通常新会话才生效,也会改变缓存前缀 |
| `.claude/rules/` | 会话开始或匹配文件时加载 | path-specific rules 可减少无关上下文 |
| Skill 描述 | 会话开始用于模型判断是否调用 | 描述越多,每轮固定成本越高 |
| Skill 正文 | 调用或匹配时加载 | 作为消息追加,通常不破坏旧前缀 |
| MCP 工具名和 schema | server 启动时或按 tool search 延迟加载 | 工具 schema upfront 时最容易造成 miss |
| Hook 输出 | Hook 返回内容时进入上下文 | 输出越长,后续每轮成本越高 |
| Subagent 结果 | 子代理总结返回主会话 | 中间过程不占主会话上下文 |




不要把百科式长文都塞进 `CLAUDE.md`。稳定、短、每次都需要的规则放 `CLAUDE.md`;偶尔用到的参考资料放 Skill;外部系统接 MCP;必须强制执行的规则放 Hook 或 permissions。




## 扩展选择

| 你遇到的问题 | 用什么 | 为什么 |
| --- | --- | --- |
| Claude 总是忘记构建命令或目录约定 | `CLAUDE.md` | 每个会话都要知道 |
| 某个流程经常重复,但不是每次都用 | Skill | 按需加载,可用 `/skill-name` 调用 |
| 一个规则只对某些目录或文件类型有效 | `.claude/rules/` | 降低根 `CLAUDE.md` 噪音 |
| 需要访问 Jira、Slack、数据库、浏览器、内部 API | MCP | 外部系统连接和认证由 server 管理 |
| 需要让 Claude 自动格式化、拦截危险命令、发通知 | Hook | 生命周期事件上确定性执行 |
| 一个任务要读很多文件,但主会话不需要中间过程 | Subagent | 隔离上下文,只返回摘要 |
| 多个 Claude session 要互相协作 | Agent Teams | 独立 session 之间通信和共享任务 |
| 多个项目要共享同一套 skills/hooks/MCP | Plugin | 版本化、可分发、可市场化 |

## 容易混淆的能力

| 对比 | 结论 |
| --- | --- |
| `CLAUDE.md` vs Skill | `CLAUDE.md` 是 always-on,Skill 是 on-demand。根文件超过 200 行时通常该拆 Skill 或 rules。 |
| Skill vs Subagent | Skill 是知识或流程,Subagent 是独立 worker。Skill 增加主上下文,Subagent 隔离主上下文。 |
| MCP vs Skill | MCP 提供工具和数据连接,Skill 教 Claude 如何使用这些工具。两者经常组合。 |
| Hook vs Skill | Hook 必定在事件上运行,适合强制规则。Skill 需要模型理解,适合需要推理的流程。 |
| Subagent vs Agent Team | Subagent 回报给主会话,Agent Team 是多个完整 Claude Code session 互相协作。 |

## 缓存和成本视角

| 动作 | 5m / 1h 影响 |
| --- | --- |
| 连续在同一会话追问 | 命中会刷新 TTL,5m 足够高频工作 |
| 离开 10 到 45 分钟回来 | 5m 通常冷,1h 更可能继续读旧前缀 |
| 改 `CLAUDE.md` 后重启 | 前缀变,5m/1h 都会重新写缓存 |
| 增删 MCP server | 工具定义变化,容易 miss;tool search 更友好 |
| 调用 Skill | 正文作为消息追加,通常保留旧前缀 |
| 大量 Hook 输出 | 不一定破坏前缀,但会抬高后续输入 token |
| Subagent 做大范围探索 | 子代理自己付 token,主会话只拿摘要,主上下文更干净 |
| Plugin 带 MCP | 可能同时改变 skill 描述和工具定义,首次 reload 后要观察 cache creation |

更细的逐命令影响看 [命令与缓存影响](https://docs.passion8.cc/docs/claude-code/command-cache)。底层 TTL 和 usage 字段看 [Prompt 缓存](https://docs.passion8.cc/docs/claude-code/prompt-caching)。

## 建议的扩展顺序

1. 先跑 `/init`,把项目基础约定写进 `CLAUDE.md`。
2. 把敏感路径放进 permissions deny,不要只写自然语言提醒。
3. 把重复 prompt 固化成 Skill 或自定义命令。
4. 给必须执行的格式化、审计、通知写 Hook。
5. 需要外部系统时再接 MCP,并确认 tool search。
6. 大任务再引入 Subagent、Worktree、Agent Teams 或 SDK。
7. 多项目复用后再打包成 Plugin 或内部 marketplace。

## 官方参考

- [Overview](https://code.claude.com/docs/en/overview.md)
- [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md)
- [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md)
- [Context window](https://code.claude.com/docs/en/context-window.md)
- [Prompt caching](https://code.claude.com/docs/en/prompt-caching.md)
- [Plugins](https://code.claude.com/docs/en/plugins.md)