Claude Code 最佳实践：从「能用」到「用得好」的 15 个关键技巧

最近 GitHub 上有个仓库火了------claude-code-best-practice，4.6 万 star，登顶 GitHub Trending 第一。

作者 Shayan Rais 把 Claude Code 的用法从底层拆透了，涵盖记忆系统、子代理、技能模块、Hook 机制等全链路。我花了几个小时通读了整个仓库，把最有价值的部分提炼出来，结合我自己的使用经验，整理成这篇实操指南。

如果你已经在用 Claude Code，这篇文章至少能让你的效率再翻一倍。

---

一、大多数人用错的第一件事：上下文管理

Claude Code 现在支持 100 万 token 的上下文窗口，听起来很大，但实际上------

在 30-40 万 token 时，模型表现就开始退化了。

这是 claude-code-best-practice 仓库里提到的一个核心概念：Context Rot（上下文腐烂）。模型并不会在塞满 100 万 token 之后才变差，而是远远提前就开始丢精度、忘指令、漏细节。

怎么做？

手动 /compact，不要等系统自动触发。

系统自动压缩触发时，上下文已经在退化区间了。正确做法是在 50% 左右 就手动执行 /compact。

更好的做法：带提示词压缩。

比如输入 /compact 保留 auth 重构的上下文，丢掉之前调试测试的部分。

有针对性地告诉 Claude 保留什么、丢弃什么，压缩质量远好于盲压。

还有一个反直觉的操作：Rewind 优于修正

当 Claude 的一次操作出了问题，很多人的本能反应是在对话里纠正它。但更好的做法是：按两次 Esc 回退到出错之前的节点，然后重新给指令。

原因很简单：失败的尝试会留在上下文里，持续污染后续的判断。回退到干净的状态重来，比在脏上下文里修补更高效。

---

二、CLAUDE.md 文件：你的 AI 工程师"入职手册"

CLAUDE.md 是 Claude Code 的记忆核心------每次启动时自动加载的指令文件。但大多数人要么不写，要么写成了一坨无用的长文档。

最佳实践：控制在 200 行以内

Claude Code 创始人 Boris Cherny 在多次访谈中反复强调这个数字。HumanLayer 团队甚至把他们的 CLAUDE.md 压缩到了 60 行。

为什么？指令越长，被忽略的概率越高。 模型会在大量文本中"走神"。

核心原则："任何开发者启动 Claude，说'跑测试'，第一次就能成功"

这是 Boris 给出的 CLAUDE.md 黄金标准。你的 CLAUDE.md 应该包含：

• 项目的构建和测试命令
• 代码风格和约定（简洁版）
• 必须遵守的硬性规则

不应该包含： 可以从代码本身推断出来的信息，比如目录结构、函数列表、架构描述。Claude 可以自己读代码。

防止指令被忽略的技巧

当你发现 Claude 总是无视某条规则时，用 XML 标签包裹：

<important if="editing API routes">
所有 API 路由必须包含 rate limiting 中间件
</important>

条件触发式的指令比全局的"你必须做 X"更容易被遵守。

Monorepo 场景

在 monorepo 中，可以在不同子目录放不同的 CLAUDE.md。Claude Code 会自动加载：

• 祖先目录的 CLAUDE.md（向上查找）
• 当前目录的 CLAUDE.md（立即加载）
• 子目录的 CLAUDE.md（按需懒加载）

这样前端、后端、基础设施可以有各自的规则，互不干扰。

---

三、子代理（Subagents）：让 Claude 自己分工协作

这是 Claude Code 最被低估的功能之一。

子代理 = 拥有独立上下文的自主执行单元。 每个子代理可以有自己的工具权限、模型选择、记忆设置。

什么时候用子代理？

一句话判断："这个工具的输出，我后续还需要原始数据，还是只需要结论？"

如果只需要结论------交给子代理。它在隔离上下文中处理完，返回一个精简结果，不污染主对话。

实战场景

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: 审查代码变更，关注安全和性能
model: opus
tools: Read, Grep, Glob
---

审查以下变更，重点关注：
1. 安全漏洞（注入、XSS、敏感信息泄露）
2. 性能问题（N+1 查询、不必要的循环）
3. 边界条件处理

你可以同时启动多个子代理并行处理不同任务------一个跑测试，一个审查代码，一个搜索相关文件------效率直接翻倍。

---

四、技能系统（Skills）：教 Claude 学会你的业务

Skills 是 Claude Code 中最灵活的模块化知识单元。它是一个文件夹，而不只是一个文件。

.claude/skills/deploy-checker/
├── SKILL.md           # 技能定义和触发条件
├── references/        # 参考文档
├── scripts/           # 可执行脚本
└── examples/          # 示例

关键经验

1. 技能描述是"触发器"，不是"摘要"

错误写法：这个技能用于部署检查

正确写法：当用户要求部署、发布、上线、推送到生产环境时使用此技能

描述的作用是让 Claude 判断"什么时候该激活我"，所以要用触发场景来写。

2. 给目标和约束，不给步骤

不要在技能里写"第一步做 X，第二步做 Y"。Claude 不需要被手把手教。

写清楚目标是什么、边界在哪里就够了。过度指导反而会限制模型找到更优解的能力。

3. 建一个"踩坑记录"区域

在每个 SKILL.md 里加一个 Gotchas 部分，记录已知的坑。比如：

## Gotchas
- 生产环境的数据库连接超时设置是 5s，不是默认的 30s
- iOS 端的推送证书每年 1 月需要更新
- staging 环境的 CDN 缓存是 1 小时，调试时记得清除

4. 用 !command 注入动态上下文

在 SKILL.md 中嵌入 shell 命令，技能加载时自动执行并注入结果：

当前 Git 分支和最近提交：
`!git log --oneline -5`

这样技能每次被触发时，都能拿到实时信息。

---

五、Hooks：在 AI 执行循环之外加入你的规则

Hooks 是在 Claude 的 agentic 循环之外运行的事件处理器，支持 25 种事件。

实战例子：自动格式化

设置 PostToolUse Hook，在 Claude 每次写完文件后自动运行 prettier 或 eslint --fix。Claude 不需要记住格式化规则，Hook 自动处理。

实战例子：安全守卫

设置 PreToolUse Hook，拦截危险命令：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "command": "检查命令是否包含 rm -rf, git push --force 等危险操作"
    }]
  }
}

最酷的用法：Stop Hook

在 Claude 准备结束一轮对话时触发，可以让它：

• 检查是否真的完成了所有任务
• 运行一遍验证测试
• 自动生成总结

---

六、工作流：高手都在用的开发模式

Plan → Execute → Review

Claude Code 创始人的工作流核心：永远从 Plan Mode 开始。

不要上来就让 Claude 写代码。先让它分析需求、拆分任务、输出计划。你确认计划后，再进入执行。

更进阶的做法：

"先面试我，用 AskUserQuestion 工具问清楚所有细节，然后在新会话中执行。"

这样做的好处是：执行会话的上下文里只有干净的需求和计划，没有来回讨论的噪音。

小 PR 原则

Boris Cherny 的数据：一天 141 个 PR，中位数 118 行。

大 PR 会让审查者疲劳，也会让 Claude 在处理时更容易出错。把大任务拆成一系列小的、可独立验证的 PR。

用第二个 Claude 审查第一个 Claude 的计划

启动一个子代理，角色设定为"资深工程师"，让它审查主会话中 Claude 的实现计划。两个独立的上下文互相检查，能抓到很多单一视角看不到的问题。

---

七、权限管理：安全与效率的平衡

很多人为了省事，开启 --dangerously-skip-permissions。这是个坏主意。

更好的替代方案

1. 通配符权限

在 settings.json 中配置：

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ]
  }
}

只放行你信任的命令模式，而不是全部跳过。

2. /sandbox 模式

数据显示 /sandbox 能减少 84% 的权限弹窗，同时保持安全边界。

3. Auto Mode

基于模型的安全分类器，自动判断操作是否安全。比全跳过安全得多，比手动确认方便得多。

---

八、搜索策略：为什么 Claude Code 放弃了 RAG

一个有趣的事实：Claude Code 团队曾经尝试过向量数据库和 RAG 方案，最终放弃了。

他们发现 agentic search（基于 glob + grep 的主动搜索）效果更好。

原因是模型可以根据搜索结果动态调整下一步搜索策略，而 RAG 的一次性检索往往不够精确。

这对你的启示是：不需要给 Claude Code 建索引或嵌入数据库，它自带的文件搜索能力已经是最优解。

---

九、产品验证技能："值得花一周来打磨"

Boris 特别强调的一个方向：为你的产品构建专门的验证技能。

比如：

• signup-flow-driver------自动走完注册流程，检查每一步
• checkout-verifier------模拟下单到支付的全链路
• api-health-checker------验证所有 API 端点的响应

这类技能的投资回报极高。写一次，每次改动后自动验证，省掉大量手动测试时间。

---

十、正在改变游戏规则的新功能

claude-code-best-practice 仓库还追踪了一些前沿功能：

• Agent Teams：多个代理并行在同一代码库上工作
• Routines：在 Anthropic 云端自动执行任务（类似 GitHub Actions 但由 AI 驱动）
• Chrome 扩展：直接在浏览器里用 Claude Code 调试前端
• Voice Dictation：20 种语言的语音输入，边说边写代码
• Agent SDK：用 Python/TypeScript 构建生产级 AI 代理的官方 SDK

---

写在最后

Claude Code 的能力边界远超大多数人的使用深度。上面这些实践，核心逻辑只有一条：

把 Claude 当成一个需要好的工作环境的工程师，而不是一个需要精确指令的工具。

给它清晰的上下文（CLAUDE.md），合理的分工（子代理），可复用的知识（技能），自动化的流程（Hooks），以及安全的边界（权限管理）。

GitHub 仓库地址：shanraisshan/claude-code-best-practice，持续更新中，建议 Star 收藏。

---

你在用 Claude Code 时踩过什么坑？或者有什么独家技巧？欢迎在评论区分享。