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

一、CLAUDE.md 配置原则

核心原则：保持简短

• 控制在 60 行以内
• ，硬上限 300 行
• LLM 能可靠遵循约 150-200 条指令，Claude Code 系统提示已占用约 50 条
• 只放 Claude 可能忽略的信息
• ：构建命令、测试命令、分支命名规范、项目特定架构决策
• 能从代码推断的内容不要写进去
• 规则太多？拆分到 .claude/rules/ 目录下按需加载
• 关键规则用标签包裹
• 防止被忽略
• 运行 /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

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

2. 让 Claude 先采访你

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

3. 分阶段工作流

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

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

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

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

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

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

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

7. 重复性监控用 /loop

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

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

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

三、调试与纠错

1. 粘贴 bug，说"fix"

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

2. 两次失败 = /clear

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

3. 走偏了？Esc Esc 回滚

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

4. 要求重写平庸方案

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

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

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

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

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

四、上下文管理

1. 50% 时手动压缩

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

2. /compact 可指定压缩策略

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

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

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

4. Checkpoints（检查点）

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

五、Subagents（子智能体）

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

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

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

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

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

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

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

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

5. 典型用法

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

六、Skills（技能）管理

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

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

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

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

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

3. 堆叠调用多个技能

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

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

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

Gotchas 结构示例

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

Gotchas 维护原则

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

七、Superpowers 使用详解

1. 什么是 Superpowers？

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

核心功能：

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

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. 四步强制序列

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

6. 管理已安装的插件

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

八、Spec Kit（OpenSpec）使用详解

1. 什么是 OpenSpec？

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

核心功能：

• proposal.md：为什么、范围、不在范围内什么（防止 AI 添加未请求的功能）
• specs/：使用 GIVEN/WHEN/THEN 场景的行为规范
• design.md：技术决策及推理
• 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 机制

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

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:*)"
    ]
  }
}

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

4. 权限规则进阶用法

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

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

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

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

十、规格与实现分离

推荐流程

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

为什么分离？

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

十一、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 情况下不工作。代码已充分测试，这是好的开始。

缓解：

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

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

表现：

• 不知道之前看的文件
• 重复之前纠正的错误
• 性能明显下降

缓解：

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

陷阱 3 & 4：测试问题

表现：

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

缓解：

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

陷阱 5：忘记编译

表现：

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

缓解：

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

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

表现：

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

缓解：

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

陷阱 8：重写但不删除

表现：

• 创建新文件但不删除旧文件
• 新旧代码共存导致混淆

缓解：

• 审查 diff 确认删除
• 明确指示"删除旧实现"
• 检查文件列表确认清理

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

表现：

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

缓解：

• 更新到最新版本，后台会话已支持自动恢复
• 如果后台卡住，在 claude agents 中检查状态
• 通过 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

十三、核心原则总结

上下文是宝贵资源

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

系统约束 > 提示词约束

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

分而治之

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

不要过度工程

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

持续改进

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

参考资料

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