FEATURE ARTICLE

1-5 Claude Code最佳实践指南

Claude Code 环境配置实践，包含 CLAUDE.md 设计原则、分层加载和常见配置建议。

2026-05-22 技术 Claude Code / 环境配置 / CLAUDE.md

难度标注

本文档使用以下标注帮助你根据自身水平选择性阅读：

标注 含义 建议
🟢 基础 每个用户都需要掌握 必读
🟡 进阶 提升效率的关键技巧 熟练后阅读
🔴 高级 团队级和自动化场景 按需深入

1 导读：理解 Claude Code

核心交互模型

它会经历三个阶段：收集上下文、采取行动和验证结果
你的角色：

你做什么 Claude 做什么
通过 @ 引用文件，帮 Claude 看见正确的上下文 阅读文件、搜索代码、理解架构
用自然语言描述需求，帮 Claude 思考正确的方向 分析问题、规划方案、评估风险
配置权限，让 Claude 能够行动 编辑文件、运行测试、执行命令
@ 和 ! 速览
符号 作用 示例
@ 感知：将文件/资源注入上下文 解释 @src/auth.ts 的逻辑
! 行动：在提示框中直接执行 Shell ! git log –oneline -5（结果注入上下文） 
1
2
3
4
5
6
7
8
# @ 的常见用法
> 解释 @src/auth.ts 的逻辑              # 引用单个文件
> 对比 @old-api.ts 和 @new-api.ts       # 引用多个文件
> @src/components 的结构是什么？          # 引用目录

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

2 快速上手

项目目录结构全景 🟢

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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。其他配置随着需求逐步添加。

settings.json 分层配置 🟡

Claude Code 使用分层配置系统，优先级从高到低：

优先级 层级 位置 作用范围 是否共享
最高 🔴 托管策略 系统级路径（IT 部署） 组织内所有用户 是
↓ 命令行参数 CLI flags 当前会话 否
↓ 本地项目设置 .claude/settings.local.json 你在此项目 否
↓ 共享项目设置 .claude/settings.json 所有协作者 是（提交 Git）
最低 🟢 用户设置 ~/.claude/settings.json 你的所有项目 否

规则：高优先级覆盖低优先级。托管策略不可覆盖。

基础配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(curl *)"
    ]
  },
  "enabledPlugins": {
    "example-skills@anthropic-agent-skills": true,
    "context7@claude-plugins-official": true
  },
  "alwaysThinkingEnabled": true,
  "env": {
    "CLAUDE_CODE_EFFORT_LEVEL": "high"
  }
}

提示：添加 $schema 字段可以在 VS Code / Cursor 中获得自动补全。

必备 CLI 工具 🟢

Claude Code 可以调用任何已安装的 CLI 工具。以下工具强烈建议提前安装：

1
2
3
4
5
6
7
8
9
# GitHub CLI（Claude Code 用它操作 PR、Issue）
brew install gh
gh auth login

# jq（Hooks 脚本中解析 JSON 必备）
brew install jq

# ripgrep（高速代码搜索）
brew install ripgrep

关键：CLI 工具是与外部服务交互最节省上下文的方式。例如 gh、aws、gcloud、sentry-cli 等。

快速验证配置 🟢

1
2
3
4
5
6
7
8
9
cd your-project
claude

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

3 给 Claude 验证自己工作的能力

四种验证策略 🟢

策略 模糊做法 ❌ 高效做法 ✅
提供测试用例 “实现一个验证邮箱的函数” “写一个 validateEmail 函数。测试: user@example.com → true, invalid → false, user@.com → false。实现后运行测试。”
UI 变更截图对比 “让 dashboard 更好看” “[粘贴截图] 按这个设计实现。完成后截图对比原图，列出差异并修复。”
根因修复 “构建失败了” “构建失败，错误信息: [粘贴]。修复它并验证构建成功。解决根本原因，不要抑制错误。”
指定验证命令 “修改认证流程” “修改认证流程后，运行 npm test – –testPathPattern auth 验证所有认证测试通过。”

4 先探索，再计划，再编码

为什么需要分阶段 🟢

让 Claude 直接跳到编码可能产出解决错误问题的代码。使用 Plan Mode 将探索与执行分离。

推荐的工作流有四个阶段：

阶段 模式 做什么 关键操作
1️⃣ 探索 Plan Mode（只读） 理解代码库、定位相关文件 Shift+Tab 进入 Plan Mode
2️⃣ 计划 Plan Mode（只读） 制定实施方案、确认范围 Ctrl+G 在编辑器中编辑计划
3️⃣ 编码 Normal Mode 按计划实现、运行测试 Shift+Tab 切回 Normal Mode
4️⃣ 提交 Normal Mode 提交代码、创建 PR /commit-push-pr

Boris Pro Tip B3：Boris 把 Plan Mode 视为基础操作而非可选步骤。他的日常流程是：先让 Claude 在 Plan Mode 下理解代码、生成计划，然后用第二个 Claude 会话审计这个计划的合理性，确认后才开始编码。

第一阶段：探索（Explore）🟢

按 Shift+Tab 切换到 Plan Mode，让 Claude 只读地探索代码库：

1
2
3
# 进入 Plan Mode 后
> 阅读 /src/auth 目录，了解我们如何处理会话和登录。
> 同时看看我们如何管理用于密钥的环境变量。

Plan Mode 的特点：

  • Claude 只执行读取操作，不会修改任何文件
  • 适合安全地探索不熟悉的代码
  • 按 Shift+Tab 循环切换：Normal Mode → Auto-Accept Mode → Plan Mode

也可以从命令行启动：

1
claude --permission-mode plan

第二阶段：计划（Plan）🟢

让 Claude 在 Plan Mode 下创建详细的实施计划：

1
2
> 我想添加 Google OAuth 登录。需要修改哪些文件？
> 会话流程是怎样的？创建一个实施计划。

关键操作：

  • 按 Ctrl+G 在文本编辑器中打开计划，可以直接编辑
  • 计划确认后再切换到 Normal Mode 执行
  • 你可以修改计划中的任何部分，删除不需要的步骤，或添加额外约束

用第二个 Claude 审计计划 🟡

对于复杂任务，Boris 推荐的做法是：

1
2
3
4
5
6
# 会话 A（Plan Mode）
> 分析 @src/auth 目录，制定添加 Google OAuth 的实施计划

# 会话 B（独立会话）
> 审查这个实施计划 [粘贴计划]。
> 指出遗漏的边界情况、潜在的安全问题、和更好的替代方案。

第三阶段：编码（Implement）🟢

切换回 Normal Mode，让 Claude 按计划编码：

1
2
> 按你的计划实现 OAuth 流程。
> 为回调处理器编写测试，运行测试套件并修复所有失败。

增量开发技巧：

  • 写一个文件 → 测试 → 继续，尽早发现问题
  • 如果 Claude 偏离方向，按 Esc 立即停止
  • 按两次 Esc 或 /rewind 回到之前的检查点

第四阶段：提交（Commit）🟢

1
> 用描述性的消息提交更改并创建 PR

或直接使用自定义 Skill：

1
> /commit-push-pr

实战：用规范驱动开发（SDD）做业务需求 🟡

规范驱动开发（Spec-Driven Development, SDD） 提供了一种更结构化的做法：先把需求写成 Markdown 规范文件，再用 Claude Code 逐步实现。

核心理念

传统做法 SDD 做法
口述需求 → Claude 直接写代码 先写 spec.md → Claude 按规范编码
需求散落在聊天记录中 规范集中在文件中，可版本管理
发现问题时改代码 发现问题时先改规范，再重新生成
Claude 的理解随上下文衰减 每次通过 @spec.md 注入完整需求

核心价值：把”发现需求理解偏差”的成本从”改代码”左移到”改 Markdown”——代价低一个数量级。

三层产物

1
2
3
4
specs/001-feature-name/
├── spec.md      ← WHAT：功能需求（用户故事、验收标准、边界情况）
├── plan.md      ← HOW：技术方案（架构设计、数据结构、接口定义）
└── tasks.md     ← DO：原子任务（逐步执行指令，每个任务改一个文件）
产物 定位 核心内容 谁来写
spec.md 需求规范（WHAT/WHY） 用户故事、验收标准、边界情况、MVP 范围 你主导，Claude 辅助提问
plan.md 技术方案（HOW） 技术选型、目录结构、数据模型、接口设计、风险评估 Claude 主导，你审核决策
tasks.md 执行计划（DO） 原子化任务列表、依赖关系、TDD 顺序 Claude 生成，你审核完整性

在 Claude Code 中实操

第一步：协作编写 spec.md

1
2
3
> 我想构建 [功能描述]。用采访模式对我进行详细提问，
> 帮我生成一份 spec.md，包含：用户故事、验收标准、边界情况。
> 不要写任何技术实现细节。

第二步：生成 plan.md

1
2
3
4
> @specs/001-feature/spec.md
> 基于这份需求规范，生成技术方案 plan.md。
> 技术栈约束：[TypeScript / React / PostgreSQL]
> 包含：目录结构、核心数据模型、接口定义、实施阶段。

第三步：分解 tasks.md

1
2
3
> @specs/001-feature/spec.md @specs/001-feature/plan.md
> 将技术方案分解为原子任务列表 tasks.md。
> 要求：每个任务只改一个文件，测试先行（奇数任务写测试，偶数任务写实现）。

第四步：逐步执行

1
2
> @specs/001-feature/tasks.md
> 执行任务 T001-T006。严格按 TDD 顺序：先写测试（必须失败），再写实现（使测试通过）。

TDD 防幻觉原则

这是 SDD 中最实用的洞察：

⚠️ 不要让 Claude 同时写代码和测试。如果它先写了有 Bug 的代码，再写测试，它会写出”验证错误逻辑”的测试——一切绿色但全是错的。

正确做法：测试先行，独立验证。

1
2
3
4
5
6
# ❌ 错误：同时生成
> 实现用户注册功能，并编写测试

# ✅ 正确：分步进行
> 第一步：为用户注册写测试用例，覆盖正常流程和边界情况。先不要实现。
> 第二步：现在实现代码，使所有测试通过。不要修改测试。

防止 AI 偷改测试：仅靠提示词说”不要修改测试”并不可靠。建议用三层防护：

  1. 提示词约束：在 CLAUDE.md 中写明 严禁修改 *_test.go / *.test.ts 文件
  2. 权限控制：在 .claude/settings.json 中配置 "deny": ["Write(*_test.go)", "Write(*.test.ts)"]
  3. Git 兜底：先提交测试代码，实现完成后用 git diff 检查测试文件是否被意外修改

第 2 层是关键——即使 AI 忽略提示词，权限系统也会硬性阻止。

何时使用 SDD

场景 推荐做法
修 Bug、小改动、单文件 直接编码（3.6 的流程）
明确的小功能（< 3 文件） Plan Mode → 编码（3.1-3.5 的流程）
完整业务功能、新模块、多文件 SDD 三层规范 → 逐步实现
大型重构、系统迁移 SDD + worktree 并行（第 9 节）

5 提供具体的上下文

5.1 具体化原则 🟢

Claude 能推断意图，但无法读你的心。引用具体文件、提及约束、指向示例模式。

策略 模糊提示 ❌ 具体提示 ✅
限定范围 “添加测试” “为 foo.py 编写测试，覆盖用户已注销的边界情况。不要使用 mock。”
指向来源 “为什么 API 设计这么奇怪？” “查看 ExecutionFactory 的 git 历史，总结它的 API 是怎么演变成现在这样的”
参考已有模式 “添加日历组件” “查看首页已有 widget 的实现方式，HotDogWidget.php 是好的参考。按相同模式实现日历组件。”
描述症状 “修复登录 bug” “用户报告会话超时后登录失败。检查 src/auth/ 中的 token 刷新。写一个能复现问题的失败测试，然后修复它。”

模糊提示有时也有用——当你在探索阶段、可以承受方向纠正时。"这个文件有什么可以改进的？" 可能发现你没想到的问题。

丰富的上下文输入方式 🟢

![[Pasted image 20260304161759.png]]

用 @ 引用文件

1
2
> 解释 @src/utils/auth.js 中的逻辑
> 对比 @src/old-api.ts 和 @src/new-api.ts 的实现差异

@ 引用文件时，Claude Code 会自动加载该文件所在目录的 CLAUDE.md。

粘贴截图/图片

  • 直接拖放图片到 Claude Code 窗口
  • 使用 Ctrl+V 粘贴剪贴板中的图片
  • 提供图片路径：分析这张截图: /path/to/screenshot.png

管道输入

1
2
3
4
5
6
7
8
# 文件内容传入
cat error.log | claude -p "简洁地解释这个构建错误的根因"

# 命令输出传入
git diff main | claude -p "审查这些变更中的安全问题"

# 多个文件传入
git diff main --name-only | claude -p "审查这些修改过的文件"

提供 URL或者文件、目录

1
2
3
参考 https://docs.example.com/api-v2 的文档，为我们的客户端添加 v2 支持

参考文档 ~/Download/design_doc/implementation_plan.md

使用 /permissions 将常用域名加入白名单，避免每次批准。

让 Claude 自己获取上下文

不需要你手动提供一切——Claude 可以自己通过 Bash 命令、MCP 工具、文件读取来获取上下文。

Boris Pro Tip B4：Boris 大量使用语音输入（macOS 上按两次 fn 键触发听写），他发现语音描述需求比打字快约 3 倍。语音天然产出更详细的描述，而 Claude 擅长理解非结构化的自然语言。

提示词结构图 🟡

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

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

结构化提示模板 🟡

功能开

1
2
3
4
5
6
7
8
9
10
11
12
13
14
实现 [功能描述]。

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

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

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

Bug 修复模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
修复 [问题描述]。

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

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

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

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

代码审查模板

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

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

采访模式：让 Claude 采访你 🟡

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

AskUserQuestion：采访模式的秘密武器

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
我想开发一款独特的小游戏，但具体做什么、怎么做还没想好。

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

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

从第一轮开始吧。

当你耐心回答完所有问题，就得到了一份完整的需求文档：
适用环境：AskUserQuestion 在 Claude Code IDE Extension 和 CLI 中都可用。在 CLI 里，用键盘上下箭头选择选项。

标准提示模板

1
2
3
4
5
6
我想构建 [简要描述]。用 AskUserQuestion 工具对我进行详细采访。

问我关于技术实现、UI/UX、边界情况、顾虑和权衡的问题。
不要问显而易见的问题，深入挖掘我可能没有考虑到的困难部分。

持续采访直到我们覆盖了所有方面，然后把完整的需求规格写入 SPEC.md。

引申用法：用 AskUserQuestion 排查盲区

对于真实项目中的复杂问题，当你有不确定的地方，可以这样用：

1
2
3
4
5
对于这个问题，我们还有哪些没有考虑到的？

使用 AskUserQuestion 工具，像苏格拉底一样帮助我，
无论是技术选型、潜在风险、需求对齐等等任何方向，
因为我是小白我什么都不懂，请帮助我理解。

这个模式把 Claude 从「执行者」变成了「顾问」——它不再猜你想要什么，而是通过结构化提问帮你自己想清楚。
完成采访后，开一个新会话来执行规格。新会话有干净的上下文，完全聚焦于实现。