Claude Code 最佳实践指南

AI2026年2月27日161 次阅读约 19 分钟

前言

本文档的核心目标：帮助团队成员高效使用 Claude Code。

内容以官方最佳实践为主线，穿插 Claude Code 之父 Boris Cherny 在 X 上分享的真实工作流（标注为 Boris Pro Tip），并从团队实践中提取实用模板。

一个核心约束贯穿全文：Claude 的上下文窗口（~200K tokens）会快速填满，而填满后性能会下降。几乎所有最佳实践都围绕这个约束展开。

1. Claude Code 的核心交互模型 🟢

当你给 Claude 一个任务时，它会经历三个阶段：收集上下文、采取行动和验证结果。这些阶段相互融合。Claude 始终使用工具，无论是搜索文件以了解你的代码、编辑以进行更改，还是运行测试以检查其工作。

你的角色：

你做什么	Claude 做什么
通过 @ 引用文件，帮 Claude 看见正确的上下文	阅读文件、搜索代码、理解架构
用自然语言描述需求，帮 Claude 思考正确的方向	分析问题、规划方案、评估风险
配置权限，让 Claude 能够行动	编辑文件、运行测试、执行命令

@ 和 ! 速览

符号	作用	示例
@	感知：将文件/资源注入上下文	解释 @src/auth.ts 的逻辑
!	行动：在提示框中直接执行 Shell	! git log --oneline -5（结果注入上下文）

# @ 的常见用法
> 解释 @src/auth.ts 的逻辑              # 引用单个文件
> 对比 @old-api.ts 和 @new-api.ts       # 引用多个文件
> @src/components 的结构是什么？          # 引用目录

# ! 的常见用法
> ! git diff --stat                       # 执行命令，结果注入上下文
> ! npm test 2>&1 | tail -20              # 运行测试，截取尾部

2. Effort Level 🟢

Opus 4.6 引入了 Adaptive Thinking（自适应思考）——Claude 会根据任务复杂度自动决定是否以及多少使用深度推理。你通过 effort level 来控制推理深度，而不再需要在提示词中写 think hard 或 ultrathink 等关键词。

三个等级：

Effort Level	推理行为	适用场景
High（默认）	Claude 几乎总是进行深度思考	复杂架构设计、多文件重构、疑难 Bug
Medium	适度思考，简单问题可能跳过	日常编码、跨文件修改、中等复杂度任务
Low	最小化思考，优先速度	简单问答、格式化、小修改

💡 API 层面还支持 max 等级（仅 Opus 4.6），思考无上限。Claude Code CLI 目前暴露 low/medium/high 三级。

配置方式（三选一）：

# 方式 1：在 /model 菜单中用 ← → 箭头键调节滑块
/model

# 方式 2：环境变量
export CLAUDE_CODE_EFFORT_LEVEL=low    # low | medium | high

# 方式 3：settings.json
{
  "effortLevel": "high"
}

3. 项目目录结构全景 🟢

一个完整的 Claude Code 项目配置结构：

your-project/
├── CLAUDE.md                    # 📋 项目级指令（团队共享，提交到 Git）
├── CLAUDE.local.md              # 👤 个人项目偏好（自动 gitignore）
├── .claude/
│   ├── settings.json            # ⚙️ 项目设置（团队共享）
│   ├── settings.local.json      # 👤 个人项目设置（gitignore）
│   ├── CLAUDE.md                # 📋 等效于根目录 CLAUDE.md
│   ├── rules/                   # 📏 模块化规则文件
│   │   ├── code-style.md        #    代码风格
│   │   ├── testing.md           #    测试规范
│   │   └── security.md          #    安全要求
│   ├── agents/                  # 🤖 自定义子代理
│   │   ├── code-reviewer.md
│   │   └── debugger.md
│   ├── skills/                  # ⚡ 自定义技能
│   │   └── fix-issue/
│   │       └── SKILL.md
│   └── worktrees/               # 🌳 Git Worktree 目录（加入 .gitignore）
├── .mcp.json                    # 🔌 项目级 MCP 服务器配置
└── .github/
    └── workflows/
        └── claude.yml           # 🔄 Claude Code GitHub Actions

新手提示：刚开始只需要 CLAUDE.md 和 .claude/settings.json。其他配置随着需求逐步添加。

4. 快速验证配置 🟢

cd your-project
claude

# 在 Claude Code 中运行
> /init          # 自动生成 CLAUDE.md
> /config        # 查看/修改全局配置
> /permissions   # 查看/修改权限规则
> /cost          # 查看当前会话 token 用量
> /context       # 查看上下文消耗分布

5. 你的第一次对话 🟢

安装完成后，试试这些命令快速上手：

# 探索项目（最安全的开始方式）
> 给我一个这个代码库的概览

# 理解代码
> 解释 @src/main.ts 的主要逻辑

# 做一个小修改
> 把 @src/utils/format.ts 中的 formatDate 函数改为支持 ISO 8601 格式

# 验证修改
> 运行测试确认修改没有破坏任何东西

6. 提示词结构图 🟡

一个高质量提示词的结构：

┌─────────────────────────────────────────────┐
│  1. 任务描述                                 │
│     做什么？（一句话清晰描述）                 │
├─────────────────────────────────────────────┤
│  2. 上下文                                   │
│     相关文件：@path/to/files                  │
│     参考模式：@path/to/example                │
│     背景信息：为什么要做这个                    │
├─────────────────────────────────────────────┤
│  3. 约束                                     │
│     不能做什么 / 必须满足什么                   │
│     "不引入新依赖"、"保持向后兼容"              │
├─────────────────────────────────────────────┤
│  4. 验证标准                                  │
│     怎么确认做对了？                           │
│     "运行 npm test"、"截图对比"               │
└─────────────────────────────────────────────┘

7. 结构化提示模板 🟡

功能开发模板

实现 [功能描述]。

上下文：
- 相关文件：@path/to/relevant/files
- 参考已有模式：@path/to/similar/implementation

要求：
1. [具体要求 1]
2. [具体要求 2]
3. [具体要求 3]

验证：
- 运行 `npm test` 确保所有测试通过
- 运行 `npm run typecheck` 确保无类型错误

Bug 修复模板

修复 [问题描述]。

复现步骤：
1. [步骤 1]
2. [步骤 2]
3. [出现错误]

错误信息：
[粘贴完整错误信息或堆栈跟踪]

期望行为：[描述正确行为]

请：
1. 找到根因
2. 写一个能复现问题的失败测试
3. 修复问题
4. 确认测试通过

代码审查模板

审查 @path/to/file 的以下方面：
- 安全漏洞（注入、XSS、认证问题）
- 边界情况处理
- 性能问题
- 与项目现有模式的一致性

对每个问题给出：
1. 问题严重度（Critical / Warning / Suggestion）
2. 具体位置（文件名和行号）
3. 修复建议

8. 采访模式：让 Claude 采访你 🟡

对于大型功能，让 Claude 先采访你以明确需求，而不是一开始就写代码。

AskUserQuestion：采访模式的秘密武器

AskUserQuestion 是 Claude Code 内置的一个交互工具。当 Claude 需要你做决策时，它会弹出结构化的选择题界面——不需要你打字组织语言，只需点击选项即可。

这个工具有时会被 Claude 自动触发，但你也可以显式要求使用它。

实战演示：用苏格拉底式提问对齐需求

假设你要做一个「与众不同的小游戏」，在 Claude Code 中输入：

我想开发一款独特的小游戏，但具体做什么、怎么做还没想好。

请你作为游戏策划顾问，用苏格拉底式提问法帮我从零厘清思路。要求：

 - 必须使用 AskUserQuestion 工具向我提问，不要用纯文字提问
 - 每轮提问后，根据我的回答总结洞察，再发起下一轮提问
 - 至少覆盖以下维度：游戏类型、核心玩法、美术风格、目标平台、技术方案
 - 灵活运用 single_select、multi_select、rank_priorities 三种题型
 - 3-5 轮提问结束后，输出一份「游戏设计一页纸」

从第一轮开始吧。

9. 编写有效的 CLAUDE.md 🟢

CLAUDE.md 是一个特殊文件，Claude 在每次会话开始时读取它。写入 Bash 命令、代码风格、工作流规则等Claude 无法从代码中推断的信息。

什么该写，什么不该写

该写 ✅	不该写 ❌
Claude 猜不到的 Bash 命令	Claude 读代码就能知道的信息
与默认不同的代码风格规则	标准语言规范（Claude 已知）
测试指令和首选测试框架	详细的 API 文档（链接即可）
仓库约定（分支命名、PR 格式）	频繁变化的信息
项目特有的架构决策	长篇教程或解释
开发环境怪癖（必需的环境变量）	逐文件的代码库描述
常见陷阱和非显而易见的行为	"写干净的代码"之类的废话

格式自由但保持精炼，例如：

# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, not the whole test suite, for performance

CLAUDE.md 模板集 🟢

最小可用模板

# 构建
- 安装：`npm install`
- 测试：`npm test`
- Lint：`npm run lint`

# 规范
- TypeScript strict 模式
- 提交消息使用 Conventional Commits

通用项目模板

# 项目：[项目名]
[一句话描述]。技术栈：[列出关键技术]。

# 构建与测试
- 安装：`pnpm install`
- 开发：`pnpm dev`
- 构建：`pnpm build`
- 测试全部：`pnpm test`
- 测试单个：`pnpm test -- path/to/test`
- 类型检查：`pnpm typecheck`
- Lint：`pnpm lint`

# 代码规范
- 使用 ES modules（import/export）
- 函数参数 >3 个时使用对象参数
- 错误处理使用 AppError 类（@src/lib/errors.ts）
- API 路径 kebab-case，JSON 属性 camelCase

# 架构
- 状态管理：Zustand（不是 Redux）
- ORM：Drizzle（不是 Prisma）
- API：tRPC

# 工作流
- **IMPORTANT**: 修改代码后运行 `pnpm typecheck`
- **NEVER**: 不要修改 migrations/ 下的已有文件
- 提交遵循 Conventional Commits

# 压缩指令
When compacting, preserve:
- 修改过的文件完整列表
- 测试命令和结果
- 未完成的任务

前端项目模板

# 构建命令
- 开发：`pnpm dev`（端口 3000）
- 构建：`pnpm build`
- 测试：`pnpm test`（Vitest）
- E2E：`pnpm e2e`（Playwright）

# 代码规范
- 函数式组件 + hooks
- Tailwind CSS（不用 CSS modules）
- 导入顺序：React → 第三方 → 本地 → 类型 → 样式

# 组件结构
- 页面：`src/app/`（Next.js App Router）
- 组件：`src/components/`
- 参考：`src/components/ui/Button.tsx`

# 测试
- 优先运行单个测试文件
- UI 变更后截图对比验证

10. 配置权限 🟡

默认情况下，Claude Code 对可能修改系统的操作请求权限。这很安全但频繁打断你。

权限允许列表

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git commit *)",
      "Bash(git push *)"
    ],
    "ask": [
      "Bash(git push --force *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)",
      "Bash(rm -rf *)"
    ]
  }
}

继续阅读

基于全文检索与主题相似度

AI2025年9月10日