基于 Claude Code 源码深度分析的Claude Code 使用最佳实践

基于 Claude Code 源码深度分析，从使用者视角整理的实战指南。
源码版本：2026-03-31 快照，~1,884 个 TypeScript 文件，~110,000 行代码。

一、CLAUDE.md：你和 Claude 之间的持久合同

CLAUDE.md 不是备忘录，是每次对话自动加载的系统提示。Claude 没有跨会话记忆，不告诉它就是不知道。

加载优先级（越靠后越优先）

/etc/claude-code/CLAUDE.md          企业 MDM 统一策略（只读）
~/.claude/CLAUDE.md                 个人全局规则
父目录 CLAUDE.md（逐级向上）        父项目规则
./CLAUDE.md                         项目主规则
./.claude/CLAUDE.md                 Claude 专属配置
./.claude/rules/*.md                细粒度规则文件（按文件名排序加载）
./CLAUDE.local.md                   本地私有规则（加入 .gitignore）

写什么最值钱

• 架构决策及原因：不只是「用 React」，而是「用 React + Ink 因为需要终端 UI，不要改这层」。
• 硬性禁令：「禁止直接修改 migrations/」「SQL 必须走 ORM」。口头说会被遗忘，写进来就是强制约束。
• 代码风格原则：不只是格式，而是「本项目用 Result 类型而不是抛异常」「工具函数不加 docstring」。
• 已知陷阱：踩过的坑、legacy 问题、不能动的文件。
• 测试约束：「集成测试必须打真实数据库，禁止 mock」（防止测试通过但生产挂掉）。

文件结构建议

./CLAUDE.md                    ← 项目总纲（提交 git）
./.claude/rules/               ← 拆分的细粒度规则
    api-conventions.md
    testing-rules.md
    security.md
./CLAUDE.local.md              ← 个人私有覆盖（.gitignore）

@include 引用外部文件

@./docs/api-conventions.md
@~/shared-rules/security.md

支持相对路径、~/ 家目录、绝对路径。文件不存在静默忽略，循环引用自动跳过。

二、Auto Memory：跨会话的持久记忆系统

Claude Code 内置了一套文件化记忆系统，存放在 ~/.claude/projects/<项目路径>/memory/。每次对话开始时自动加载 MEMORY.md 索引（最多 200 行 / 25,000 字节，超出截断）。

四种记忆类型

什么不该存进记忆

源码中有明确约束——以下内容不应保存，因为可以从当前项目状态推导：
- 代码模式、架构、文件路径（读代码就能知道）
- Git 历史和变更记录（git log 更权威）
- 调试方案（fix 在代码里，上下文在 commit message 里）
- 已在 CLAUDE.md 中记录的内容
- 只在本次会话有用的临时状态

记忆文件格式

---
name: 测试约束
description: 集成测试必须打真实数据库 — 用于所有测试决策
type: feedback
---

禁止在集成测试中 mock 数据库。

**Why:** 上季度 mock 测试通过但生产迁移失败，排查了两天。
**How to apply:** 写任何测试时，若需要数据库，必须启动真实实例。

记忆索引 MEMORY.md

- [测试约束](feedback_testing.md) — 集成测试必须打真实数据库，禁止 mock
- [项目背景](project_context.md) — 合规驱动的认证中间件重写，优先合规而非便利

每行一条，保持在 150 字符以内。MEMORY.md 超过 200 行后内容会被截断。

三、权限模式：让 Claude 的自主度匹配任务风险

源码中定义了五种权限模式，对应不同的信任级别：

# 启动时指定权限模式
claude --permission-mode acceptEdits
claude --permission-mode bypassPermissions  # 危险：仅用于沙箱

权限规则：精细化控制工具调用

在 settings.json 中可以配置 allow / deny / ask 规则：

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm test*)",
      "FileEdit(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)"
    ],
    "ask": [
      "Bash(git push*)"
    ]
  }
}

权限拒绝的熔断机制

源码揭示了一个重要行为：当你连续拒绝同一工具 3 次，或累计拒绝 20 次时，系统会自动切换到「总是询问」模式，不再尝试自动判断。这意味着：
- 如果你经常拒绝某类操作，把它加进 deny 规则比手动拒绝更高效
- 频繁拒绝会降低 Claude 的自主度，影响工作效率

四、上下文压缩：避免会话中途崩溃

Claude Code 有多层上下文管理机制，理解它们能让你更好地控制长会话。

自动压缩（AutoCompact）

当上下文接近模型限制时自动触发，触发阈值为：

有效上下文窗口 = 模型上下文窗口 - 20,000 token（为输出预留）
自动压缩触发线 = 有效上下文窗口 - 13,000 token（缓冲）

压缩会将历史对话总结为摘要，保留关键信息继续工作。失败超过 3 次后熔断，不再重试（防止无限浪费 API 调用）。

手动压缩

/compact                          使用默认策略压缩
/compact 只保留认证模块相关的上下文   带自定义指令压缩

建议：在切换任务方向前主动 /compact，比等自动触发效果更好，因为你可以指定保留什么。

环境变量覆盖

# 测试自动压缩行为时，人为缩小窗口
CLAUDE_CODE_AUTO_COMPACT_WINDOW=50000 claude

# 按百分比设置压缩触发阈值
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 claude

五、Hooks：把 Claude 嵌入你的工作流自动化

Hooks 是 Claude Code 最被低估的功能。它允许你在特定事件发生时自动执行 shell 命令、HTTP 请求或 AI prompt，实现真正的工作流自动化。

完整的 Hook 事件列表（来自源码）

配置方式（settings.json）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Hook] Bash executed' >> ~/.claude/audit.log"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -message 'Claude 已完成任务'"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash(git push*)",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查这个 git push 命令是否安全，如果目标是 main 分支且没有经过 PR，阻止执行并说明原因"
          }
        ]
      }
    ]
  }
}

Hook 类型

实战场景

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "FileEdit",
        "hooks": [{ "type": "command", "command": "npm run lint --fix" }]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [{ "type": "command", "command": "git add -A && git stash" }]
      }
    ]
  }
}

六、MCP：把任何外部系统接入 Claude

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，让 Claude 能与外部工具、数据库、API 交互。Claude Code 的 MCP 支持极其完整。

传输协议选择

配置范围（7 种作用域）

local      → 当前项目（.claude/settings.local.json）
project    → 项目级（.claude/settings.json，提交 git）
user       → 个人全局（~/.claude/settings.json）
dynamic    → 运行时动态注入
enterprise → 企业 MDM 下发（只读）
claudeai   → claude.ai 平台
managed    → 托管配置

配置示例

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/项目路径"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your_token" }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

常用 MCP 管理命令

/mcp                  查看已连接的 MCP 服务器状态
/mcp add              添加 MCP 服务器

七、多智能体与并行任务

Claude Code 内置了完整的多智能体框架，支持协调模式和子智能体并行执行。

Agent 工具的正确用法

子智能体适合以下场景，不要滥用：
- 独立并行任务：互相不依赖的研究或搜索任务同时发出
- 保护主上下文：把可能产生大量输出的搜索委托给子智能体
- 专项任务：使用特定类型的智能体（Explore、Plan 等）

不适合子智能体的场景：
- 简单的文件读取或代码搜索（用 Glob/Grep 直接查）
- 任务结果相互依赖时（必须串行等待）

内置智能体类型（源码中的 built-in agents）

global-purpose   通用多步骤任务
Explore          快速代码库探索（只读）
Plan             架构设计和实现规划
claude-code-guide Claude Code 文档问答

Worktree 隔离执行

# 在隔离的 git worktree 中执行（不影响主工作区）
# 使用 /worktree 命令或 EnterWorktree 工具

子智能体支持 isolation: "worktree" 参数，在临时 git worktree 中运行，完成后无修改则自动清理，有修改则返回 worktree 路径供审查。

八、Skills：可复用的提示词模块

Skills 是 Claude Code 的可复用命令系统，类似宏，可以被斜杠命令触发。

内置 Skills 示例

/commit          生成规范的 git commit 信息
/review-pr       代码审查
/simplify        审查已改代码的质量和可简化空间
/schedule        管理定时任务
/claude-api      调用 Claude API 构建应用

自定义 Skill

在 .claude/skills/ 目录创建 markdown 文件，用 YAML frontmatter 声明触发条件：

---
name: security-review
description: 对代码变更进行安全审查
trigger: /security-review
---

审查以下内容是否存在安全漏洞：
1. SQL 注入（用户输入是否直接拼接 SQL）
2. XSS（用户输入是否未经转义输出到 HTML）
3. 命令注入（用户输入是否传给 shell 命令）
4. 敏感信息泄露（密钥、token 是否硬编码）

对每个发现给出：风险级别、代码位置、修复建议。

Hooks 与 Skills 联动

源码中 registerSkillHooks.ts 展示了 Skills 可以注册为 Hooks 触发，实现「特定事件自动执行某个 Skill」的模式：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "FileEdit(src/api/**)",
        "hooks": [{ "type": "prompt", "prompt": "运行 /security-review 检查这次 API 变更" }]
      }
    ]
  }
}

九、模型选择与成本控制

可用模型层级（源码推断）

/model          查看和切换当前模型
/fast           切换 Fast 模式（相同模型，更快输出）

成本追踪

Claude Code 内置了精细的成本追踪系统，记录每次会话的：
- 输入 token / 输出 token
- 缓存读取 token / 缓存创建 token（提示词缓存可大幅降低成本）
- 总 USD 成本
- API 耗时 / 工具执行耗时
- 代码行变更数（增删行）

/cost           查看本次会话的 token 用量和成本
/usage          查看历史用量统计

提示词缓存（重要）

源码中的 cacheCreationInputTokens 和 cacheReadInputTokens 表明 Claude Code 自动利用 Anthropic 的提示词缓存：
- 重复的系统提示（CLAUDE.md 内容）会被缓存
- 长对话中前缀内容缓存后，后续调用成本大幅下降
- 会话越长、CLAUDE.md 越稳定，缓存命中率越高

十、Plan 模式：先对齐方案再动手

对于复杂任务，直接让 Claude 开始写代码是效率最低的方式。Plan 模式让你在执行前审查并批准方案。

何时使用 Plan 模式

源码中 EnterPlanModeTool 的触发条件说明了适用场景：
- 新功能实现（涉及多处代码修改）
- 存在多种技术方案的任务
- 会影响现有行为的修改
- 需要做架构决策的任务
- 会跨越 2-3 个以上文件的变更
- 需求不明确，需要先探索再规划

不需要 Plan 模式的场景：
- 单行或几行的小修改
- 明显的 bug 修复
- 用户已经给出了非常详细的指令

使用方式

claude --permission-mode plan   # 以 plan 模式启动，只规划不执行

或在对话中：

请先给我一个实现方案，不要开始写代码

Plan 模式的工作流

1. Claude 用 Glob/Grep/Read 探索代码库
2. 设计实现方案，识别关键文件
3. 考虑架构权衡
4. 输出步骤化计划供你审查
5. 你批准后才开始执行

十一、文件操作的安全机制

理解 Claude Code 的文件操作机制，能帮你避免意外和风险。

FileEdit 的读取前置要求

源码中 FileEditTool 的描述明确要求：必须先用 Read 工具读取文件，才能编辑。这是个强制约束，不是建议。其原因是 FileStateCache 会追踪已读取的文件，防止 Claude 在未了解现有内容的情况下盲目修改。

实践意义：如果 Claude 在没读文件的情况下尝试编辑，工具调用会失败并报错。

old_string 唯一性要求

Edit 工具要求 old_string 在文件中唯一。如果不唯一，编辑会失败。遇到这种情况：
- 提供更多上下文（包含更多周围代码）
- 或使用 replace_all 参数替换所有匹配项

工具输出大小限制

源码注释揭示：Write/Edit 工具有 ~8,192 token 的传输层硬限制，超出会静默截断，产生损坏文件且无法恢复。

最佳实践：
- 超过 50 行的内容分块写入
- 每块以唯一占位符结尾，下一块用 Edit 追加
- 宁可多次写入，不要单次超限

权限边界：additionalDirectories

{
  "permissions": {
    "additionalDirectories": ["/shared/configs", "../sibling-project"]
  }
}

默认情况下 Claude 只能操作当前工作目录。通过 additionalDirectories 可扩展访问范围，但要谨慎——这会让 Claude 能修改工作目录外的文件。

十二、斜杠命令速查表

源码 commands/ 目录下有约 50 个命令，以下是最实用的分类整理：

会话管理

/clear            清空对话历史（保留 CLAUDE.md 上下文）
/compact          压缩历史，可加自定义摘要指令
/resume           恢复上次会话
/exit             退出

模型与性能

/model            查看/切换模型
/fast             切换 Fast 模式
/cost             查看本次会话成本
/usage            查看历史用量

代码工作流

/commit           生成并执行 git commit
/pr_comments      查看 PR 评论
/review           代码审查
/diff             查看变更 diff
/branch           分支操作

配置与环境

/config           查看/修改配置
/mcp              管理 MCP 服务器
/memory           管理记忆文件
/hooks            管理 Hooks 配置
/permissions      查看权限设置
/doctor           诊断环境问题

界面与体验

/theme            切换终端主题
/vim              切换 Vim 模式
/voice            语音输入（实验性）
/keybindings      自定义快捷键
/output-style     输出样式设置

调试与诊断

/doctor           环境诊断
/debug-tool-call  调试工具调用
/status           查看系统状态
/stats            统计信息
/version          版本信息

十三、IDE 集成：Bridge 模式

Claude Code 通过 bridge/ 模块与 VS Code 和 JetBrains 深度集成，不只是在 IDE 里开一个终端那么简单。

Bridge 模式提供的能力

• LSP 集成：Claude 能获取语言服务器的诊断信息（错误、警告），在修改代码时直接感知编译错误
• 文件同步：IDE 中的文件变更会通过 FileChanged 事件通知 Claude
• JWT 身份验证：IDE 扩展和 CLI 之间通过 JWT 安全通信
• 远程会话：支持在云端运行 Claude Code，本地 IDE 连接远程实例

实践建议

在 IDE 集成模式下，Claude 能看到你的光标位置和选中内容，可以直接说「修复这里的错误」而不用复制粘贴代码。

十四、安全与合规

企业策略（MDM）

企业可通过 /etc/claude-code/CLAUDE.md 和 policySettings 统一下发：
- 强制的 CLAUDE.md 内容
- 禁止的工具列表
- 允许的模型范围
- allowManagedHooksOnly：只允许企业管理的 Hooks，禁止用户自定义

防 PII 设计

源码中有一个独特的类型名：

type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS

这个类型名本身就是审计约束——开发者必须在命名时主动确认数据不含代码或文件路径，才会用这个类型。这是一种用类型系统强制安全审查的设计模式，值得借鉴。

SSRF 防护

源码中有 ssrfGuard.ts，对 HTTP Hook 的目标 URL 进行 SSRF 检查，防止 Hook 被用于探测内网服务。

十五、高效使用的核心原则

基于源码揭示的系统设计，总结以下原则：

1. 越具体越好

Claude 没有跨会话记忆，越具体的指令效果越好。CLAUDE.md 里的「不要抛异常，用 Result 类型」比「写好代码」有用一百倍。

2. 不要重复解释，写进 CLAUDE.md

如果你在两次不同的会话里说了同一句话，它就应该在 CLAUDE.md 里。

3. 用 feedback 记忆保存纠正

当你纠正了 Claude 的某个行为，用 /memory 把它记下来。下次会话自动生效，不用再说一遍。

4. 信任内部 API，不要过度防御

源码的设计原则是：只在系统边界（用户输入、外部 API）做验证，内部调用信任框架保证。不要让 Claude 给每个内部函数加多余的防御代码。

5. 复杂任务先 Plan

任何跨越 3 个以上文件、或有多种实现路径的任务，先让 Claude 出方案，确认后再执行。方案对齐的成本远低于错误返工。

6. Hooks 是工作流的胶水

把重复的手动步骤（lint、格式化、通知、日志）变成 PostToolUse Hook，让 Claude 执行后自动触发，而不是每次手动补充指令。

7. 分块写大文件

Write/Edit 工具有 ~8,192 token 的硬限制，超出静默截断产生损坏文件。任何超过 50 行的写入都要分块。

8. 用拒绝规则代替手动拒绝

与其每次手动拒绝某个危险操作，不如把它加进 permissions.deny。连续拒绝 3 次或累计 20 次后，系统会进入「总是询问」模式，影响自动化效率。

附录：关键环境变量

# API 配置
ANTHROPIC_API_KEY=sk-ant-...        API 密钥
ANTHROPIC_BASE_URL=https://...      自定义 API 端点（第三方兼容）

# 模型覆盖
ANTHROPIC_DEFAULT_SONNET_MODEL=...  覆盖默认 Sonnet 模型

# 上下文压缩
CLAUDE_CODE_AUTO_COMPACT_WINDOW=50000   人工限制上下文窗口（测试用）
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80      压缩触发百分比

# 功能开关
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1  禁用后台任务
DISABLE_COMPACT=1                        禁用压缩命令

# 调试
CLAUDE_CODE_DEBUG=1                     开启调试日志

本文档基于 Claude Code 2026-03-31 源码快照分析，部分内部机制随版本更新可能有变化。