Claude Code 实用技巧

Claude Code 实用技巧是一套针对 Anthropic 官方命令行编码工具的实际操作方法，涵盖前置检查、常用命令、上下文管理、错误恢复和会话效率优化。这些技巧的核心价值在于帮你把 Claude Code 从"能跑起来"推进到"用得顺手"，尤其是处理长会话的项目级任务时，正确的操作顺序和检查点可以大幅减少无效对话和上下文溢出。如果你对工具的基础概念尚不熟悉，建议先阅读 Claude Code 核心概念与工作流，这部分内容能帮你建立操作前的思维框架。

本文假设你已安装了 Claude Code（通过 npm install -g @anthropic-ai/claude-code 或系统包管理器），并且拥有可用的 API 密钥或已登录 Claude 账号。如果你的环境尚未完成这些前置条件，Claude Code 安装与初始设置指南 可以帮助你快速补齐。

下一步：请求与响应格式 入门教程、请求与响应格式 实用技巧

Before you start

开始应用实用技巧前，先确认三个基础条件是否满足。新手最容易在这里卡住，检查完成后后续操作会更顺畅。若你在项目初始化时遇到障碍，可参考 项目环境标准化配置 获取更系统的指导。

• 检查当前版本：每次使用前运行 claude --version，对比 Claude Code 官方发布页的版本号。不同版本之间的 CLI 参数和内核行为差异较大（比如从 v0.4.x 到 v0.5.x，--allow-write 的生效范围发生过变化），直接复制网络上的旧版命令而不验证版本是常见错误之一。版本相关的深度解析可查阅 Claude Code 版本差异与迁移。
• 确认会话上下文可用量：Claude Code 在终端顶部会显示当前会话的令牌消耗进度条。建议在实际项目操作前，用一个简短的测试指令如 ls -la 确认进度条位置——如果已经超过 70%，先开一个新会话再来做需要多轮修改的任务。关于令牌管理的最佳实践，详见 会话上下文窗口管理。
• 检查 API 或本地认证状态：运行 claude status 查看连接状态和剩余配额。如果使用 API Key 模式，额度率可能只有 2 RPM，此时逐步修改而非一次性发出长指令会更高效。认证问题的排查流程，请参考 Claude Code 认证问题解决。

以下是一个快速环境核查示例：

检查项	命令或方法	预期正常状态	问题信号
版本兼容	claude --version	与官方最新小版本一致	低于 v0.5.0 时某些参数不生效
令牌水位	查看终端顶部进度条	< 60%	接近 80% 时应开启新会话
认证状态	claude status	显示 "connected"	显示 "auth expired" 或 "rate-limited"
项目根目录	确认 .claude 或 CLAUDE.md 存在	项目有自定义系统提示	缺少项目配置时可手动添加

检查的顺序不能调换：先确认版本（不同版本参数解析可能不同），再确认认证和配额（版本身后认证才会走对的路由），最后看令牌水位（它会随会话数变化）。为了确保检查高效且不遗漏，建议配合 日常检查清单模板 进行核对。

Tips for efficient daily usage

前置准备：配置项目级上下文

Claude Code 会读取项目根目录下的 CLAUDE.md 文件作为系统提示的一部分。这一步不是可选的——在中小型项目中，它会直接影响模型对你的代码库结构的理解准确性。如果你对如何设计系统提示感到困惑，CLAUD.md 编写最佳实践 提供了更详细的规范说明。

在你的项目根目录创建 CLAUDE.md，至少包含以下内容：

# Project: 项目名称

## 技术栈
- 语言：TypeScript 5.x + Node 20
- 框架：Next.js 14, App Router
- 数据库：PostgreSQL 16, Prisma ORM
- 目录结构：/src/app 下为路由组件，/src/lib 为业务逻辑

## 编码规范
- 所有组件使用默认导出
- 类型定义放在 /src/types 下
- API 路由命名遵循 /api/v1/resource

## 当前工作上下文
- 正在重构用户认证模块
- 避免修改 /src/lib/legacy-auth.ts
- 测试覆盖率要求 > 80%

重点：只写当前迭代的真实信息。过时的技术栈或已废弃的目录结构比没有更糟糕——模型会根据这些信息推断错误路径，导致生成的代码不能编译。关于上下文配置的常见错误，请参阅 上下文配置陷阱与回避。

步骤一：任务分片

不要一次发出 "帮我优化这个整个项目的性能" 这样的指令。Claude Code 的单次上下文中能有效处理的文件数有限（实际观察中大约 5-8 个关键文件是稳定区间）。要掌握任务拆分的系统方法，可参考 任务分片与渐进式开发。

正确做法是将大任务拆分为可验证的小块。例如：

• 错误做法："重构支付模块的整个错误处理系统。"
• 正确做法：
  1. "分析 /src/payments/errors.ts 中的自定义错误类，列出继承关系和缺失的类型约束。"
  2. "为缺货场景（InventoryShortfallError）添加 payload 类型定义和对应的错误码常量。"
  3. "在 /src/payments/handlers.ts 中已有 catch 块中引入新的错误类型，只修改第一个 handler。"

每个子任务完成后立即验证结果（比较预期输出与实际输出），确认无误后再进入下一步。这样即使后续步骤出现问题，也可以回退到上一个已知正确的状态——Claude Code 的工作区会自动创建 .gitignore 中文件的备份，但依赖版本管理的回滚更可靠。关于验证各子任务结果的更多方法，见 任务验证与回滚策略。

步骤二：利用 .claudeignore 控制扫描范围

默认情况下 Claude Code 会扫描项目的文件树，但大型项目中的 node_modules、.next 构建产物、日志文件等会浪费上下文窗口。

在项目根目录创建或编辑 .claudeignore：

node_modules/
.next/
dist/
*.log
*.min.js
*.map
coverage/

注意事项：不要用 .gitignore 直接当 .claudeignore 使用。gitignore 中的某些模式（如 /build/）可能不够宽，Claude Code 的 ignore 模式匹配行为略有不同。建议保留两份文件，但保持同步的排除规则。详细的规则编写方法，请参考 .claudeignore 规则编写参考。

验证方法：运行 claude "列出项目中的全部文件类型分布"（不写 claude --dry-run），观察它的回复中是否出现了本应被忽略的目录。如果看到了 dist/ 下的内容，说明 ignore 规则未生效或路径写错了。验证过程中若遇到调试困难，文件扫描范围调试指南 提供了系统的排查步骤。

步骤三：善用 --allow-read / --allow-write 作用域

Claude Code 的读写权限可以限定到指定目录，而不是开放全部文件系统权限。这在多模块项目中尤其重要——限制写入范围可以减少意外修改的风险。

• claude --allow-read=/src/api,/src/lib — 只允许读取两个目录，无论模型生成什么都不会写磁盘。
• claude --allow-write=src/components — 允许写组件目录，但禁止修改配置文件或 test 目录中的内容。

边界情况：如果你的项目使用软链接或符号链接，Claude Code 的路径解析可能会把链接目标视作实际路径。例如 src/shared -> ../packages/shared，那么 --allow-read=src 不会自动覆盖 ../packages/shared 的读取权限，需要显式添加。可以先在项目根目录运行 find . -type l -ls 列出链接并在参数中包括它们。关于权限管理的更详细说明，参见 读写权限与安全配置。

步骤四：会话状态管理与恢复

Claude Code 会在后台维护一个 .claude/sessions/ 目录，记录会话历史。当你遇到上下文溢出或模型输出质量下降时，不必从头开始。以下是一个可复现的检查步骤：

1. 确认起始状态：运行 claude sessions list 查看最近会话列表，注意时间戳和会话摘要。
2. 恢复指定会话：claude --continue <session_id>

关于会话恢复的最佳实践，请参考 会话生命周期管理。此外，错误恢复与故障排除 提供了