Claude 高级使用完整手册
> 适用于 2026 年，面向工程师与团队。从"搜索框"思维升级到"初级团队成员"工作流。
> 本手册整合：模型选择、简报方法、Effort 控制、Claude Code、上下文管理、MCP、代码审查、团队规范、可实践清单。
> 配套速查文件：`任务简报模板速查.md`、`MCP接入清单速查.md`。
目录
- 核心理念(#1-核心理念)
- 模型选择(#2-模型选择)
- 任务简报方法(#3-任务简报方法)
- Effort 控制(#4-effort-控制)
- Claude Code 核心功能(#5-claude-code-核心功能)
- 上下文管理(#6-上下文管理)
- MCP 接入(#7-mcp-接入)
- 代码审查(#8-代码审查)
- 端到端工作流(#9-端到端工作流)
- 五大区分性习惯(#10-五大区分性习惯)
- 团队规范(#11-团队规范)
- 可实践清单(#12-可实践清单)
- DevOps/SRE 场景补充(#13-devopssre-场景补充)
1. 核心理念
大多数人把 Claude 当搜索框：问一句 → 复制 → 粘贴 → 祈祷能编译。
资深工程师把它当作**拥有 root 权限的初级团队成员**：强大、快速，但必须设定规则和边界。
两种工作流之间的产出差距是数量级的。关键转变：**你不是在写代码，是在指导和审查代码。**
2. 模型选择
技术之前，先选对模型。用错套餐是浪费时间和金钱的最常见方式。
| 模型 | 定位 | 适用场景 |
|------|------|---------|
| **Sonnet 5** | 日常主力，100 万 token 上下文，Sonnet 定价 | 大多数编码、重构、日常问题 |
| **Opus 5** | 高难度智能编码，默认高推理强度，有 `xhigh` 层 | 真正困难或长期性任务 |
| **Haiku 4.5** | 快速、廉价 | 高频、延迟敏感（分类、简单转换） |
| **Fable 5** | 比 Opus 高一档，难度最高、视野最广，价格约 Opus 两倍 | 大多数队伍不需要 |
**实用原则**：Sonnet 5 干绝大多数活；Opus 5 给难题；Haiku 给高频廉价调用。
**计费提醒**：Sonnet 5 / Opus 4.7+ 使用新分词器，相同文本可能比旧模型多 1.0~1.35 倍 token。不要假设 token 数和上个季度一样。
3. 任务简报方法
3.1 停止"提示"，开始"简报"
不要给初级工程师一句指令就走开------要提供**背景、约束、完成定义**。
**弱简报（反面）**：
> 为该 API 客户端添加缓存功能。
**强简报（正面）**：
> 你在一个现有 Swift 包中工作。**不要重组模块。**
>
> **任务**：为 API 客户端添加轻量级内存响应缓存。
>
> **约束**：仅缓存 GET 请求；TTL 可配置默认 60 秒；线程安全；无新第三方依赖；保留公共 API 向后兼容。
>
> **完成定义**：现有测试通过；新增缓存命中/未命中/过期测试。
>
> **写代码前，先列出计划和你会接触的文件。**
3.2 通用 BRIEF 骨架
所有任务遵循同一套骨架，各场景填充重点不同：
```
【背景】你现在工作在 <项目/模块>，技术栈 <语言+框架>。现状：<...>。
【范围】做什么：<列出>。不做什么：<排除>。
【约束】架构/依赖/性能/风格。
【输入】相关文件、参考链接、数据/schema。
【验收】测试通过、新增测试、无错误、diff 可审可回滚。
【先出计划】列步骤 + 接触文件 + 风险，等我确认再动手。
```
> 完整模板与各场景（新需求/迭代/bug/重构/审查）详见配套文件 `任务简报模板速查.md`。
4. Effort 控制
新一代用**自适应推理**取代固定思考预算。你通过 effort 级别引导它。
| 难度 | effort | 示例 |
|------|--------|------|
| 日常编码/重构 | `standard`/`high` | 加函数、改接口 |
| 棘手问题 | `xhigh` | 难 bug、架构决策、并发问题 |
| 真正棘手、一次性 | `max` | 愿意为额外计算付费的硬题 |
Claude Code 中：`/effort xhigh` 然后布置任务。
**常见错误**：为了"安全"把所有事都开到 `max`。更慢、更贵、无收益。按难度匹配。
5. Claude Code 核心功能
只在聊天窗口用 Claude，你只用了它 ~20% 的能力。
5.1 Plan Mode（计划模式）⭐ 最高价值
只读状态：可读/分析文件，但**批准前不能编辑、写入、跑命令**。
- 进入：`Shift+Tab`（按两次）或 `/plan`
- 工作流：进入 → 描述需求 → 读计划 → **修正假设** → 才放行
- 这一个习惯避免大多数"Claude 失控重写半个项目"的灾难。
5.2 检查点（Checkpoints / Rewind）
每次改动前自动快照，`Esc` 两次或 `/rewind` 回滚。可只撤销代码、只撤销对话、或两者。让你敢于批准大胆重构。
5.3 权限模式
默认每次写文件/跑命令都询问。**强烈建议权限要紧**。已有公开案例：代码代理被给过多权限后删除数据。
5.4 子代理（Subagents）
可并行生成后台子代理，主会话继续工作。大型任务可用动态工作流按脚本编排多子代理。第一天不需要，但知道它存在会改变你对大型重构范围的认知。
6. 上下文管理
更多 ≠ 更好。给对**那一片**才重要。
- **Projects（项目）**= 长期记忆。保存代码库/规格/风格指南；接近上下文上限时自动切检索模式，只取需要的段落。
- **Artifacts（成果）**= 工作台。侧边栏实时渲染代码/图表/文档，可就地高亮编辑。
心智模型：**Projects 是记忆，Artifacts 是工作台**。
7. MCP 接入
MCP（模型上下文协议）是开放标准，把 Claude 接到 GitHub、数据库、浏览器、内部服务。
**安全红线**：
- 只暴露最有用的工具
- 尽量只读
- 破坏性操作必须人工批准
- 不会在员工入职第一天给的凭证，别当毫无防备的 MCP 工具暴露
> 完整接入步骤、决策表、治理清单详见配套文件 `MCP接入清单速查.md`。
8. 代码审查
Claude 又快又常表现好------但会**自信地犯错**，输出看起来对、实际错到足以造成问题。
每次有意义改动，当**才华横溢的初级工程师的 PR** 对待：
- **读 diff，不只读摘要**------摘要是它对工作的描述，diff 才是实际发生的
- **自己跑测试**------别信"测试通过"
- **新会话里让它自审**------和写代码的会话分开，降低自我验证偏差
- **钱、认证、持久化处格外小心**------涉及财务/凭证的操作，人工审核不容商榷
`/code-review` 获取第二意见------视为**第二意见**，不是盖章凭证。
9. 端到端工作流
- 在仓库里打开 Claude Code，默认 Sonnet 5
- **进入 Plan Mode**，描述功能（含范围/约束/完成定义）
- **读计划，修正假设**，确认后再放行
- 权限模式开启，你批准每次文件写入
- 遇真正棘手问题，把 effort 提到 Opus 5 `xhigh`
- 跑测试，看 diff
- 开新会话做 code review 拿第二意见
- 出问题 → `/rewind` 回检查点，调整简报
- 提交，署你的名------因为你审过了
10. 五大区分性习惯
- **简报而非提示**------范围、约束、完成定义
- **先规划后编码**------永远先看计划
- **按难度调 effort**------别所有事都 max
- **权限从严**------尤其破坏性/敏感操作
- **读 diff**------你是最后一道防线，不是模型
11. 团队规范
分四层落地：
第 1 层：项目级约定（CLAUDE.md / AGENTS.md）
仓库根放项目说明（技术栈、禁区、必守项、提交规范）。Claude Code 自动读取。
第 2 层：简报规范
统一 BRIEF 模板，PR 描述附简报，reviewer 据此审查。
第 3 层：审查流程
```
AI 产出 → CI 门禁（测试/lint/类型）→ 作者读 diff → 独立会话第二意见 → 红线人工签 → 合并署名
```
**红线清单（必须人工签）**：金钱、认证、数据持久化、删除类操作、生产配置/密钥/基础设施。
第 4 层：权限与模型策略
- 权限默认询问模式，破坏性操作永不自动
- Sonnet 日常 / Opus 难题 / Haiku 高频
- `max` effort 需说明理由
- 大重构前确认 `/rewind` 可用
12. 可实践清单
个人即刻
- 每次任务用 BRIEF 模板，禁一句指令
- 强制"先出计划再动手"
- 读 diff 不读摘要，自己跑测试
- 权限默认询问，破坏性操作永不自动
- 按难度配 effort，不全 max
个人本周
- 模型分流：Sonnet 日常 / Opus 难题 / Haiku 高频
- 开启检查点意识，大重构前确认 `/rewind`
- 核心代码库建为 Project
- Bug 任务强制"先复现再修"
团队本月
- 仓库根建 `CLAUDE.md`（禁区/必守项）
- 沉淀统一简报模板 + PR 模板字段
- 公布红线清单 + 模型/effort 策略
- code review 双签流程落地
- 接入 GitHub MCP（只读优先）+ 数据库 MCP（强制只读）
- MCP 清单与评审流程建立
持续
- 月度复盘 AI 引入的 bug，定位失效环节
- 季度 MCP 审计 + 凭证轮换
- token 账单监控（留意新分词器放大效应）
13. DevOps/SRE 场景补充
> 完整 DevOps/SRE 场景分析见本文档末尾的"场景缺口分析"。
> 核心未覆盖领域：事件响应/复盘、IaC 审查、CI/CD、K8s、可观测性、迁移与发布、安全加固、容量与成本、灾备、自动化脚本、密钥管理。
资深 DevOps/SRE 使用 Claude 的核心差异：**生产环境无小事，每一次改动都可能影响真实用户和金钱**。因此简报要更严、审查要更深、人工门要更多。
> **一句话总结**：从 Claude 身上获得 10× 产出的人，没有秘密提示------他们实行**严格工作流**：积极授权、不懈核验、关键环节保持人工在场。
# 任务简报模板速查
> 独立速查文件。所有 Claude 任务统一使用 BRIEF 骨架，各场景填充重点不同。
> 核心纪律：**先出计划再动手**——这一句不可省，把"失控重写"挡在执行之前。
---
## 通用 BRIEF 骨架
```
【背景】
你现在工作在 <项目/仓库/模块>，技术栈 <语言+框架>。
当前状态：<相关现状，已有代码/已知行为/已做过的尝试>。
【范围】Scope
本次任务：<一句话目标>。
做什么：<明确列出>。
不做什么：<明确排除，防止越界>。
【约束】Constraints
- 架构：不重组模块 / 不改公共 API / 保持向后兼容
- 依赖：不引入新第三方库
- 性能/线程：<如线程安全、假定并发>
- 风格：<遵循项目既有约定>
【输入】Inputs / 上下文
- 相关文件：<路径列表>
- 参考：<issue/PR/设计文档/规格链接>
- 数据：<示例输入或 schema>
【验收】Definition of Done
- 现有测试通过
- 新增测试：<列明要覆盖的场景>
- 无 lint/类型错误
- diff 可审、可回滚
【先出计划】
写代码前，先列出：
1. 你的实现步骤（编号）
2. 你会改/新建哪些文件
3. 你识别到的风险或替代方案
等我确认计划后再动手。
```
### 字段说明
| 字段 | 必填 | 作用 |
|------|------|------|
| 背景 | ✅ | 让模型知道"在哪、现状如何" |
| 范围（做什么/不做什么） | ✅ | 划边界，最重要 |
| 约束 | ✅ | 防越界、防引入依赖 |
| 输入 | 视情况 | 给文件路径和参考，省得它猜 |
| 验收 | ✅ | 可验证的完成标准 |
| 先出计划 | ✅ | 强制 Plan Mode 心智 |
---
## 场景 1：新需求开发
**effort**：`high`，复杂域用 `xhigh`
**重点**：先理解域、再设计、再编码
```
【背景】
项目：<仓库>，技术栈 <TS + Next.js + Prisma>。
需求来源：<PRD/issue #123>，业务目标：<一句话>。
【范围】
做：实现 <用户可上传头像并裁剪> 的完整功能。
不做：不做权限改造、不做历史数据迁移、不动现有认证流程。
【约束】
- 复用现有 Storage 模块，不引新依赖
- 图片 < 5MB，格式 jpg/png/webp
- 前端裁剪用纯 CSS/canvas，不引 cropper 库
- 接口遵循现有 RESTful 约定
【输入】
- 相关文件：src/api/upload.ts、src/components/Avatar.tsx
- 参考：PRD 链接 / 设计稿链接
- DB schema：User.avatarUrl 字段已存在
【验收】
- 上传成功、裁剪成功、保存到 DB
- 新增单测：上传、裁剪、格式校验、超限拒绝
- E2E 通过、无类型错误
【先出计划】
列出实现步骤 + 接触文件 + 你认为的 2 个设计风险点。
```
---
## 场景 2：功能迭代（已有功能改造）
**effort**：`high`
**重点**：向后兼容、回归测试
```
【背景】
现有功能：<搜索接口 GET /search>，当前行为：<关键词模糊匹配>。
本次迭代目标：<增加按时间范围过滤 + 结果高亮>。
【范围】
做：新增 from/to 时间参数、高亮命中关键词。
不做：不重写现有匹配逻辑、不改分页契约、不动前端路由。
【约束】
- 公共 API 向后兼容：新参数可选，旧调用行为不变
- 高亮仅在响应体新增 highlight 字段，不破坏现有字段
- 现有消费者不感知变化
【输入】
- 相关文件：src/api/search.ts、tests/search.test.ts
- 现有测试：<路径>，必须全部继续通过
【验收】
- 旧测试 100% 通过（回归基线）
- 新增测试：时间过滤命中/未命中、高亮正确、空参数退回旧行为
- 文档更新对应接口说明
【先出计划】
列出步骤 + 接触文件 + 明确哪些是"破坏性变更"需我确认。
```
---
## 场景 3：Bug 修复
**effort**：`high`，诡异 bug 用 `xhigh`/`max`
**重点**：先复现再修，禁止"看起来对就改"
```
【背景】
现象：<用户列表页偶发性 500，约 0.3% 请求>。
影响：<生产环境，影响真实用户>。
已知排查：<已排除 DB 超时，日志见 XXX>。
【范围】
做：定位根因 + 最小修复 + 防回归测试。
不做：不借机重构、不改无关代码、不做"顺手优化"。
【约束】
- 修复必须针对根因，不掩盖症状
- 不引入新依赖
- 改动尽量小、可单独 review、可独立回滚
【输入】
- 报错日志：<粘贴或路径>
- 相关文件：<路径>
- 复现步骤：<已知或"请先尝试复现">
- 环境信息：<prod/staging，版本号>
【验收】
- 复现：先写一个能稳定复现的测试（红）
- 修复：该测试转绿
- 回归：现有测试全过
- 根因说明：用 1-2 句说清"为什么之前会错"
【先出计划】
1. 先尝试复现（不要直接改）
2. 给出根因假设 + 验证方法
3. 再提出修复方案
等我确认根因后再修。
```
> 最致命失败模式：模型凭现象猜根因、直接改、改完看似好了但没复现验证。**强制"先复现再修"**。
---
## 场景 4：重构
**effort**：`high`/`xhigh`，大重构用子代理分片
**重点**：行为不变、可分步、可回滚
```
【背景】
重构对象：<PaymentService 类，1200 行>。
动机：<可维护性，非功能>，目标：<按职责拆分到 3 个类>。
【范围】
做：拆分结构、保持行为、迁移调用点。
不做：不改业务逻辑、不改外部契约、不优化性能。
【约束】
- 行为必须等价：现有测试是安全网，必须全程绿
- 分步提交：每步可独立 review 和回滚
- 公共 API 签名不变
【输入】
- 相关文件：<路径>
- 现有测试：<路径>（若不足，先补测试再重构）
【验收】
- 每一步后：现有测试全过
- 最终：调用点全部迁移、旧类可删
- 无行为变化（测试是证据）
【先出计划】
拆成 N 个可独立提交的步骤，每步说明改什么、为什么安全。
```
---
## 场景 5：代码审查（让 Claude 自审 / 互审）
**effort**：`high`
**重点**：和写代码的会话**分开**，降低自我验证偏差
```
【背景】
请审查以下改动，你**没有参与编写**，请以独立 reviewer 视角。
【范围】
审查目标：正确性 > 安全 > 可维护性 > 风格。
重点看：
- 逻辑错误 / 边界条件 / 空值
- 安全：注入、鉴权、敏感数据
- 并发：竞态、死锁
- 是否引入破坏性变更
【输入】
- diff：<粘贴或文件路径>
- 相关上下文：<被调用方/调用方>
【输出要求】
按严重程度分级：blocker / major / minor / nit。
每条给出：文件:行、问题、复现或触发条件、建议。
不要泛泛而谈，要具体可操作。
不确定的地方明确标注"需人工确认"，不要装确定。
```
---
## 场景速查表
| 场景 | effort | 核心纪律 | 最常见失败 |
|------|--------|---------|-----------|
| 新需求 | high / xhigh | 先设计后编码 | 越界改无关模块 |
| 功能迭代 | high | 向后兼容、回归基线 | 破坏现有消费者 |
| Bug 修复 | high / xhigh | **先复现再修** | 凭现象猜根因直接改 |
| 重构 | high / xhigh | 行为等价、分步可回滚 | 借机改逻辑 |
| 代码审查 | high | 独立会话、分级输出 | 自我验证偏差 |
---
## 反模式速查（不要这样写简报）
| ❌ 反面 | ✅ 正面 |
|---------|---------|
| "加个缓存" | 范围+约束+验收三件套 |
| "帮我优化下性能" | 指标基线 + 目标值 + 不改 API |
| "这有个 bug 修一下" | 现象 + 复现 + 先复现再修 |
| "重构这个模块" | 行为等价 + 分步 + 测试全程绿 |
| 不说"不做什么" | 明确排除边界 |
| 不要求先出计划 | 强制"列步骤+接触文件+风险" |
---
> 配套文件：`Claude高级使用完整手册.md`、`MCP接入清单速查.md`任务简报模板速查
# MCP 接入清单速查
> 独立速查文件。MCP（模型上下文协议）是 Claude 与外部系统（GitHub、数据库、浏览器、内部服务）连接的开放标准。
> 核心原则：**不会在员工入职第一天给的凭证，别当毫无防备的 MCP 工具暴露出来。**
---
## 一、选型------从最小集开始
不要一上来接一堆。先接**最高频、最安全**的两个。
| 优先级 | MCP 服务器 | 用途 | 风险 |
|--------|-----------|------|------|
| P0 | GitHub MCP | 读 issue、开 PR、查 CI | 中（写操作需限） |
| P0 | 数据库 MCP（**只读**） | 查真实 schema/数据 | 低（强制只读） |
| P1 | 文件系统 MCP | 受限目录读写 | 中 |
| P1 | 浏览器/Chrome MCP | 调试前端、读控制台 | 低 |
| P2 | Slack/Linear/Jira | 读任务上下文 | 中 |
| P2 | 内部 API/服务 MCP | 查内部系统状态 | 视接口而定 |
---
## 二、安全原则（接入前必读）
1. **最小暴露**：只公开真正有用的工具，不公开全家桶
2. **默认只读**：能只读就只读，写操作单独开
3. **破坏性操作人工门**：删除、推送、合并、改配置------必须人工批准
4. **凭证隔离**：用最小权限 token，不用个人主 token；能短期 token 就别用长期
5. **范围限制**：文件系统 MCP 限定到项目目录，别给整个家目录
6. **审计**：保留 MCP 调用日志，可回溯
---
## 三、接入步骤（以 GitHub MCP 为例）
```
1. 创建专用 GitHub token
- 仅勾选必要 scope（repo:read 优先，需要开 PR 再加 repo）
- 设过期时间，别用 no-expiry
- 用项目/组织专用 bot 账号，不用个人账号
2. 配置 MCP server（按你用的 Claude 客户端文档）
- claude_desktop_config.json 或 Claude Code 的 MCP 配置
- 注入 token via 环境变量，别硬编码
3. 限定工具暴露
- 只开：list_issues / read_pr / check_ci / open_pr
- 关闭：delete_branch / force_push / admin 操作
4. 写操作人工门
- open_pr：允许（可回滚）
- merge_pr / delete_branch：关闭或强制人工确认
5. 验证
- 让 Claude 读一个 issue，确认能拿到内容
- 试一个破坏性指令，确认被拦
```
---
## 四、数据库 MCP 接入（只读强制）
```
1. 创建只读数据库账号（SELECT 权限，无 INSERT/UPDATE/DELETE/DROP）
2. 配置 MCP server 指向该账号
3. 若数据库支持，开 statement timeout（防慢查询）
4. 生产库只读 + 行数限制（防扫全表）
5. 敏感字段（PII）考虑视图屏蔽
```
---
## 五、文件系统 MCP 接入
```
1. 限定根目录到项目路径，不给家目录或系统目录
2. 写操作默认关闭，需要时单独开并人工门
3. 排除 .env / 密钥 / 凭证文件（glob 黑名单）
4. 排除 node_modules / .git / build 产物（防误操作）
```
---
## 六、MCP 接入决策表
| 想接入 | 先问 | 默认 |
|--------|------|------|
| GitHub | 需要 PR 写权限吗？ | 只读优先，开 PR 单独授权 |
| 数据库 | 能只读吗？ | 强制只读账号 |
| 文件系统 | 范围能限到项目吗？ | 限到项目目录 |
| Slack | 只读频道够吗？ | 只读，禁发消息 |
| 浏览器 | 只调试本机？ | 限定本地页面 |
| 内部 API | 有只读端点吗？ | 只读端点优先 |
---
## 七、团队 MCP 治理清单
- [ ] 维护一份 **MCP 清单**：名称、用途、权限级别、负责人
- [ ] 每个新 MCP 接入需**评审**：暴露工具列表 + 风险 + 凭证来源
- [ ] 写操作 MCP **统一人工门**策略
- [ ] 凭证 **90 天轮换**，过期 token 自动失效
- [ ] 季度审计：哪些 MCP 实际被用、哪些可下线
- [ ] 调用日志留存，可回溯谁在何时调了什么
---
## 八、接入验收清单（每个新 MCP 上线前过一遍）
- [ ] 凭证是专用最小权限账号，非个人主账号
- [ ] token 设了过期时间
- [ ] token 通过环境变量注入，未硬编码
- [ ] 工具暴露做了最小化，只开必需
- [ ] 写/破坏性操作有人工门或已关闭
- [ ] 范围限定到必要目录/资源
- [ ] 敏感文件/PII 已屏蔽或排除
- [ ] 调用日志可审计
- [ ] 已在 MCP 清单登记，有负责人
- [ ] 团队评审通过
---
## 九、常见错误
| ❌ 错误 | 后果 | ✅ 正确 |
|--------|------|---------|
| 用个人主 GitHub token | token 泄漏=整个账号失守 | 专用 bot 账号 + 最小 scope |
| 数据库给读写权限 | 误删/误改生产数据 | 强制只读账号 |
| 文件系统给家目录 | 误删个人文件/密钥 | 限定项目目录 |
| 暴露全部工具 | 攻击面过大 | 只开必需工具 |
| 写操作无人工门 | 代理自动执行破坏性操作 | 人工确认才执行 |
| token 不过期 | 长期泄漏风险 | 设过期 + 定期轮换 |
| 无调用日志 | 出事无法回溯 | 留存审计日志 |
---
> 配套文件：`Claude高级使用完整手册.md`、`任务简报模板速查.md`MCP 接入清单速查