# Claude Code 最佳实践与工作流

> Claude Code 官方最佳实践、常见 prompt recipes、探索-计划-实现、验证、上下文管理、子代理、worktree、headless 和 review 流程。

URL: https://docs.passion8.cc/docs/claude-code/best-practices-workflows
Language: zh-CN
Publisher: Passion8

这页把官方 Best practices、Common workflows 和 How Claude Code works 合并成可执行工作流。它不是命令清单,命令细节看 [命令大全](https://docs.passion8.cc/docs/claude-code/commands)。

如果你想先理解 Claude Code 的 agentic loop、工具、上下文加载和扩展能力分工,看 [工作原理与扩展地图](https://docs.passion8.cc/docs/claude-code/how-it-works)。如果你要直接复制 prompt 给团队用,看 [Prompt 模板与团队推广](https://docs.passion8.cc/docs/claude-code/prompt-library)。

## 工作方式总览

Claude Code 的核心循环是:读上下文,决定下一步,调用工具,观察结果,继续迭代。你的提示越能给它验证路径和边界,结果越稳定。

| 阶段 | 你给什么 | Claude 做什么 |
| --- | --- | --- |
| 探索 | 目标、相关目录、不要改文件 | 读代码、画依赖、找风险 |
| 计划 | 约束、验收标准、测试命令 | 产出步骤和取舍 |
| 实现 | 明确允许改哪些文件 | 小步修改 |
| 验证 | lint、typecheck、test、build、截图 | 运行证据并修回归 |
| Review | 让它按 code review 姿态找问题 | 排 bug、风险、测试缺口 |

## 给 Claude 可验证路径

不要只说“修好”。给它能判断成败的命令:

```text
修复登录页移动端布局。
完成后运行:
- npm run lint
- npm run typecheck
- npm run build
- 用 390px 和 1440px 视口检查按钮不重叠
```

如果没有测试,让 Claude 先找最接近的验证方式:

```text
这个仓库没有明确测试。先找 package scripts、CI 配置和 README 里的验证命令,再决定最小验证集合。
```

## 探索先于实现

适合复杂任务的提示:

```text
先只读探索这个模块。找出数据流、关键文件、现有测试和风险。
不要修改文件。最后给我一个不超过 6 步的实现计划。
```

如果你已经授权它继续:

```text
按你刚才的计划执行。每完成一块就运行相关验证,不要改无关文件。
```

## 提供具体上下文

好提示通常包含:

- 目标用户和场景。
- 允许改的目录。
- 不允许碰的文件或行为。
- 现有错误日志或截图。
- 验收标准。
- 回滚或兼容要求。

示例:

```text
把 docs 站的搜索弹层改到手机可用。
范围: src/components/DocsClientControls.tsx 和 src/app/globals.css。
要求: 320px 宽不溢出,Esc 能关闭,Tab 不跑出弹层,浅暗色都可读。
完成后运行 lint/typecheck/build。
```

## 写好 CLAUDE.md

`CLAUDE.md` 适合写新同事需要知道的稳定知识。

```markdown title="CLAUDE.md"
# 项目约定

- 使用 npm,不要引入 pnpm lockfile。
- 文档内容在 content/docs。
- 修改 UI 后运行 npm run lint、npm run typecheck、nice -n 10 npm run build。
- 本地 3017 是静态预览服务,不要重启,构建会刷新 out。
- 不要把 API Key 写入 .claude/settings.json。
```

不适合放进 `CLAUDE.md` 的内容:

- 一次性任务说明。
- 过期 bug 记录。
- 需要强制执行的安全规则。安全边界用 permissions 或 Hooks。
- 大段复制的日志。

## 权限、Hooks 和环境

| 需求 | 推荐 |
| --- | --- |
| 常用测试免确认 | permissions allow 精确命令 |
| 永远禁止读密钥 | permissions deny + Hook 双保险 |
| 改文件后自动 lint | PostToolUse hook |
| 控制网络访问 | Bash deny、Hook 或沙箱 |
| 团队共享规则 | `.claude/settings.json` |
| 个人 Key | 用户环境变量或 `~/.claude/settings.json` |

权限详情看 [权限与模式](https://docs.passion8.cc/docs/claude-code/permissions),Hook 看 [Hooks 自动化](https://docs.passion8.cc/docs/claude-code/hooks),沙箱看 [沙箱与隔离环境](https://docs.passion8.cc/docs/claude-code/sandboxing)。

## 子代理和并行

子代理适合“可独立完成的探索或审查”,不要把当前关键路径完全交出去。

好用法:

```text
让一个 subagent 只读审计移动端样式问题。
主线程继续修文档内容。
子代理最终只输出文件/行号和建议,不要改文件。
```

可写子代理要给清楚所有权:

```text
Worker A 只改 content/docs/claude-code/*.mdx。
Worker B 只改 src/app/globals.css。
不要互相回滚对方改动。
```

并行工作区用 [Worktrees 并行工作区](https://docs.passion8.cc/docs/claude-code/worktrees) 隔离。

## 管理上下文

| 现象 | 做法 |
| --- | --- |
| `/context` 显示很满 | `/compact` 或开新会话 |
| 反复贴大日志 | 先过滤错误关键词 |
| 代码库太大 | 让 Claude 先 `rg` 定位,再读文件 |
| 多轮偏离目标 | 用短提示重申验收标准 |
| 需要回到旧状态 | 用 `/rewind` 或 Git |

缓存相关:

- 保持模型和 effort 不变,更容易命中 5m/1h 前缀缓存。
- 大幅改 `CLAUDE.md`、MCP、skills 或 output style 会改变前缀。
- `/compact` 能降上下文,但摘要替换后缓存形状也变。

详细规则见 [Prompt 缓存](https://docs.passion8.cc/docs/claude-code/prompt-caching) 和 [命令与缓存影响](https://docs.passion8.cc/docs/claude-code/command-cache)。

## 常见工作流

### 了解新代码库

```text
只读探索这个仓库。输出:
1. 技术栈
2. 入口文件
3. 主要数据流
4. 测试和构建命令
5. 高风险区域
不要修改文件。
```

### 修 bug

```text
复现并修复这个 bug。
先找相关测试或最小复现,再改代码。
完成后运行最小相关测试和全局 lint/typecheck。
```

### 重构

```text
重构这个模块但保持行为不变。
先列出当前外部接口和测试覆盖,再小步改。
每一步都说明行为为什么没变。
```

### 写文档

```text
根据当前实现更新文档。
不要猜 API 行为,从源码、测试和官方文档核对。
保留链接到权威来源。
```

### 创建 PR

```text
总结当前 diff,生成 PR 描述:
- 背景
- 主要改动
- 验证命令
- 风险和回滚
```

### Headless 脚本

```bash
claude -p "Review this diff for bugs. Return JSON with severity, file, line, finding." \
  --output-format json
```

脚本里要限制输入规模,避免把整个仓库和长日志塞进去。

## 反模式

| 反模式 | 后果 | 改法 |
| --- | --- | --- |
| “把项目优化一下” | 范围失控 | 写清目标、指标和允许范围 |
| 不给验证命令 | 容易只做表面改动 | 给 lint/test/build 或让 Claude 找 |
| 让多个 agent 改同一文件 | 冲突和覆盖 | 拆所有权或用 worktree |
| 把秘密放进 prompt | 进入上下文和日志 | 用 env、secret manager、deny rules |
| 长时间不清上下文 | 成本高、注意力下降 | `/context`、`/compact`、新会话 |
| 只靠 CLAUDE.md 做安全 | 无强制力 | permissions、Hooks、sandbox |

## 官方参考

- [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices.md)
- [Common workflows](https://code.claude.com/docs/en/common-workflows.md)
- [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md)
- [Memory](https://code.claude.com/docs/en/memory.md)
- [Worktrees](https://code.claude.com/docs/en/worktrees.md)