Claude Code 最佳实践完整指南 最新更新

在 Claude Code 的实际运用中，合理配置 CLAUDE.md 文件并掌握一系列工作流程，能够显著提升开发效率。本文将系统梳理从配置原则到工具组合的完整实践路径，帮助用户避免常见陷阱并最大化 AI 助手的价值。

一、CLAUDE.md 配置原则

核心原则：保持简短

1. 控制在 60 行以内，硬上限 300 行。
2. LLM 能可靠遵循约 150-200 条指令，Claude Code 系统提示已占用约 50 条。
3. 只放 Claude 可能忽略的信息：构建命令、测试命令、分支命名规范、项目特定架构决策。
4. 能从代码推断的内容不要写进去。
5. 规则太多？拆分到 .claude/rules/ 目录下按需加载。
6. 关键规则用标签包裹防止被忽略。
7. 运行 /doctor 可检查 CLAUDE.md 中有哪些内容 Claude 其实能自行推导，把冗余指令删掉。

示例：好的 CLAUDE.md 结构

## 工作流
- 每次代码变更后运行 `npm test`
- 每个任务创建新分支，绝不直接提交到 main
- 使用 Conventional Commits（feat:, fix:, refactor:, docs:）
- 每次提交前运行 `eslint . --fix`
- 完成后通过 `gh pr create` 创建 PR
## 技术栈
- Node.js 18+, Express 4.x, PostgreSQL 16
- 测试：Jest + React Testing Library
- 认证：JWT + bcrypt

二、工作流最佳实践

1. 复杂任务用 Plan Mode

1. 按 Shift+Tab 两次进入计划模式。
2. Claude 只研究和规划，不写代码。
3. 确认计划后再切换回正常模式执行。
4. 官方推荐流程：探索 → 规划 → 实现 → 提交。

2. 让 Claude 先采访你

1. 给出简单需求描述，让 Claude 用 AskUserQuestion 工具采访你。
2. 它能发现你忽略的边缘情况。
3. 采访后开新会话执行（采访对话会污染上下文）。

3. 分阶段工作流

1. 理解代码库 → 修改。
2. 先规划 → 再实现。
3. 生成 → 验证。
4. 不要把所有步骤压缩到一个大提示词里。

4. 小任务别用复杂工作流

1. 3-5 分钟能完成的事，直接用原生 Claude Code。
2. 复杂工作流（Superpowers、Workflows 等）适用于多文件、多步骤的大任务。
3. 重命名变量这种小事，一句话就行。

5. 善用 ! 命令的自动响应

1. Bash 模式下执行命令后，Claude 会自动分析输出并判断是否需要行动，不需要额外指示。
2. 如果你需要聚焦自己读输出，可以在 settings.json 中设置 "respondToBashCommands": false。

6. 用大模型做大活，用小模型做小活

1. 日常编码用 Sonnet 5（默认模型，1M 上下文窗口，性价比最高）。
2. 复杂架构设计切 Opus 4.8（更高精度）。
3. 极限推理任务切 Fable 5（最强推理能力）。
4. 临时切换：/model claude-fable-5。
5. 备用模型配置：设置 fallbackModel 防止主模型不可用时卡住。

7. 重复性监控用 /loop

1. /loop 让 Claude 按固定间隔反复执行一个任务，适用于：
   1. 监控部署状态：/loop 5m 检查 staging 部署是否完成。
   2. 等待外部依赖：/loop 30s 看看 CI 跑完了没有。
   3. 定时检查告警：/loop 10m 检查日志中有没有新增的 error。
2. /loop <间隔> <提示词>，间隔支持 5m（分钟）、30s（秒）、1h（小时）。
3. /proactive 是 /loop 的别名，两者功能相同。
4. 按 Esc 取消等待中的下一次唤醒。
5. 注意：/loop 在远程会话中不会被持续唤醒，远程环境建议用替代方案。

8. 输出复杂结果用 Artifacts 发布页面

1. 依赖 project-artifact 插件。
2. 当终端文字不够直观时，让 Claude 发布一个交互页面（Artifact），发布到 claude.ai 的私有链接。
3. 适用场景：
4. PR 走查：让 Claude 把 diff 逐行标注发布为可交互页面，比看终端输出直观得多。
5. 数据仪表盘：从会话数据生成图表、仪表盘发布为网页。
6. 文档输出：复杂的技术文档直接渲染为 HTML 页面。
7. 用法：做一个 artifact，用 diff 逐行标注的方式走查这个 PR。
   1. Claude 会先创建内容，然后请求你批准发布。
   2. Artifact 会随着会话更新实时刷新，不需要重复发布。
8. 注意：Artifacts 目前在 Team 和 Enterprise 计划上 beta 可用。

三、调试与纠错

1. 粘贴 bug，说"fix"

1. 把错误信息粘贴给 Claude，说一个字：“fix”。
2. 不要指导怎么修，不要猜测原因，不要指定解决方案。
3. Claude 的调试能力比想象中强，管得越多越容易带偏。
4. 直接让 Claude 修的成功率 80%+。

2. 两次失败 = /clear

1. 同一个问题修正超过两次，/clear 重新开始。
2. 上下文污染会降低性能。
3. 官方建议：修正超过两次就重启。
4. 如果清空后又想找回历史，可以用 /rewind 回退到 /clear 之前的对话。

3. 走偏了？Esc Esc 回滚

1. 按两次 Esc（或 /rewind）直接回滚到上一个检查点。
2. 在同一上下文中纠正偏差往往更糟。
3. 同一个问题偏差两次？/clear 重启。

4. 要求重写平庸方案

1. 当 Claude 给出能工作但不优雅的解决方案时，不要修补。
2. 说：“知道你现在知道的一切，抛弃这个，实现优雅的解决方案”。
3. 重写版本通常比修补版本好得多。

5. 用 /doctor 做定期健康检查

1. 每隔一段时间运行 /doctor，它会检查：安装健康度、未使用的 Skills/MCP/插件、重复的 CLAUDE.md、慢速 Hooks。
2. 把不用的东西清掉，既省上下文也省 token。

6. 配置出问题时用 --safe-mode

1. 如果怀疑自定义配置（CLAUDE.md、插件、Hooks 等）导致 Claude 行为异常，用 --safe-mode 启动。
2. 所有自定义配置被禁用，能快速定位问题源。

四、上下文管理

1. 50% 时手动压缩

1. 上下文使用超过 60-70% 时，性能明显下降。
2. 在 50% 时手动执行 /compact，不要等自动压缩。
3. 用 /statusline 实时监控使用情况。
4. 或使用 /clear 开新会话。
5. Sonnet 5 拥有 100 万 token 窗口，长上下文会话更需要主动管理，不要等到快满了才压缩。

2. /compact 可指定压缩策略

# 聚焦 API 变更压缩
/compact focusing on API changes
# 保留测试相关历史
/compact keep test-related history
# 保留错误解决历史
/compact keep error resolution

3. 切换目录用 /cd 不要用 /clear

1. 需要切到项目另一个子目录继续工作时，用 /cd <新路径>。
2. 不会破坏提示缓存，上下文窗口不受影响。
3. 比 /clear + 重新启动效率高得多。

4. Checkpoints（检查点）

1. 每次 Claude 操作自动创建。
2. 可独立回滚对话或代码。
3. 跨会话持久化。
4. 不是 git 的替代品。

五、Subagents（子智能体）

1. 什么时候该用子智能体

1. 当任务可以自然拆分为多个独立单元时，在提示词中加 “use subagents”。
2. 典型场景：代码审查、大规模重构、多模块并行开发。
3. 子智能体有独立的上下文窗口，研究、验证、审查隔离进行，防止污染和偏见。

2. 专用子智能体 > 通用 mega-agent

1. 创建功能特定的子智能体（如"前端组件智能体"），而不是通用的（如"QA 智能体"）。
2. 功能越具体，上下文越精准，效果越好。
3. 子智能体可嵌套最多 5 层，复杂任务可以逐层抽象，但日常使用 1-2 层就够了。

3. 后台子智能体可以在重启后自动恢复

1. 长时间运行的任务放到后台执行（/bg 或 ←←）。
2. daemon 升级或重启后，后台子智能体会自动恢复，不再丢失进度。
3. 通过 claude agents 列表查看和管理所有运行中的会话。

4. 子智能体有独立上下文窗口

1. 研究、验证、审查隔离在独立上下文中。
2. 防止污染和偏见。
3. 不污染主上下文。

5. 典型用法

# 让 Claude 自动拆分任务并行处理
> 审查用户认证模块，use subagents
# 跨文件批量修改
> 重命名所有文件中的 User 为 Account，use subagents

六、Skills（技能）管理

1. 技能应该是文件夹结构

skills/
  api-design/
    SKILL.md          # 主文件：核心规则和索引
    references/       # 语料库、参考资料
    scripts/          # 辅助脚本
    examples/         # 示例代码

1. 主文件只包含核心规则和索引。
2. 语料库、检查表放在 references/。
3. 渐进式披露：Claude 只在需要时读取子目录内容。

2. 嵌套 Skills 自动按路径加载

1. 把技能放在 .claude/skills/ 的子目录中，在该目录下工作时会自动加载。
2. 名称冲突时显示为 <目录名>:<技能名>，两者都可访问。
3. 最佳实践：按模块/领域组织技能目录，不用把所有技能塞在一个平铺目录里。

3. 堆叠调用多个技能

1. 一行调用多个技能：/skill-a /skill-b do XYZ（最多 5 个）。
2. 适合组合多种专业技能的复杂任务，不用分多次对话。

4. 添加 Gotchas（坑点记录）部分

这是长期最有价值的技术：每次 Claude 犯错时记录失败模式，长期积累成为信噪比最高的内容。

Gotchas 结构示例

# SKILL.md
## Gotchas（坑点记录）
### 2026-04-15: API 分页参数遗漏
- **问题**：生成 API 时忘记添加分页参数
- **表现**：返回所有数据导致性能问题
- **修复**：在 SKILL.md 中添加分页规则
- **预防**：检查清单中增加"是否包含分页"

Gotchas 维护原则

1. 每次犯错必记录：不要等，立即记录。
2. 包含四个要素：问题描述、表现形式、修复方法、预防措施。
3. 定期回顾：每周回顾一次，识别重复出现的模式。
4. 转化为规则：如果某个坑点出现 3 次以上，转化为正式规则。
5. 归档已解决的：超过 30 天未出现的问题，移到归档区。

七、Superpowers 使用详解

1. 什么是 Superpowers？

Superpowers 是由 Jesse Vincent 和 Prime Radiant 团队开发的 Claude Code 插件，解决工程纪律问题。

核心功能：

1. 强制结构化工作流：头脑风暴 → 分支隔离 → 详细计划 → 执行。
2. TDD（测试驱动开发）。
3. 代码审查。
4. 系统调试。
5. 验证完成。

2. 安装与配置

# 在 Claude Code 会话中安装
/plugin install superpowers@claude-plugins-official
# 下次启动时看到"You have Superpowers"即表示成功

3. 技能激活方式

技能	何时激活	触发方式
brainstorming	创建功能或组件前	单独使用时自动
writing-plans	需求需要多步分解时	单独使用时自动
test-driven-development	实现功能或修复 bug 前	需在 CLAUDE.md 中显式配置
systematic-debugging	遇到 bug、测试失败、意外行为时	需在 CLAUDE.md 中显式配置
code-reviewer	完成主要实现步骤后	需在 CLAUDE.md 中显式配置
dispatching-parallel-agents	多个独立任务可并行时	当 2+ 任务无依赖时自动
verification-before-completion	声称工作完成前	需在 CLAUDE.md 中显式配置

## Superpowers 工作流规则
### 新功能开发
- 使用 /opsx:propose 开始（路由到 OpenSpec）
- 跳过 brainstorming/writing-plans（避免重复）
### 编码纪律
- 使用 /opsx:apply 时，始终遵循 TDD：先写失败的测试，再实现代码
- 遇到 bug 时，使用 systematic-debugging 技能
- 完成主要实现后，自动触发 code-reviewer
### 验证规则
- 声称工作完成前，必须通过 verification-before-completion
- 所有测试必须通过，无跳过测试

5. 四步强制序列

1. 头脑风暴：解决重大架构决策（比写代码便宜）。
2. 分支隔离：每个功能在独立分支上开发。
3. 详细计划：编写可审查的计划文档。
4. 执行：按计划实施，每步都有检查点。

6. 管理已安装的插件

1. /plugin list 查看所有插件，用 --enabled/--disabled 过滤。
2. 长时间未用的插件会被提示清理，节省上下文。
3. 插件钩子的标识符匹配规则：含连字符的钩子名（如 code-reviewer）现在精确匹配，不会误触。

八、Spec Kit（OpenSpec）使用详解

1. 什么是 OpenSpec？

OpenSpec 是 Fission AI 开发的开源框架，解决需求不匹配问题。将一句话需求扩展为四个结构化文档。

核心功能：

1. proposal.md：为什么、范围、不在范围内什么（防止 AI 添加未请求的功能）。
2. specs/：使用 GIVEN/WHEN/THEN 场景的行为规范。
3. design.md：技术决策及推理。
4. tasks.md：实现清单，每个任务 2-5 分钟可完成。

2. 安装与配置

# 需要 Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init  # 选择 Claude Code
# 创建 openspec/ 目录，包含 specs/、changes/archive/、AGENTS.md

3. 与 Claude Code 集成

// .claude/settings.json
{
  "mcpServers": {
    "openspec": {
      "command": "npx",
      "args": ["-y", "@fission-ai/openspec-mcp"]
    }
  },
  "permissions": {
    "allow": ["Bash:openspec:*", "Bash:npm:*", "Bash:git:*"]
  }
}

4. 工作流程

# 会话 1：需求 → 规范
> /opsx:propose 用户认证 API，Express + MongoDB + JWT
# 生成：
# - openspec/changes/YYYY-MM-DD--proposal.md
# - openspec/changes/YYYY-MM-DD--specs/
# - openspec/changes/YYYY-MM-DD--design.md
# - openspec/changes/YYYY-MM-DD--tasks.md
# 会话 2：规范 → 实现
> /opsx:apply
# 会话 3：独立验证
> /opsx:archive  # 归档当前迭代

5. Delta/Archive 机制

1. Delta：每次迭代保留决策历史。
2. Archive：归档已完成的迭代，保留审计追踪。
3. 解决设计决策在迭代中丢失的问题。

6. 五大常见陷阱

陷阱	表现	预防
规范写成伪代码	描述实现而非行为	使用 GIVEN/WHEN/THEN
过度详细规范	限制 AI 创造性	描述"什么"，不描述"怎么做"
每次功能后不归档	历史混乱	每个功能完成后执行 archive
与 Superpowers 冲突	两个规划系统重复	在 CLAUDE.md 中路由到一个
忽略 out-of-scope	AI 添加未请求功能	明确定义范围边界

九、权限与安全

1. Hooks vs CLAUDE.md

需求	推荐	原因
文件保存后自动 lint	Hook	每次必须执行
阻止写入敏感文件	Hook	安全不能妥协
代码规范遵循	CLAUDE.md	需要情境判断
API 命名规则	CLAUDE.md	存在例外模式

2. Allowlist 减少审批疲劳

{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)",
      "Bash(git status)",
      "Read",
      "Glob",
      "Grep"
    ]
  }
}

3. deny 比 Hooks 更安全

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl:*)"
    ]
  }
}

1. 权限评估顺序：deny → ask → allow。
2. 设为 deny 后文件对 Claude"不可见"。

4. 权限规则进阶用法

1. 参数化匹配：Agent(model:opus) 可精确禁止 Opus 子智能体。
2. Glob 模式："*" 在 deny 规则中匹配所有工具。
3. 安全强化：破坏性 git 命令（git reset --hard、git checkout -- . 等）自动模式已默认阻止，除非你明确要求。
4. rm -rf 在自动模式下也需要确认。

5. --dangerously-skip-permissions 正确使用

适用场景	不适用场景
Lint 修复自动化	联网环境
样板代码生成	包含敏感数据的环境
封闭工作流	通用开发工作

重要：应在无互联网的隔离环境中使用。企业可设置 disableBypassPermissionsMode: true 全局禁用。

十、规格与实现分离

推荐流程

1. Session 1：通过采访创建规格。
2. Session 2：基于规格实现。
3. Session 3：独立验证。

为什么分离？

1. 采访和规格讨论污染上下文。
2. 新会话有干净的上下文窗口。
3. 规格文档作为实现依据。
4. 验证会话独立于实现偏见。

十一、Claude Code 常见陷阱（Gotchas）

8 大陷阱

#	陷阱	表现	缓解方法
1	过早放弃	"已实现大部分功能，但 XX 不工作"	拆分任务为更小单元
2	上下文压缩后变笨	忘记之前纠正的错误	手动 /compact，必要时 /clear
3	初始测试质量差	测试看起来对但实际失败	TDD 模式，仔细审查测试
4	修改测试而非代码	降低测试标准匹配错误代码	严格审查测试变更
5	忘记编译	测试失败因为未编译	在 CLAUDE.md 中明确编译步骤
6	工作目录混乱	留下测试脚本、构建产物	git status 检查，手动清理
7	Git 操作危险	错误的变更合并到 PR	人工执行 Git 操作
8	重写但不删除旧代码	新旧代码共存	审查 diff，确认删除

陷阱 1：过早放弃

表现：

我已实现大部分功能。功能在 XX 情况下工作正常。
但 YY 情况下不工作。代码已充分测试，这是好的开始。

缓解：

1. 拆分任务为更小、更隔离的单元。
2. 即使人类认为可以分组，Claude Code 也需要分离。
3. 示例：两个相似表 → 分两个 PR，每个 10 分钟完成。

陷阱 2：上下文压缩后变笨

表现：

1. 不知道之前看的文件。
2. 重复之前纠正的错误。
3. 性能明显下降。

缓解：

1. 50% 时手动 /compact。
2. 指定压缩策略（保留什么）。
3. 必要时 /clear + git reset --hard。
4. 如果已经 /clear 了又想找回之前的对话，用 /rewind。

陷阱 3 & 4：测试问题

表现：

1. 生成看起来对但失败的测试。
2. 修改测试匹配错误代码。
3. 降低测试标准。

缓解：

1. TDD 模式：先写测试。
2. 仔细审查生成的测试。
3. 严格审查测试变更（比代码变更更严格）。

陷阱 5：忘记编译

表现：

1. 测试循环失败因为未编译。
2. 依赖变更后忘记重新编译。

缓解：

1. CLAUDE.md 中明确编译步骤。
2. 测试前强制编译。
3. 注意：编译语言 vs 解释语言混合时特别容易出错。

陷阱 6 & 7：工作目录和 Git

表现：

1. 留下测试脚本、数据库文件。
2. Git 操作错误导致 PR 混乱。

缓解：

1. 每次完成后 git status 检查。
2. 人工执行 Git 操作（分支、提交、推送）。
3. Claude Code 只修改文件，不操作 Git。

陷阱 8：重写但不删除

表现：

1. 创建新文件但不删除旧文件。
2. 新旧代码共存导致混淆。

缓解：

1. 审查 diff 确认删除。
2. 明确指示"删除旧实现"。
3. 检查文件列表确认清理。

新陷阱：后台会话意外中断

表现：

1. 后台会话在 daemon 重启后消失。
2. 状态显示异常（一直"Working"或空白）。

缓解：

1. 更新到最新版本，后台会话已支持自动恢复。
2. 如果后台卡住，在 claude agents 中检查状态。
3. 通过 claude agents 的过滤功能按状态定位问题会话。

十二、工具组合策略

Claude Code + OpenSpec + Superpowers 三重栈

解决三个核心问题：

问题	工具	解决方式
AI 构建的不是你想要的	OpenSpec	需求 → 结构化规范
AI 跳过工程纪律	Superpowers	强制 TDD、审查、验证
设计决策在迭代中丢失	OpenSpec	Delta/Archive 机制

分工明确

OpenSpec 负责：思考 WHAT（构建什么、为什么）
Superpowers 负责：确保 HOW（如何构建好）
Claude Code 负责：执行（编辑文件、运行测试、处理 Git）

配置协作

# CLAUDE.md 中的路由规则
## 规划阶段
- 任何新功能：从 /opsx:propose 开始
- 跳过 brainstorming/writing-plans（避免重复）
## 编码阶段
- 使用 /opsx:apply 时：始终遵循 TDD
- 遇到 bug：使用 systematic-debugging
- 完成实现：触发 code-reviewer
- 声称完成：通过 verification-before-completion

十三、核心原则总结

上下文是宝贵资源

1. 保持简洁、及时压缩、污染就重置。
2. 50% 时手动 /compact。
3. 两次失败 = /clear。
4. /cd 切目录不破坏缓存。
5. /rewind 可找回 /clear 之前的对话。

系统约束 > 提示词约束

1. 用 Hooks 和权限配置代替"希望 Claude 记住"。
2. deny 比 Hooks 更安全。
3. 关键规则用标签包裹。
4. 定期运行 /doctor 清理冗余。

分而治之

1. 子智能体、分阶段工作流、规格与实现分离。
2. 专用子智能体 > 通用 mega-agent。
3. Skills 按目录组织、可嵌套加载和堆叠调用。

不要过度工程

1. 3-5 分钟能完成的事，直接用原生 Claude Code。
2. 复杂工作流适用于多文件、多步骤的大任务。
3. 重命名变量这种小事，一句话就行。

持续改进

1. 每次犯错必记录 Gotchas。
2. 定期回顾，识别重复模式。
3. 将高频问题转化为正式规则。
4. 用 /doctor 定期清理不用的插件和配置。

参考资料

1. Claude Code 官方文档：https://code.claude.com/docs/en
2. Claude Code 发布日志：https://github.com/anthropics/claude-code/releases
3. Superpowers 插件：https://github.com/obra/superpowers
4. OpenSpec 框架：https://openspec.dev/
5. 10 个必备最佳实践：https://discuss.huggingface.co/t/10-essential-claude-code-best-practices-you-need-to-know/174731
6. Claude Code Gotchas：https://www.dolthub.com/blog/2025-06-30-claude-code-gotchas/
7. Superpowers 插件详解：https://www.builder.io/blog/claude-code-superpowers-plugin
8. OpenSpec + Superpowers 三重栈：https://www.heyuan110.com/posts/ai/2026-04-09-claude-code-openspec-superpowers/

以上从配置原则到工具组合的完整实践路径，涵盖了 CLAUDE.md 优化、工作流管理、上下文控制及常见陷阱规避。通过持续记录 Gotchas 并遵循系统约束而非仅靠提示词约束，用户能够与 Claude Code 建立高效且可复用的协作模式。