Claude Code 最佳实践：把上下文变成生产力（团队可落地长文）
Claude Code 的“最佳实践”看起来很多，但背后只有一个核心约束：上下文窗口会很快被填满。一旦上下文接近上限，模型就更容易遗忘早期约束、误解需求、在细节上犯错。
所以本文不按功能罗列，而是按“从高杠杆到低杠杆”的顺序，整理为一份团队可以落地的实操长文：先建立验证闭环，再建立可复用配置与安全边界，最后再谈自动化与规模化。
文章主线参考官方《Best Practices for Claude Code》，并结合本站文档中的 Quickstart / Workflows / Plugins / Subagents / Advent of Claude 等内容补充细节。
如果你还没把 Claude Code 跑起来（尤其是 Provider/环境变量配置这一步），建议先看：
- 安装与 Provider 配置：/blog/claude-code-install-and-provider-switching/
- 官方安装文档页：/docs/claude-code/getting-started/installation/
0) 一句话总纲：让 Claude 有办法“自证正确”
你能做的最高杠杆动作只有一个：给 Claude 一个可执行的验证方式。
- “写一个函数” → 给输入输出样例 + 测试用例，并要求实现后跑测试。
- “UI 调整” → 给截图/设计稿，并要求实现后再对比截图、列差异、再修。
- “构建失败” → 给完整报错，并要求修复后重新构建验证通过，强调“解决根因，不要压制错误”。
这会把你的反馈从“人肉验收”变成“可重复的验证闭环”，Claude 的产出质量会显著提升。
1) 探索 → 规划 → 实现 → 提交：先做对事，再写代码
Claude 很擅长写代码，但它并不天然理解你的业务意图。复杂任务推荐拆成四个阶段（官方最佳实践给出的典型流程）：
1.1 Explore：先探索现状（建议 Plan Mode）
目标：在不改代码的前提下，搞清楚“现在是怎么做的”。
你可以这样写：
read @src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.1.2 Plan：把方案写成可验证的计划
目标：让 Claude 明确“要改哪些文件、为什么、怎么验收”，避免实现阶段反复扯皮。
I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.1.3 Implement：按计划实现 + 持续验证
implement the OAuth flow from your plan.
write tests for the callback handler,
run the test suite and fix any failures.1.4 Commit：把结果沉淀成可审查资产
commit with a descriptive message and open a PR什么时候可以跳过 Plan？
官方建议非常务实：如果你能用一句话描述 diff（例如“修一个拼写错误”“改一个变量名”），Plan 的开销可能比收益更大；多文件改动、不熟悉模块、路径不清晰时才强烈建议 Plan。
站内延伸：
2) 提示词写法：像“任务单”，不要像“愿望”
Claude 可以推断意图，但读不懂你没写出来的约束。越具体，你返工越少。
2.1 三段式模板（建议直接复用）
- 范围：要动哪些文件/目录，或者明确“不允许触碰哪些区域”。
- 症状与证据：复现步骤、错误堆栈、日志片段、截图。
- 验收方式：要跑什么命令、要看到什么输出、要满足什么测试。
示例（修 bug）：
Bug: users report login fails after session timeout.
Scope: check @src/auth/ token refresh flow.
Evidence: paste error stack trace below.
Acceptance: add a failing test that reproduces it, fix it, run npm test.示例（加功能）：
Add feature: Google OAuth.
Constraints: keep current session model; don't change public API.
Acceptance: add unit tests for callback handler; update docs if behavior changes.2.2 “富内容输入”：用 @ / 截图 / 管道，少用口述
官方最佳实践强调：尽量用“直接给数据”的方式减少描述成本。
- 用
@引用文件/目录，而不是口述路径。 - 直接粘贴截图/设计稿（UI 场景尤其有效）。
- 把日志/数据直接 pipe 进 Claude：
cat error.log | claude -p "Analyze this log file and propose fixes"另外，有一个很实用的效率技巧来自 Advent of Claude：当你只是想跑个命令（比如 git status、npm test）时，用 ! 前缀可以更快把输出注入上下文（不同版本行为可能略有差异，以你本机为准）。
站内延伸：
3) 配置环境：先把“可验证”这条路打通
很多“Claude 写得不对”的根因，其实是项目缺少可运行的验证路径：没有测试命令、构建命令不稳定、环境变量缺失、CLI 工具未装。
从 Quickstart/Best Practices 可以提炼出一个朴素顺序：
- 安装并登录 Claude Code（
claude//login）。 - 让 Claude 能跑你的测试/构建（命令必须真实可用）。
- 再谈更高级的自动化（Hooks、CI、MCP）。
4) 把 CLAUDE.md 当作“项目可执行规约”，并保持短
官方建议用 /init 先生成 CLAUDE.md 的骨架，然后像维护代码一样持续迭代。
4.1 CLAUDE.md 的内容边界（官方建议的取舍）
- ✅ 推荐写进去：Claude 无法从代码推断的命令/规则（测试、构建、lint、分支/PR 规范）、关键目录入口、常见坑。
- ❌ 不要写进去：长教程、会频繁变化的信息、逐文件说明、可以从代码直接看出来的常规风格。
一个很好用的自检问题是：删掉这一行，会不会显著增加 Claude 犯错概率？
4.2 把 CLAUDE.md 当作“可版本控制资产”
- 规则不生效：通常是太长/太散/表述含糊。
- 让团队一起维护：把它提交到 git，让它随项目演化。
- 需要拆分时：用模块化规则文件（例如
.claude/rules/）或用@path引用其他文件（官方文档提到@path/to/import风格）。
站内延伸：
5) 权限与沙箱：减少打断，但别牺牲安全
官方 Best Practices 建议用两种方式减少频繁确认：
/permissions：把你确认安全的命令加入 allowlist（例如npm run lint、git commit）。/sandbox：启用 OS 级隔离，限制文件系统/网络访问，让 Claude 在边界内更自由执行。
同时官方也明确警告：--dangerously-skip-permissions 只适用于隔离环境（尤其是无网络），否则可能造成数据损坏或提示词注入导致的数据外泄。
6) 先用 CLI，再接 MCP：把外部系统访问做成“低上下文”
官方建议：与外部服务交互时，优先让 Claude 使用 CLI 工具（因为比“解释一大段背景”更省上下文）。
6.1 常见 CLI 组合
- GitHub：
gh（读 issue、开 PR、读评论） - 云平台：
aws/gcloud - 监控：
sentry-cli
如果 Claude 不熟某个 CLI，也可以让它先读 --help 自学：
Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.6.2 什么时候需要 MCP？
当你要把 Claude 接到工单系统、数据库、监控、设计稿、知识库等外部系统，MCP 就是更合适的能力边界：
- 用
claude mcp add连接 Notion/Figma/数据库等。 - 用项目级
.mcp.json团队共享配置，并用环境变量占位符注入密钥。 - 控制启用数量（开太多会吃上下文）。
站内延伸：
7) Slash Commands：把高频流程固化成“入口”
官方 Best Practices 和 Common workflows 都强调：把重复流程保存成 .claude/commands/（项目级）或 ~/.claude/commands/（个人级）。
一个典型的命令文件长这样（官方示例 fix-github-issue.md 的结构）：
---
description: Fix a GitHub issue
---
Please analyze and fix the GitHub issue: $ARGUMENTS.
Follow these steps:
1. Use `gh issue view` to get the issue details
2. ...落地建议：
- 命令不求多，先把“团队最常用的 1~3 条”固化下来。
- 命令要带验收（测试/构建/截图对比），否则只是“更方便地返工”。
站内延伸：
8) Plugins：把命令/agents/hooks/mcp 打包成“可分发能力”
Plugins 的定位是：把常用能力做成可安装组件，适合团队推广与跨项目复用。根据 cc/Plugins.md 的内容，可以把 plugin 看成一个“能力包”，里面可以包含：
- commands
- agents
- skills
- hooks
.mcp.json
并且支持从 marketplace 安装/启用/禁用/卸载。
8.1 Plugin 结构（官方示例的抽象）
my-plugin/
├── .claude-plugin/plugin.json
├── commands/
├── agents/
├── skills/
└── hooks/8.2 团队落地建议
- 先从“只读类能力”开始（命令模板、审查 agent），再逐步引入会自动执行的 hooks。
- 团队统一安装时，把 marketplace 和启用配置写进仓库的
.claude/settings.json。
站内延伸：
9) Hooks：把“必须发生”的动作做成确定性护栏
官方 Best Practices 对 Hooks 的一句话总结很到位：
不要“希望 Claude 记得做某事”，用 hooks 确保它每次都做。
9.1 Hooks 适合做什么
- Auto-format（每次 edit 后自动跑 prettier/gofmt）
- Linting（自动 lint 改动文件）
- Guardrails（阻止写入
.env、secrets/、生产配置） - Logging/Notifications（合规与可观测性）
9.2 Hooks vs CLAUDE.md（官方给出的边界）
- 必须确定性执行、零例外：用 Hooks。
- 需要判断与权衡：写进
CLAUDE.md（它是“建议”，不是“强制执行器”）。
站内延伸：
10) Subagents：把“研究/验证/审查”从主会话分出去
cc/Subagents.md 强调了 Subagents 的核心价值：独立上下文窗口。
这对于“上下文很容易被探索污染”的场景非常关键：
- 探索陌生模块（读很多文件）
- 安全审查（需要对照大量规则）
- 代码评审（需要保持“新鲜上下文”，不被自己刚写的代码带偏）
10.1 Subagents 的两个关键设计点
- 独立上下文：避免主会话被大量阅读内容塞满。
- 可控权限：可以只给 subagent 必要工具（例如只读 + grep）。
官方还给了一个很实用的提示：如果你希望 Claude 更“主动地”调用某个 subagent，可以在 description 里写类似 “MUST BE USED PROACTIVELY”。
站内延伸：
11) Skills：把“领域知识与团队规范”沉淀成可自动触发的资产
Best Practices 对 Skills 的定位很清晰：它不是命令模板，而是“随上下文自动触发”的知识模块。
11.1 Skills、命令、Subagents 的分工
CLAUDE.md：全局项目上下文（总是加载）- Slash commands：显式调用的流程模板（你主动
/command） - Skills：上下文触发的领域知识（Claude 自动决定何时用）
- Subagents：委派型角色（独立上下文 + 独立工具权限）
11.2 团队最容易忽略的一件事：给人看的 Skills 索引
如果团队只写 SKILL.md，但没有一个入口索引，新人通常不知道：有哪些 skills、一个任务应该启用哪些组合。
你可以维护一个 .claude/skills/README.md，用“类别 + 一句话用途 + 推荐组合”把技能体系变得可理解。
站内延伸：
12) 沟通与会话管理：及时纠偏，敢于清空，善用回滚
官方 Best Practices 和 Advent of Claude 在“会话操作”上给了很多实用建议，这里按“最常用”整理：
12.1 纠偏：越早越好
Esc：立刻中断当前动作并纠正方向。- “Undo that”：让 Claude 撤销刚刚的更改。
官方还给出一个很实用的判断：
同一个问题在一个会话里纠偏超过两次，说明上下文已经被失败路径污染。用
/clear重开一个干净会话，效果通常更好。
12.2 上下文管理：/clear 与 /compact
/clear：在不相关任务之间清空上下文。/compact <instructions>：当上下文接近上限时，用指令控制压缩总结的侧重点。
12.3 回滚与“大胆尝试”
Esc Esc或/rewind：回到 checkpoint。
注意：checkpoint 不是 git 的替代，外部命令的副作用（例如已运行的 bash）不一定能回滚。
12.4 恢复工作与命名会话
claude --continue：继续最近一次会话。claude --resume：从列表中选择恢复。/rename：给会话命名（把会话当成“工作流分支”）。
12.5 让 Claude 采访你：先写 SPEC，再开新会话实现
Best Practices 里给了一个很好的“做大功能”的范式：先让 Claude 问问题，把需求补齐，输出到 SPEC.md；再开一个新会话只做实现（干净上下文，专注执行）。
13) 自动化与规模化：Headless、并行会话、批处理
当你已经有了“验证闭环 + 权限边界”，就可以进一步把 Claude 变成自动化组件。
13.1 Headless：在 CI/脚本里跑 Claude
官方 Best Practices 给出了最常见的形态：
claude -p "your prompt"
claude -p "List all API endpoints" --output-format json
claude -p "Analyze this log file" --output-format stream-json13.2 多会话并行：Writer/Reviewer
官方给了一个很实战的模式：让一个会话写代码（Writer），另一个会话审查代码（Reviewer）。审查会话保持“新鲜上下文”，更容易发现边界与漏洞。
13.3 批处理 fan-out：用 --allowedTools 收敛权限
批处理时更要小心：限制工具权限、先小范围试跑、再扩大规模。
14) 最小落地路线图（7 天版）
如果你要把这些最佳实践落到团队日常，可以按这个节奏：
- Day 1：明确每类任务的验收方式（测试/构建/截图对比）。
- Day 2：用
/init生成并收敛CLAUDE.md（短小、可执行）。 - Day 3：固化 1 个命令（例如
/plan或/code-review）。 - Day 4：上 1~2 个 Hooks（格式化 + 阻断敏感写入）。
- Day 5：接入
gh，把 PR/Issue 流程跑通。 - Day 6：引入 1 个 subagent（code-reviewer 或 security-reviewer）。
- Day 7：把最核心的 2~3 个 Skills 做成“索引 + 组合”，并开始迭代。
参考
- 官方文档（Best Practices）：
https://code.claude.com/docs/en/best-practices - 站内相关文档（便于对照实践）：