前言

Github：https://github.com/HealerJean

博客：http://blog.healerjean.com

一、Claude Code 工作原理

1、Claude Code 到底是什么

核心定义：Claude Code 是终端运行的 AI 智能代理助手，不只是简单聊天写代码，而是能自主完成：读文件、改代码、跑命令、查网络、修 Bug、重构项目、运行测试、管理 Git 等全流程工程任务。

和普通代码助手最大区别

• 普通助手：只看当前单个文件，一问一答
• Claude Code：看整个项目全目录，懂代码依赖、项目架构、Git 状态，自主循环执行任务、自我验证纠错

核心架构-由两大核心驱动：

1. 推理模型：理解代码、拆解任务、做决策（Sonnet / Opus
2. 执行工具：读文件、改代码、跑命令、搜网络、查语法错误
   • Claude Code 就是把大模型 + 内置工具 + 上下文管理封装成可自主干活的编程智能体。

2、核心重点：代理循环（Agentic Loop）—— 一切功能的底层引擎

1）代理循环三阶段

任何任务都会走 收集上下文 → 采取行动 → 验证结果 循环，可重复迭代，直到任务完成。

收集上下文：扫描项目结构、读取代码、加载 CLAUDE.md、读取 Git 状态、加载自动内存、理解需求和项目规则。

采取行动：自主选择工具：读文件 / 编辑代码 / 执行命令 / 搜索网络 / 启动子代理，拆解多步骤自动执行。

验证结果：运行测试、检查报错、对比预期效果；不合格就回到前两步重新修改，自动纠错。

2）不同任务的循环差异

• 单纯查问题 / 问代码规范：只走收集上下文就结束

• 修 Bug / 小功能开发：三阶段循环多次

• 大型重构 / 架构调整：大量验证、多轮迭代

二、扩展功能

1、核心基础认知

1）什么是 Claude Code 扩展层

Claude Code 本身自带代码推理模型 + 内置工具（文件读写、搜索、命令执行、网络访问），能完成基础编码任务；扩展层是自定义能力，用来：

• 固化项目 / 团队约定知识
• 接入外部服务、数据库、IM、浏览器
• 封装可复用工作流
• 事件自动化、任务隔离并行
• 打包多仓库复用 / 市场分发

2）触发 & 落地顺序

不用一次性配置所有功能，按遇到问题再添加的节奏：

2、VS

1）CLAUDE.md vs Skill

两者都存储说明，但它们的加载方式和用途不同。

2）Skills vs subagents

3）Subagent vs Agent team

两者都并行化工作，但它们在架构上不同：

4）Hook vs Skill

3、按功能的上下文成本

节约成本：

• CLAUDE.md 精简到 200 行，冗余移到 Skills

• 不常用 Skill 加 disable-model-invocation: true，零开销

• 多文件检索优先用 Subagent，不占主会话上下文

• 固定自动化逻辑放 Hooks，零上下文消耗

• 超大代码库开启 Code intelligence，减少文件读取

4、扩展功能详细解释

1）CLAUDE.md：持久会话上下文

核心作用：每次会话自动加载，全局持久生效，存放项目固定规则、约定、命令，无需每次重复叮嘱 Claude。

适用场景：项目技术栈、包管理器规范、提交规则、禁止修改目录、构建 / 测试命令、编码强制约定。

使用技巧：Claude 两次违背约定，直接把规则补进 CLAUDE.md，不要每次聊天口头纠正。

关键特性

• 会话启动全自动加载
• 可通过 @path 导入其他规则文件
• 不能主动触发工作流命令
• 建议控制在 200 行以内，冗余内容拆到 Skills

a、实战案例（项目根目录 CLAUDE.md 模板）

# 项目基础约定
## 技术栈
React18 + TypeScript + Vite + TailwindCSS

## 包管理器
统一使用 pnpm，禁止使用 npm/yarn

## 构建&测试命令
- 本地启动：pnpm dev
- 打包：pnpm build
- 单测：pnpm test
- 代码校验：pnpm lint

## 目录约束
- 禁止修改：node_modules/、dist/、.env、public/静态资源
- 业务代码统一放在 src/ 下

## 编码规范
- 组件使用函数式组件，禁止class组件
- 所有接口请求必须加异常捕获
- 变量使用小驼峰，常量全大写

2） Skills：可复用知识 & 可调用工作流

核心作用：最灵活的扩展，markdown 格式文件，存放参考文档、操作流程、任务清单；支持手动 /deploy 调用或 Claude 自动匹配加载。

适用场景：API 文档、代码审查清单、部署流程、调试剧本、团队风格指南。

关键特性

• 按需加载，非会话常驻
• 支持 /技能名 手动触发
• 可被 Subagent 预加载
• 分参考型（给知识）、操作型（执行流程）

目录位置：.claude/skills/xxx.md

使用技巧：

• 添加 disable-model-invocation: true，仅手动调用，Claude 不会自动加载，节省上下文、避免误触发。

a、代码审查 Skill（.claude/skills/code-review.md）

使用：Claude会话输入 /code-review 或直接说 帮我审查本次代码变更。

---
name: code-review
description: 代码质量审查，输入review即可触发，检查安全、性能、规范
---
# 代码审查清单
## 安全检查
- 禁止硬编码密钥、接口地址
- 入参必须做参数校验
## 性能检查
- 避免循环内重复请求
- 大列表必须做虚拟滚动
## 规范检查
- 遵循项目TS类型定义
- 新增函数必须写注释

b、部署自动化 Skill

---
name: deploy
description: 项目打包部署流程，输入/deploy执行
---
# 部署步骤
1. 执行 pnpm lint 校验代码
2. 执行 pnpm build 打包
3. 检查dist目录是否生成成功
4. 输出部署完成提示

3）Subagents ：隔离子代理

核心作用：独立隔离上下文的任务分身，单独运行推理、读取大量文件，只返回摘要结果，不污染主会话上下文。

适用场景：多文件源码调研、批量文件分析、并行子任务、不想让中间日志占满主对话。

关键特性

• 独立上下文窗口，不占用主会话令牌
• 只返回最终摘要，隐藏中间过程
• 可预加载指定 Skills
• 适合：读几十份文件、大范围检索、专项核查

a、实战用法1：会话直接指令：

用 subagent 帮我全局搜索所有axios请求，整理统一封装点

b、实战用法2：自定义 Subagent 配置（agents/file-analyze.md）

---
name: file-analyzer
description: 批量文件分析子代理
model: haiku
tools: ["Read","Grep","Glob"]
---
帮我遍历src下所有ts文件，统计接口数量、未加类型定义的函数，汇总成精简报告

4）Agent teams ：代理团队

核心作用：多个独立 Claude Code 会话组成团队，互相发消息、共享任务、自主协作。

适用场景：复杂功能开发、多维度并行审查（安全 / 性能 / 规范）、竞争假设调试、大型架构调研。

关键特性

• 每个代理都是独立实例，可互相通信
• 自主协调任务，无需主代理逐一调度
• 令牌成本比 Subagent 高
• 默认禁用，需手动开启

实战场景：

同时启动 3 个代理（三者互相沟通，输出综合审查报告。）：

• 安全代理：检查漏洞、敏感信息
• 性能代理：分析接口耗时、渲染性能
• 规范代理：校验代码风格、命名规范

5）Code intelligence 代码智能

核心作用：对接语言服务器（LSP），实现符号跳转、定义查找、实时类型错误、引用检索。

适用场景：TS/Java/Go 等类型化语言、超大代码库（grep 低效不准确）。

核心价值：不用通读整个文件，直接跳定义、查引用，减少文件读取，节省上下文成本。

使用方式：安装对应语言的 code intelligence 插件，自动生效：编辑文件后自动检测类型错误，查询符号时自动定位定义。

6）MCP 外部服务连接协议

核心作用：Claude Code 的外部接口标准，连接数据库、Slack、浏览器、内网接口、本地工具。

适用场景：查询业务数据库、发送 Slack 通知、自动化浏览器操作、调用内网服务。

核心特性

• MCP 负责连接 + 鉴权 + 工具暴露
• 搭配 Skill 存放使用规范、数据模型、查询模板
• 解耦外部连接和业务使用知识

实战组合案例

1. MCP 服务：连接 MySQL 数据库，提供查询 / 插入工具
2. 编写 Skill：定义库表结构、常用查询语句、字段规范
3. 使用：直接告诉 Claude 查询用户表近7天注册数据，自动通过 MCP 执行，按 Skill 规范返回结果

常见接入：数据库（MySQL/PostgreSQL）、Slack 消息推送、浏览器自动化、本地脚本调用。

7）Hooks 生命周期事件钩子

核心作用：监听 Claude Code 生命周期事件（文件编辑、命令执行、会话启动、工具调用），自动运行脚本 / HTTP 请求 / 子代理。

适用场景：自动格式化、编辑后自动 lint、会话结束发通知、禁止高危命令、保存自动校验。

核心特性

• 事件触发，无需人工干预
• 默认零上下文成本，外部运行
• 适合做强制规则、自动化护栏（比 CLAUDE.md 文字约束更可靠）

常用触发事件

• SessionStart：会话启动
• PostToolUse：工具执行后（文件编辑 / 写入）
• PreToolUse：工具执行前（可拦截高危操作）

a、实战案例 ：编辑后自动 Prettier` 格式化

在 .claude/settings.json 配置：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

b、实战案例 2：禁止执行 rm -rf / 高危命令

8）Plugins 功能打包分发

核心作用：把 Skills + Hooks + Subagents + MCP 服务 打包成一个可安装单元，支持多仓库复用、市场分发。

适用场景：多项目共用一套审查 / 部署 / 校验规则、团队统一配置分发。

核心特性

• Plugin 内 Skill 自带命名空间（如 /my-plugin:review），避免冲突
• 一键安装，无需逐个配置扩展
• 适合团队标准化、开源分享

三、claude 目录

1、核心基础认知

1）两个 .claude 目录

a、项目级目录

路径：项目根目录 ./.claude/

• 作用：项目专属规则、技能、子代理、权限、Hooks
• 版本：可提交到 Git，团队全员共享统一配置
• 适用：编码规范、项目命令、团队工作流、MCP 服务

b、全局级目录

路径：~/.claude

• 自定义路径：可设置环境变量 CLAUDE_CONFIG_DIR 改位置
• 作用：个人全局偏好、会话记录、插件、全局技能、自动内存
• 版本：绝不提交 Git，只作用于你本机所有项目
• 适用：个人编码习惯、全局插件、会话历史、主题配色、快捷键

2、完整目录树结构

1）项目仓库完整结构

your-project/
├── CLAUDE.md                # 项目全局约定（提交Git）
├── CLAUDE.local.md          # 个人私有偏好（自动gitignore）
├── .mcp.json                # 项目MCP外部服务配置（提交Git）
├── .worktreeinclude         # Git worktrees 同步配置
│
└── .claude/
    ├── settings.json        # 项目权限、Hooks、环境变量（提交Git）
    ├── settings.local.json  # 个人本地覆盖配置（gitignore）
    ├── rules/               # 模块化路径规则（按目录/语言加载）
    ├── skills/              # 可复用技能 /xxx 调用
    ├── commands/            # 自定义斜杠命令
    ├── agents/              # 自定义 Subagents 子代理
    ├── agent-memory/        # 子代理持久内存
    ├── output-styles/       # 自定义AI输出格式
    └── hooks/               # 生命周期钩子脚本

2）全局～/.claude 完整结构

~/.claude/
├── settings.json        # 全局默认设置
├── rules/               # 全局通用规则
├── skills/              # 全局所有项目可用技能
├── agents/              # 全局子代理
├── plugins/             # 已安装插件市场包
├── projects/            # 所有项目会话记录、对话日志
├── file-history/        # 文件编辑快照（用于回退）
├── history.jsonl        # 你所有输入过的指令历史
├── stats-cache.json     # Token 用量统计 /usage 命令
├── debug/               # 调试日志
├── paste-cache/         # 粘贴内容缓存
├── image-cache/         # 图片缓存
└── 各类自动生成缓存目录

3、核心文件

1）项目根目录文件

a、CLAUDE.md

• 范围：项目级 + 全局均可存在
• 加载：每个会话自动全量加载
• 用途：项目架构、包管理器、编码强制约定、禁止修改目录
• Git：✅ 提交，团队共享
• 建议：控制在 200 行内，冗余拆到 .claude/rules/

b、CLAUDE.local.md

• 范围：仅当前项目个人私有
• 加载：和 CLAUDE.md 一起自动加载
• 用途：你个人对此项目的特殊偏好，不干扰团队
• Git：❌ 必须加入 .gitignore，不提交

c、.mcp.json

• 范围：仅项目级
• 用途：配置项目专属 MCP 外部服务（数据库、Slack、浏览器）
• Git：✅ 提交，团队共用一套外部连接配置

2）.claude 目录核心文件

a、settings.json

• 范围：项目 / 全局都有
• 用途：权限控制、允许 / 拦截命令、Hooks 配置、环境变量、模型默认值
• Git：✅ 项目版提交，全局版本地私有

b、settings.local.json

• 范围：仅项目个人本地
• 用途：覆盖项目默认配置，自己单独改权限、环境变量
• Git：❌ gitignore，只自己生效

c、rules/ 目录

• 存放：按语言 / 目录拆分的规范 xxx.md
• 加载：可按文件路径门控，只在匹配目录时加载，节省上下文
• 适用：TS 规则、Vue 规则、后端接口规范，拆分减轻 CLAUDE.md 负担
• Git：✅ 提交共享

d、skills/ 目录

• 存放：可复用工作流、文档、审查清单，用 /技能名 调用
• 分项目级（本项目用）、全局级（所有项目通用）
• Git：✅ 项目技能提交，个人全局技能不提交

e、agents/ 目录

• 存放：自定义 Subagents 子代理配置
• 可预加载指定 skills、限定工具、隔离上下文
• Git：✅ 项目专属代理提交，通用代理放全局

f、output-styles/ 目录

• 自定义 Claude 输出文案格式、代码注释风格、返回语气
• 统一团队 AI输出规范

3）全局～/.claude 独有文件

a、plugins/

• 存放通过 claude plugin 安装的插件包
• 自动版本管理、7 天清理无用旧版本
• 所有项目共用插件能力

b、history.jsonl

• 记录你所有输入过的指令，终端向上箭头可回溯
• 不建议删，方便复用历史命令

c、file-history/

• 每次文件编辑自动快照，按两次 Esc 回退靠它
• 自动 30 天清理

4、实战经验

1）快速选文件

2）Git 忽略规范

# Claude 个人私有配置
CLAUDE.local.md
.claude/settings.local.json

# Claude 自动缓存、本地临时文件
~/.claude/  # 全局本来就不在仓库，不用管
.claude/**/cache/
.claude/**/temp/

3）应用数据自动清理 & 手动清理

4）自动清理规则

~/.claude 下大部分会话日志、工具输出、文件快照 默认 30 天自动删除

可通过配置修改 cleanupPeriodDays 调整天数。

b、. 永久保留不自动删

• history.jsonl：指令历史

• stats-cache.json：Token 用量统计

• plugins 已安装插件包

c、手动清理命令（实用）

# 预览要删除的项目缓存，不实际删除
claude project purge ~/work/你的项目路径 --dry-run

# 直接清理单个项目所有会话记录、快照、缓存
claude project purge ~/work/你的项目路径

# 清理所有项目缓存（慎用）
claude project purge --all

d、删除后会丢失什么

• 删除 ~/.claude/projects/ → 无法恢复历史会话

• 删除 file-history/ → 无法 Esc 回退文件修改

• 删除 history.jsonl → 终端向上箭头找不到历史指令

5）隐私安全建议

Claude 会把读取的 .env 密钥、命令输出凭证存入会话明文日志。

优化方案：

1. 缩短自动清理天数 cleanupPeriodDays
2. 用权限规则禁止读取凭证文件
3. 设置环境变量 CLAUDE_CODE_SKIP_PROMPT_HISTORY 关闭日志记录
4. 一次性任务用 --no-session-persistence 不保存会话

5）新手落地实操步骤

1. 项目根目录新建 CLAUDE.md 写入项目技术栈、包管理器、编码规则
2. 新建 .claude 文件夹，创建 settings.json 配置允许的命令、Hooks
3. 新建 .claude/skills/ 放代码审查、部署技能
4. 新建 .claude/rules/ 拆分 TS / 业务规范，精简 CLAUDE.md
5. 在 .gitignore 忽略 *.local.* 私有文件
6. 全局 ~/.claude/skills 放自己通用的调试、查询技能，所有项目可用\
7. 配置 MCP 就新建 .mcp.json 提交团队共享

五、Prompt Caching

1、Prompt Caching 是什么

提示缓存：让 Claude Code 不用每一轮都完整重跑全量上下文，复用之前已经处理过的固定内容，更快、更省 Token、更省钱。

• 没有缓存：每轮把「系统提示 + 项目规则 + 全部历史对话」重新计算一遍
• 有缓存：只处理最新变化的内容，前面不变的前缀直接读缓存，缓存 Token 仅约原价 10%

Claude Code 默认全自动开启缓存，你不用手动开，只需要懂哪些操作会搞坏缓存、怎么保住缓存命中率。

2、底层工作原理

1）核心机制：前缀精确匹配

每一次发消息，都会把完整上下文发给模型；

API 会匹配请求最开头的前缀，只要前缀一字不变 → 直接读缓存；

只要前缀任意一处改动 → 后面所有缓存全部失效，整段重算、重写缓存。

重点：不是按文件缓存、不是按段落缓存，是从头开始整段前缀精确匹配。

2）上下文三层结构（缓存分层逻辑）

Claude 刻意把请求内容按「变动频率从低到高」排序，最大化缓存命中率：

3、缓存失效

1）必失效高危操作（尽量别在任务中途做）

• 会话中途 切换模型 /model opus/sonnet

• 切换 工作量级别 /effort high/low
• 连接 / 断开 MCP 服务器（工具定义变了，系统层改动）
• 会话中途 全盘禁止 / 放行工具（如禁止 Bash、WebFetch）
• 执行 /compact 手动压缩对话历史
• 升级 Claude Code 版本
• 用 --resume 恢复超长历史会话

2）不会破坏缓存的安全操作

这些操作只追加在对话末尾，不改前缀，缓存完好无损：

• 编辑项目普通业务代码文件
• 会话中途修改 CLAUDE.md（改了也不生效，要重启 //clear 才加载）
• 切换权限模式（默认 / 自动编辑 / Plan 模式）
• 调用 Skills、自定义命令
• 运行 /recap 会话总结
• 用 /rewind 回退到历史对话
• 生成 Subagents 子代理

4、FQA

1）对话压缩 /compact 深度解析

1./compact 做了什么？

答案：用精简摘要替换冗长历史对话，缩短上下文、减少冗余。

2. 缓存代价

• 压缩会破坏对话层前缀，必须重建对话缓存
• 但会保留系统层、项目上下文层缓存，不用全量重算

3. 最佳使用时机

• 不要在任务中途压缩；

• 放在任务结束、自然停顿时执行，把缓存重建开销放在空闲间隙。

4. 替代优选：/rewind

答案：想放弃当前错误思路，优先用 /rewind 回退旧回合，直接复用历史缓存，比 /compact 更省成本。

2）缓存生命周期

1. 缓存自动过期：缓存长时间不使用会过期，每次命中都会刷新计时，连续工作永久保持缓存有效。

2. 两种 TTL 时长

• 5 分钟：短时缓存，便宜、过期快
• 1 小时：长时缓存，跨休息仍保留，适合长会话

1. 不同身份默认 TTL

• Claude 订阅用户：默认 1 小时 TTL，不额外收费
• 超订阅额度后：自动降级 5 分钟
• API 密钥 / Bedrock / 第三方：默认 5 分钟

1. 手动强制修改 TTL 环境变量

   # 开启1小时长缓存（API/第三方用）
   export ENABLE_PROMPT_CACHING_1H=1
      
   # 强制固定5分钟缓存
   export FORCE_PROMPT_CACHING_5M=1
   

3）缓存生效范围 & 会话隔离

1. 按目录隔离：不同项目目录、git worktree 互相不共享缓存
2. 同目录多会话：同一项目开多个终端会话，共享缓存，互相命中
3. 子代理 Subagent
   • 子代理独立缓存，首次调用无命中，自己慢慢预热
   • 子代理默认只有 5 分钟 TTL，哪怕主会话是订阅 1 小时
   • 父会话缓存不受子代理任何影响
4. 会话分叉 Fork：分叉会话继承父会话完整缓存，开局直接命中

4）实战最佳实践

1. 会话开局固定配置：任务一开始就定好：模型 /effort 级别 / MCP 服务，中途尽量不改。

2. CLAUDE.md 提前定稿：开会话前把规则写全，会话中途尽量不修改；必须改就重启会话。

3. 避免中途切换 Plan 模式：OpusPlan 会在 Opus/Sonnet 之间自动切模型，频繁切换 = 频繁重建缓存。

4. MCP 服务尽量稳定：不要频繁增删 MCP 服务；MCP 尽量会话开局就连好，中途少变动。

5. 压缩选时机：任务做完再 /compact，别做一半压缩。走错路优先 /rewind 回退。

6. 长任务尽量不中断：少用 --resume 恢复超长会话，容易缓存失效、Token 暴涨。

7. 动态内容放对话尾部：时间戳、动态变量、临时提示不要写在系统层，追加到对话末尾，不破坏前缀缓存。