waylongo

Claude Code 使用最佳实践 50 条

按从简单到复杂排序,每条具体、可执行。基于 2026 年最新功能和实战数据持续迭代。


核心原则(1–5)

1. 一个任务一个会话,长会话质量退化

长会话中 Claude 反复犯错,纠正次数增加 3 倍。一个任务一个会话是社区公认的第一实践。用 claude -c 继续上次会话,用 /rename 命名会话方便后续恢复。

2. 用 /clear 在不相关任务之间清空上下文

每次切换到新任务前执行 /clear。旧上下文会污染新任务的推理质量。清空比带着历史继续更高效。

3. 理解两次纠正规则:超过两次就重新开始

如果你在同一个问题上纠正了 Claude 两次以上,说明上下文已被失败尝试污染。执行 /clear 用更好的 prompt 重新开始,几乎总是比继续修补更好。纠正螺旋是最危险的反模式——Claude 修了 A 破了 B,修了 B 又回到 A,5 轮下来消耗 40K tokens 却原地踏步。

4. 用结构化上下文替代模糊 prompt(调试同理)

差:"fix this bug"。好:"在 src/auth/login.ts,validateToken 函数在 JWT 过期时返回 undefined 而非抛出 TokenExpiredError。Stack: Node.js 22, Express 5, jsonwebtoken 9.0.2"。

结构化四要素——文件路径、期望行为、实际行为、技术栈——适用于所有场景(功能开发、调试、重构)。结构化 prompt 解决率从 45% 升至 85%,token 消耗降至模糊 prompt 的 1/3。

5. 用 /effort 控制思考深度匹配任务复杂度(Opus 4.6 核心功能)

/effort 同时控制三个维度:思考深度、工具调用意愿、响应长度。五个级别:

级别 适用场景 特点
low 重命名变量、修 typo、生成样板代码 跳过思考,最少工具调用,简短回复
medium 已知模式的测试编写、简单功能 按需思考(Opus Max/Team 默认)
high 日常编码(推荐默认) 几乎总是思考,主动读相关文件
max 卡住的 bug、架构决策、安全审查 全力思考无 token 限制,仅 Opus,会话级重置
auto 重置为计划默认 恢复默认行为

lowmax 的 token 消耗差异可达 10 倍。low/medium/high 跨会话持久化,max 会话结束后重置。日常保持 high,批量简单操作切 low,遇到难题上 max。也可以在 prompt 中用 "think harder" 或 "ultrathink" 等触发词提升思考深度。


项目配置基础(6–15)

6. 用 /init 生成 CLAUDE.md 起步

在项目根目录运行 /init,自动生成包含构建命令、代码风格、架构信息的 CLAUDE.md 初始文件。不要从空白开始手写。/init 会扫描 package.jsontsconfig.jsonpyproject.toml 等配置文件,10 秒内生成 15-30 行初始指令。

7. 在 CLAUDE.md 中写明项目常用命令

# Commands
- Dev: `npm run dev`
- Test: `npm test` (单个: `npm test path/to/file`)
- Lint: `npm run lint`
- Build: `npm run build`

Claude 无法猜到你的项目用什么命令,必须明确写出。缺少 CLAUDE.md 的项目效率下降 45%。

8. 创建 .claudeignore 排除无关文件

.gitignore 一样,创建 .claudeignore 排除 node_modules/dist/build/*.lockcoverage/。每个被读取的无关文件都在消耗你的上下文窗口。

9. 用 /code init 启用 LSP 获得语义代码理解

在项目根目录运行 /code init,启动 Language Server Protocol。支持 TypeScript、Rust、Python、Go、Java、Ruby、C/C++。启用后 Claude 可精确搜索符号、找引用、导航定义,避免模糊搜索浪费 token。禁用:删除 .kiro/settings/lsp.json

10. 利用 CLAUDE.md 层级 + .claude/rules/ 管理复杂项目

CLAUDE.md 加载层级(从强到弱):managed policy(IT 部署,不可排除)→ ./CLAUDE.md(项目共享)→ ~/.claude/CLAUDE.md(全局个人偏好)→ CLAUDE.local.md(本地不提交)。更具体的文件优先。

对于大型项目,用 .claude/rules/ 目录替代臃肿的 CLAUDE.md:

.claude/rules/
├── code-style.md    # 代码风格
├── testing.md       # 测试约定
├── security.md      # 安全要求
└── frontend/
    └── react.md     # 前端特定规则

关键特性:支持 YAML frontmatter 的 paths 字段按路径加载——规则只在 Claude 处理匹配文件时触发,减少上下文噪音:

---
paths:
  - "src/api/**/*.ts"
---
# API 开发规则
- 所有端点必须包含输入验证
- 使用标准错误响应格式

CLAUDE.md 中用 @path/to/file 语法引入外部文件(README、package.json、工作流文档),最大递归深度 5 层。Rules 是持久记忆(每次加载),Skills 是任务工具(按需加载)。

11. 配置权限规则防止生产事故(关键)

{
  "permissions": {
    "deny": ["Read(.env*)", "Bash(rm -rf:*)", "Bash(aws:*)", "Bash(kubectl:*)"],
    "askUser": ["Bash(git push:*)", "Bash(npm publish:*)"]
  }
}

55% 的团队未配置权限限制。deny 绝对阻止,askUser 在执行前要求人工确认。一个 git push --forcerm -rf 就能毁掉整个项目。绝对不要配置 "allow": ["*"]

12. 用 settings.local.json 存放个人偏好

.claude/settings.local.json 用于个人配置(加入 .gitignore),.claude/settings.json 用于团队共享配置(提交到 git)。

13. 用 IMPORTANT 标记关键规则但不滥用

在 CLAUDE.md 中对关键规则加 IMPORTANT: 前缀可显著提高遵从率。但如果所有规则都标重要,等于没有重要。每个文件最多 2–3 条 IMPORTANT。

14. CLAUDE.md 以 Common Pitfalls 开头

最高 ROI 的内容是 Claude 反复犯的错误。每次在会话中纠正 Claude 后,把错误模式加入 CLAUDE.md 顶部的 Pitfalls 区。五行具体的"不要做 X,要做 Y"比五十行项目哲学更有价值。

参考基准:Boris Cherny(Claude Code 创建者)的团队 CLAUDE.md 仅 2.5K tokens(~100 行),提交到 git,全团队贡献。总量控制在 500 行以内——冗长文件会被忽视。每行问自己:"删除这行会导致 Claude 犯错吗?"如果不会,删掉。详细内容移到 .claude/rules/ 或用 @path 引入。

15. 理解五层配置体系,把规则放对层

从强到弱:settings.json(硬性权限)→ Hooks(生命周期强制执行)→ CLAUDE.md + .claude/rules/(上下文与约定)→ Auto Memory(Claude 自动学习的模式)→ Skills/Agents(多步工作流)。

"NEVER do X" 类规则应放在 Hook 或 settings deny 中,而非 CLAUDE.md——CLAUDE.md 是建议性的,Claude 可以忽略;Hook 是确定性的,每次都执行。

Auto Memory 存储在 ~/.claude/projects/<project>/memory/,包含 MEMORY.md 索引文件(只加载前 200 行或 25KB)和 topic files(debugging.mdapi-conventions.md 等,按需读取)。同一 git repo 的所有 worktree 共享一个 auto memory 目录。定期用 /memory 检查,把有价值的条目提升到 CLAUDE.md,删除过时的。


IDE 与工作流优化(16–27)

16. 用 /rewind 精确撤销错误操作

/rewind 不仅回退对话到上一轮,还恢复被修改的文件。比 /clear 精细得多——/clear 清空所有上下文但不动文件,/rewind 同时回退对话和文件状态。

命令 对上下文的影响 对文件的影响
/rewind 回退到上一轮 恢复被修改的文件
/clear 清空所有上下文 无影响
/compact 压缩摘要 无影响

Claude 生成了不想要的重构?立即 /rewind。等得越久,上下文偏离恢复点越远。

17. 用 Plan Mode 先规划再编码(减半 token 消耗)

Shift+Tab 进入 Plan Mode。Claude 只读取文件、回答问题,不做修改。规划完成后切回 Normal Mode 执行。小改动(一句话能描述的 diff)跳过规划。

Plan Mode 的优势:减少 token 消耗 50%(规划阶段不生成代码),提高实现准确率(先确认方向再编码),减少返工(问题在规划阶段就被发现)。

18. 用 JetBrains Claude Agent 在 IDE 内工作

JetBrains IDEs(PyCharm、WebStorm、IntelliJ、Rider 等)现已原生集成 Claude Agent。核心工作流:Diff 预览(文件级审查,行级增删可视化)、Selection Context(选中代码片段后基于选中内容工作)、Plan Mode(分离规划和执行)。对于 JetBrains 用户,IDE 工作流比终端更高效。

19. 用 VS Code 扩展的 Inline Diffs 和 @-mentions

VS Code 的 Claude Code 扩展提供 Inline Diffs(编辑器内直接显示建议改动)、@-mentions(@filename 引用文件,@folder 引用目录)、快捷键(Cmd+K 快速打开 Claude)。混合工作流:Claude 在终端改代码,你在 IDE 中实时看 diff——比 git diff 可读性强得多。

20. 给 Claude 提供可验证的完成标准(关键)

差:"实现邮箱验证"。好:"写 validateEmail 函数,测试 user@example.com 返回 true,invalid 返回 false,user@.com 返回 false,写完跑测试。"

验证是最高杠杆的投入。给 Claude 反馈循环(测试、lint、构建命令),输出质量提升 2–3 倍。有效的验证类型:测试套件、Linter 输出、编译器错误、截图对比、性能基准数字。核心原则:给 Claude 结构化的信号,而非模糊的人工判断。

21. 拆分 monolithic prompt 为顺序步骤

差:"重构 auth 模块、加测试、迁移 API、更新文档"。好:拆成 3–5 个步骤,每步 100 词以内。单块 500+ 词的 prompt 在 60% 的情况下产生不一致结果。拆分后准确率提升 50%。

22. 用 Interview Pattern 让 Claude 先采访你再动手

对大型功能,先让 Claude 提问而非直接实现。采访完毕后写完整 spec 到 SPEC.md,然后开新会话基于 spec 实现,上下文干净且聚焦。

23. 用 /model 切换模型匹配任务复杂度

简单任务用 Haiku(快速便宜,成本仅 Opus 的 5%),日常编码用 Sonnet(Opus 的 20% 成本),复杂架构用 Opus(强推理)。Opus 虽慢但错误更少,总纠正时间反而更短——净生产力更高。

24. 用 /cost 建立成本意识

/cost 实时显示当前会话的输入 token、输出 token 和累计费用。一个 45 分钟会话通常花费 $0.50–$3.00。重构操作平均消耗 3 倍于简单生成的 token。养成习惯:每完成一个主要任务后检查 /cost,然后决定是否需要 /compact

25. 用 /statusline 设置持久状态栏监控上下文

/statusline show current directory, git branch, and context usage percentage.
Use ANSI colors: green for directory, cyan for git branch, yellow for context percentage.

一眼看到当前目录、活跃 git 分支、上下文使用百分比——三个关键信息不打断工作流。在多 worktree 并行时尤其有用,帮你提前预判何时需要 /compact

26. 用 claude -cclaude --resume 恢复会话

claude -c 恢复最近的会话(无需选择),claude --resume 打开交互式选择器(支持 P 预览、R 重命名、/ 搜索)。用 /rename feature-auth 命名会话,之后精确恢复。

27. 用 Auto Mode 在安全和效率之间平衡

Auto Mode 是 --dangerously-skip-permissions 和默认模式之间的中间路径。安全分类器分析每个操作,自动批准安全操作,阻止危险操作。用 claude --enable-auto-mode 启用,Shift+Tab 切换。适合长时间运行的任务和隔离环境,不适合生产环境和敏感操作。


Skills 与自定义工作流(28–34)

28. 用 Skill 封装可复用的工作流(2026 核心功能)

Skill 是模块化的 SKILL.md 文件,包含 YAML 元数据和 Markdown 指令。Claude 根据任务上下文自动调用相关 Skill,无需手动触发。三个部署层级:个人 ~/.claude/skills/、项目 .claude/skills/(版本控制)、插件 Marketplace 分发。

Skill 的核心优势:一次编写,自动复用,无需重复指令。Claude 维护所有 Skill 的轻量级索引(名称 + 描述),只在需要时加载完整 Skill,即使有 50 个 Skill 也不会在每个会话开始时消耗大量 token。

29. Skill 的自动调用机制:description 字段是关键

Claude 使用 LLM 推理(非关键字匹配)决定何时激活 Skill。好的 description 包含:简洁的功能说明(一句话)、触发场景(何时使用)、触发短语示例("生成提交信息"、"写测试"、"审查代码")。差的 description 导致 Skill 永远不被调用。

30. 用 allowed-tools 限制 Skill 的权限范围

Skill 可以声明允许的工具集。只读 Skill:["Read", "Grep"]。测试 Skill:["Read", "Bash(npm test:*)"]。文档 Skill:["Read", "Write(docs/**)"]。权限最小化原则同样适用于 Skill。

31. Skill vs Command 的区别

大多数工作流应该是 Skill(自动),只有需要用户显式触发的才用 Command。

32. 创建高价值 Skill 的三个模板

提交信息 Skill:分析 git diff → 确定类型 → 生成规范信息。自动调用频率最高。

测试生成 Skill:读源文件 → 识别测试场景 → 生成测试用例。覆盖快乐路径、边界情况、错误处理。

代码审查 Skill:系统化检查正确性、安全性、性能、可维护性。按严重程度分类(CRITICAL/MAJOR/MINOR/SUGGESTION)。

这三个 Skill 覆盖 80% 的日常工作流。

33. 用子代理隔离探索性工作并控制成本

让 Claude 用子代理搜索代码库,结果在独立上下文中处理,只有摘要返回主会话。节省 40%+ 的输入 token,主会话保持聚焦。在 .claude/agents/ 中为不同任务创建 agent,用 model 字段指定模型(探索用 Haiku,实现用 Sonnet),混合使用可降低 40–50% 成本。

34. 用 Scout Pattern 定向探索陌生代码

对不熟悉的库或边界行为,不要把完整文档塞进上下文。用子代理作为 Scout:

目标:找到实现 X 所需的最少文档和示例。
范围:只关注 Y 和 Z 约束。
输出:10 条发现、3 条 do/don't 规则、1 个最小代码示例、相关文件路径。

Scout 探索,主会话实现——分层方式避免上下文膨胀。


高级工作流与优化(35–44)

35. 用 -p 无头模式并行执行独立任务

claude -p "Add unit tests for the auth module" &
claude -p "Document the REST API for the orders service" &
claude -p "Refactor the billing module to use the new SDK" &
wait

每个实例有独立上下文,互不干扰。比 Agent Teams 更轻量,适合不需要交互的独立任务。Boris Cherny(Claude Code 负责人)日常同时运行 10-15 个会话。

36. 用 Agent Teams 协调多个 Claude 实例协作(实验性)

设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用(研究预览阶段)。Claude 自动生成多个 teammate 处理不同子任务,teammates 之间可直接通信、共享任务列表、自我协调。teammateMode 控制显示方式:tmux(分窗格)、in-process(同终端)、auto(自动选择)。

适合有依赖关系的并行工作(读/分析/汇总、构建/测试/文档)。纯顺序任务用单会话 + /clear 更简单。

37. 用 --worktree 在隔离的 git worktree 中工作

git worktree add ./worktrees/feature-a -b feat/feature-a
git worktree add ./worktrees/feature-b -b feat/feature-b
cd ./worktrees/feature-a && claude  # Terminal 1
cd ./worktrees/feature-b && claude  # Terminal 2

每个会话有独立上下文和独立分支,互不干扰。与 git clone 不同:共享 .git 历史,磁盘节省 ~90%,git fetch 在一个 worktree 更新所有。完成后 git worktree remove 清理。

38. 用 Writer/Reviewer 双会话模式提高代码质量

会话 A 写代码,会话 B 审查代码(通过 worktree 或只读方式)。审查者有干净的上下文,不会对自己刚写的代码产生偏见。对基础设施变更尤其有效——一个错误可能代价巨大。

39. 用 PROGRESS.md 和 DECISIONS.md 作为外部记忆(关键)

不要依赖 Claude 跨会话记住一切,把状态存到仓库中:

写描述性的 commit message(如 "Added CLI test hardening: new fixtures, stricter exit-code assertions"),Claude 可以通过 git log 在未来会话中引用。外部记忆减少 token 消耗,提升跨会话连续性,且对队友可见。

40. 用 Hooks 而非 Prompt 保证必须执行的操作

告诉 Claude "每次编辑后运行 Prettier" 它可能忘记。Hook 保证每次都执行。判断标准:如果一次违反就浪费你的时间或破坏构建,用 Hook;如果只是偶尔忘记的约定,留在 CLAUDE.md。

最常用的 PostToolUse Hook——每次文件编辑后自动格式化:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npm run format || true"
      }]
    }]
  }
}

|| true 防止格式化错误阻塞会话。Boris Cherny(Claude Code 创建者)的团队使用此模式确保代码风格一致。

41. 用 Notification Hook 在 Claude 等待时收到通知

最实用的第一个 Hook——Claude 完成任务或等待输入时发送桌面通知:

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "notify-send 'Claude Code' \"$CLAUDE_NOTIFICATION\" --icon=dialog-information"
      }]
    }]
  }
}

不用每 30 秒检查终端。macOS 用 osascript,Linux 用 notify-send

42. 用 PreToolUse Hook 阻止危险操作

Hook 是确定性执行,prompt 是概率性遵从。PreToolUse Hook 可以在工具执行前拦截:阻止写入 .env/.pem/.key 文件(exit code 2 = 操作被阻止)、自动格式化编辑后的文件(如 Go 文件自动 gofmt)、审计执行的命令到日志文件。

43. 用 --max-turns 限制自主执行轮次

claude -p "重构认证模块" --max-turns 10

防止无限循环,配合 deny 规则和权限模式形成三层防护。

44. 用 /loop/schedule 实现定时自动化

/loop:在会话内运行定时任务,最多 3 天。用法:/loop every 30 minutes check deployment status。适合轮询部署、监控 PR、检查构建。

/schedule:Desktop 应用中的持久化定时任务,跨会话运行。适合长期自动化工作流。

两者都需要明确的任务定义和间隔,监控输出防止无限循环。


Token 管理与企业实践(45–50)

45. 理解 token 基线和 70% 阈值,用 /compact 主动压缩(关键)

Opus 4.6 和 Sonnet 4.6 现已支持 1M context window(Max/Team/Enterprise 用户)。即便如此,上下文管理仍然重要——更大的窗口意味着更高的 token 成本,且模型在超长上下文中的召回准确率会下降。

关键阈值(适用于 200K 和 1M 上下文):

不要等到自动压缩(95%)。在 70% 时主动压缩,质量损失最小。/compact 可带焦点参数如 /compact focus on auth changes,将上下文从 ~180K 压缩到 ~40K,响应时间从 8-12s 降到 3-5s。CLAUDE.md 在 /compact 后会从磁盘重新读取并注入——不会丢失。

Monorepo token 预算:跨仓库工作导致 40-60% 的 token 重复消耗。用子代理处理跨包搜索(主会话只接收摘要),简单改动 5-10K,中等改动 15-25K,大型重构用新会话。

46. 用 ENABLE_TOOL_SEARCH 按需加载 MCP 工具定义

每个启用的 MCP 会注入工具定义到上下文。6-7 个 MCP 可占用超过 10% 的上下文窗口——还没开始工作就消耗了。

export ENABLE_TOOL_SEARCH=auto:10

启用后 Claude 只在需要时加载工具定义,而非全部常驻内存。10 是触发阈值(上下文百分比)。另一个原则:成熟工具(kubectlgitgh)优先用 CLI 而非 MCP——LLM 对这些 CLI 已经非常熟悉,避免额外 MCP 开销。

47. 用 Docker/DevContainer 沙箱隔离 Claude 执行环境(安全关键)

Docker 沙箱为每个工作区创建隔离容器。即使 Claude 运行 rm -rf / 也只影响容器内部,主机系统完全安全。官方安全文档推荐此方案。

核心优势:

适合场景:自主工作流(无人值守长时间运行)、并行执行、处理不信任的仓库、低风险实验。用 DevContainer 配置标准化开发环境,确保团队成员使用相同的沙箱设置。

48. 企业级配置:managed policy + claudeMdExcludes + 安全边界

对于多人团队,用子目录 CLAUDE.md 和 .claude/rules/ 定义安全边界:

src/auth/CLAUDE.md          # 认证模块特定规则
src/billing/CLAUDE.md       # 支付逻辑约束
infra/terraform/CLAUDE.md   # 基础设施规则

企业级特有功能:

企业团队还应维护中央 claude-standards 仓库,通过 CI/CD 同步共享规则到所有项目。

49. 用 code-simplifier 插件在提 PR 前清理 AI 生成代码

Anthropic 官方的 code-simplifier 插件自动清理 AI 生成代码:消除重复、简化过度复杂的结构、统一风格。在 Opus 上运行。养成习惯:密集编码会话后、创建 PR 前运行一次,减少 AI 引入的技术债。

50. 系统化审查 AI 生成代码防止 bug(关键)

1/4 的 PR 包含 AI 生成的 bug。建立审查清单:

建立验证反馈循环:让 Claude 先写测试 → 确认测试在无实现时失败 → 提交测试 → 让 Claude 写代码通过测试(不修改测试)→ 用子代理验证实现不会过度拟合测试。花 2 分钟审查 10 分钟生成的代码,回归率下降 70%,代码质量提升 2-3 倍。


反模式与陷阱(必读)

不要做的事(按影响程度排序):

  1. 不要配置 "allow": ["*"] 权限(影响:灾难性)
  2. 不要让 Claude 在 main 分支上直接工作(影响:灾难性)
  3. 不要在一个会话中处理多个无关项目(影响:-60% 效率)
  4. 不要用模糊的 prompt(影响:-55% 效率)
  5. 不要纠正 Claude 超过两次同一问题(影响:-50% 效率,纠正螺旋)
  6. 不要忽视 /cost/context 输出(影响:-40% 效率)
  7. 不要安装超过 10 个 MCP 服务器(影响:-30% 效率,上下文膨胀)
  8. 不要让 CLAUDE.md 超过 500 行(影响:-30% 遵从率)
  9. 不要跳过代码审查(影响:+25% bug 率)
  10. 不要在 max effort 下做批量简单操作(影响:10 倍 token 浪费)

隐蔽陷阱(Claude 不会告诉你的):


关键数据与对标

指标 数值 来源
长会话纠正次数增加 3 倍 社区调查
结构化 prompt 解决率 85% vs 45% 实战对比
AI 生成 PR 包含 bug 1/4 2026 研究
代码审查减少回归率 70% 实战数据
验证反馈循环提升质量 2-3 倍 实战数据
子代理节省 token 40%+ 实战测试
结构化 prompt token 消耗 模糊 prompt 的 1/3 对比数据
拆分 prompt 准确率提升 50% 实战数据
Plan Mode token 节省 50% 实战数据
/compact 上下文压缩率 60-80% 实战测试
/compact 后响应时间 3-5s vs 8-12s 实战测试
Haiku vs Opus 成本比 5% 官方定价
Sonnet vs Opus 成本比 20% 官方定价
/effort low vs max token 差异 最高 10 倍 实战测试
MCP 工具定义上下文占用 6-7 个 MCP 占 >10% 实战测试
Monorepo 跨仓库 token 重复消耗 40-60% 实战测试
新会话基线消耗 15-25K tokens 实战测试
Skill 自动调用覆盖率 80% 日常工作 设计目标
Boris Cherny 团队 CLAUDE.md 大小 2.5K tokens (~100 行) 公开分享
会话放弃率(方向错误) 10-20% Boris Cherny
Opus 4.6 / Sonnet 4.6 上下文窗口 1M tokens(GA) 官方公告 2026-03

最后更新:2026-03-29 14:43 | 基于 Claude Opus 4.6 & Sonnet 4.6 | 第十一轮迭代 | 累计新增:/effort、/rewind、/statusline、/cost、外部记忆、ENABLE_TOOL_SEARCH、Notification Hook、PostToolUse auto-format Hook、Scout Pattern、-p 无头并行、code-simplifier、Docker 沙箱、.claude/rules/、path-specific rules、Auto Memory 机制、managed policy、claudeMdExcludes、Boris Cherny 基准 | 累计删除:WarpGrep | 累计合并:结构化 prompt + 调试、Monorepo token 预算