保姆级 Claude Code 使用指南：把安装、配置、子代理、MCP、工作流一次讲透文章写于 2026 年中，Clau

这篇是我把 Claude Code 的用法从头到尾整理的一份指南。工具上手是快，可想真用顺手、少踩坑，门道还不少。从装好登录、日常怎么跟它聊，到记忆和权限怎么配，再到子代理、技能、MCP、钩子这些进阶玩法，最后怎么搭成一套顺手的工作流，能讲的我都讲了，尽量让你照着就能跑起来。

文章写于 2026 年中，此时「最新」模型（主力 Opus 4.8 / Sonnet 4.6 / Haiku 4.5，加上刚发布的 Fable 5）。这东西迭代快，命令、价格、版本号最终以官方文档和 changelog 为准。

一、概述与快速开始

Claude Code 是什么

Claude Code 是个跑在你终端里的编码 agent——也能塞进 IDE、桌面应用和浏览器，但终端是它的主场。它跟普通 AI 助手最大的不同，就一点：它真能动手。

你给它派个活，它会自己去读代码、改文件、跑 npm / python / bash 命令，跑完看结果。编译报错、测试挂了，它不等你，自己改了再试一遍，来回折腾到通过为止。git 那套它也干——提交、开分支、发 PR。唯一会停下来问你的是写操作：改文件、跑有风险的命令、提交之前，它默认都会先征得你同意。

Claude Code vs. 对话版 Claude

能力	对话版 Claude（claude.ai / API）	Claude Code
理解并讨论代码	✓	✓
修改本地文件	✗	✓
运行命令与测试	✗	✓
创建/推送 git 提交	✗	✓
迭代修复（自动重试失败）	✗	✓
集成开发工具（MCP）	部分	✓

怎么选？只是想让 AI 帮你看看代码、聊聊思路，对话版就够了；想让它真把代码改完、测试跑过、东西交出去，才轮到 Claude Code。

它能在哪儿跑

它能在好几个地方跑，但底子是同一套：同一个引擎、同一份 CLAUDE.md 和 MCP 配置，换的只是个壳。挑你顺手的就行：

入口	启动方式	适用场景
CLI（终端）	`claude` 命令	本地开发、脚本自动化、CI/CD 集成、Unix 管道
VS Code 扩展	扩展市场搜索 "Claude Code"	IDE 内编辑、内联 diff、会话历史保留
JetBrains 插件	JetBrains 市场（PyCharm/WebStorm 等）	IntelliJ 生态开发、交互式 diff 查看
桌面应用	下载安装后启动	并行多会话、可视化 diff 审查、调度任务
Web（浏览器）	claude.ai/code	无需本地配置、长时间任务、移动/异地访问

安装与登录

安装方法

推荐：原生安装脚本（自动更新）

macOS / Linux / WSL：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

其他安装方式（可选）

使用 Homebrew（需手动更新）：

brew install --cask claude-code        # 稳定版（推荐）
brew install --cask claude-code@latest # 最新版

使用 WinGet（Windows，需手动更新）：

winget install Anthropic.ClaudeCode

Linux 包管理器（Debian/Fedora/RHEL/Alpine）：见官方高级设置指南。

登录与鉴权

第一次启动会自动引导登录。

cd /path/to/your/project
claude

登录走浏览器，认证完自动回到终端。能用的账户类型有三种：

Claude 订阅账户：Pro、Max、Team / Enterprise 都行，日常开发一般走这个。
Anthropic Console 的 API 密钥：适合企业或 API 驱动的工作流。
云服务商：Amazon Bedrock、Google Vertex AI、Microsoft Foundry，多用于企业环境。

至于各档位的差别、价格和额度，以官方文档为准，这里不展开。

OAuth 令牌还是 API 密钥？ 浏览器登录拿到的是 OAuth 令牌（sk-ant-oat01- 开头），自动绑你的订阅账户——这是 Claude Code 的原生方式，日常用它就对了。要是你设了 ANTHROPIC_API_KEY 环境变量，它会优先走 API 密钥，这条路留给 API 集成场景。

CI / GitHub Actions 的长效令牌

在 CI 等无人值守环境，官方推荐用 claude setup-token 生成长效 OAuth 令牌，并通过环境变量 CLAUDE_CODE_OAUTH_TOKEN 注入；这比把订阅交互式登录或裸 API 密钥塞进流水线更合适。

后续登录

凭证自动保存。如需切换账户或重新认证，在会话中输入：

/login

最小可跑流程

# 1. 安装
curl -fsSL https://claude.ai/install.sh | bash

# 2. 进入项目目录，启动 Claude Code
cd /path/to/your/project
claude

# 3. 输入第一条指令（见下一小节示例）

第一次会话怎么开口

第一句话别急着派活。先让它把仓库摸熟，它心里有谱了，后面才不容易瞎改。怎么开场，看你这次要干嘛：

就想先认识下这个项目，我一般直接丢一句：

先帮我把这个仓库看一遍：这是个什么项目、用了哪些主要技术和框架、核心模块在哪、构建和测试命令分别是什么？

它会自己去翻 package.json、README 和目录结构，顺手把构建、测试命令记下来，省得你后面每次都卡在「测试到底咋跑」上。

已经知道要加个功能，那就把活儿和约束一起说清楚：

我想加个 XX 功能。先别动手，帮我看看会牵动哪些模块和文件、大概要改哪些地方、有没有什么风险或冲突。

是来排查问题的，把现象和报错都贴上：

现在 XX 不对劲（比如构建挂了、某个功能不工作）。帮我跑下相关命令抓日志、定位到根因，再给个修复方案。

反正就一个道理：背景给得越足，它答得越准。报错、最近动过哪儿、本来该啥样、现在又啥样，能贴的都贴上，比来回纠正它省事多了。

运行前提：建议在 git 仓库里用

强烈建议在 git 仓库里用 Claude Code。 倒不是技术上非要——非 git 目录它照样读写文件、跑命令，只是 git 操作（开分支、提交、推 PR）用不了。真正的理由是：AI 一上手往往成片地改文件，而 git 给你一张随时能反悔的安全网——git diff 一看就知道它到底动了哪儿，改炸了用 git checkout / git reset 一键退回，想试新方案就单开个分支折腾，互不干扰。没有 git，这些保险就都没了。

系统要求

项目	要求
操作系统	macOS 13.0+ / Ubuntu 20.04+ / Debian 10+ / Windows 10（WSL）
内存	4 GB 最低，8 GB 推荐
网络	需持续连接 Anthropic API
Node.js（npm 安装时）	18+

架构上它不挑：单体也好、微服务也好，前端（React/Vue/Svelte）、后端（Node/Python/Go）、全栈，乃至多语言混搭，都接得住。上下文它自己从 README、构建脚本、包管理文件里学，不用你喂。

官方文档（想深入就看这几篇）

下面几篇都是 Claude Code 的官方文档（站点 code.claude.com），比本文更全、更新也更勤，想抠细节直接去翻：

二、运行方式：怎么直接用，怎么把它塞进脚本

Claude Code 有两种跑法。一种是你开着窗口自己用——敲 claude 进去，你一句它一句地聊，它干活你盯着，不对就打断。另一种是甩一条命令让它自己跑完——claude -p "任务"，它闷头做完、把结果吐出来就退出，全程不问你（这种一次性跑法官方叫「打印模式」或 headless，后面会用到这个词）。前者适合日常开发、边想边调；后者适合写进脚本、塞进 CI 流水线这种没人盯着的场合。

跑法	命令	啥样	用在哪
自己盯着用	`claude`	窗口开着不关，你一句它一句，随时能打断改方向	开发调试、边探索边迭代
一条命令跑完	`claude -p "任务"`	给一句它自己跑完，不问你、出结果就退出	CI/CD 流水线、脚本自动化、各种无人值守集成

自己盯着用，长这样：

claude
> 分析 src/auth 目录的认证逻辑
> 这里有什么安全问题吗？

一条命令跑完，长这样：

claude -p "生成一个 hello world 函数并写入 main.ts"

想接着上次的会话聊，用 claude --continue（或 claude -c）；想挑一个特定的旧会话恢复，用 claude --resume（或 claude -r）打开选择器。

打印模式（`claude -p`）的三种输出格式

claude -p 用 --output-format 控制输出形态，三选一。选哪个，取决于你是「给人看」、「脚本取最终结果」还是「实时看全过程」。

格式	输出形态	是否含中间回合	典型用途
`text`（默认）	纯文本最终答案	否	人直接看、最简单的管道
`json`	单个聚合 JSON 对象（跑完才输出）	否（折叠为 `num_turns` 计数）	脚本取最终结果 + 判成败/读成本
`stream-json`	JSONL，每个事件一行，实时流出	是（每回合都打印）	实时监控、调试、做进度 UI

1) text —— 最简单

claude -p "生成一个 hello world 函数并写入 main.ts"

只把最终答案打到 stdout，适合 result=$(claude -p "...") 直接取文本。代价：拿不到成败标志、成本、用量——脚本里要判错就别用它。

2) json —— 脚本首选

claude -p "这是什么项目" --output-format json

跑完一次性返回一个聚合对象。关键字段：

字段	含义
`is_error`	是否出错（首要判断依据）
`subtype`	`success` / `error_max_turns` / `error_max_budget_usd` / `error_during_execution` 等
`result`	最终文本答案
`num_turns`	内部回合数（中间过程被折叠成这个计数）
`total_cost_usd`	本次花费估算（本地按 token 估算，非账单口径）
`usage`	token 用量明细（含 `cache_read_input_tokens` 等缓存命中信息）
`session_id`	会话 ID；失败后可 `claude --resume <id>` 续接排查

判成败的标准写法（别只信退出码——旧版本里达到 max-turns/超预算时退出码也可能是 0）：

out=$(claude -p "任务" --output-format json)
jq -e '.is_error==false and .subtype=="success"' <<<"$out" >/dev/null \
  && jq -r '.result' <<<"$out" \
  || { echo "失败: $(jq -r .subtype <<<"$out")" >&2; exit 1; }

num_turns: 5 只是计数——agent 内部「读目录 → 读文件 → 再回答」这 5 个回合，在 json 里全被折叠进了一个 result。想看每一回合，用下面的 stream-json。

3) stream-json —— 看全过程

claude -p "这是什么项目" --output-format stream-json --verbose

逐行（JSONL）实时输出每个事件，json 折叠掉的中间回合在这里都看得到：

{"type":"system","subtype":"init","model":"claude-opus-4-8","tools":[...],"permission_mode":"default"}   // 起始：环境/工具/模型
{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Bash","input":{"command":"ls"}}]}}  // 某回合：模型决定调工具
{"type":"user","message":{"content":[{"type":"tool_result","content":"docs/"}]}}                          // 工具返回结果
// …… 中间这些 assistant/user 往返，就是被折叠的回合 ……
{"type":"result","subtype":"success","is_error":false,"num_turns":5,"result":"..."}                      // 最后一行 = json 模式给你的那个对象

要点：

-p 下的 stream-json 一般要加 --verbose 才打印完整中间事件；想要逐 token 增量，再加 --include-partial-messages。
最后一行 type=="result" 就是终态，判 is_error/subtype 即可——所以一条命令能同时「看过程 + 判成败」。
事件类型大致：system（init、API 重试等）、assistant（模型输出，含 tool_use）、user（工具结果 tool_result）、result（终态）。

三种格式的对应输入：用 --input-format stream-json 还能把多轮消息以 JSONL 流式喂给 -p，实现程序对程序的多轮交互（进阶，按需了解）。给 -p 设边界与权限预授权（--max-turns、--max-budget-usd、外层 timeout、--allowedTools / --permission-mode）的批处理示例见第六章 6.5「成本与速度工程」与 6.6「安全与可控」。

会话内基本操作

引用文件：打个 @ 就能把文件或目录塞进上下文——@src/index.ts 是单个文件，@src/ 是整个目录。图片、截图直接粘进去它也看得懂（UI 稿、报错弹窗都行），文件拖进窗口会自动当成 @文件 引用。

喊停和纠偏：按一下 Esc 立刻停，它就等你发话；不想等它磨完，中途直接打字纠正，它读到就改方向。要是觉得它改歪了，连按两下 Esc 或者敲 /rewind，能退回之前的检查点——这套快照独立于 git，文件改动随时可逆（具体范围以官方 checkpoints 文档为准）。

清空与压缩会话上下文

命令	效果
`/clear`	清除全部对话历史，释放上下文空间（保留 CLAUDE.md 和自动记忆）
`/compact [焦点]`	手动摘要并压缩历史，保留关键代码片段；可指定焦点，如 `/compact focus on API 改动`
`/context`	显示上下文使用分布（对话、文件、工具输出等），诊断溢出原因

续接和分支会话

操作	命令/快捷键
恢复上次会话	`claude -c` 或 `claude --continue`
打开会话选择器	交互模式中输入 `/resume`
分支会话（复制历史到新会话）	`/branch` 或 `claude --fork-session <session-id>`

权限与运行模式

通过 Shift+Tab 在权限模式间切换。默认的 Shift+Tab 循环为 default → acceptEdits → plan 三个状态；其余模式按条件加入或仅能用启动标志启用：

模式	行为	适用时机
普通模式 default（默认）	每次文件编辑和执行命令前征求许可	首次接触陌生代码、需要审核每一步
自动接受编辑 acceptEdits	自动编辑文件和通用文件系统命令（`mkdir`、`mv` 等），仍对外部命令询问	信任 Claude、加快开发速度
计划模式 plan	Claude 仅探索和提议计划，不编辑源文件	先想清楚再动手——复杂重构、架构决策、风险修改
自动模式 auto（研究预览）	账户满足要求且 opt-in 后加入循环；安全分类器筛查破坏性操作与 prompt 注入	高度自动化、内部工具、受信任环境
bypassPermissions	跳过权限提示，需 `--permission-mode` 或 `--dangerously-skip-permissions` 启动	受信任的自动化（谨慎使用）
dontAsk	从不提示，仅能用启动标志启用，不在 `Shift+Tab` 循环中	特定无人值守场景

计划模式的工作流

计划模式就是让 Claude 先把要动的地方摸清楚、把逻辑验证一遍，再动手。适合：

大型重构（理解全景后再修改）

跨模块改动（确保依赖正确）

风险操作（代码审查后再落地）

Shift+Tab 切换到计划模式
> 把认证从回调改为 async/await
# Claude 阅读代码、生成计划、展示影响范围
> 计划看起来不错，改吧
# Shift+Tab 切到执行模式，Claude 落地改动

也可在 .claude/settings.json 中允许特定命令（如 npm test、git status），避免每次询问。

斜杠命令总览

在会话中输入 / 查看全部可用命令和技能；/help 显示帮助。常用命令：

命令	干啥的	示例
`/help`	列出所有命令和快捷键	`/help`
`/login`	登录 / 切换账户	`/login`
`/init`	扫一遍项目，生成 CLAUDE.md	`/init`
`/clear`	清空对话历史	`/clear`
`/compact [焦点]`	摘要并压缩上下文	`/compact focus on 权限处理`
`/context`	看上下文占用	`/context`
`/resume`	恢复某个旧会话（别名 `/continue`）	`/resume`
`/branch`	把当前会话复制一份分叉出去	`/branch`
`/rewind`	回退到之前的检查点（等同连按 `Esc`）	`/rewind`
`/model`	切模型或打开选择器	`/model opus`
`/effort`	调推理深度	`/effort high`
`/fast`	开关 Fast 模式（同模型加速）	`/fast`
`/plan`	进计划模式（只读探索）	`/plan`
`/review`	本地审查 PR / 改动（云端深审用 `/code-review ultra`）	`/review`
`/security-review`	扫当前分支改动里的安全漏洞	`/security-review`
`/loop`	让某个 prompt/命令按间隔重复跑，不给间隔就让模型自己掌握节奏	`/loop 5m /review`
`/goal`	设个"完成条件"，它跨多轮一直干到满足为止（v2.1.139+）	`/goal 所有测试通过`
`/schedule`	创建 / 管理云端定时例程 Routines（别名 `/routines`）	`/schedule`
`/agents`	管理子代理	`/agents`
`/batch`	把大改动拆成独立单元并行跑	`/batch`
`/mcp`	管理 MCP 服务器连接	`/mcp`
`/permissions`	配工具权限	`/permissions`
`/fewer-permission-prompts`	扫历史、自动生成权限白名单	`/fewer-permission-prompts`
`/memory`	编辑 CLAUDE.md	`/memory`
`/config`	打开设置（主题、编辑器模式等）	`/config`
`/usage`	看用量与花费（订阅看额度，API 看花费估算；别名 `/cost`、`/stats`）	`/usage`
`/doctor`	诊断安装和配置问题	`/doctor`
`/export`	导出对话记录	`/export`

这些是常用的。还有一批按需才用的——/hooks（看钩子配置）、/install-github-app（配 GitHub Actions）、/diff（可视化 diff）、/statusline（配状态栏）、/feedback（报 bug，别名 /bug）、/add-dir（给会话加工作目录）、/teleport（把网页会话拉回本地）、/bashes（看后台任务）等。会话里敲个 /，全部命令加上你自己装的技能都会列出来。

模型切换与策略

内置模型别名

按能力递增：

别名	解析模型	成本	用途
`haiku`	Haiku 4.5	最低	简单任务、快速反馈
`sonnet`	Sonnet 4.6	中等	日常编码（默认推荐）
`opus`	Opus 4.8	高	复杂架构、深度推理
`best` / `fable`	Fable 5（若可用），否则最新 Opus	最高	超长会话、自主探索、高难决策
`opusplan`	Plan 模式用 Opus，执行用 Sonnet	混合	规划时用强模型，实施时快速执行

带后缀 [1m] 激活 100 万令牌上下文窗口（如 opus[1m]）。

模型切换方式

会话内切换

/model sonnet      # 切到 Sonnet 并保存为默认
/model             # 打开交互式选择器

启动时指定

claude --model opus
claude -c --model haiku

环境变量（全局）

export ANTHROPIC_MODEL=sonnet

settings.json（持久配置）

{ "model": "opusplan" }

推理深度（`/effort`）

任务越难，模型给自己留的思考时间越多。五档，从低到高：

等级	令牌开销	何时用
`low`	最小	低延迟、简单任务（格式化、查询）
`medium`	中等	成本敏感，可接受推理权衡
`high`	中高	默认，平衡令牌和智能
`xhigh`	高	深度推理、复杂问题
`max`	最大	一次性最大努力（可能过度思考）

重要：可用 effort 等级取决于模型。 Sonnet 4.6 与 Opus 4.6 只支持 low/medium/high/max（无 xhigh）；xhigh 仅 Opus 4.7、Opus 4.8 与 Fable 5 支持，设置超出会回退到最高可用级。默认等级为 high（Fable 5 / Opus 4.8 / Opus 4.6 / Sonnet 4.6），Opus 4.7 默认 xhigh。low/medium/high/xhigh 跨会话持久，max 仅当前会话有效。

此外，/effort 还有 ultracode 档，会编排动态工作流（dynamic workflows）做大规模并行处理；会话中也可用 ultrathink 关键词触发更深思考。设置方式：/effort high 或启动时 claude --effort xhigh。

Fast 模式

/fast 切换 Fast 模式，让当前模型更快地完成响应（同一个模型加速，并非更换模型）。注意：若当前在 Haiku 或 Sonnet 上启用 Fast，会自动升级到 Opus 以更快完成；它不是降级到更小的模型。Fast 模式通过会话内 /fast 命令切换。

适合：迭代开发、单文件改动、已明确需求。

advisor 模式

advisor 模式下，Claude 在解题中途可自行咨询第二个模型获取建议，再继续推进，适合高难度决策点。

三、配置、记忆与上下文管理

这一章就讲三件事：CLAUDE.md 怎么写、权限在 settings.json 里怎么配、上下文塞满了怎么办。三件事配到位，长会话不容易跑偏，也少踩那些重复的坑。

3.1 CLAUDE.md：项目长期记忆

CLAUDE.md 就是一个放在项目里的 markdown 文件，写给 Claude Code 看的「长期备忘」。每开一个新会话，它都会先读一遍。这跟你在对话里临时交代的话不一样——临时那种说完这轮就忘了，CLAUDE.md 是写一次、以后每次都照着办。

放置位置与层级

作用域	路径	共享方式	适用场景
组织级	macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`；Linux/WSL: `/etc/claude-code/CLAUDE.md`；Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`	IT/DevOps 强制部署	公司编码标准、安全策略
用户级	`~/.claude/CLAUDE.md`	个人（所有项目）	个人偏好、常用工具快捷方式
项目级	`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	版本控制（团队共享）	项目架构、构建命令、代码规范
本地个人	`./CLAUDE.local.md`	本地仓库（.gitignore）	个人沙箱 URL、本地测试数据

分层合并规则：从文件系统根目录向下，逐层加载所有发现的 CLAUDE.md 文件。较深层级的指令在上下文中出现在较浅层级之后，因此项目级指令的优先级最高（最后读）。所有文件均被拼接而非覆盖；如出现冲突，Claude 可能任意选择其一——要定期检查、排除矛盾的指令。大型单体仓库可用 claudeMdExcludes 跳过无关团队的指令文件。

自动生成

运行 /init 自动扫描项目并生成初始 CLAUDE.md（含构建测试命令、项目约定、文件架构）。若已存在，/init 会建议改进而非覆盖。

最该写进去的几样东西：构建和测试命令（npm run build、pytest src/ 这类——这是最值钱的，省得它每次瞎猜怎么跑）、代码风格（缩进、命名、import 顺序）、架构决策（模块怎么分、API 原则、关键依赖）、它最容易栽跟头的地方，还有那些你反复交代的流程（「提交前跑 linter」「改完同步文档」）。

别写太长。一个 CLAUDE.md 尽量压在 200 行以内——它每一行都占 token、挤上下文，写太长反而把真正有用的信息挤出去了。内容多了就往外挪：大段流程做成 skill（用到才加载），按文件生效的规则交给 path-scoped rules，外部文件用 @path/to/import 引进来（还是算 token，但起码好维护）。

3.2 Settings.json / settings.local.json

层级	文件	共享	用途
用户级	`~/.claude/settings.json`	不共享	个人偏好，跨所有项目
项目级	`.claude/settings.json`	git 共享	团队强制策略
本地覆盖	`.claude/settings.local.json`	.gitignore	开发者私密覆盖
管理级	系统位置（MDM/策略）	IT 部署	组织强制执行

优先级顺序（高到低）：

管理级设置（无法被用户覆盖）
CLI 参数临时覆盖
本地 settings.local.json
项目 settings.json
用户 ~/.claude/settings.json

主要可配置项

配置键	说明	示例
`model`	默认模型	`"claude-opus-4-8"` 或别名 `"opus"`
`effortLevel`	工作量等级	`"high"`（注意与模型匹配，见 2 节）
`permissions.allow`	明确允许的工具操作	`["Bash(npm run test:)", "Read(src/*)"]`
`permissions.deny`	明确禁止的操作	`["Bash(rm -rf )", "Read(.env)"]`
`permissions.defaultMode`	默认权限模式	`"default"` / `"acceptEdits"` / `"plan"` 等
`env`	环境变量注入	`{"NODE_ENV": "development"}`
`hooks`	自动化钩子（事件触发）	见 4 节
`autoMemoryEnabled`	启用自动记忆	`true` / `false`
`fileCheckpointingEnabled`	启用文件快照	`true`
`autoCompactEnabled`	自动压缩对话	`true`

精简示例配置

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-opus-4-8",
  "effortLevel": "high",

  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(git commit *)",
      "Read(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(.env*)"
    ]
  },

  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "notify-send 'Claude finished'" }]
      }
    ]
  },

  "env": { "NODE_ENV": "development" },
  "autoMemoryEnabled": true
}

3.3 权限系统：allow / ask / deny 规则

规则很简单：权限评估顺序是 deny → ask → allow，谁先匹配上谁说了算。例如 Bash(rm *) 的 deny 规则会阻止 Bash(rm -rf /)，即使存在更窄的 allow 规则。

需注意两条重要安全语义：

ask 规则在 auto / bypassPermissions 模式下仍会强制提示——它是逃逸阀，不会被自动模式吞掉。
受保护路径（protected paths，如 .git/、.claude/）在除 bypassPermissions 外的所有模式下都不会被 allow 规则自动批准。这是防止 agent 误改关键配置的硬保护。

规则格式

完全匹配：Bash(npm run build)
通配符模式：Bash(npm run test:*)（官方推荐的前缀+冒号形式）
工具整体：Bash 或 Bash(*)（deny 时会从上下文移除该工具）
字段匹配：Agent(model:opus)

给只读命令开个白名单：像 git status、npm test 这种你天天跑、又没什么风险的命令，丢进 allow 里。好处很实在——不用再一遍遍点确认，少浪费上下文，也等于告诉 Claude「这些你随便用」。

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(npm run test:*)",
      "Bash(ls -la)"
    ]
  }
}

懒得一条条加？ 跑一下 /fewer-permission-prompts，它会翻你的会话历史，把你已经批准过的命令整理成白名单、追加进 .claude/settings.json，后面的提示一下就少了。

3.4 上下文管理：窗口、压缩与长会话

上下文窗口与初始加载

每个会话始于一个新鲜的上下文窗口（最多 200K token；Fable 5 及 Opus 4.6+ 可选 1M token）。启动时按顺序自动加载：系统提示 → 自动记忆 MEMORY.md（前 200 行或 25KB）→ 环境信息 → MCP 工具列表（延迟加载名称，按需加载完整 schema）→ Skill 描述清单 → 用户级 CLAUDE.md → 项目 CLAUDE.md 与 path-scoped rules。

自动记忆的存储位置：自动记忆默认存于 ~/.claude/projects/<project>/memory/ 下的 MEMORY.md 及若干 topic 文件，可用 autoMemoryDirectory 设置调整目录。

自动压缩（compaction）

当上下文接近上限时自动触发 /compact——将对话历史替换为结构化摘要，保留：你的原始请求与意图、关键技术概念、检查或修改过的文件（含重要代码片段）、错误及其修复方案、当前待做任务。详细工具输出和中间推理会被丢弃。

压缩后什么会重新加载

内容	压缩后状态
系统提示	重新加载
项目根 CLAUDE.md	从磁盘重新加载
Auto memory	从磁盘重新加载
Path-scoped rules（带 `paths:` 的）	丢失，直到再次读取匹配文件
Nested CLAUDE.md（子目录）	丢失，直到再次读取该目录文件
已调用过的 skill 体	重新加载（限 5K token/skill，总计 25K）

长会话怎么保持状态不崩：

任务拆小。干完一个逻辑单元就 /compact 或者干脆开新会话，别让一堆东西攒着。
大任务前先 /compact focus on X。让摘要提前记住这次的重点，别等满了被动压缩。
该 /clear 就 /clear。换任务了（比如从「修 auth bug」跳到「接支付」）、换项目了，或者发现它开始不听话、错误越积越多，清掉重开最省事。
读文件这种脏活丢给子代理。让它在自己的上下文里啃大文件，只把结论返回来，别脏了主会话。
拿不准就 /context。看看 token 都花在哪了，它还会顺便给点优化建议。

3.5 其他可定制项

配置键	说明	常用值
`theme`	UI 主题	`"light"` / `"dark"`
`outputStyle`	输出格式化方式	见自定义 output-style 文档
`permissions.defaultMode`	默认权限模式	`"default"` / `"acceptEdits"` / `"plan"` / `"auto"` / `"dontAsk"` / `"bypassPermissions"`
`language`	界面语言	`"english"` / `"chinese"` 等
`alwaysThinkingEnabled`	启用扩展思考	`true` / `false`
`verbose`	详细日志	`true` / `false`

注：web 与 project 级设置会忽略 defaultMode 的 auto 与 bypassPermissions 取值。这些个人偏好通常在用户级 ~/.claude/settings.json 中设置，项目级一般不覆盖。具体可配置键名以官方 settings 文档为准。

四、进阶能力

前面讲的都还在「一个会话干一件事」的范围里。这一章往外扩：子代理、技能、MCP、钩子，让 Claude Code 能多角色分工、按事件自动触发、跨着工具一起用。

1. 子代理（Subagents）

子代理就是一个个独立的小助手，每个都有自己的系统提示、工具权限和上下文窗口。主 agent 把某个副任务甩给它，它在自己那块隔离的上下文里把活干完，只把结论摘要递回来——主会话不会被一大堆搜索结果和日志糊一脸。它只在单个会话内部干活，适合那种边界清楚、能独立做完的小任务：代码审查、翻文档、查 bug。

怎么用

在 .claude/agents/ 目录中用 Markdown + YAML frontmatter 定义子代理（系统提示写在 --- 之后的正文，tools 是逗号分隔字符串）：

---
name: code-reviewer
description: 专注多维度代码审查，评估正确性、可读性、架构、安全性、性能
model: opus
tools: Read, Edit, Bash
---

你是资深代码审查工程师。审查时分别从正确性、可读性、架构、安全、性能五个维度给出意见……

注：仅 --agents CLI 标志才接受 JSON 形式的内联定义；磁盘上的子代理一律用上述 Markdown+frontmatter 格式。

子代理支持三层权限模型：只读工具（Read、Bash grep 等探索型）、有限写权限（Edit、Write，不允许删除）、完全权限（信任的自动化）。最佳实践：先建一个项目级只读助手，给精确描述、限制为搜索读取工具，在小任务上验证后再扩权。

什么时候用：要深读代码的活（审查、覆盖率分析）；工具授权代价高、想用便宜模型（如 Haiku）来兜的活；以及任何你想让主会话保持干净的场合。

示例

> claude "review the pending changes for security and performance issues"

2. 技能（Skills）

技能就是一个可复用的工作流包，用 Markdown 文件定义，里面装着给 Claude 的指导、步骤清单和参考资料。技能既可被 Claude 自动检测并调用，也可被用户显式调用 /技能名。

技能大体两种。一种是给它新本领——它本来不会的事，比如生成文档、操作浏览器；另一种是教它按你的规矩办事——它本来就会，只是得顺着你团队的风格走，比如 NDA 审查流程、周报格式。官方还自带了一堆现成的，像 /review、/plan、/test、/code-simplify。

怎么用

推荐用 .claude/skills/ 结构：

.claude/skills/deploy/
├── SKILL.md
├── deploy-staging.sh
└── rollback.sh

SKILL.md 的基本结构与调用控制字段：

---
name: deploy
description: Deploy the app to staging or production
# 可选的调用控制（默认两者皆可调用）：
# disable-model-invocation: true   # 仅用户 /deploy 触发，Claude 不自动调用
# user-invocable: false            # 从 / 菜单隐藏，仅 Claude 调用
# context: fork                    # 配合 agent: 字段，在隔离子代理上下文中运行
---

# Deploy Workflow

1. Check git status: all changes committed
2. Run test suite
3. Build production bundle
4. Push to registry

调用方式由真实 frontmatter 字段控制：disable-model-invocation（禁止 Claude 自动调用）、user-invocable（控制是否出现在 / 菜单）；隔离运行用 context: fork。不存在 invoke: auto/user/subagent 这类字段。

常见技能：/code-review（多维度审查）、/docx（Word 文档）、/pdf（PDF 读取合并提取）、/plan（任务规划）、/test（测试驱动）。

适合：会反复跑的多步骤流程、团队想统一的做法、需要随手查的长文档。

3. MCP 服务器（Model Context Protocol）

MCP 是个开源标准，作用是让 Claude Code 接上外部工具、数据源和企业系统。每个 MCP 服务器是一个独立进程，把一组工具和数据源端出来给 Claude 用，比如：数据库、设计工具（Figma）、项目管理（Jira/Linear/GitHub Issues）、各种内部系统、浏览器自动化。

怎么用

首选 CLI 命令式管理：

claude mcp add --scope project postgres -- node /path/to/postgres-mcp/index.js
claude mcp add --scope user figma -- python -m figma_mcp

三种 scope 决定配置存储位置：

Scope	存储位置	共享性
`project`	仓库根目录的 `.mcp.json`	可入 git，团队共享
`local`	`~/.claude.json`	仅当前机器、当前项目
`user`	`~/.claude.json`	当前机器、所有项目

注：标准路径是仓库根目录的 .mcp.json（项目级）与 ~/.claude.json（local/user 级），不是 .claude/mcp.json 或 ~/.claude/mcp.json。

项目级 .mcp.json 示例：

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/postgres-mcp/index.js"],
      "env": { "DATABASE_URL": "postgresql://user:pass@localhost/db" }
    }
  }
}

会话内用 /mcp 管理连接。Claude 使用任何 MCP 工具前会请求权限，可选「总是允许」或「本次询问」。

适合：要读写外部系统、不想再手动把数据复制进对话框、或者要把多个工具串成一条自动化链路（从 Jira 读需求、在 GitHub 开 PR、往 Slack 发通知）的时候。

> claude "查看 Jira ENG-521，实现其中的特性，然后创建 GitHub PR"

4. 钩子（Hooks）

钩子是挂在 Claude Code 生命周期事件上的脚本，到点自动跑，用来强制规范、检查格式、控制权限、发通知。支持的类型：

类型	触发方式	场景
`command`	执行 Shell 脚本	Git 检查、代码格式化
`http`	POST 请求到端点	远程通知、外部服务调用
`mcp_tool`	调用 MCP 工具	更新项目管理系统、Slack 消息
`prompt`	LLM 评估（是/否）	内容审核、合规检查
`agent`	子代理执行工具	复杂验证逻辑

生命周期事件包括：SessionStart、SessionEnd、UserPromptSubmit、Stop（Claude 完成回应）、PreToolUse（工具执行前）、PostToolUse（工具执行后）等。

怎么用

在 .claude/settings.json 或 ~/.claude/settings.json 配置：

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "bash check-safe-bash.sh" }] },
      { "matcher": "Edit", "hooks": [{ "type": "command", "command": "bash format-on-edit.sh" }] }
    ],
    "Stop": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "bash run-tests.sh" }] }
    ]
  }
}

钩子脚本接收 JSON 通过 stdin，可输出决策（退出码 0=成功、2=阻止）：

#!/bin/bash
echo '{"decision": "block", "reason": "危险命令 rm -rf /"}'
exit 2

Hooks vs CLAUDE.md

维度	Hooks	CLAUDE.md
执行方式	脚本进程，在事件上运行	文本文档，会话启动时读取
动态性	每次执行，反映最新状态	静态，加载后不更新
用途	强制执行规范、权限检查	指导、教育、约定
性能	较慢（进程开销）	快速（内存中）

钩子是自动化与安全的工具；记忆是上下文与指导的工具。

适合：拦误操作（PreToolUse 挡住危险的 rm 或 git push --force）、强制格式化（PostToolUse 跑 prettier）、收尾前跑一遍测试（Stop），还有各种审计和通知。

5. 自定义斜杠命令

自定义斜杠命令是快速调用特定工作流的快捷方式，输入 /命令名 即触发对应技能。推荐用 .claude/skills/名/SKILL.md 新格式（也兼容旧的 .claude/commands/名.md）。

---
name: debug
description: 启动调试会话，打开日志，设置 DEBUG=true
disable-model-invocation: true   # 仅用户 /debug 触发
---

# 调试工作流
1. 设置环境变量 DEBUG=true
2. 查看最近的错误日志
3. 运行 npm run dev --debug

参数传递：命令后跟参数作为 $ARGUMENTS 可用。

> /review --effort high --focus security

适合：把常跑的多步骤流程打包（部署、审查、发布）、统一团队做法、让新人快速上手（/onboard、/setup-dev）。

6. 计划模式深入

计划模式是一个只读探索阶段：Claude 在不修改任何代码的前提下读取分析代码库、追踪依赖与影响范围、推导实现策略、输出结构化方案；等待用户显式批准后才进入执行阶段。

进入：输入 /plan 或按 Shift+Tab。工作流为探索 → 推理 → 方案输出 → 等待批准 → 执行 → 验证。

何时用：大型重构、架构决策、团队评审、高风险改动。

> /plan 为项目添加单元测试框架

Claude 分析项目、提议选用 Vitest/Jest、列举需改动文件、展示配置示例，等待批准。

7. 后台任务与定时任务

形式	运行位置	触发方式	使用场景
Routines（路线/例程）	Anthropic 云端	定时 / API / GitHub 事件	夜间 PR 审查、监控告警响应
桌面定时任务	本地机器	每小时 / 每天 / 每周	本地数据处理、特定工具访问
`/loop` 轮询	当前会话（前台）	时间间隔	临时监控、快速迭代
背景代理	云端或本地	用户触发	并行独立工作流

/loop 是会话内按间隔重复运行某 prompt/命令的前台轮询，不是云端/后台定时任务，使用时会话需保持开启。

Routines（研究预览）

Routines 是云端定时 Agent，可定义一次、自动重复执行，不依赖本地机器。创建：

> /schedule 每天下午 5 点，审查当天合并的 PR 并总结到 Slack

三种触发方式：定时（cron 或自然语言）、API（webhook）、GitHub 事件。通过 API 触发时需 beta 头 anthropic-beta: experimental-cc-routine-2026-04-01。

Routine 执行的具体行为（克隆 GitHub 仓库、加载项目 .claude/skills/ 与 MCP、自动运行、推送改动到 claude/* 分支并开 PR、结果留在会话中）以官方 routines 文档为准。

# 通过 API 触发 Routine
curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_xxx/fire \
  -H "Authorization: Bearer sk-ant-xxx" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -d '{"text": "Sentry 告警：内存泄漏检测到，堆栈跟踪已附"}'

8. 让它自己连着干：`/goal` 和 `/loop`

平时你得一轮一轮催它「继续」。这俩命令能让它在一定范围内自己往下跑，省点人工。

/goal——给个目标，它干到达标为止（需 v2.1.139+）

/goal <完成条件> 设一个目标，之后 Claude 会一轮接一轮地干，每轮结束都用一个轻量模型核一下「达标没」，没达标就接着来，达标了自动把目标撤掉。适合那种「反复试到对为止」的活：

/goal 所有测试通过
/goal 这个文件 lint 没有任何报错
/goal 把 Vue 2 写法全改成 Vue 3，且 npm run build 通过

设的时候有个讲究：条件得能被明确判定、最好还有个边界（像「测试通过」「build 绿了」这种）。要是给个模模糊糊、永远判不出「完成」的目标，它可能一直转下去，白烧 token。

/loop——让一条命令按间隔重复跑

/loop 是把某个 prompt 或斜杠命令隔一段时间跑一次。给了间隔就按间隔来，不给就让模型自己看着办：

/loop 5m /review              # 每 5 分钟跑一次 /review
/loop 检查下部署状态，挂了就喊我    # 不给间隔，模型自己定节奏

它是前台的，跑在当前会话里，窗口得一直开着；想停，Esc 一打断就行。适合盯部署、轮询 CI、看着一批 PR 这种「隔一会儿瞄一眼」的事。

容易跟这俩搞混的是 Routines（/schedule）：那个是云端定时任务，定义一次就自己重复跑，本地不用开着会话（上一节讲过）。三个别混：/goal 是「干到好为止」，/loop 是「每隔一会儿再来一遍」，Routines 是「扔云上自己定时跑」。

这些能力怎么搭着用

单看每个都还行，真正好用是搭起来用：MCP 配 Skills（接上外部工具，再按固定流程处理）；Subagents 配 Hooks（子代理干活，钩子在旁边把质量关）；Plan Mode 配 Routines（例行任务先过一遍计划再自动跑）；Custom Commands 配 Skills（攒一套团队公用的快捷命令）。

一个端到端例子：

触发 /schedule 每日 PR 审查
  → Routine 克隆仓库、加载 MCP（GitHub + Linear）
  → 自动调用 code-review 子代理
    → 子代理受 PreToolUse 钩子约束（禁止危险命令）
    → 输出审查意见到 Linear ticket
  → PostToolUse 钩子运行 prettier 检查
  → 生成 PR，Slack 通知

五、接到终端之外：IDE、CI/CD、SDK 和团队协作

前面都在讲怎么在终端里自己单干。这一章是往外接：接进 IDE、用桌面 app 或网页版、拿 Agent SDK 把它的内核嵌进自己的程序、接进 CI/CD 做无人值守自动化，再到团队之间怎么共享配置和流程。不管在哪儿接，那套 CLAUDE.md、settings、MCP、自定义技能都是同一份，跟着你走。

IDE 集成

VS Code 扩展

快速发起：Cmd+Shift+P（macOS）/ Ctrl+Shift+P（Win/Linux），输入 "Claude Code"。
内联 Diff 查看：改动呈现在侧边栏，支持逐个接受或拒绝。
上下文共享：用 @文件 或 @符号 引用代码，或选中代码段引用。
多轮对话 与 计划预览：执行前审批操作计划。

示例：选中一个函数，按 @ 引用它，要求 Claude「添加单元测试，并运行以验证通过」。

JetBrains 插件

IntelliJ IDEA、PyCharm、WebStorm、Android Studio 等通过官方插件提供类似能力（快速发送代码、模型切换、MCP 配置、IDE 内诊断共享）。需本地已安装 Claude Code CLI；安装后可右键选中代码 "Send to Claude" 或用快捷键启动。

桌面与 Web：平台选择指南

界面	特色	适用人群	核心差异
终端 CLI	完整功能；脚本化与管道	开发者；键盘工作流	最强大、最灵活
VS Code 扩展	内联 Diff；编辑器内对话	IDE 用户	编辑器原生体验
JetBrains 插件	类似 VS Code	JetBrains 用户	IDE 原生体验
桌面应用	可视化 Diff；并行会话；定时任务	多窗口管理团队	可视化最佳
Web（claude.ai/code）	无本地安装；iOS 支持；多任务并行；长时运行	移动/跨设备/服务器端任务	云端执行、最便携

几个关键区别：

执行环境：终端访问本地文件，Web 在云沙箱执行；IDE 扩展与桌面应用需本地 CLI 配合。
会话移动性：claude --teleport 用于把 Claude Code on the web 的会话接续/恢复到本地终端（web → 本地），方便把云端起的活儿拉回本机继续。
持久化调度：定时任务（Routines）由桌面应用和 Web 支持。

Claude Agent SDK：构建自定义 Agent

Claude Code 的底层引擎被封装为 Claude Agent SDK（曾名 Claude Code SDK），面向开发者构建完全自定义的自主 agent。这不同于 Claude Code 内置的子代理模式——前者是编程框架，适合嵌入应用；后者是 Claude Code 内置的并行工作流。

适用场景：企业自动化、多 Agent 编排、工具定制（经 MCP 或自定义函数）、权限与安全控制、成本追踪。

核心能力：内置工具库（代码执行、计算机操作、Web 搜索、文件操作、Bash）、自定义工具、生命周期钩子、结构化输出（JSON Schema）。一级支持 Python、TypeScript/JavaScript。

正确的包名与入口：

Python（包名 claude-agent-sdk）：

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="构建一个 API 端点",
    options=ClaudeAgentOptions(model="claude-opus-4-8"),
):
    print(message)
# 需要会话控制时用 ClaudeSDKClient

TypeScript（包名 @anthropic-ai/claude-agent-sdk）：

import { query } from "@anthropic-ai/claude-agent-sdk";

注意区分：from anthropic import Anthropic + client.messages.create(...) 是基础 Anthropic SDK（Messages API），不是 Agent SDK；TS 的基础 SDK 包为 @anthropic-ai/sdk，Agent SDK 包为 @anthropic-ai/claude-agent-sdk。Apple Xcode 26.3 已集成 Agent SDK。

关于订阅计划对 Agent SDK / Claude Code 的具体额度政策，请以官方 pricing / usage 文档为准（不要把订阅档位当成「为 Agent SDK 单独设置的月度额度」）。

CI/CD 与无人值守自动化

GitHub Actions 集成

官方快捷方式：运行 claude /install-github-app 一键生成可用的 Actions 工作流。之后可实现自动 PR 审查、Issue 自动分类（提及 @claude）、提交后自动格式化修复。

on: [pull_request]
jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code Review
        env:
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
        run: claude -p "Review this diff for bugs and style issues. Comment inline on any findings."

提示词写得好不好，直接决定这套自动化有没有用。把要查的问题类型、反馈格式、该忽略的模式都讲清楚，审查结果会有用得多。鉴权用 claude setup-token 生成的 CLAUDE_CODE_OAUTH_TOKEN（见第一节）。

无头模式与脚本集成

-p / --print 标志加管道输入，可集成到 shell 脚本：

# 从日志中分析异常
tail -100 app.log | claude -p "列出所有错误，按严重程度排序"

# 批量安全审查
git diff main --name-only | claude -p "检查这些文件是否有安全风险"

定时巡检与 Routines

长时间运行的自动化任务（夜间依赖检查、周报生成）用 Routines，在 Anthropic 托管基础设施运行，不依赖本地机器；也可由 GitHub 事件或 API 触发。

团队协作：统一编码标准与工作流

多人开发时，配置、指令和技能应纳入版本库，确保成员看到一致的工作流和标准。

CLAUDE.md（项目级指令） 描述架构决策与模块边界、代码风格、工具框架偏好、常见工作流：

# 项目指南
## 架构
- 后端：Node.js + Express；前端：React 18。
- 不允许修改 `./scripts/` 目录中的文件。
## 代码标准
- 命名：驼峰式；函数必须有 JSDoc 注释。
- 提交前运行 `npm run lint:fix` 和 `npm test`。

Settings 与权限共享：基础配置放项目 .claude/settings.json（git 跟踪），个人覆盖放 .claude/settings.local.json（.gitignore）。

// .claude/settings.json（版本库共享）
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git *)", "Write(src/**)", "Write(tests/**)"]
  },
  "model": "claude-opus-4-8"
}

自定义技能共享：在 .claude/skills/ 放团队技能，自动被所有成员加载。

多 Agent 协作：用 /batch 或子代理把大改动分解到独立单元并行处理，再汇总结果——处理大型代码库或复杂重构时尤其有用。

六、工作流范式与最佳实践

用顺了之后会发现，干活其实就那么几种套路。关键是看任务挑套路，别端着流程硬走。

6.1 核心工作流范式

范式	适用场景	核心步骤	关键点
探索→规划→编码→提交	新功能、大改动、不熟悉的代码库	Plan 模式读文件理解现状 → 写详细实现计划 → 切默认模式执行 → 验证+提交	最大化避免做错方向；plan 模式开销值得
测试驱动开发	需求明确、需高可信度	写失败测试 → Claude 实现使其通过 → 迭代到覆盖边界	测试即验证环；Claude 既实现也自验
小步增量提交	任何复杂改动	每 1-3 个逻辑单元提交一次	便于 review、bisect、rollback；保持上下文清洁
快速迭代修复	小 bug、微调	直接描述 → Claude 改 → 测试；跳过 plan	过度规划小任务浪费时间
并行多 agent	独立的调查、审查、改动	用 subagent / worktree / `/batch` 拆分	保持各线程上下文独立

决策树：

一句话说清 & 代码很熟 → 直接编码，跳过 plan
改动涉及 3+ 文件 & 不确定方向 → plan 模式探索 → 规划 → 实施
需验证逻辑正确 & 边界复杂 → 先写测试，驱动实现
任务很大（几百行） → 拆成 2-4 个小 PR

6.2 高质量提示词的写法

做法	差的例子	好的例子	为什么
明确验收标准	"添加日志功能"	"在 @src/logger.ts 加 debug 级日志，用 Winston，输出到 stdout 和 /logs/app.log，行为用测试验证"	Claude 知道什么叫"完成"
指向参考实现	"写一个 API 端点"	"按 @src/routes/users.ts 的模式写 GET /posts/:id，404 when not found，验证: curl localhost:3000/posts/1"	学会你的约定而非猜测
让 Claude 先复述	"修复登录 bug"	"这是 bug 报告：[粘贴]。回答前先总结：symptom 是什么、最可能原因、怎么验证修复"	在实施前抓住误解
要求跑测试自验	"实现 email 验证"	"实现 validateEmail。边界：user@example.com→true，invalid→false，user@.com→false。写测试覆盖并运行确保通过"	Claude 变成验证循环
范围约束	"重构这个文件"	"重构 src/auth.ts 提升可读性，但不改公开 API 或行为。风格参考 @src/utils.ts，前后对比测试输出"	防止 scope creep

提示词结构模板

[背景 / 为什么] 我要在登录后显示用户欢迎信息。
[约束 / 你知道什么]
- 看 @src/layouts/Dashboard.tsx 理解组件结构
- 用户信息存在 context 中 user 对象，不要改 API endpoints
[具体任务] 在 Dashboard 顶部添加欢迎 banner，显示 "Welcome, {user.name}!"
[验收标准]
1. 写测试 mock user context，验证 banner 渲染
2. 运行测试确保通过
3. 对比设计稿 [paste/image]，列出任何不符
[可选] 实施前先说一下你的方案

6.3 多 agent 与并行工作

情形	工具	优势	成本
一个任务需两个独立视角（写+审查）	Subagent（`/agents` 或自动委派）	鲜上下文无偏见	中等
大范围调查/研究（grep 整库、读 50+ 文件）	Subagent for investigation	主会话干净，获总结非全列表	低
并行改动多文件/目录互不冲突	`/batch` / `/worktrees`（git worktree 隔离）	可并行、合并无冲突	磁盘空间；需 git
很多独立小任务（迁移 500 文件）	Workflow / `ultracode`	脚本编排、可重复、规模化	高 token；需仔细设计
多 agent 同时 + 实时协调	Agent teams（`/agents`）	lead 分配、peer 并行	非常高 token；复杂

并行改动通过 /batch（把跨码库大改动分解为独立单元，各自在 worktree 运行）或 /worktrees 管理实现；并行后台会话用 claude agents / 背景代理。不存在 claude --branch 标志。

对抗式核验：合并前让独立的 agent review 你的改动，而非自己审查自己——reviewer 无偏见、用 xhigh 思考，更可信。

1. Writer session: 实现功能 + 写测试
2. Reviewer subagent: "审查这个 diff 对照 PLAN.md，找出：需求是否全实现、边界是否有测试、是否有超 scope 改动。只报影响正确性的差距"
3. Writer session: 读反馈，修复差距

6.4 上下文卫生与管理

Claude Code 绕不过去的硬约束就是上下文窗口。后面这些讲究，说到底都是为了让它别撑太满、别跑题。

问题	症状	解决方案
会话堆积多个无关任务	Claude 开始"忘记"早期指令；错误增多	任务间 `/clear` 重置
CLAUDE.md 太长	Claude 忽视一半规则	删掉能从代码推断的；长程序移到 skill
大重构涉及 10+ 文件	上下文爆炸	拆成 2-3 个小 PR，各自清空点
同一任务改 3 次还错	失败尝试污染上下文	`/clear` 重开，用更具体的提示
Subagent 读太多文件	返回摘要太长	用 hook 预处理日志（grep 只要 ERROR）；用 skill 预总结

用 CLAUDE.md 固化约定（保持简洁）：

## 代码风格
- ES modules，不用 CommonJS；变量 camelCase，常量 UPPER_SNAKE_CASE
## 测试规范
- jest，放 __tests__/；每个单测 < 20 行测一件事
- 用 `npm test -- --testPathPattern=foo` 只跑相关测试
## Git 工作流
- 功能分支从 main 创建，命名 feat/xxx 或 fix/xxx；CI 通过后才合并

不要写进去：常识（"写干净的代码"）、详细 API 文档（改为链接）、整个文件列表（Claude 自己读）、高频变化的信息。

6.5 成本与速度工程

任务类型	推荐模型	Effort	典型成本
日常编码、单文件	Sonnet 4.6	`high`	低
架构设计、多文件重构	Opus 4.8	`high` 或 `xhigh`	中-高
小 subagent 任务（验证、grep）	Haiku 4.5	默认	最低
大规模并行（workflow）	Opus lead, Sonnet teammates	混合	最高

控制成本技巧：一次性查询用 claude -p "prompt" --model sonnet；subagent 里指定 model: haiku；workflow lead 用 opus、teammate 用 sonnet；用 /clear 清无关上下文。

Headless 批处理（避免交互式会话开销）：

for file in $(cat files.txt); do
  claude -p "Migrate $file from Vue 2 to Vue 3. Run tests. Output OK or FAIL." \
    --model sonnet --permission-mode acceptEdits
done

用 --output-format json 解析结果；用 --verbose 只在前几个文件上调试。

6.6 安全与可控

操作类型	风险	检查点
文件编辑（非敏感）	语法/逻辑错误	运行测试或构建；code review
删除文件	不可恢复	看 git status；只删列表中文件；提前备份
Git 操作（push、force push）	分支污染；历史破坏	push 前看 git log；never force push to main
敏感/不可逆（DB migration、删库）	数据丢失	人工审查 + 签核；dry-run
外部 API（部署、发数据）	污染生产；信息泄露	明确确认

防提示注入与不可信输入——在 CLAUDE.md 中：

## Security
- Never execute untrusted user input as shell commands; use parameters, not string interpolation
- Never write .env or secrets to files; use env vars only
- URLs from external sources: validate with allowlist before fetch

用 hook 在执行前验证命令；在 plan 模式审查大改动的 diff 再合并，批准后转 acceptEdits，git diff 再看一遍才 commit。

注：自 v2.1.183 起，Claude Code 默认拦截破坏性 git 命令（git reset --hard、git clean -fd 等）与 terraform/pulumi destroy，除非显式要求；Auto Mode 内置 prompt 注入筛查。

6.7 常见反模式与避坑

反模式	症状	修复方案
厨房水槽会话	A→B→A 切换，上下文乱	每个独立任务一个新会话；用 `/resume` 切换
盲目接受大 diff	100+ 行不看就合并	用 plan 模式或 `/code-review`；超 50 行必看
一次塞太多	同一提示 3 个独立任务	一个会话一个逻辑任务
不给上下文就让它猜	改了不该改的地方	花 30 秒指向参考实现，省 10 轮修正
长会话不清理	8 小时一个会话，最后脑子乱	每 2-3 小时 `/clear`，关键决策点新开
CLAUDE.md 太厚重	规则多了被忽视	只留必要的；长文档移 skill；定期审查
对抗式审查不独立	自己审自己，缺陷看不出	用 subagent 或新会话 review，用 `xhigh`
Workflow 成本失控	跑 200 个 agent，费用翻倍	先小范围试；设 agent 上限；看进度

6.8 归根到底，就这五条

按规模来：小活儿直接干，大活儿拆开或上多 agent
上下文最要紧：所有优化都是为了让它小而专注
留个能自查的闭环：丢给 Claude 一个测试、截图或 diff，让它自己迭代到好
分好工：探索和动手交给 Claude，定方向和拍板留给你
前面多花五分钟，后面少纠正五十次：CLAUDE.md 或计划写扎实，回报在后头

八、一页速查

最关键命令

命令	作用
`claude` / `claude -c` / `claude -r`	启动 / 续接上次 / 恢复指定会话
`claude -p "任务"`	一次性打印模式（脚本/CI）；配 `--output-format text/json/stream-json`
`/usage`（别名 `/cost`、`/stats`）	看用量与花费：订阅用户看额度，API 用户看花费估算
`/init`	扫描项目生成 CLAUDE.md
`/clear` / `/compact [焦点]` / `/context`	清空 / 压缩 / 查看上下文
`/model` / `/effort` / `/fast`	切模型 / 调推理深度 / 同模型加速
`/plan`（或 `Shift+Tab`）	进计划模式（只读探索）
`/permissions` / `/fewer-permission-prompts`	配权限 / 收敛权限提示
`/agents` / `/batch`	管理子代理 / 分解并行任务
`/mcp`（`claude mcp add --scope ...`）	管理 MCP 服务器
`/rewind`（或 `Esc Esc`）	回退到检查点
`claude setup-token`	生成 CI 用长效令牌

权限模式（Shift+Tab 默认循环 default → acceptEdits → plan）：plan 只读探索；acceptEdits 自动改文件；auto/bypass/dontAsk 需条件或启动标志。

模型与 effort 速记：日常 sonnet+high；复杂架构 opus+xhigh（仅 Opus 4.7/4.8、Fable 5 支持 xhigh）；轻量子任务 haiku；超长会话 opusplan / [1m]。

配置三件套：CLAUDE.md（≤200 行，项目约定）+ .claude/settings.json（权限/模型/hooks，团队共享）+ .claude/settings.local.json（个人覆盖，gitignore）。权限评估顺序 deny → ask → allow；受保护路径（.git/、.claude/）除 bypass 外不被 allow 自动批准。

最佳实践清单

首会话先让 Claude 扫描仓库（结构、技术栈、构建测试命令）
大改动先 plan，小改动直接做
提示词给足上下文：参考实现 + 验收标准 + 让它跑测试自验
每个逻辑单元小步提交；任务切换时 /clear
把反复交代的约定写进 CLAUDE.md，长内容移到 skills
合并前用独立 subagent 做对抗式审查（xhigh）
危险操作（删除、force push、destroy、DB migration）人工把关
团队配置入版本库；CI 用 CLAUDE_CODE_OAUTH_TOKEN
研究预览功能（Routines、web/移动等）可试用，但生产路径要能降级

进阶能力速记：Subagents（隔离副任务）· Skills（可复用工作流）· MCP（接外部工具）· Hooks（事件自动化与安全闸）· Plan Mode（先想后做）· Routines（云端定时）。单用都行，搭起来才香。

收个尾：Claude Code 是个靠谱、但得你好好"配置上下文 + 设清边界 + 留审查关口"的自主队友。约定和工作流这种能跟着你走的东西多花点心思，具体功能让它随版本升级就好，你的方法论稳住不变。

保姆级 Claude Code 使用指南：把安装、配置、子代理、MCP、工作流一次讲透

一、概述与快速开始

Claude Code 是什么

Claude Code vs. 对话版 Claude

它能在哪儿跑

安装与登录

安装方法

登录与鉴权

最小可跑流程

第一次会话怎么开口

运行前提：建议在 git 仓库里用

官方文档（想深入就看这几篇）

二、运行方式：怎么直接用，怎么把它塞进脚本

打印模式（claude -p）的三种输出格式

1) text —— 最简单

2) json —— 脚本首选

3) stream-json —— 看全过程

会话内基本操作

清空与压缩会话上下文

续接和分支会话

权限与运行模式

斜杠命令总览

模型切换与策略

内置模型别名

模型切换方式

推理深度（/effort）

Fast 模式

advisor 模式

推荐策略

三、配置、记忆与上下文管理

3.1 CLAUDE.md：项目长期记忆

3.2 Settings.json / settings.local.json

3.3 权限系统：allow / ask / deny 规则

3.4 上下文管理：窗口、压缩与长会话

3.5 其他可定制项

四、进阶能力

1. 子代理（Subagents）

2. 技能（Skills）

3. MCP 服务器（Model Context Protocol）

4. 钩子（Hooks）

5. 自定义斜杠命令

6. 计划模式深入

7. 后台任务与定时任务

8. 让它自己连着干：/goal 和 /loop

这些能力怎么搭着用

五、接到终端之外：IDE、CI/CD、SDK 和团队协作

IDE 集成

VS Code 扩展

JetBrains 插件

桌面与 Web：平台选择指南

Claude Agent SDK：构建自定义 Agent

CI/CD 与无人值守自动化

GitHub Actions 集成

无头模式与脚本集成

定时巡检与 Routines

团队协作：统一编码标准与工作流

六、工作流范式与最佳实践

6.1 核心工作流范式

6.2 高质量提示词的写法

6.3 多 agent 与并行工作

6.4 上下文卫生与管理

6.5 成本与速度工程

6.6 安全与可控

6.7 常见反模式与避坑

6.8 归根到底，就这五条

八、一页速查

打印模式（`claude -p`）的三种输出格式

推理深度（`/effort`）

8. 让它自己连着干：`/goal` 和 `/loop`