来源：code.claude.com/docs/en/best-practices | 整理时间：2026-04-01
核心认知：上下文窗口是最重要的资源
Claude Code 的所有最佳实践都围绕一个核心约束：
上下文窗口会快速填满，越满性能越差
上下文包含：对话历史 + Claude 读取的所有文件 + 命令输出。单次调试会话可能消耗数万 Token。
→ 管理上下文 = 管理 Claude Code 的性能
原则一：给 Claude 提供验证方式
这是效果提升最大的单一操作。
Claude 在能够验证自己工作时，表现大幅提升。
| 场景 | 低效做法 | 高效做法 |
|---|---|---|
| 实现功能 | "implement a validateEmail function" | "write validateEmail. test cases: user@example.com → true, invalid → false. run the tests after" |
| UI 修改 | "make the dashboard look better" | "[截图] implement this design. take a screenshot and compare, list differences and fix them" |
| 修复错误 | "the build is failing" | "build fails with: [错误信息]. fix it and verify the build succeeds. address root cause, don't suppress" |
原则二：探索 → 规划 → 编码
不要让 Claude 直接跳到写代码。用四阶段工作流：
阶段 1：探索（Plan Mode）
claude --permission-mode plan
# 在 Plan Mode 下，Claude 只读文件，不做任何修改
read /src/auth and understand how we handle sessions
阶段 2：规划
I want to add Google OAuth. What files need to change?
What's the session flow? Create a detailed plan.
# 按 Ctrl+G 在文本编辑器中直接编辑计划
阶段 3：实现（切回 Normal Mode）
# Shift+Tab 切换模式
implement the OAuth flow from your plan.
write tests for the callback handler, run the test suite and fix any failures.
阶段 4：提交
commit with a descriptive message and open a PR
💡 小任务（改个变量名、加一行日志）可以跳过规划阶段
原则三：提供精确上下文
| 技巧 | 示例 |
|---|---|
用 @ 引用文件 |
look at @src/auth/login.ts |
| 粘贴截图 | 直接把错误截图或 UI 设计拖进来 |
| 给 URL | 让 Claude 直接读文档链接 |
| 管道输入 | cat error.log | claude |
| 让 Claude 自己拿上下文 | "用 bash 命令找出相关文件" |
配置：CLAUDE.md 文件
每次会话开始时 Claude 都会读取的文件。
/init # 自动生成项目 CLAUDE.md
例子：
# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible
# Workflow
- Be sure to typecheck when done with changes
- Prefer running single tests, not the whole suite
CLAUDE.md 放哪里？
| 位置 | 作用 |
|---|---|
~/.claude/CLAUDE.md |
所有项目的全局指令 |
./CLAUDE.md |
当前项目（建议 commit 到 git） |
./subdir/CLAUDE.md |
子目录专用配置 |
写好 CLAUDE.md 的原则
✅ 放进去的内容：
- Claude 猜不到的 Bash 命令
- 与默认不同的代码风格规则
- 测试指令和偏好
- 项目特定的架构决策
❌ 不要放：
- Claude 自己能从代码里看出来的内容
- 详细的 API 文档（放链接就够了）
- 不常改动的标准规范
⚠️ CLAUDE.md 太长反而有害！Claude 会忽略掉部分内容
管理会话
频繁清除上下文
/clear # 在不相关任务之间清除
使用 /compact 压缩
/compact # 自动压缩
/compact Focus on the API changes # 带指令的压缩
使用子 Agent 做探索
Use subagents to investigate how our auth system handles token refresh
# 子 Agent 探索文件，只把摘要返回给主会话
# 大量文件读取不会污染你的主上下文
用 Rewind 回退
Esc + Esc # 或 /rewind
# 打开回退菜单，恢复之前的对话和代码状态
命名并恢复会话
claude -n auth-refactor # 给会话命名
claude --resume auth-refactor # 后续恢复
自动化与扩展
非交互模式（CI/CD）
claude -p "Explain what this project does"
claude -p "List all API endpoints" --output-format json
claude -p "Analyze this log file" --output-format stream-json
并行多会话
# 同时跑多个任务（不同 worktree）
claude --worktree feature-auth
claude --worktree bugfix-login
批量文件处理
for file in $(cat files.txt); do
claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
--allowedTools "Edit,Bash(git commit *)"
done
自动模式（后台运行）
claude --permission-mode auto -p "fix all lint errors"
# 分类器自动审查命令，阻止高风险操作
常见陷阱
| 陷阱 | 症状 | 解决方法 |
|---|---|---|
| 堆砌会话 | 混入不相关任务，上下文杂乱 | 用 /clear 分隔任务 |
| 反复纠错 | 同一问题改了 3 次还没对 | 清空上下文，用更好的初始 prompt 重新开始 |
| CLAUDE.md 过长 | Claude 忽略某些指令 | 删掉 Claude 不看也会做对的内容 |
| 无限探索 | 让 Claude "研究" 某事，结果读了几百个文件 | 明确缩小范围，或用子 Agent 隔离 |
| 只看不验 | 代码看起来对，但边界情况没处理 | 永远提供验证（测试/截图/检查脚本） |
进阶技巧
让 Claude 先采访你
I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs.
Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.
安装 Hooks（自动触发脚本）
# Claude 会自动运行相关 hook
/hooks # 查看当前配置的 hooks
创建 Skills（专属工作流）
<!-- .claude/skills/fix-issue/SKILL.md -->
---
name: fix-issue
description: Fix a GitHub issue
---
1. Use `gh issue view` to get the issue details
2. Search the codebase for relevant files
3. Implement the fix
4. Write and run tests
5. Create a descriptive commit and PR
使用：/fix-issue 1234
相关链接
- 🚀 快速入门
- 🔄 常见工作流
- ⚙️ Claude Code 设置：https://code.claude.com/docs/en/settings
- 🪝 Hooks 指南：https://code.claude.com/docs/en/hooks-guide
- 🤖 子 Agent 文档：https://code.claude.com/docs/en/sub-agents
- 🔌 MCP 集成：https://code.claude.com/docs/en/mcp