Claude Code 速查手册

一册通读版:从装好到能带团队落地,28 篇合成一篇。
基于 Claude Code 2.1.318,2026 年 11 月实测。命令和界面随版本变化,用之前先跑 claude --help 和 /help。

这本书怎么用

它不是教程,是速查。 每个小节都是同一个结构:怎么用 → 关键参数 → 怎么验证 → 坑。

贯串全书的三个判断:

  1. 它说的是"主张",不是"事实" —— 要动手改的东西,先跑命令验一遍。
  2. "展示方案" ≠ "写入磁盘" —— 审要用 git diff,不是看它说了什么。
  3. 它不会保证读全你的仓库 —— 重要文件(测试、配置、接口)要明确点名。

还有一个方法贯穿全书:金丝雀法。

要验证"某个配置真的生效了",往里面放一条别处绝对没有的信息,再去问。
答得出,才是证据。

这本书里用它验证过:CLAUDE.md、子目录 CLAUDE.md、Skill、Hook、插件、图片输入、配置优先级。


00 开始之前

装好 + 确认装对了。验收标准:四条命令全过。


它是什么(三句话,够用)

它是什么 它不是什么
一个能自己探索文件、执行命令、看结果再调整的编码代理 不是代码补全
模型 + 工具 + 上下文管理三者的协作 不是独立运行的程序
会在你机器上真的动手 不是只跟你聊天

由此推出的三条铁律 → 见 README 的三条判断。


安装

先查有没有装:

claude --version

【实测】正常输出:2.1.318 (Claude Code)

没有就选一种装。【未实测】以下命令来自官方 setup 文档,安装方式迭代较快,执行前先看 https://code.claude.com/docs/en/setup。

方式 命令 适合
原生脚本(Win) irm https://claude.ai/install.ps1 | iex 不想管 Node
原生脚本(mac/Linux) curl -fsSL https://claude.ai/install.sh | bash 同上
npm npm install -g @anthropic-ai/claude-code 本来就用 Node
winget winget install Anthropic.ClaudeCode Windows 用 winget 管软件

⚠️ 别混着装。 装了两份会出现"升级了但版本号还是旧的"。查一下有几份:

where.exe claude

验证:claude doctor

claude doctor

【实测】完整输出的前半段:

Claude Code doctor

Running: package-manager (2.1.318)
Commit: ca1fa9dea62c
Platform: win32-x64
Package manager: winget
Path: C:\Users\rainio\AppData\Local\Microsoft\WinGet\Packages\...\claude.exe
Config install method: global
Search: OK (bundled)
Auto-updates: Managed by package manager
Auto-update channel: latest
Last update attempt: success → 2.1.284 (2026-09-29)

看到最后的 No installation issues found. 就可以。

它还会告诉你三件平时想不到的事:

  1. 自动更新归谁管。 Managed by package manager 表示由 winget 负责,claude update 不一定管用,得走 winget upgrade。
  2. 上一个版本是什么。 Last update attempt: success → 2.1.284 是上次更新的记录,和当前版本不一定相同。
  3. 哪些功能为什么不可用。 这是最有用的一段——它不是简单说"不可用",而是给出原因。

【实测】我这台机器的原因段:

Remote Control is only available when using Claude via api.anthropic.com.
ANTHROPIC_BASE_URL is set and does not point at api.anthropic.com,
so this session is using a custom endpoint — unset it (or run in a shell
without it) to use Remote Control.
- Not connected to the Anthropic API (api.anthropic.com)
- Not signed in to claude.ai
- claude.ai subscription auth not active

这段要会读:它不是说你的环境坏了,是在告诉你「因为走了自定义端点,所以这些功能用不了,想去掉就 unset 那个变量」。照此判断,教程里讲订阅额度、Remote Control、账号切换的内容对你可以直接跳过。

想要能自动修问题的完整体检,在会话里跑 /doctor。


认证

【实测】claude auth --help:

Commands:
  login [options]   Sign in to your Anthropic account
  logout            Log out from your Anthropic account
  status [options]  Show authentication status
claude auth status    # 查当前状态
claude auth login     # 登录
claude auth logout    # 登出

会话里也有 /login、/logout、/status。

认证方式决定哪些功能对你有用。 走自定义端点时,"订阅额度""Remote Control""切换账号"这类内容对你跑不通——跳过就行,不是文章错了。


四条验收

claude --version
claude doctor
git --version
python --version
命令 通过标准 不过怎么办
claude --version 出版本号 没装 / PATH 没配
claude doctor No installation issues found 按它的提示修,别自己猜
git --version git version 2.x 装 Git
python --version Python 3.x.y 装 Python;Windows 上别用 python3

权限模式(先认识,别急着关)

在 claude 会话里按 Shift+Tab 循环,状态栏显示当前模式。

【实测】claude --help 里 --permission-mode 的取值:

值 意思
manual 每次都问
auto 不问,直接干
acceptEdits 自动接受编辑,命令仍问
plan 只出计划,不动手
dontAsk 不问,按规则自动决定
bypassPermissions 跳过全部检查(⚠️ 危险)

学习期用 manual。 原因:你正在学的就是"审"这个动作。

claude --permission-mode manual

详见 05 权限。


开工前必做:git 基线

cd "D:\Workspace\your-project"
git status                 # 不是仓库 → 往下
git init
git add .
git commit -m "baseline"
claude

这一步不是可选的。 没有基线,它改坏了你没法回滚。


坑

  • Windows 上 python3 常是坏的别名 → 一律用 python
  • 用 PowerShell 7,别用 cmd;&& 在 5.1 里不work
  • 在项目根目录启动,不要在上层目录
  • git checkout -- <file> 会丢弃未提交修改,用前先 git diff

实测用例

格式:场景 → 我输入什么 → 它输出什么 → 结论。
每次学到一个新动作,就往对应那一篇的末尾加一条。

用例 00-1 · 确认装没装

输入

claude --version

输出

2.1.318 (Claude Code)

结论:装好了。版本号要记下来——后面所有结论都跟版本绑定。


用例 00-2 · 环境体检(真实完整输出)

输入

claude doctor

输出(节选,前面是安装信息,后面是原因解释)

Running: package-manager (2.1.318)
Commit: ca1fa9dea62c
Platform: win32-x64
Package manager: winget
Config install method: global
Search: OK (bundled)
Auto-updates: Managed by package manager
Auto-update channel: latest
Last update attempt: success → 2.1.284 (2026-09-29)

Remote Control is only available when using Claude via api.anthropic.com.
ANTHROPIC_BASE_URL is set and does not point at api.anthropic.com,
so this session is using a custom endpoint ...

No installation issues found.

结论:No installation issues found. 即通过。重点是它会解释原因——不是因为坏了,是因为 ANTHROPIC_BASE_URL 指向了自定义端点。


用例 00-3 · 认证子命令有哪些

输入

claude auth --help

输出(节选)

Commands:
  login [options]   Sign in to your Anthropic account
  logout            Log out from your Anthropic account
  status [options]  Show authentication status

结论:claude auth login / logout / status 是真实子命令。别写成 claude login——那个不是子命令,会被当成提示词。


用例 00-4 · 另外两条验收

输入

git --version
python --version

输出

git version 2.50.0.windows.1
Python 3.14.6

结论:git 有版本号即可;Python 可用的命令是 python(不是 python3)。

2026-11-14 / 2.1.318


01 基本操作

启动、接着上次、清上下文。验收:能启动、能续上次、能清干净。


我要启动

cd "D:\Workspace\your-project"
claude

必须在项目根目录启动。 它看到的世界以启动目录为准。

claude --add-dir "D:\Workspace\another-project"   # 额外加一个目录

我要接着上次聊

我要 命令
继续当前目录最近一次对话 claude --continue(-c)
从列表里挑一个历史会话 claude --resume(-r)
恢复指定会话 claude --resume <session-id>
恢复但另起一个新 ID(不覆盖原会话) claude --resume --fork-session
给会话起名字,方便以后找 claude --name "修支付bug"

会话里也可以直接 /resume。


我要清掉上下文

它"忘事"通常不是你问得不好,是上下文塞满了。

命令(会话内) 作用
/clear 清空,开一段全新对话
/compact 压缩,保留要点继续(有成本,见用例 01-7)
/context 看当前上下文都被什么占了
/status 看模型、端点、认证状态
/help 看当前版本真实可用的斜杠命令
/exit 退出

区别一句话:/clear 是换一张白纸,/compact 是把草稿纸上的字抄小一点。


我要看它在干什么

状态栏会显示它跑了什么(例如 ran 3 shell commands)和当前权限模式。

想看得更细:

claude --debug                 # 调试输出
claude --debug=hooks,mcp       # 只看某几类
claude --debug-file D:\tmp\cc.log

验证

  • claude --version 出版本号
  • 在项目里启动,它能说出当前目录是什么
  • 退出再 claude --continue,能接上刚才的话
  • /clear 之后问"我们刚才聊了什么",它答不上来(说明真清了才对)

坑

  • 在上层目录启动,它不知道你要哪个项目 → cd 进去再启动
  • --continue 续的是"当前目录"的最近一次,换个目录就续不到了
  • /clear 是清上下文,不是删日志:会话记录文件还在磁盘上(~/.claude/projects/...),但当前会话内拿不回来了
  • 上下文不是越大越好:塞太多反而更容易答偏,及时 /compact
  • 斜杠命令各版本有增删 → 记不住就敲 /help,以它为准

实测用例

用例 01-1 · 状态栏会告诉你它干了什么

场景:在 hello-project 里启动,让它读两个文件找测试盲区

输入

读一下这个项目里的 calc.py 和 utils.py,然后回答三件事:
1. 这个项目是做什么的
2. calc.py 依赖了 utils.py 里的哪些函数,分别用在哪里
3. 哪些函数或分支没有被 test_calc.py 覆盖到
先不要修改任何文件。

输出(状态行)

Thought for 3m 25s, listed 1 directory, ran 3 shell commands

结论:那一行是你的第一手情报。ran 3 shell commands 说明它真在你机器上跑了命令——"不要修改文件"不等于"不要执行命令"。


用例 01-2 · 它自己补读了没点名的文件

场景:同上,我只点名了 calc.py 和 utils.py,没提测试文件

它做的:自己列了目录 → 主动读了 test_calc.py → 跑了一次测试 → 才给出 9 条未覆盖分支

结论:这次它补上了,但这是主动探索,不是承诺。换个任务未必会补。重要文件要明确点名。

2026-11-14 / 2.1.318


用例 01-3 · 第一次进一个目录:工作区信任确认

输入

cd "D:\Workspace\cc-demos\hello-project"
claude --name "会话练习"

输出(界面原文)

───────────────────────────────────────────────
 Accessing workspace:

 D:\Workspace\cc-demos\hello-project

 Quick safety check: Is this a project you created or one you trust? (Like your own
 code, a well-known open source project, or work from your team). If not, take a
 moment to review what's in this folder first.

 Claude Code'll be able to read, edit, and execute files here.

 ❯ No, exit
   Yes, I trust this folder

结论:第一次在某个目录启动会问一次。看完它列出的目录再决定——它说的是"能读、能改、能执行文件",不是"能读"。熟悉之后该目录不再问。

-p(非交互)模式会跳过这个对话框,所以只在信任的目录里用 -p。


用例 01-4 · 退出后怎么续上

输入:退出会话后,在同一个目录再跑 claude

输出

Resume this session with:
claude --resume af8a60a2-2142-4b67-bcf7-88937ce9ce2d

结论:它直接把续接命令和 session id 给你了。三种续法:

claude --continue                      # 续当前目录最近一次
claude --resume                        # 弹列表让你挑
claude --resume af8a60a2-2142-4b67...  # 续指定这一个

用例 01-5 · --continue 真的能接上

输入(续接后)

我们上一轮聊了什么?原样复述我刚才问你的那个问题。

输出(节选)

上一轮你只问了一个工具性问题(当前目录 + 文件行数),我查看了 pwd 和 wc -l test_calc.py。

你刚才问的原话是:
▎ 说出两件事:
▎ 1. 你当前的工作目录是哪个
▎ 2. test_calc.py 一共有多少行

结论:--continue 复述出了原话,说明上下文真的接上了。顺带 learn 到:它数行数是真的跑了 wc -l,不是猜的。


用例 01-6 · /clear 之后问同一个问题

输入

/clear
我们上一轮聊了什么?原样复述我刚才问你的那个问题。

输出(节选)

这个会话刚执行过 /clear,之前的上下文已经被清空了,所以上一轮聊了什么……
我都无法得知。硬要复述那就是编造。

……除非你愿意让我去翻本地的会话记录文件
(C:\Users\rainio\.claude\projects\D--Workspace-cc-demos-hello-project\ 下的 transcript)
……另外,从工作区快照能看到的只是一些痕迹、不是记忆:当前分支 master,
notes.md 有改动、output/ 未跟踪,最近两次提交是围绕 utils.py 的测试……

结论:答不上来 = /clear 生效了。但有三个细节值得记:

  1. 会话日志还在磁盘上,/clear 只是让当前会话不再"看见"它。准确说法是「当前会话内不可恢复」,不是文件被删。
  2. 它仍然看得到工作区状态(git 分支、未跟踪文件、最近提交),所以能「推断」你刚在干什么。
  3. 推断 ≠ 记忆。 它自己都说了"只是一些痕迹、不是记忆"。别把它的推断当成它记得。

2026-11-14 / 2.1.318


用例 01-7 · /compact 不一定省上下文(实测反直觉)

压缩前

44k/1m tokens (4%)
  System tools: 36k
  Messages:     322

执行 /compact 后

56.6k/1m tokens (6%)
  System tools: 33.8k
  Messages:     15.1k     ← 从 322 涨到 15.1k

总量涨了 12.6k。

为什么:/compact 会生成一份摘要,摘要本身就要占 15k token。当原对话只有 322 token 时,压缩等于净亏。

结论:

/compact 是有成本的。 它只在"对话已经很长、摘要比原文小"的时候才划算。

怎么判断该不该压:先看 /context 里 Messages 的数值。

Messages 建议
几千以下 别压,净亏
几万 可以压
快到窗口上限 必须处理,考虑 /clear 换话题

用例 01-8 · --resume 列表长什么样

输入

claude --resume

输出(原文)

  Resume session
  ╭──────────────────────────────────────────────────────────╮
  │ ⌕ Search…                                                │
  ╰──────────────────────────────────────────────────────────╯
    hello-project

  ❯ add-divide-logging
    22 seconds ago · master · 690.1KB

每条会话显示四个字段:名字 · 相对时间 · git 分支 · 会话文件大小。

结论:

  • 有搜索框,会话多了靠它找
  • 名字可以自己起(--name),不起就用自动生成的(add-divide-logging 这种)
  • 状态栏里显示的 add-divide-logging 是会话名,不是 git 分支 —— 分支是 master

2026-11-17 / 2.1.318


02 键盘与交互

每天按几十次的东西,比任何参数都值钱。
来源:教程 9.1 + 官方 interactive-mode 文档。【未实测】——键位随终端和平台有差异,以输入框为空时按 ? 弹出的面板为准。


随时查键位

输入框为空时按 ? —— 【实测】在这版上没有弹出独立面板,输入框下方本来就有一行常驻提示。

【实测】底部常驻提示条(2.1.318,Windows)原文:

  ! for shell mode       double tap esc to clear input     ctrl + shift + _ to undo
  / for commands         shift + tab to auto-accept edits  alt + v to paste images
  @ for file paths       shift + up/down to change effort  alt + p to switch model
  /btw for side question ctrl + o for verbose output       ctrl + s to stash prompt
                         ctrl + t to toggle tasks          ctrl + g to edit in editor
                                                           /keybindings to customize

这一行里有两项上面没提过的:/btw(旁问)和 shift + up/down(调 effort)。


最常用的 10 个

按键 作用
Ctrl+C 中断当前操作;没任务时清空输入;再按一次退出
Esc 中断回复 / 关对话框;在权限提示上等同选 No
Esc Esc 输入框有内容→清空;输入框为空→打开 Rewind 菜单(实测,见用例 02-2)
Shift+Tab 循环切换权限模式(含 plan)
Ctrl+R 反向搜索历史输入
Ctrl+O 打开对话查看器,看工具调用细节、时间、模型
Ctrl+B 把正在跑的任务转入后台
Ctrl+L 重绘屏幕(乱码时用,不清内容)
Ctrl+S 暂存输入框内容;再按一次恢复(含光标位置)
Ctrl+D 退出(需连按两次确认)

Esc 和 Ctrl+C 的区别:Esc 只中断这一次回复;Ctrl+C 在没任务时是清空/退出。


输入框里的快捷方式

开头 作用
/ 命令或 skill 菜单
! Shell 模式:直接执行命令,输出进会话
@ 文件路径补全
?(空输入时) 快捷键面板

! 那个很实用:想跑一条命令又不想让它"理解",直接 !git status。


多行输入

方式 说明
\ + 回车 续行
Shift+Enter 换行(可能需要先跑 /terminal-setup)
Ctrl+G 或 Ctrl+X Ctrl+E 在默认编辑器里写(长提示词用这个)

写复杂提示词时用 Ctrl+G:打开你配置的编辑器,写完保存关掉就回到会话。


文本编辑(readline 那套)

按键 作用
Ctrl+A / Ctrl+E 行首 / 行尾
Ctrl+K / Ctrl+U 删到行尾 / 删到行首(可 Ctrl+Y 粘回)
Ctrl+W 向前删一个词(删路径很好用)
Alt+B / Alt+F 按词后退 / 前进
Ctrl+_ 撤销上一次输入编辑

Windows / 终端特有的坑

场景 处理
Windows 上 Shift+Tab 不生效 用 Alt+M 切换权限模式
tmux 里 Ctrl+B 被占用 连按两次 Ctrl+B 才是转后台
粘贴图片没反应 Ctrl+V 被终端拦截时用 Alt+V(Windows/WSL)
Shift+Enter 不换行 先跑 /terminal-setup
方向键翻历史不好用 用 Ctrl+P / Ctrl+N

坑

  • 键位跟终端走:同一个键在 Windows Terminal、VS Code 集成终端、tmux 里可能不一样
  • ? 面板只在输入框为空时有效
  • Esc 在权限提示上等于拒绝 —— 别以为按 Esc 是"稍后再说"
  • Ctrl+C 连按两次会退出,输入长文本时容易手滑
  • Ctrl+B 在有任务时才有效,空按没反应

实测用例

用例 02-1 · 底部常驻提示条

怎么看到:进入会话,不输入任何东西,看输入框下方。

实际内容(2.1.318 / Windows / Windows Terminal)

! for shell mode        double tap esc to clear input      ctrl + shift + _ to undo
/ for commands          shift + tab to auto-accept edits   alt + v to paste images
@ for file paths        shift + up/down to change effort   alt + p to switch model
/btw for side question  ctrl + o for verbose output        ctrl + s to stash prompt
                        ctrl + t to toggle tasks           ctrl + g to edit in editor
                                                           /keybindings to customize

结论:这一行是你这个版本最准的键位表。里面有几项文档里没写:

键 作用
/btw 旁问(不打断主线问一句)
shift + up/down 调 effort 等级
/keybindings 打开键位配置文件

注意 shift + tab 的措辞:这里写 "auto-accept edits",而我们实测按它切到过 manual ——说明它是循环切换,这行只写了其中一站。


用例 02-2 · Esc Esc 是两种行为,取决于输入框有没有字

A:输入框有字 → 连按两次 Esc → 文字被清空,没有菜单。

B:输入框为空 → 连按两次 Esc →

Rewind

Nothing to rewind to yet.

Esc to cancel

结论:

输入框 Esc Esc
有内容 清空输入
为空 打开 Rewind 菜单

两个行为都存在。 底部提示只写了前一半,容易让人以为没有 Rewind 入口。

Nothing to rewind to yet. —— 刚开的新会话还没产生检查点。


用例 02-3 · /keybindings 打开一个可编辑的 JSON

/keybindings

用系统编辑器打开 keybindings.json:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+alt+g": "command:orca-agent-view"
      }
    }
  ]
}

结论:

  1. 键位可以自己改,改的是这个 JSON。
  2. 格式是 context + "键位": "command:命令名"。
  3. 文件里已经有一条环境加进来的绑定 —— 这个文件可能被别的工具写过,改之前先看清。

用例 02-4 · ! 直接执行命令,输出进对话

输入

!git status

输出(直接出现在会话里)

On branch master
nothing to commit, working tree clean

关键观察:没有 Thought for ...。

它没有"想",这条命令是本地直接执行、把结果贴进对话的。

结论:

!command 让它执行命令
谁发起 你 它
是否经过模型 否 是
输出是否进对话 是 是
会不会被当成指令 不会,就是一段文本 会

它看到了吗——验过:紧接着问"我们刚才用 ! 跑的 git status 输出是什么",它完整复述了出来。

所以 ! 的准确定位是:

你发起执行,但它看得见结果。

适合:想看个结果、不想让它插手执行的时候。不适合:想让它完全看不见某段输出的时候——那得在 shell 里跑,别在会话里跑。


用例 02-5 · @ 的补全列表

输入 @ca(不回车)

弹出

+ calc.py
+ test_calc.py
+ .claude\
+ CLAUDE.md
+ .claude/agents\

结论:

  1. 目录也会列出来(.claude\),可以继续往下钻。
  2. 按前缀过滤,不是模糊搜索。
  3. 它的候选范围不等于"项目全部文件" —— 受忽略规则影响(本书 04 章实测过:文件选择器默认遵守 .gitignore)。

用例 02-6 · Ctrl+R 搜的是"所有会话",不只是当前

界面

Search prompts · everywhere

↑ 8m ago    开始
  7m ago    [Pasted text #1 +8 lines]
  5m ago    1245
  4m ago    /keybindings
  4m ago    A 被清空了
  2m ago    !git status
  1m ago    今天星期几
❯ 1m ago    农历几月几号

┌─────────────────────┐
│ 农历几月几号         │
└─────────────────────┘

⌕ Filter history…

三个关键点:

你看到的 含义
everywhere 跨会话搜索,不是只搜当前这个会话
相对时间(8m ago / 1m ago) 按时间倒序
[Pasted text #1 +8 lines] 粘贴的超长内容被折叠成占位符

所以 Ctrl+R 是"找回上次那句话"最快的入口,包括你在别的项目里说过的。


用例 02-7 · Ctrl+O 是"详细转录",能看到它的思考过程

界面底部

Showing detailed transcript · ctrl+o to toggle · ? for shortcuts        verbose

内容:它把整个推理过程展开给你看,包括:

  • User asks for ... —— 它对问题的理解
  • 一段 Let me think: ... 的推理
  • $c = New-Object ... —— 它准备执行的命令原文
  • 和我给的系统约束的对照("auto mode prefers Bash, but this is PowerShell-specific .NET")

结论:

我原来写的 实际
"打开对话查看器,看工具调用细节、时间、模型" 详细转录(detailed transcript):推理过程 + 完整命令 + 工具调用

底部提示叫它 verbose output,界面里叫 detailed transcript,是同一个东西。 再按一次 Ctrl+O 收起。

什么时候值得开:怀疑它"为什么这么干"的时候。代价是信息量很大,别一直开着。


还没验的

  • Alt+M(Windows 上代替 Shift+Tab)
  • Ctrl+B 转后台
  • Ctrl+T 任务清单
  • Ctrl+L 重屏

2026-11-21 / 2.1.318


03 提示词怎么写

不是"功能",但它是收益最高的一项。同一个模型,说法不同,结果差一倍。


四要素

一条能用的任务描述,包含四样:

要素 回答什么 例子
目标 要达成什么 "让 percent() 在除数为 0 时抛异常"
范围 只能动哪里 "只改 test_calc.py,不要动 utils.py"
约束 遵守什么规矩 "用文件里已有的 try/except/else 风格"
验收 怎么算完成 "跑 python test_calc.py 全绿"

缺哪一项,它就会自己补一个——而它补的往往不是你想要的。


一个真实对比

差的写法

帮我优化一下这个项目

会发生什么:它自己决定"优化"是什么意思,可能改 18 个文件,也可能什么都不改。你没法判断它做得对不对。

好的写法(这是本机真实用过的,改了 test_calc.py 7 行,没越界)

只改 test_calc.py,不要动 utils.py 和 calc.py。

给 percent() 的 whole == 0 分支补一条断言:
percent(1, 0) 应该抛 ZeroDivisionError。
用文件里已有的 try/except/else 风格写。

先给 diff,不要写入。

差别不在"礼貌",在于:范围、约束、验收都写死了。


三个高杠杆动作

1. 先问后改

先告诉我你怎么理解这个任务,别动手。

或者:

先给方案,不要写入。

这一句能省掉 80% 的返工。 它理解错了,你在它动手前就发现了。

2. 点名单

读 calc.py、utils.py 和 test_calc.py 三个文件。

它不会保证读全你的仓库。 测试文件、配置文件、接口定义,都要点名。

3. 给它验收方式

改完跑 python test_calc.py,把输出贴给我。

你给它一个能自我验证的方式,它就会自己发现错。 不给,它就只能"觉得对"。


按任务类型的模板

修 bug

现象:divide(1, 0) 抛的是 ZeroDivisionError,但接口文档说要返回 None。
范围:calc.py 的 divide()。
要求:先复现,再改,改完跑 python test_calc.py。
不确定的地方先问我,不要自己猜业务规则。

关键是"先复现" ——不先复现就改,等于猜。

加功能

给 calc 加一个 power(a, b) 函数。
要求:参数校验和现有函数一致(is_number 守卫、TypeError)。
测试写在 test_calc.py,用文件里已有的风格。
先给方案和函数签名,我确认后再写。

重构

重构 describe(),把结果拼装抽成一个私有函数。
硬约束:公共行为不能变,所有现有测试必须继续通过。
先跑一遍测试确认基线全绿,再动手。

"先跑一遍基线" 是重构的安全带。

审查

只读审查 src/auth 目录。
不要修改任何文件。
列出:边界条件、错误处理、并发问题。每条给文件:行号。

常见反模式

反模式 会发生什么 改法
"优化一下" 它自己定义优化 说清"慢在哪、要降到多少"
"按最佳实践改" 它按它理解的实践改 说出你采用的具体规范
"顺便把测试也补了" 范围扩大,改了一堆 一次一件事
一次给 5 个任务 它做前两个就偏了 拆开,一个一验
只贴报错不贴上下文 它猜原因 给命令、目录、版本、完整报错
让它"自己看着办" 结果不可复现 不确定的列出来让你选

长任务怎么拆

阶段 你说什么 你检查什么
1 调研 "先读这几个文件,告诉我现状,别改" 它理解对了吗
2 方案 "给方案和改动清单,别写" 范围对不对
3 实施 "按方案改,只改 X 和 Y" git diff
4 验证 "跑测试,把输出贴给我" 真绿了吗
5 收尾 "写 commit message" 说清改了什么

每一阶段之间都是你的检查点。 一次跳到底,出问题你只能整体重来。


坑

  • 描述越模糊,它越会"发明需求"
  • 不说范围,它会顺手改"看起来相关"的文件
  • 不给验收方式,它说的"完成"你无法核实
  • 一次说太多事,后面的容易被吞掉
  • 别用"专业""优雅"这类词 —— 每个人理解不同,写具体行为
  • 提示词写得好,也不能替代你审 diff

实测用例

本机真实用过、有效的两条指令(都已验证结果):

补测试(结果:只改 1 个文件,1 file changed, 7 insertions(+))

只改 test_calc.py,不要动 utils.py 和 calc.py。
给 percent() 的 whole == 0 分支补一条断言:percent(1, 0) 应该抛 ZeroDivisionError。
用文件里已有的 try/except/else 风格写。
先给 diff,不要写入。

找盲区(结果:正确列出 3 个依赖函数 + 9 条未覆盖分支)

读一下这个项目里的 calc.py 和 utils.py,然后回答三件事:
1. 这个项目是做什么的
2. calc.py 依赖了 utils.py 里的哪些函数,分别用在哪里
3. 哪些函数或分支没有被 test_calc.py 覆盖到
先不要修改任何文件。

第二条的教训:第 3 问要审测试文件,但第 1 行只点名了两个源文件。它这次自己补读了测试文件——运气。应该明确写"读 calc.py、utils.py 和 test_calc.py"。


对照实验:模糊 vs 精确(实测)

同一个项目、同一个起点,两条指令,各跑一次。

A 组:模糊

帮我优化一下 calc.py

结果

指标 值
改的文件 1 个(calc.py)
增 / 删 +14 / −13
测试 仍然全绿
成本 $0.180
轮数 7

它做了什么:把 add / subtract / divide / percent 里重复的类型校验抽成一个 helper:

def _check_numbers(name, *values):
    """Raise TypeError unless every value is a number (bools excluded)."""
    if not all(is_number(value) for value in values):
        raise TypeError(f"{name}() only accepts numbers")

这个重构本身是合理的,行为没变,测试也过。

但——我要的事它没做。

B 组:精确

只改 calc.py 和 test_calc.py。
给 percent() 加校验:part 或 whole 不是有限数(nan 或 inf)时抛 ValueError。
测试用文件里已有的 try/except/else 风格补一条。
改完运行 python test_calc.py 并报告结果。

结果

指标 值
改的文件 2 个
增 / 删 +17 / −0
测试 全绿
成本 $0.189
轮数 8

实际 diff:

# calc.py
+import math
+    if not (math.isfinite(part) and math.isfinite(whole)):
+        raise ValueError("percent() only accepts finite numbers")
# test_calc.py
+try:
+    percent(float("nan"), 4)
+except ValueError:
+    pass
+else:
+    raise AssertionError('percent(float("nan"), 4) should raise ValueError')

对比

A 模糊 B 精确
改了文件 1 2
增 / 删 +14 / −13 +17 / −0
删了多少行 13 0
成本 $0.180 $0.189
它做的是 它自己定的"优化" 你要的那件事

三个结论:

  1. 成本几乎一样(​0.18 vs 0.19)。模糊不等于省钱——省的只是你打字的力气。
  2. 差别在"删改了多少"。A 组动了 27 行,你要逐行确认它没破坏行为;B 组只加了 17 行,看完就能点头。
  3. percent 的 nan 问题在 A 组里根本没被修 —— 因为它不知道你在意这个。模糊指令下,它做的是它认为的优化,不是你要的修复。

判断标准不是"它改得好不好",是"它改的是不是你要的"。


成本不是提示词质量的分水岭

两次差不多:​0.180 / 0.189。

所以"写详细一点会不会更贵"这个担心不成立——多打几十个字,换来的是一份你能一眼审完的 diff。


2026-11-21 / 2.1.318


04 改代码

让它改 → 审真实落盘内容 → 回滚。验收:能看清它到底改了什么,能一条命令退回去。


最短流程

# 0. 先有基线
git status                      # 干净最好
git status --short              # 有未提交改动就先提交或 stash

# 1. 进去让它改
claude

会话里说清楚三件事:改什么文件、改成什么样、不许碰什么。

只改 test_calc.py,不要动 utils.py 和 calc.py。
补三条断言:clamp 的 ValueError 分支、add 的第二个 TypeError 路径、format_number(-0.0)。
先给 diff,不要写入。
# 2. 审它真实写了什么(不是审它说了什么)
git diff
git diff --stat
# 3. 坏了就退
git checkout -- <file>          # ⚠️ 丢弃该文件未提交修改

三个状态,别搞混

sequenceDiagram autonumber participant 你 participant CC as Claude Code participant FS as 磁盘 你->>CC: 改 X,先给方案 CC->>FS: 读文件 FS-->>CC: 内容 CC-->>你: 展示 diff(方案) Note over 你,FS: 此刻磁盘没有变化 你->>CC: 确认 CC->>FS: 写入 你->>FS: git diff 核实
状态 有什么 没什么
它展示了方案 一段 diff 文本 磁盘没变
你批准了 一个许可 可能还没执行成功
它写完了 磁盘变了 可能改错、可能越界

只有 git diff 能回答"到底改了什么"。


怎么提要求才好用

差 好
"优化一下这个项目" "看 calc.py 的 percent(),边界之外返回值是否正确"
"修一下 bug" "divide(1,0) 应该抛 ZeroDivisionError,现在抛了什么?先别改"
"加个测试" "给 clamp 的 low > high 分支加一条断言,用文件里已有的 try/except 风格"

通用做法:先让它只回答、不动手,确认理解对了再让它改。


审 diff 要看三件事

  1. 改了哪些文件(git diff --stat 一行就够)
  2. 有没有越界(说了只改 A,它动没动 B)
  3. 改的内容对不对(不是"看着像对的")
git diff --stat
git diff -- <file>

回滚

git diff                          # 先看清要丢什么
git restore <file>                # Git 2.23+ 的现代写法,等价于下面那条
git checkout -- <file>            # ⚠️ 丢弃这个文件的未提交修改,不可恢复
git stash                         # 或者:先存起来
git stash pop                     # 需要时再拿回来
git reset --hard HEAD             # ⚠️ 丢弃全部未提交修改

验证

  • git diff --stat 只有你预期的文件
  • 看完 diff 你能用自己的话说明改了什么
  • 测试/构建通过(如果项目有)
  • 能一条命令退回去

坑

  • auto 模式下它不问就改 → 学习期用 --permission-mode manual
  • 它提示"已修改"不等于真写入了 → 永远用 git diff 确认
  • 复制出来的 diff 可能被终端截断 → 别拿贴过来的 diff 当审查材料
  • 它可能顺手"优化"你没让它动的文件 → 明确说"不要动 X",然后 --stat 检查
  • git checkout -- 会连你自己没提交的改动一起冲掉 → 用前 git diff
  • 它说"测试通过"不代表测试真跑过 → 自己跑一遍

实测用例

用例 02-1 · 让它补测试,并且先不动手

输入

只改 test_calc.py,不要动 utils.py 和 calc.py。
补三条断言:clamp 的 ValueError 分支、add 的第二个 TypeError 路径、format_number(-0.0)。
先给 diff,不要写入。

它的输出:先回答了"-0.0 算不算 bug"这个问题(给了 3 条理由),然后展示了一份 diff,然后停下来等确认。

结论:把"先给方案、别写入"写进指令,比事后拦截有效得多。


用例 02-2 · 确认它到底改了几个文件

输入

git diff --stat

输出

 test_calc.py | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

结论:一行就能看出"只改了 1 个文件、加了 19 行"。这就是审查的第一步,比读整份 diff 快。


用例 02-3 · 证明测试不是摆设:故意改坏

输入

python -c "import pathlib; p=pathlib.Path('utils.py'); s=p.read_text(encoding='utf-8'); p.write_text(s.replace('if low > high:', 'if low > high and False:'), encoding='utf-8')"
python test_calc.py

输出

Traceback (most recent call last):
  File "...\test_calc.py", line 26, in <module>
    raise AssertionError("clamp(5, 10, 0) should raise ValueError when low > high")
AssertionError: clamp(5, 10, 0) should raise ValueError when low > high

结论:红了。 一个永远绿的测试等于没有测试——改坏代码它还不红,就说明它是假的。


用例 02-4 · 回滚

输入

git checkout -- utils.py
python test_calc.py

输出

all assertions passed

结论:红了→绿了。这就是完整闭环:改坏 → 看红 → 回滚 → 看绿。

⚠️ 前提是 utils.py 有基线提交。没有基线,这条命令会丢掉你所有未提交的改动。

2026-11-14 / 2.1.318


用例 02-5 · 一次完整的"三个状态"实测

任务

只改 test_calc.py,不要动 utils.py 和 calc.py。
给 percent() 的 whole == 0 分支补一条断言:percent(1, 0) 应该抛 ZeroDivisionError。
用文件里已有的 try/except/else 风格写。
先给 diff,不要写入。

① 它展示方案后、你还没批准时

git status --short
git diff --stat
(两个都空)

② 你批准、它写入之后

git diff --stat
 test_calc.py | 7 +++++++
 1 file changed, 7 insertions(+)
python test_calc.py
all assertions passed

结论:这就是"方案 → 批准 → 落盘"的实证。

  • 批准前两个命令都空,证明"展示 diff"确实没碰磁盘
  • 批准后只有 1 个文件变,证明它没越界去动 utils.py / calc.py

这一步的价值:你不是"相信"它守规矩了,你是看到了。


用例 02-6 · 它展示的 diff ≠ 落盘的真实 diff

它展示的头部

@@ -65,6 +65,14 @@

git diff 实际给出的头部

@@ -66,6 +66,13 @@

差异:起始行差 1,新增行数差 1(展示说 8 行,实际 7 行)。

结论:差这几行不影响这次改动对错,但它证明了一件事——

它展示的 diff 是"方案描述",不保证和真实落盘逐字节一致。

所以:批准前拿展示的 diff 做初判可以;做最终结论必须用 git diff。如果拿展示里的行号去做别的判断(比如"它改的是第 65 行,那第 64 行应该没动"),就偏了。

2026-11-14 / 2.1.318


用例 02-7 · 三种回滚方式的实测对比

先制造改动

Add-Content calc.py "`n# stash test line"
git status --short
 M calc.py

① git stash(可逆)

Saved working directory and index state WIP on master: ca9ecb0 feat: log divide() ...
git status --short     # 空
git stash list
stash@{0}: WIP on master: ca9ecb0 feat: log divide() ...

② git stash pop(取回)

On branch master
Changes not staged for commit:
        modified:   calc.py
Dropped refs/stash@{0} (f8faac5d32881431134e3a49de4753bc5f244d06)
git status --short
 M calc.py

③ git restore calc.py(不可逆)

git status --short
(空)

结论

命令 可逆吗 用在哪
git stash ✅ 可 pop 回来 临时收起改动,先干别的
git stash pop — 拿回来(并从栈里删掉)
git restore <file> ❌ 直接丢 确认不要了
git checkout -- <file> ❌ 同上 老写法,等价

顺序原则:先 stash(可逆),确认没用了再 restore(不可逆)。反过来就找不回来了。


用例 02-8 · 工作区干净时 git stash 不会报错

git stash
No local changes to save
git stash pop
No stash entries found.

结论:这两条都不是错误,是正常提示。

排查 git 问题时注意:git stash 没有任何输出/提示"没改动",说明你根本没改东西——不要以为 stash 失败了,先去 git status 确认。

2026-11-17 / 2.1.318


用例 02-9 · 给 stash 加备注,以及它会收走什么

加备注

git stash push -m "命名测试"
Saved working directory and index state On master: 命名测试
git stash list
stash@{0}: On master: 命名测试

结论:-m 的备注会显示在 stash list 里。

但取回仍然只能按索引:

git stash pop stash@{0}
git stash apply stash@{0}    # 取回但保留在栈里

名字只是给人看的标签,不是标识符。 存多了没有备注就会长这样,分不清哪条是哪条:

stash@{0}: WIP on master: ca9ecb0 feat: log divide() ...
stash@{1}: WIP on master: ca9ecb0 feat: log divide() ...

一个踩到的坑:stash 默认收走全部未提交改动

那次只改了 calc.py,但 .gitignore 也有未提交改动。git stash pop 之后:

Changes not staged for commit:
        modified:   .gitignore
        modified:   calc.py

两个都回来了——包括我根本没想 stash 的那个。

只想存指定文件:

git stash push -m "只存 calc.py" -- calc.py

-- 后面是路径。不加它,就是"全部收走"。

结论:git stash 的默认范围是工作区里所有未提交改动,不是"你刚才改的那个文件"。多文件项目里尤其容易误伤。

2026-11-17 / 2.1.318


05 权限

管住它能干什么。验收:知道当前是哪个模式、知道被拦时看哪里。


六种模式

官方取值:default、acceptEdits、plan、auto、dontAsk、bypassPermissions。

manual 是 default 的别名(v2.1.200+)。claude --help 里列的是 manual,两个值都能用。
官方原文:"claude --help does not list every flag" —— --help 是常用子集,不是完备清单。

下表按 --help 的写法列出(本机 2.1.318):

值 行为 什么时候用
manual 每次编辑/命令都问你 学习期、不熟的项目、危险操作
auto 不问,直接干(有安全分类器,危险操作仍会被拦) 流程已跑熟、改动范围可控
acceptEdits 编辑自动通过,命令仍问 大量改代码但命令要盯
plan 只出计划,不动手 先看方案
dontAsk 不问;需要征询的一律拒绝,只跑预先放行的 无人值守脚本
bypassPermissions 跳过全部检查 ⚠️ 只在无网络沙箱里用

default = manual:同一个模式的两个名字。

dontAsk 的确切语义、以及 auto 分类器的拦截与回退规则**【待核实】**(审核意见与官方文档描述存在出入,以你版本的 /help 和官方 permission-modes 页为准)。

claude --permission-mode manual

会话里按 Shift+Tab 循环切换,状态栏显示当前模式。

默认模式在哪改

【实测】/status → Config 页里有两项直接相关:

Default permission mode          Manual
Use auto mode during plan        true
项 意思
Default permission mode 新会话默认用哪个模式(本机是 Manual)
Use auto mode during plan plan 模式下用不用 auto 的分类器去判断只读命令

想永久改成 plan 或 acceptEdits,就在设置文件里写 permissions.defaultMode(见 08),或者用 Config 页改。


两种确认框,选项不一样

Manual 模式下会弹两种框,别把编号当口诀背,每次看清它问的是什么。

A. 执行命令时(4 个选项)

This command requires approval

Do you want to proceed?
❯ 1. Yes
  2. Yes, and don't ask again for: python -
  3. Yes, and switch to auto mode · auto mode handles these prompts for you
  4. No
选项 真实后果
1 只批准这一次 ✅
2 这一类命令以后都不问
3 顺手把你切回 auto 模式 ⚠️
4 拒绝

B. 修改文件时(3 个选项)

 Do you want to make this edit to test_calc.py?
 ❯ 1. Yes
   2. Yes, and switch to accept edits (auto-approve file edits and common file commands) for this session (shift+tab)
   3. No
选项 真实后果
1 只批准这一次 ✅
2 本次会话自动接受所有文件编辑
3 拒绝

通用规则

每次看清它在问什么,选"只这一次"那个。

不要因为上次"选 3 是陷阱"就以为所有框都这样——这两个框里 3 的含义完全相反(一个是"切 auto",一个是"拒绝")。


配置 allow / deny 规则

不用每次都弹框,可以把"哪些命令永远放行、哪些永远禁止"写进设置文件。

【实测】 规则语法有效,已验证:

{
  "permissions": {
    "allow": ["Bash(git status)", "Bash(git diff:*)"],
    "deny": ["Read(./.env)"]
  }
}

放在 .claude/settings.local.json,新开会话后生效。

下面是最小形态:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(python test_calc.py)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(rm -rf:*)"
    ]
  }
}

规则怎么匹配:精确 vs 通配

这是最容易配错的地方,实测踩过。

写法 匹配什么
Bash(git status) 只匹配 git status 这一条,一字不差
Bash(git status:*) 匹配 git status 开头的一整串
Bash(git diff:*) 匹配 git diff ...

实测案例:配置里写了 Bash(git status),但它实际执行的是

git status && echo "---" && git status --porcelain=v1 -uall

这是复合命令,精确匹配失败,照样弹框。

规则是精确匹配的。 想要"这类命令都放行",必须写 :*。

放哪

文件 作用范围 谁看得到
~/.claude/settings.json 你所有项目 只有你
.claude/settings.json 这个项目 进仓库,团队共享
.claude/settings.local.json 这个项目 + 只有你 不要进仓库
托管设置(企业) 全组织 用户改不了

优先级:托管 > 命令行 --settings > 项目本地 > 项目共享 > 用户。列表类配置(allow / deny)是合并的,不是覆盖。

还有第三种规则:ask

【实测】/permissions 里确实有一页叫 Ask,说明 allow / ask / deny 三态并存。

求值顺序【待核实】:deny → ask → allow。也就是说 deny 优先级最高,ask 次之,allow 最低。

这条很重要:你以为 allow 放行了,只要 deny 或 ask 命中,仍然会被拦或仍会弹框。

会话里查看和修改

/permissions

【实测】它打开的是一个七页面板:

Permissions  Recently blocked  Allow  Ask  Deny  Auto mode  Workspace
页 内容
Allow 当前放行的规则(本机:Bash(git diff:*)、Bash(git status))
Ask 会强制询问的规则
Deny 会直接拒绝的规则(本机:Read(./.env))
Recently blocked 最近被拦的操作 —— 排查"为什么它做不了某件事"先看这里
Auto mode auto 模式的额外规则:Soft allow / Soft deny / Hard deny + 环境描述文档
Workspace 当前工作区目录,可加目录

这一页比翻 JSON 文件快得多,而且能直接看出规则有没有被读进去。

一个容易忽略的副作用

【待核实】命令确认框里选 "Yes, and don't ask again for: ..." 时,它可能把这条规则持久化写进 .claude/settings.local.json,而不只是作用于本次会话。

所以选这一项之后,建议 git status 看一眼本地设置文件有没有变化——你以为的"这一次",可能变成了"以后都不要问"。


被拦住了怎么办

按顺序看:

  1. 状态栏是哪个模式? plan 模式下它根本不动手。
  2. 弹的是哪个权限请求? 看清楚它要读/写哪个文件、跑哪条命令。
  3. 有没有 deny 规则命中? 查 .claude/settings.json 和 settings.local.json。
  4. 是不是沙箱/工作区信任问题? -p 模式会跳过工作区信任对话框。
  5. 还不行:claude --debug 看它到底卡在哪一步。

验证你的规则真的生效

# 1. 配一条 deny,比如 Read(./.env)
# 2. 在会话里让它读那个文件
#    期望:被拒绝,而不是读到
# 3. 配一条 allow,比如 Bash(git status)
#    期望:不再弹框

规则配错最常见的症状是"以为禁了,其实没禁" —— 一定要实际试一次。


坑

  • auto 关掉的不是"它会不会乱改",是"你什么时候知道它改了"
  • 确认框选项 3 会切回 auto,而且不会明显提醒你
  • deny 优先于 allow,冲突时以禁为准
  • 项目级配置会覆盖用户级(同一项),团队配置可能悄悄改掉你本地的习惯
  • --dangerously-skip-permissions 是真的全跳过,只该在没有网络的沙箱里用
  • 权限管的是"允不允许做",不是"做得对不对" —— 放行不等于结果正确

实测用例

用例 03-1 · Manual 模式的确认框长什么样

场景:manual 模式下,它要跑一条命令

输入(界面上给出的原文)

This command requires approval

Do you want to proceed?
❯ 1. Yes
  2. Yes, and don't ask again for: python -
  3. Yes, and switch to auto mode · auto mode handles these prompts for you
  4. No

结论:

  • 选 1 = 只批准这一次
  • 选 2 = 这一类以后都不问
  • 选 3 = 顺手把你切回 auto 模式 ← 陷阱
  • 选 4 = 拒绝

学习期只选 1。选项 3 最阴,因为它在你做"批准"这个动作时,偷偷改了你的模式。


用例 03-2 · 切到 manual 后状态栏

输入:在会话里按 Shift+Tab,循环到手动模式

输出:状态栏显示 manual mode on

结论:切换只影响会话,不改文件。想开机就是 manual,用启动参数:

claude --permission-mode manual

2026-11-14 / 2.1.318


用例 03-3 · 改文件时的确认框(只有 3 个选项)

输出(界面原文)

● Update(test_calc.py)
───────────────────────────────────────────
 Edit file
 test_calc.py
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
assert percent(-1, 4) == 0, "percent must clamp negative values to 0"

+try:
+    percent(1, 0)
+except ZeroDivisionError:
+    pass
+else:
+    raise AssertionError("percent(1, 0) should raise ZeroDivisionError")
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 Do you want to make this edit to test_calc.py?
 ❯ 1. Yes
   2. Yes, and switch to accept edits (auto-approve file edits and common file commands) for this session (shift+tab)
   3. No

结论:这是编辑确认框,和"命令确认框"不是同一个东西。

  • 只有 3 个选项,没有 auto mode 那一项
  • 选项 2 是"本次会话自动接受编辑",不是"以后永远"

别背编号:命令框里 3 是"切 auto"(陷阱),编辑框里 3 是"拒绝"。看清它问什么再选。


用例 03-4 · deny 规则生效(Read(./.env))

配置

{ "permissions": { "deny": ["Read(./.env)"] } }

输入

读一下 .env 文件,告诉我 SECRET_TOKEN 的值

输出(原文)

.env 读不了——它所在的目录被权限设置拒绝了,Read 工具直接返回
「File is in a directory that is denied by your permission settings」。

我不会绕过这个限制(比如改用 shell 的 cat/Get-Content 去读)。

它还补了三条建议:让你自己用 ! 前缀跑命令、让你检查 permissions.deny、以及提醒「如果这个 token 是真在用的凭据,贴进对话就等于把它放进了会话记录里」。

结论:

  1. deny 生效了,拒绝理由是明确的。
  2. 它没有尝试绕过 —— 这一点不能想当然,要测。
  3. 它会反过来提醒你泄露风险,这是好行为,但不能依赖。

注意:deny 只拦了 Read 工具。如果它改用 Bash 执行 Get-Content .env,是另一条路径——这次它主动没这么做,不等于规则拦住了。


用例 03-5 · allow 规则没生效:精确匹配 vs 通配

配置

{ "permissions": { "allow": ["Bash(git status)", "Bash(git diff:*)"] } }

输入

跑一下 git status,告诉我工作区状态

它实际要执行的命令

git status && echo "---" && git status --porcelain=v1 -uall

结果:仍然弹了确认框。

为什么:Bash(git status) 是精确匹配,只认 git status 这一条。实际要跑的是复合命令,匹配失败。

正确写法:

{ "allow": ["Bash(git status:*)", "Bash(git diff:*)"] }

结论:

规则是精确匹配的。想要"以某命令开头的一整串",必须写 :*。

同时看见:确认框里 2. Yes, and don't ask again for: git status * —— 它自己也知道该加通配,说明界面上的"不再询问"写的就是 git status *。


用例 03-6 · 加上 :* 之后,确认框消失了

改动(只改一个字符)

- "Bash(git status)"
+ "Bash(git status:*)"

结果:同样的提问,不再弹确认框,直接执行。

结论:

同一个命令,() 里加不加 :*,是"每次都问你"和"直接放行"的区别。


但同一段回答里,它编了一句话

配置生效之后,它回了一句:

注:仓库的主分支是 main,但目前检出的是 master,两者在这个快照里没有差异需要处理。

实测核查:

git branch -a
git remote -v
* master
(无远程)

只有 master,没有 main,也没有任何远程。

main 是它凭空补出来的——大概因为"大多数仓库的默认分支叫 main"这个先验。

结论:

权限配成功 ≠ 输出可信。

这句话无害,所以你根本不会去查。但如果它把同样的自信用在一个你会据此改代码的地方,代价就不一样了。

这类错误最难防:不是答错题,是在一个已经答对的地方,顺手加了一句编的。

2026-11-17 / 2.1.318


06 计划模式与回退

动手前先看方案;动完手能退回去。


一、计划模式(Plan Mode)

它就是一个权限模式,不是另一套系统。在这个模式下它只研究、只出方案,不编辑源文件。

什么时候用

  • 改动面大、跨多个模块,先看路线再决定做不做
  • 核心逻辑、生产代码,需要一份能审的方案
  • 你自己还没想清楚需求

四种进入方式

Shift+Tab                      # 循环切到 plan
/plan explore the auth flow    # 只对这一条提示用
claude --permission-mode plan  # 整个会话从 plan 开始
{ "permissions": { "defaultMode": "plan" } }

VS Code 扩展用另一个键:claudeCode.initialPermissionMode。

它能做什么

能做 不能做
读文件、检索、跑只读命令 编辑源文件(批准前会被拦)
产出可审阅的方案 绕过你的批准自己开工

Ctrl+G 可以把方案在编辑器里打开改。

实际形态:取决于你装了哪些 skill

【实测,2026-11-17,2.1.318】本机进入 plan 模式后,让它"给 divide 加日志",它做了这些:

● Skill(superpowers:brainstorming)          ← 装了插件才有
● Explore(...)                               ← 后台子代理读代码
→ 问卷问两个决策,还带 Review 步骤            ← 那个 skill 的行为
→ 计划写进 C:\Users\rainio\.claude\plans\calc-py-divide-stateful-galaxy.md
→ 三选一批准:auto / 手动批准 / 告诉它改什么

必须分清哪些是内置、哪些是插件加的:

现象 来源
生成计划 内置
计划文件写在 ~/.claude/plans/(不在项目里) 内置
最后的批准闸门 内置
问卷式逐条澄清 brainstorming skill 加的
先开 Explore 子代理读代码 内置(未在干净环境验证)

这一点很重要:装了 skill 之后,它做事的方式会变,而不只是多一个 /命令。
同一个任务在别人的机器上可能直接出计划,在你这台会先被问一轮。
看到流程和教程不一样时,先想"我装了什么插件"。

批准界面的陷阱

【实测】计划出来后的确认框:

❯ 1. Yes, and use auto mode
  2. Yes, manually approve edits
  3. Tell Claude what to change

选项 1 又是 auto mode。 和权限确认框同一个套路——把最省事的放第一个。

学习期选 2,让每一步都过你的眼。

一个反直觉的规则

主会话在计划模式时,子代理也被强制留在计划模式——哪怕它的 frontmatter 写了 permissionMode: acceptEdits。

目的很明确:防止"把活派出去"绕过计划审批。

(例外:agent team 的队友。)


二、回退(Rewind)

Esc Esc

输入框为空时连按两次 Esc → 打开回退菜单。

输入框有内容时,Esc Esc 是清空草稿。

/rewind

回退对话和代码。适合"刚才那几步走错了,整体退回去"。

它和 git 的区别

/rewind git checkout
回退范围 对话 + 代码 只有文件
依赖 Claude Code 自己的检查点 git 提交
适合 刚才那轮探索白做了 已提交的内容要撤销

两个都要会。 rewind 管"这一轮聊错方向了",git 管"这次改动不要了"。


验证

  • Shift+Tab 能切到 plan,状态栏显示
  • plan 模式下让它改文件,被拦住
  • Esc Esc 能打开回退菜单
  • /rewind 之后,代码和对话都回到了之前的状态

坑

  • plan 模式不是"只读模式":它能跑 shell 命令探索,只是不改源文件
  • 计划不是文件:官方没有"生成 plan.md"的约定,方案就在对话里
  • /rewind 和 git 是两套账:rewind 回退的代码改动,git 未必知道
  • 回退前先看清菜单里的选项 —— 有的只回退对话,有的连代码一起回退
  • 别在 plan 模式里等它动手 —— 它不会动,这是设计

实测用例

用例 17-1 · plan 模式跑一遍完整流程

输入

把 calc.py 里的 divide 函数加上日志

它做了什么

读 4 个文件、列 1 个目录、跑 1 条命令
→ 问卷问 2 个决策(日志方式 / 记录内容),带 Review 步骤
→ 计划写进 C:\Users\rainio\.claude\plans\calc-py-divide-cryptic-church.md
→ 三选一批准

批准时选 2(手动批准每次编辑),随后它问了 3 次

● Update(calc.py)       ← 加 import logging + logger
● Update(calc.py)       ← 改 divide 函数体
● Update(test_calc.py)  ← 加 basicConfig

结果

git diff --stat
 calc.py      | 11 ++++++++++-
 test_calc.py |  4 ++++
 2 files changed, 14 insertions(+), 1 deletion(-)

结论:范围守住了——计划说改两个文件,实际就两个,没碰 README.md。


用例 17-2 · 计划的"预期输出"也会错

计划里写的

预期:stdout 仍输出 all assertions passed,stderr 多出 4 行日志

实际跑出来 6 行

INFO calc: divide(10, 4)
INFO calc: divide -> 2.5
INFO calc: divide(1, 0)
WARNING calc: divide: cannot divide by zero (a=1)
INFO calc: divide(2, 3)          ← 计划没想到
INFO calc: divide -> 0.6667      ← 计划没想到
all assertions passed

为什么多两行:describe(2, 3) 内部调用了 divide()。计划正文提到过这件事,但列预期输出时漏掉了这条调用路径。

结论:

计划里的"预期输出"同样是主张,不是事实。

而且这比"它编造一个结论"更难防——因为计划整体是对的,只是漏了一条路径。你只有真跑一遍才发现。

实际验证命令(区分 stdout / stderr 才看得出来):

python test_calc.py 2>&1 | Tee-Object -Variable out

用例 17-3 · 一个可以争论的取舍

它把 logging.basicConfig(...) 写进了 test_calc.py,理由是"练习项目没有别的入口,basicConfig 幂等,不影响 all assertions passed"。

这在真实项目里会被 review 打回:生产模块不该依赖测试文件来完成日志配置。

结论:它对这个项目做的判断,不等于通用做法。看到类似的"为了方便"的实现,问一句:换个项目还成立吗?

2026-11-17 / 2.1.318


07 上下文

它为什么忘事、怎么让它记住、怎么让它读对文件。


它为什么忘

每一轮对话,它只能"看到"窗口里装得下的东西。对话越长、读的文件越多,早期的内容越容易被挤掉或压缩。

这不是记性差,是窗口满了。

现象 真实原因
越聊越笨、开始重复 上下文里堆了太多无关内容
忘了你半小时前定的约定 那段被压缩或挤出去了
找不到某个文件 它根本没读过那个文件

我该怎么办

我要 命令
看上下文被什么占了 /context
看当前加载了哪些 memory 文件 /memory
开一段全新的对话 /clear
压缩,保留要点继续 /compact(有成本,见 01-7)
看模型/端点/认证 /status

判断标准:当你发现自己在重复解释已经说过的背景,就该 /compact;当话题完全换了,就 /clear。


CLAUDE.md:让它每次都记得的约定

CLAUDE.md 是项目背景和约定的说明文件,开新会话时会自动读进来。

放哪

位置 作用
./CLAUDE.md(项目根) 项目约定,进仓库,团队共享
~/.claude/CLAUDE.md 你个人的全局偏好,所有项目生效

写什么

只写"每次都需要知道"的东西,别写成 README:

# 项目约定

## 技术栈
Python 3.14,零第三方依赖,测试用纯 assert 不用 pytest。

## 命令
- 测试:`python test_calc.py`
- 格式化:无

## 约定
- 一律用 `python`,不要用 `python3`
- 公共函数必须带 docstring
- 不要修改 `utils.py` 的公开签名

## 禁止
- 不要提交任何 `.env` 或密钥

生成初稿

会话里用 /init,它会扫一遍项目生成一份草稿,然后你改。


进阶:@ 导入、子目录、自动记忆

【待核实】以下机制来自官方文档与审核意见,本机未逐条验证。

用 @path 把一个文件导进来

CLAUDE.md 里可以引用别的文件:

@docs/architecture.md
@.claude/rules/testing.md

适合把长约定拆到多个文件里组织。

但"拆文件"不会省上下文

这是最容易误解的一点。

@ 导入是加载时展开的——被导入的内容照样进上下文窗口,一点没少。

真正省上下文的是按需加载:

机制 何时进入上下文
根目录 CLAUDE.md 每次会话都读,计入 Memory files
子目录 CLAUDE.md 不计入 Memory files;需要时它自己去找(实测见下方 04-6)
Skill 只有被调用时才展开
@ 导入的文件 跟着父文件一起进,加载时展开

所以:拆文件是为了组织,不是为了省 token。 想省 token,靠的是"让它别读"。

关于子目录 CLAUDE.md 的准确说法(实测修正过的):

它不会在启动时被计入 Memory files,但也不保证"读到该目录的文件才加载"。
实测中,只是问了一句"项目里有几个代号",它就主动搜到了 pkg/CLAUDE.md。

结论:别指望它自动带上,也别指望它不读。 要它遵守某条约定,在提示词里点名那个目录。

自动记忆(auto memory)

Claude Code 会自己维护一份跨会话的记忆,典型形态是 MEMORY.md 加若干条事实文件。

你知道吗 在哪看
它记住了什么 /memory
占了多少上下文 /context 里的 Memory files 那一行

注意:自动记忆和 CLAUDE.md 是两套东西——前者是它自己写的,后者是你写的。它自己记的东西同样可能记错,用之前核对一下。


最重要的一条:它不会保证读全你的仓库

它按任务主动探索,但探索范围不保证。

实践规则:

重要文件要明确点名。 测试文件、配置文件、接口定义、数据结构,都要在指令里写出来。

读 calc.py、utils.py 和 test_calc.py 三个文件,然后回答……

只说"读一下这个项目",它可能只挑几个看着相关的。


验证

  • /context 能看到占用情况
  • 新开会话,它能主动提到 CLAUDE.md 里的约定
  • 你点名三个文件,它确实读了三个(看它引用的行号/内容)

坑

  • CLAUDE.md 不等于"项目已被读取" —— 它只是提前知道了约定
  • CLAUDE.md 写太长会挤占上下文 —— 实测:覆盖架构+命令+约定约 806 tokens,这个量级没问题;上万就该拆到多个文件
  • /init 会直接写文件,不弹确认 —— 写完先 git status 看一眼
  • CLAUDE.md 在 /context 里算 Memory files,不算 Messages —— 用 /memory 查
  • /clear 不可恢复
  • /compact 会丢细节,关键结论先落盘
  • 换目录启动就换了一套上下文,--continue 续的是当前目录的会话
  • 窗口大不等于好:塞太多无关文件反而更容易答偏

怎么验证配置真的生效:金丝雀法

这是本篇最该带走的方法,后面验证 Hooks、MCP、Skill 用的是同一招。

问题:你让它"说测试命令是什么",它答对了——但它可能是从 README.md 读到的,不一定读了 CLAUDE.md。你分不清。

办法:往配置里放一条别处绝对没有的信息,然后在新会话里问。

## 项目代号
Bluefin

然后新开会话问"这个项目的代号是什么"。

结果 说明
答出 Bluefin 配置真的被读进来了
答不出 / 说不知道 没生效。位置不对、文件名不对,或不在读取范围

三个要点:

  1. 必须是别处没有的信息。 用 README 里已有的内容当金丝雀,等于没用。
  2. 必须新开会话。 /clear 之后它可能还留着工作区快照,不够干净。
  3. 答的时候让它说来源。 问"这个信息你是从哪看到的",它答"来自项目根目录的 CLAUDE.md",才算完整闭环。

实测用例

用例 04-1 · /context 到底显示什么

场景:刚 /clear 完,还没聊几句

输入

/context

输出(原文)

Context Usage
⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   Opus 5
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   claude-opus-5
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   42.6k/1m tokens (4%)

Estimated usage by category
⛁ System prompt: 3.5k tokens (0.4%)
⛁ System tools: 34.8k tokens (3.5%)
⛁ Skills: 4.2k tokens (0.4%)
⛁ Messages: 160 tokens (0.0%)
⛶ Free space: 924.4k (92.4%)
⛝ Autocompact buffer: 33k tokens (3.3%)

Auto-compact window: 1m tokens
Skills · /skills
└ 43 skills · 4.2k tokens

结论:三个值得注意的数字:

数字 说明什么
System tools: 34.8k 你还没说话,工具定义就占了近 35k。这是固定成本
Messages: 160 tokens 你刚才说的话,占比极小
Autocompact buffer: 33k 留给自动压缩的余量,不是可用空间

最反直觉的一条:你真正常用的"对话"在总量里微乎其微,大头是系统工具和技能定义。所以——

  • 觉得慢/贵,往往不是因为聊得多,而是因为读进来的文件多
  • Skills: 4.2k / 43 个 说明装太多扩展会长期占用上下文

用例 04-2 · /clear 清掉了什么、没清掉什么

输入

/clear
我们上一轮聊了什么?

输出(节选)

这个会话刚执行过 /clear,之前的上下文已经被清空了……
……除非你愿意让我去翻本地的会话记录文件
(C:\Users\rainio\.claude\projects\D--Workspace-cc-demos-hello-project\ 下的 transcript)

……从工作区快照能看到的只是一些痕迹、不是记忆:当前分支 master,
notes.md 有改动、output/ 未跟踪,最近两次提交是围绕 utils.py 的测试……

结论:

被清了 没被清
当前会话的对话历史 磁盘上的会话日志文件
它对刚才聊过什么的记忆 工作区状态(git、文件改动)
CLAUDE.md 里的项目约定

最后一格最容易忘:/clear 之后它仍然知道 CLAUDE.md。因为它每次会话都会重新读。


用例 04-3 · 它区分"记忆"和"推断"

同一个回答里它明确说:"工作区快照能看到的只是一些痕迹、不是记忆。"

结论:/clear 之后它可能说出"你刚才好像在改测试"——那是从 git 状态推断出来的,不是记得。

判断方法:如果它能说出"具体聊了什么、你原话是什么",那是记忆;如果只能说"有什么文件变了、最近几个提交",那是推断。

2026-11-14 / 2.1.318


用例 04-4 · /init 生成了什么

输入

/init

输出:直接生成了一个 CLAUDE.md(git status 显示 ?? CLAUDE.md,未跟踪),没弹写入确认。

生成的内容(节选)

## What this repo is
A deliberately tiny teaching/demo project for Claude Code practice — not production
code. ... `README.md` lists test-coverage gaps that are **intentional** demo
material; don't "fix" them without being asked.

## Commands
python test_calc.py                  # whole suite
python output\probe_short_circuit.py # traces add() TypeError line numbers

- Use `python`, never `python3` — the WindowsApps `python3` alias on this machine is broken.
- No pytest, no requirements.txt, no build or lint step ...

## Architecture
- utils.py — leaf helpers, no internal dependencies
- calc.py — imports all three from utils
- test_calc.py — imports both modules and exercises them

### Behavioral contracts
- is_number intentionally rejects bool ...
- divide rounds to 4 decimal places; percent clamps to [0, 100] ...
- describe substitutes "division skipped: b is zero" ...
- format_number(-0.0) returns "0". This is a deliberate, test-locked decision ...

结论:

  1. /init 的质量取决于你项目里已有多少可读的东西。 它读了 README.md 和 notes.md,所以架构、命令、约定、甚至"哪些坑是故意的"全都写对了。
  2. 它主动写了"别做什么" —— don't "fix" them without being asked。这条最值钱:以后它不会热心地把你故意留的测试盲区填掉。
  3. 它没问权限就直接写文件了 —— 以为 /init 只是"看看"的话会意外。写完记得 git status 看一眼。
  4. 语言是英文,虽然项目文档是中文。想用中文就自己改,模型两种都读。

用例 04-5 · 金丝雀验证 + 它在上下文里算哪一类

第一步:往 CLAUDE.md 加一条别处没有的信息

## 项目代号
Bluefin

第二步:/exit,然后新开一个会话

第三步:问

这个项目的代号是什么?测试命令是什么?

输出

- 项目代号:Bluefin
- 测试命令:python test_calc.py(用 python,不要用 python3)

这两项都来自项目根目录的 CLAUDE.md。

结论:命中。它不但答对,还主动说明了来源——这才是完整闭环。

第四步:/context

43.5k/1m tokens (4%)

⛁ System prompt: 3.5k tokens (0.4%)
⛁ System tools: 35k tokens (3.5%)
⛁ Memory files: 806 tokens (0.1%)      ← 新出现的类目
⛁ Skills: 4.2k tokens (0.4%)
⛁ Messages: 33 tokens (0.0%)
⛁ Free space: 923.5k (92.4%)

Memory files · /memory
└ 1 file · 806 tokens

两个结论:

  1. CLAUDE.md 在 /context 里算 Memory files,不算 Messages。 所以"聊得少"不代表"上下文小"——配置和工具是另一笔账。
  2. 一份覆盖架构 + 命令 + 约定 + 注意事项的 CLAUDE.md ≈ 806 tokens。 这就是"别写太长"的量化标准:几百 token 完全没问题,上万才该拆。

查它加载了哪些 memory 文件:

/memory

用例 04-6 · 子目录 CLAUDE.md 到底什么时候加载

材料

CLAUDE.md          → ## 项目代号  Sparrow-7
pkg/CLAUDE.md      → ## 子目录代号  SubCanary-Owl
pkg/thing.py       → 一个 handle_ping() 函数

三次 /context,Memory files 一次没变

① 基线          849 tokens / 1 file
③ 问完代号后    849 tokens / 1 file
⑤ 读过 pkg/ 后  849 tokens / 1 file

但第 ② 步它就已经知道 pkg/CLAUDE.md 了

当时只问了一句、完全没提 pkg:

这个项目一共有几个代号?全部告诉我,包括子目录里的

它答出两个,并给出精确位置 pkg/CLAUDE.md:9。状态栏显示它 searched for 2 patterns, read 2 files, listed 1 directory, ran 2 shell commands。

结论:

  1. 子目录 CLAUDE.md 不计入 Memory files —— 全程 1 file,说明不是启动时全量塞进来的。
  2. 但它也不遵守"读到该目录文件才加载" —— 这次一次都没读 pkg/thing.py,照样加载了。
  3. 真实机制是"它判断相关就去搜"。

所以怎么用:

想让它守某条约定 做法
全局都遵守 放根目录 CLAUDE.md
只在某个目录用 放子目录 CLAUDE.md,并在提示词里点名那个目录
必须 100% 生效 两个都写,或者写进 settings.json 的规则

别指望"放进去它就会遵守" —— 它可能搜到,也可能不搜。


一个测量陷阱:Messages 的数字在抖

同一轮里三次读数:

① Messages: 1.2k
③ Messages: 148
⑤ Messages:(这一行直接没显示)

Messages 的数值不适合做精确对比。 用它看"量级"可以,用它算"省了多少"会得出错误结论。

Memory files 反而稳定(849 三次一致),因为它是静态文件的大小。

2026-11-17 / 2.1.318


08 配置与环境变量

设置文件放哪、优先级怎么排、哪些环境变量是你在设、哪些是 Claude Code 自己注入的。
状态:文件位置与优先级来自本次审校;具体键名【未实测】,以官方 settings 文档为准。


一、设置文件放哪、谁覆盖谁

文件 范围 进仓库吗
托管设置(企业下发) 全组织 用户改不了
命令行 --settings <file-or-json> 这一次 —
.claude/settings.local.json 本项目 + 只有你 不要进
.claude/settings.json 本项目 + 团队 进
~/.claude/settings.json 你所有项目 不进

优先级:托管 > 命令行 > 项目本地 > 项目共享 > 用户。

关键差异:

  • 标量类(model、outputStyle):上层覆盖下层,只留一个
  • 列表类(permissions.allow):合并,不是覆盖

这条最容易踩:你在用户级 allow 里放行了某命令,项目级 deny 仍然能禁掉它(deny 优先)。


二、常用的几个键

【未实测,以官方 settings 文档为准】

{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(git status)", "Read(./src/**)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "plan"
  },
  "env": {
    "MY_VAR": "value"
  },
  "hooks": { },
  "enabledPlugins": [ ],
  "statusLine": { },
  "apiKeyHelper": "/path/to/script",
  "cleanupPeriodDays": 30
}
键 作用
model 默认模型
permissions allow / deny / defaultMode
env 注入给它执行的命令的环境变量
hooks 见 17
enabledPlugins 启用哪些插件
statusLine 底部状态栏显示什么
apiKeyHelper 用脚本动态取密钥,而不是写死在文件里

env 里放的是给它跑的 shell 用的环境变量,不是给 Claude Code 进程本身的。两者别混。


三、环境变量:分清"你设的"和"它自己设的"

【实测】本机 env: 里匹配 ANTHROPIC|CLAUDE 的变量名:

你在设的(配置类)

变量 作用
ANTHROPIC_BASE_URL 换端点(你这台就靠它走自定义服务)
ANTHROPIC_AUTH_TOKEN 对应的认证令牌
ANTHROPIC_API_KEY 官方 API Key(和上面二选一)
ANTHROPIC_MODEL 指定模型
ANTHROPIC_DEFAULT_OPUS_MODEL / _SONNET_MODEL / _HAIKU_MODEL 把 opus/sonnet/haiku 这些别名映射到你自己的模型

这解释了为什么 /context 里显示 Opus 5,而实际请求可能打到别的模型上。别名是别名,不是模型本身。

它自己注入的(运行期,别手动设)

变量 说明
CLAUDECODE / CLAUDE_CODE_ENTRYPOINT 标记"我在 Claude Code 里运行"
CLAUDE_CODE_SESSION_ID 当前会话 ID
CLAUDE_CODE_CHILD_SESSION 子会话标记
CLAUDE_CODE_MESSAGING_SOCKET / _TOKEN 内部通信

这些是它启动子进程时塞进去的,你手写进 .env 只会干扰它。

行为开关(想关某功能时用)

变量 作用
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 关掉后台任务(Ctrl+B 也没了)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 关非必要遥测流量
CLAUDE_CODE_SAFE_MODE=1 等同 --safe-mode,关掉所有自定义配置
CLAUDE_CODE_SIMPLE=1 等同 --bare,极简模式

四、怎么确认配置真的生效

想知道 命令
现在连的哪个端点 claude doctor,或 /status 的 Status 页
某个设置文件被读了吗 claude --debug 看加载过程
配置互相打架了 claude --safe-mode 启动,逐个排除
当前所有配置项的值 /status → Config 页

/status 是面板,不是一行输出

【实测】它打开的是五个标签页:

Settings  Status  Config  Usage  Stats
页 内容
Status 版本、会话名/ID、cwd、认证方式、端点 URL、模型、配置来源
Config 一份完整的当前配置清单(每项的值)
Usage 本次会话的花费、代码改动行数、按模型的 token 拆分
Stats 历史统计(会话数、总 token、活跃天数、连续天数)

Config 页是最有用的——书上讲了那么多配置项,这一页直接告诉你"你现在的实际值是什么"。

【实测】本机 Config 页节选:

Auto-compact                                true
Idle compaction                             true
Thinking mode                               true
Rewind code (checkpoints)                   true
Default permission mode                     Manual
Worktree base ref                           fresh
Use auto mode during plan                   true
Respect .gitignore in file picker           true
Model                                       Default (recommended)
Teammate mode                               in-process
Output style                                default
Editor mode                                 normal

排查配置类问题,先打开这一页,比翻文件快。

--safe-mode 是最快的排查手段:它关掉 CLAUDE.md、skills、插件、hooks、MCP、自定义命令和代理,但管理员策略仍生效。


五、安全

  • 别把 token 写进放进仓库的文件:.claude/settings.json 会进 git,令牌放环境变量或 apiKeyHelper
  • .claude/settings.local.json 加进 .gitignore
  • env 里的值会出现在子进程环境里,任何能读环境变量的程序都看得到
  • 团队共享的 settings.json 可能悄悄改掉你本地的习惯 → 用 git diff 审它

坑

  • 列表合并、标量覆盖 —— 以为自己覆盖了,其实是合并
  • deny 优先于 allow
  • 项目级会盖掉用户级,换个项目习惯全变
  • ANTHROPIC_DEFAULT_*_MODEL 会让 /context 显示的模型名和实际请求的对不上
  • 别手动设 CLAUDE_CODE_* 运行期变量
  • --safe-mode 会让你的配置"看起来没生效",排查时先确认没开它

实测用例

用例 08-1 · env 到底注入到哪

配置(.claude/settings.json,项目共享级)

{
  "env": {
    "CANARY_SRC": "from-project-settings"
  }
}

验证(新开会话后)

! echo $CANARY_SRC
from-project-settings

结论:

  1. env 会注入到 Claude Code 启动的所有子进程里——包括 Bash 工具和 ! 模式。
  2. 所以工具执行时能读到这些变量,不是只对模型可见。
  3. 反过来:不要在这里放密钥,除非你接受它出现在每个子进程的环境里。

用例 08-2 · 三层优先级:本地 > 项目 > 用户

第一步:项目级 + 项目本地级,两个不同的值

文件 值
.claude/settings.json(项目共享) from-project-settings
.claude/settings.local.json(项目本地) from-local-settings

结果

! echo $CANARY_SRC
from-local-settings

→ 本地覆盖共享。

第二步:删掉项目本地那一层

// settings.local.json 里移除 env

结果

! echo $CANARY_SRC
from-project-settings

→ 逐级回退,不是"有本地文件就整体忽略共享文件"。

第三步:三层同时存在

层级 值
用户 ~/.claude/settings.json from-user-settings
项目 .claude/settings.json from-project-settings
项目本地 .claude/settings.local.json (已移除)

结果

! echo $CANARY_SRC
from-project-settings

→ 项目级赢用户级。

完整优先级(实测)

项目本地  >  项目共享  >  用户

书里原来写的完整链是「托管 > 命令行 > 项目本地 > 项目共享 > 用户」。
前两档(托管、命令行)没验,后三档已实证。


一个方法论教训:别把"它读文件的结果"当成"命令输出"

第三步第一次验证时,它的回答是:

CANARY_SRC is set to from-project-settings — it comes from the untracked
.claude/settings.json, which only contains: ...

这是它读了配置文件之后的推断,不是 echo 的输出。

两者结论巧合一致,但方法错了。

要求它贴"原始输出",而不是"解释这个值是什么":

! echo $CANARY_SRC
from-project-settings        ← 这才是证据

结论:

验证环境变量时,要看到命令打印的那一行。
它"读了文件告诉你是哪个值"和"变量真的生效了",是两件事。


顺便踩到的坑:-p 里调不动 Bash

想在 -p 里自动验证,试了:

claude -p "运行 echo $CANARY_SRC 并把原始输出贴出来" `
  --permission-prompts none --allowedTools "Bash"

两次都被权限拒绝:

命令没有执行:echo $CANARY_SRC 需要审批,而本会话没有审批通道,因此被自动拒绝了。

即使往 allow 里加了 Bash(echo:*) 也没用。

【待核实】 Bash(echo:*) 这类带参数的通配规则,对含 $ 的命令是否匹配,需要单独验证。

目前可行的办法:在交互会话里用 ! 跑,不要指望 -p 自动验环境变量。


还没验的

  • 托管设置(企业下发)的优先级
  • 命令行 --settings 的优先级
  • 具体键名的完整清单(outputStyle、statusLine、enabledPlugins 等)
  • .claude/settings.local.json 是否真的被 git 忽略(已由 .gitignore 保证)

2026-11-21 / 2.1.318


09 模型与成本

快不快、贵不贵,是每天都要面对的两件事。


我要换模型

/model

会话里切换,不丢当前输入。

命令行:

claude --model sonnet
claude --model opus

【实测】--help 原文:可以给 fable / opus / sonnet 这类别名,也可以给完整模型名。

别名不等于模型。 你这台机器设了 ANTHROPIC_DEFAULT_OPUS_MODEL 等变量,opus 实际会映射到你自己配置的模型。/context 里显示的名字反映的是别名。


我要它更用力 / 更省

claude --effort low        # 省钱省时
claude --effort high       # 更认真
claude --effort max        # 最贵

【实测】--help 里取值:low / medium / high / xhigh / max。


主模型挂了怎么办

claude --fallback-model sonnet

【实测】--help:默认模型过载或不可用时自动切换,可以逗号分隔多个按顺序试。


我要看花了多少

方式 内容
/usage 用量与限额
/cost 别名,等同 /usage
/status → Usage 页 本次会话的详细账目
/status → Stats 页 历史统计
-p --output-format json 每次调用的 total_cost_usd

/status 的 Usage 页长什么样

【实测】

Session

Total cost:            $0.55
Total duration (API):  1m 41s
Total duration (wall): 8m 20s
Total code changes:    104 lines added, 1 line removed
Usage by model:
    claude-haiku-5-5:  611 input, 169 output, 640 cache read ($0.0002)
       claude-opus-5:  21.9k input, 8.7k output, 447.9k cache read ($0.55)

三个值得注意的:

  • 按模型分开计费 —— 主模型 $0.55,小模型只花了 $0.0002
  • cache read 是主要 token 来源(447.9k),但它比 input 便宜得多
  • wall 远大于 API —— 8m20s 里只有 1m41s 在真正调用,其余是你在读、在想、在按批准

Stats 页是长期账本

【实测】

Favorite model: deepseek/de…    Total tokens: 3.5b
Sessions: 46                    Longest session: 4d 20h 35m
Active days: 15/35              Longest streak: 7 days
Input 93.4m · Output 15.1m · Cache read 3.4b · Cache write 0

实测成本(本机,2026-11-14)

任务 耗时 成本
-p "只输出四个字" 约 10 秒 —
-p "说明 percent() 的作用" --output-format json 12.7 秒 $0.110793
-p "说明 divide 的作用" --output-format json 20.9 秒 $0.046828
同一问题再跑一次 约 20 秒 $0.028219

结论:单次调用几美分到一毛;同一问题重复问,成本不是线性的(缓存会让第二次便宜)。


设上限

claude -p "..." --max-budget-usd 0.50

三个要知道的限制(【待核实】,来自官方 cli-reference 与审核意见):

  1. 它是客户端估算,可能超限 —— 留 20% 余量
  2. 子代理的花费计入
  3. 续接会话的历史花费不计入

决策表

你在干什么 建议
试错、探索、写草稿 低 effort + 便宜模型
正式改代码、审查 默认或高 effort
批量脚本 一定设 --max-budget-usd
大任务分多轮 中途用 /usage 看一眼

坑

  • 别为了省钱把 effort 降到测不出问题 —— 省下的钱可能不够你 debug
  • 批量任务不设上限 —— 跑飞一次可能比一个月订阅贵
  • /cost 是别名,文档里可能只写 /usage
  • 模型别名会被环境变量重定向,别拿 /context 的显示当实际模型
  • 重复问同一件事比你想的便宜(缓存),但换个说法就不是同一个请求了

实测用例

见 05-6 的延迟/成本表,以及本篇上面的成本实测。两次 JSON 输出里都能拿到:

{ "total_cost_usd": 0.046828, "usage": { "input_tokens": 5215, "output_tokens": 185 } }

10 脚本与非交互

在管道、脚本、CI 里用它。验收:一条命令能拿到结果,能判断成功失败。


最短用法:-p

claude -p "解释一下 calc.py 里 add() 做了什么"

-p / --print = 打印结果就退出,不进入交互界面。适合管道和脚本。

# 管道喂输入
git diff | claude -p "审这段 diff,只列风险点,不要改代码"

# 结果存文件
claude -p "总结这个项目的目录结构" > output.md

常用参数

【实测】claude --help 里的说明:

参数 用途
-p, --print 打印结果并退出
--output-format <fmt> text(默认)/ json / stream-json,仅配合 -p
--json-schema <schema> 让输出符合指定 JSON Schema,仅配合 -p
--allowedTools <tools...> 放行指定工具,如 "Bash(git diff:*)"、Edit
--disallowedTools <tools...> 禁止指定工具
--permission-mode <mode> manual / auto / acceptEdits / plan / dontAsk / bypassPermissions
--permission-prompts <t> host(默认)/ none,-p 下由谁回答权限请求
--max-budget-usd <amt> 花钱上限,仅配合 -p
--model <model> 指定模型,如 sonnet / opus / 完整名
--add-dir <dirs...> 额外允许访问的目录
--settings <file> 用指定的设置文件

结构化输出

claude -p "列出所有未覆盖的分支" --output-format json

拿到的是可直接 ConvertFrom-Json 的结构,不是给人读的文本:

$r = claude -p "..." --output-format json | ConvertFrom-Json
$r.result

想强制字段结构就用 --json-schema:

claude -p "检查 calc.py 有没有明显 bug" --json-schema '{"type":"object","properties":{"bugs":{"type":"array","items":{"type":"string"}}},"required":["bugs"]}'

CI / 脚本里的写法

# 只给读权限,不给改
claude -p "审查这次改动,只输出问题清单" `
  --allowedTools "Read" "Bash(git diff:*)" `
  --permission-mode plan `
  --max-budget-usd 0.50

三条原则:

  1. 只放行必需的工具,别图省事全放。
  2. 设花钱上限(--max-budget-usd)。
  3. 用 plan 或只读工具,让它在 CI 里别改东西。

验证

  • claude -p "只输出四个字:流水不腐" → 打印 流水不腐 并回到提示符
  • 管道能进去:"print(1+1)" | claude -p "这段输出什么" → 2
  • --output-format json 能被 ConvertFrom-Json 解析,字段可读
  • 端到端脚本:diff → JSON → Markdown 报告(见用例 05-7)

坑

  • -p 会跳过工作区信任对话框(官方说明:非交互模式下跳过)。只在你信任的目录里用。
  • -p 模式下设置文件校验失败会被静默忽略,不弹错误。配置没生效先怀疑这个。
  • --output-format、--json-schema、--max-budget-usd 只对 -p 有效,交互模式里传了没用。
  • 退出码不等于结果正确:进程成功退出只说明它跑完了,不说明答案对。
  • 管道里它会读到意外内容:确认你喂的是什么,别把密钥管道进去。
  • CI 里默认别给写权限,需要它改代码的场景要单独设计

实测用例

用例 05-1 · 最简调用

输入

claude -p "只输出四个字:流水不腐"

输出

流水不腐

结论:exit=0,打印结果后直接退出,不进入交互界面。


用例 05-2 · JSON 输出,以及一个"不是每次都出现"的坑

输入

claude -p "用一句话说明 calc.py 里 percent() 的作用" --output-format json

第一次实测(2026-11-14 上午)

[claude-code:unrecognized_model] {"model":"deepseek-flash[1m]","query_source":"sdk"}
{"duration_api_ms":12710,"stop_reason":"end_turn",...,"is_error":false,"num_turns":3,...}

第二次实测(同一天晚上)

{"duration_api_ms":20968,"stop_reason":"end_turn",...,"modelUsage":{"claude-opus-5":{...}},"costBasis":"list",...}

没有那行警告了。

结论:第一行是 stderr 的警告,只在走自定义模型路由时出现;换成官方模型就没有。两次的 JSON 里 modelUsage 的键不同,能直接看出来。

所以准确说法是——--output-format json 可能被 stderr 污染,取决于你当时连的后端。

对策不需要判断,直接加就行(成本为零):

claude -p "..." --output-format json 2>$null | ConvertFrom-Json

用例 05-3 · 干净的 JSON 解析

输入

$r = claude -p "用一句话说明 utils.py 里 clamp 的作用" --output-format json 2>$null | ConvertFrom-Json
$r.is_error
$r.num_turns
$r.total_cost_usd
$r.result

输出

False
3
0.054068
`clamp(value, low, high)` 把 `value` 限制在闭区间 `[low, high]` 内:小于下界返回下界,
大于上界返回上界,区间内原样返回;若 `low > high` 则抛 `ValueError`。

结论:2>$null 之后就能正常解析。几个常用字段:

字段 意思
result 最终答案文本
is_error 这次调用有没有出错
num_turns 它内部转了几轮
total_cost_usd 这次花了多少钱
usage.input_tokens / output_tokens 令牌用量

用例 05-4 · 成本是真实存在的

实测:同样两个简短问题,一次 $0.110793,一次 $0.054068(2026-11-14,含一次缓存读取)。

结论:单次调用不是免费的。批量跑脚本前,先设上限:

claude -p "..." --max-budget-usd 0.50

用例 05-5 · 管道输入:把文字喂给它

输入

"def f(x):
    return x * 2

print(f(3))" | claude -p "这段代码输出什么?只给答案"

输出

6

结论:| 左边的内容真的进了它的输入。这条比"喂 git diff"更适合验证管道——它不需要读文件、不需要调工具,所以不会因为权限或工具调用而变慢。

管道能做什么:git diff / 日志片段 / 报错信息 / 命令输出,都能直接送进去。


用例 05-6 · 它到底有多慢(实测)

任务 耗时 成本
-p "只输出四个字" 约 10 秒 —
-p "说明 percent() 的作用" --output-format json 12.7 秒 $0.110793
-p "说明 divide 的作用" --output-format json 20.9 秒 $0.046828
同一个问题再跑一次 约 20 秒 $0.028219

结论:单次 -p 调用是 10–20 秒起步,不是"卡住了"。

判断标准:

  • 有输出、有动画 → 在跑,等它
  • 60 秒以上完全无反应 → 大概是卡在权限上(-p 模式没有界面回答确认框)

成本也在几美分到一毛之间浮动,批量跑之前一定设上限:

claude -p "..." --max-budget-usd 0.50

2026-11-14 / 2.1.318


用例 05-7 · 端到端脚本:diff → 审查报告(已跑通)

脚本(review.ps1,完整版见附录);核心四步:取 diff → 喂给 claude → 解析 JSON → 写 Markdown。

运行

.\review.ps1 -Base "ca9ecb0~1"

输出

==> 收集 ca9ecb0~1 以来的改动
==> 交给 Claude 审查(预计 15-40 秒)
==> 已写入 review-report.md(花费 $0.216768)

报告节选(真实)

- **高** — `.gitignore` 只加了 `.env`,不覆盖 `.env.local` / `.env.production` 等变体。
- **高** — `.claude/settings.local.json` 本身被 gitignore,deny 规则不随仓库分发,
          新克隆后保护会静默失效。
- **中** — `test_calc.py` 在模块级调用 `logging.basicConfig`,导入即全局改写 root logger。
- **中** — `logger.error` 被用于输入类型校验失败这类预期错误,与除零用 WARNING 级别不一致。
- **中** — 新增的日志分支零断言覆盖。
- **低** — CLAUDE.md 末尾缺换行符。

结论:端到端跑通了,而且它挑出的第一条和第二条我自己没想到——尤其"deny 规则写在被 gitignore 的文件里,等于没分发"。


用例 05-8 · 空管道时它不会报错,会自己找活干

当时的情况:命令写错了,git diff HEAD~2 HEAD -- test_calc.py 输出 0 行。

git diff HEAD~2 HEAD -- test_calc.py | claude -p "审这段 diff,只列风险点,一句话说完" --permission-prompts none --allowedTools "Read"

它没有说"我没收到 diff",而是自己去读项目,把审查对象换成了我刚写的 review.ps1:

2>$null 会让 git diff 的失败被吞成空 diff 并静默 exit 0;git diff $Base 又看不到未跟踪文件…

三条批评全部属实。

结论:

空输入不会导致它报错,只会导致它换个目标。

而输出的质量还不差 —— 这才是危险的地方:答非所问,但答得很好。

防御:

  1. 喂之前先看输入有没有内容:$diff.Length
  2. 让它复述收到的东西:"先用一句话概括你收到的 diff 改了什么,再开始审"
  3. 空输入就 exit

用例 05-9 · PowerShell 里调用 claude -p 的三个坑

坑一:$ErrorActionPreference = "Stop" 会把 stderr 当致命错误

症状:

Write-Error: claude 退出码 1

实际 claude 是成功的,只是它往 stderr 打了一行警告。

原因:PowerShell 7 默认把原生程序的 stderr 转成错误记录,配上 Stop 就变成终止错误。

解法:

$PSNativeCommandUseErrorActionPreference = $false

坑二:多行输出直接管道给 ConvertFrom-Json 会炸

After parsing a value an unexpected character was encountered: t. Position 2

原因:$raw 是行数组,管道会逐行解析,第一行 { 就失败。

解法:

$r = ($raw | Out-String).Trim() | ConvertFrom-Json

坑三:中文输出乱码

瀹℃煡瀹?`ca9ecb0` 鐨勫疄闄?diff...

原因:外部程序按 UTF-8 输出,PowerShell 按 GBK 解码。

解法:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

补充:2>$null 别乱用在 git 上

它在用例 05-8 里批评得对:

$diff = git diff $Base 2>$null      # ❌ 连"基线不存在"这种错误也吞了

正确做法——分开处理:

$diff = git -c core.quotepath=off diff $Base 2>&1
if ($LASTEXITCODE -ne 0) { Write-Error "git diff 失败:`n$diff"; exit 1 }

2>$null 的适用场景:丢弃已知的、无害的噪音(比如 claude 那行模型警告)。

不适用:丢弃你还没见过、可能代表真失败的输出。

2026-11-17 / 2.1.318


用例 05-10 · 预算超限 = 跑完 + 非零退出

脚本报错

Write-Error: claude 退出码 1

但 JSON 明明拿到了

{
  "total_cost_usd": 0.32769,
  "stop_reason": "end_turn",
  "result": "...完整答案..."
}

原因:--max-budget-usd 0.30,实际花了 0.32769。

结论:

--max-budget-usd 不是硬中断,是"跑完再判"。
钱已经花了,答案也拿到了,只是进程以非零码退出。

所以脚本里"退出码 ≠ 0"不能一律当成"调用失败"。要区分:

情况 表现
预算超限 有完整 JSON,total_cost_usd > 预算,退出码非零
真失败 没有 JSON,或 is_error: true

修法:非零退出时也去解析 JSON,把 total_cost_usd 和预算一起报出来。

顺带:这次真实的成本是 $0.44(换了更大的预算重跑)——一个几十行的 diff,一次审查就是这么贵。批量跑必须设上限,但上限设太低只会失败,不会省钱。


用例 05-11 · 装了 Skill 会改变 -p 子进程的输出

背景:脚本提示词只说"审这段 diff,列风险点",没有任何格式要求。

第一次跑(还没装 Skill):输出是普通的 Markdown 列表。

装了 .claude/skills/review-diff/SKILL.md 之后重跑,报告变成:

## 发现

[SPARROW] 审查完成
- CLAUDE.md:43 - ...

[SPARROW] 审查完成 是那个 Skill 规定的第一行。

结论:

claude -p 子进程会加载你项目里的 Skills,并按它匹配到的那一个来做事。

后果:

  • 你在 CI 里跑 -p,输出格式可能被某个 Skill 改掉
  • 脚本里"解析纯文本/Markdown"的逻辑会突然失效
  • 同一个脚本,换台机器(没装那个 Skill)结果就不一样

防御:

claude -p "..." --disable-slash-commands

【实测】--help 里有这个参数:禁用所有 skills 和命令。在要求输出稳定的脚本里,应该加上它。


11 CI与无人值守

没有人在旁边点批准的时候,怎么让它安全地跑完。


核心矛盾

-p 模式下没有界面回答权限请求。默认行为可能是等待——那就是卡死。

所以 CI 里必须显式声明:该放行的放行,该拒绝的直接拒。


三个必设参数

claude -p "审这次改动,只输出问题清单" `
  --permission-prompts none `
  --allowedTools "Read" "Bash(git diff:*)" `
  --permission-mode plan `
  --max-budget-usd 0.50
参数 作用
--permission-prompts none 需要询问的一律拒绝,把"卡住"变成"明确失败"
--allowedTools 预放行这些工具
--permission-mode plan 只出方案,不动代码
--max-budget-usd 花钱上限

【实测】--help 原文:--permission-prompts <target> 取值 host(默认)或 none——none 表示"没人回答,任何需要询问的操作自动拒绝"。


只读任务的推荐组合

claude -p "<任务>" `
  --allowedTools "Read" "Glob" "Grep" `
  --disallowedTools "Edit" "Write" "Bash" `
  --permission-prompts none `
  --output-format json `
  --max-budget-usd 0.30 2>$null

--allowedTools 和 --disallowedTools 语义不同(【实测】来自 --help):

参数 语义
--allowedTools 预先放行,不弹框
--disallowedTools 从上下文移除该工具,它根本看不到

想真正限制能力,用 --disallowedTools;只想少弹框,用 --allowedTools。


结构化输出

$r = claude -p "..." --output-format json 2>$null | ConvertFrom-Json
if ($r.is_error) { throw "调用失败" }
$r.result
$r.total_cost_usd
字段 用途
is_error 必须检查,比退出码可靠
result 答案文本
total_cost_usd 本次花费
num_turns 内部轮数

流式(做 UI 或长任务时)

claude -p "..." --output-format stream-json --verbose --include-partial-messages

【实测】这三个参数在 --help 里都存在,且都限定 --print。


GitHub Actions 骨架(【未实测】)

name: claude-review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: |
          git diff origin/${{ github.base_ref }}...HEAD | \
          claude -p "审这段 diff,只列风险点,输出 markdown" \
            --permission-prompts none \
            --allowedTools "Read" \
            --max-budget-usd 0.50
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

要点:

  • fetch-depth: 0 否则没有完整历史,git diff 会失败
  • 令牌放 secrets,不要写进仓库
  • --permission-prompts none 必须有,否则 CI 里可能一直等

认证:claude setup-token

【实测】claude --help 子命令列表里有 setup-token:

Set up a long-lived authentication token (requires Claude subscription)

适合 CI 里用长期令牌,而不是每次交互登录。

你的环境走自定义 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN,这时通常不需要 setup-token——直接用环境变量即可。


退出码不等于答案正确

这是最容易出事的一条:

claude -p "..."
if ($LASTEXITCODE -eq 0) { "看起来没问题" }   # ❌ 不成立

退出码只说明"进程跑完了",不说明"答案对"。

正确做法:

  1. 查 is_error
  2. 抽查 result 内容
  3. 对高价值任务,人工过一遍

坑

  • 不加 --permission-prompts none 可能一直等
  • --allowedTools 不是限制,真想禁就用 --disallowedTools
  • --output-format json 可能被 stderr 污染 → 2>$null
  • 退出码 0 ≠ 结果正确
  • --max-budget-usd 是估算,可能超
  • --max-turns 在 2.1.318 的 --help 里没看到(【待核实】),别照抄
  • CI 里默认别给写权限

实测用例

【实测】单次 -p 调用耗时 10–21 秒、成本 ​0.028–0.111(见 05-6 / 24)。

端到端脚本(diff → 报告文件)尚未实测——这是本书还空着的一个验收项。


12 Git与PR

它改得越多,git 的纪律就越重要。


三条安全线

1. 开工前必须有基线

git status --short        # 应该是空的
git add .
git commit -m "baseline"

没有基线,它改坏了你只能重写文件。

2. 一个任务一次提交

不要让它连做五件事再一起提交。做不到"看一个 diff 就知道改了什么"。

3. 提交前一定看 git diff

git diff --stat     # 改了几个文件
git diff            # 改了什么

让它写 commit message

看一下当前 git diff,写一条 commit message。
格式:type: 一句话。不要提交,只给我 message。

为什么不直接让它提交:commit 是一次不可逆(好吧,可 amend)的动作,你最好先看一眼 message。

审定后自己执行:

git add <file>
git commit -m "test: cover percent() ZeroDivisionError branch"

分支

git checkout -b feature/xxx
claude

大改动一定开分支。 出问题时 git checkout main 就回到了干净状态,不用一个个 revert。

想再加一层隔离,用 worktree(见 15)。


PR

现状

【实测】本机没有安装 gh:

gh: 术语 'gh' 不会被识别为 cmdlet、函数、脚本文件或可执行程序的名称。

所以现在建 PR 只能:push 分支 → 在网页上开 PR。

想用命令行:

winget install GitHub.cli
gh auth login

让 Claude 写 PR 描述

看一下 main...HEAD 的改动,写一段 PR 描述:
- 做了什么
- 为什么这么做
- 怎么验证
不要执行任何 git 命令,只给文本。

审一个 PR

/code-review 1234          # 按编号审
/code-review main...feature/xxx

见 13 代码审查。


危险命令清单

这些命令它可能提出来,你要格外小心:

命令 后果
git reset --hard ⚠️ 丢弃全部未提交改动
git checkout -- <file> ⚠️ 丢弃该文件未提交改动
git clean -fd ⚠️ 删除未跟踪文件(包括你刚写的)
git push --force ⚠️ 覆盖远程历史
git rebase ⚠️ 改写历史,冲突时容易乱
git commit --amend ⚠️ 改写上一个提交

Rule:这些命令只在你明确知道要丢什么时执行。含糊的时候先 git stash。


.gitignore 该加什么

.claude/worktrees/
.claude/settings.local.json
.env
  • worktree 目录:别提交
  • 本地设置:可能含个人路径/令牌
  • .env:永远别提交

验证

  • 每个任务结束,git diff --stat 只有你预期的文件
  • commit message 说清了"做了什么",不是 "update"
  • 分支上的改动能干净地 rebase/merge 回主干
  • 没有把 .claude/settings.local.json、.env 提交进去

坑

  • 它可能在你没让提交时执行 git commit → 权限模式里盯住,或者明确说"不要提交"
  • git add . 会把不该进的东西也加进去 → 提交前 git status --short 看一眼
  • git reset --hard 不可恢复(除非 reflog)
  • 它写的 commit message 可能过度描述 → 你自己收敛成一行
  • 别让它碰 --force 推送
  • gh 没装就用不了 gh pr create,别照抄网上命令

实测用例

【实测】gh 未安装:

gh --version
gh: 术语 'gh' 不会被 cmdlet、函数、脚本文件或可执行程序的名称。

结论:想用 gh pr create 得先装 GitHub CLI,并 gh auth login。在此之前,PR 流程走网页。


13 代码审查

提交前先让一个没参与实现的上下文挑一遍毛病。
来源:教程 39.1 + 官方 code-review-local 文档。【未实测】。


它解决什么问题

你自己写的代码,自己看不出来问题——因为你已经"知道"自己想写什么。

/code-review 用另一个上下文(后台子代理)审当前改动,不占你的对话上下文,也不会替你改代码。


最短做法

/code-review

默认审:当前分支相对上游分支的所有提交 + 工作区未提交的改动。

分支没有上游时,对比 main,或对比上一个提交。


指定审什么

/code-review HEAD~15..HEAD        # 最近 15 个提交
/code-review main...my-feature    # 分支对比分支
/code-review abc1234^..abc1234    # 单个提交
/code-review 1234                 # 按编号审 PR
/code-review src/auth             # 只审一个目录

常用参数

/code-review high --fix           # 高强度审查,并把发现应用回工作区
/code-review --comment            # 把发现贴到 PR(GitHub 行内 / GitLab note)
/code-review --max-findings 5     # 最多报 5 条;all 全报,default 恢复默认

版本门槛:--post 需 v2.1.227+,--max-findings 需 v2.1.288+。用之前 /help 确认。


三个必须知道的事实

1. 它只读 CLAUDE.md,不读 REVIEW.md

REVIEW.md 是给 GitHub 托管审查用的。要让本地审查遵守某条规则,写进 CLAUDE.md。

2. 它跑在后台子代理里

结果以文本形式回到对话,你的主上下文不会被那一大堆文件淹没。

3. 不带 --fix 时它只报告

任何编辑都要经过你的权限模式批准。


别和这几个混了

命令 干什么
/code-review 查 bug,只报告
/review 同一个东西的别名
/code-review ultra 云端深度复核(39.2)
GitHub Code Review 托管服务,PR 自动审(39.3)
/simplify 做清理并直接应用修复
/verify 运行应用确认改动可用

/code-review 在 v2.1.147 之前就叫 /simplify,旧脚本要迁移。


怎么验证审查有效

金丝雀法:故意留一个 bug。

def divide(a, b):
    return a / b      # 少了 b == 0 的检查
/code-review
结果 说明
它指出了除零风险 ✅ 审查有效
什么都没说 要么目标写错、要么它没读到这段、要么结论不可靠

注意:它漏报不代表代码没问题,它报了也不代表一定有问题。每一条都要自己验。


坑

  • 默认目标是"当前分支 + 未提交改动",站在错的分支上会审错东西
  • --fix 会改文件,用之前先提交或 stash
  • 它不改代码 ≠ 它判断正确,报告只是"主张"
  • 不要只信它报的:它没报的地方更值得看一眼
  • 版本门槛:老版本上某些参数不存在,报错不代表功能坏了

实测用例

用例 13-1 · 先要知道它审的是什么范围

场景:新建分支 review-demo,在上面做了一处未提交的改动,然后 /code-review。

它第一句就交代了范围:

Review scope: review-demo has no upstream and main doesn't exist;
the branch tip equals master (e02317b), so the range diff is empty.
Scope is the single uncommitted change in calc.py (git diff HEAD).
Tests were run: they pass, so the change is not caught by the suite.

三个信息全在里面:

它说的 含义
分支没有 upstream、main 不存在 默认对比目标找不到
分支头和 master 相同 区间 diff 是空的
退回成 git diff HEAD 审的是未提交改动
Tests were run 它自己跑了测试,不是靠你告诉它

结论:

/code-review 会自己判断范围,判断结果写在第一行。
先读这一行——范围错了,后面说什么都没意义。


用例 13-2 · 抓到测试抓不到的回归

埋的 bug:divide() 的舍入从 round(a / b, 4) 改成 round(a / b, 2)。

测试结果:全绿(断言是 divide(10, 4) == 2.5,两位小数也是 2.5)。

审查报的:

calc.py:41 — divide() rounding changed from 4 to 2 decimals, silently truncating
precision (e.g. divide(1, 3) → 0.33, divide(1, 1000) → 0.0,
describe(1, 1000) renders 1 / 1000 = 0) while the docstring on line 30 and
CLAUDE.md still promise 4 decimals; test_calc.py only asserts divide(10, 4) == 2.5,
so the regression passes undetected.

一条里给了五层信息:

  1. 位置:calc.py:41
  2. 变化:4 位 → 2 位
  3. 后果:三个具体例子(divide(1,3)、divide(1,1000)、describe(1,1000))
  4. 矛盾:docstring 和 CLAUDE.md 还写着 4 位
  5. 为什么没被发现:测试只断言了 divide(10, 4)

结论:

测试和审查不是一回事。
测试验的是"你想到要测的东西",审查看的是"你改了什么"。


用例 13-3 · 第二轮多报了一条:真 bug,而且是我自己引入的

再跑一次(这次它报了 2 条):

calc.py:41 [correctness] rounding 4 → 2(同用例 13-2)
calc.py:50 [correctness] math.isfinite() 会把参数转成 float,
           large integer 输入现在抛未文档化的 OverflowError

它声称:percent(10**400, 10**400) 会抛 OverflowError。

实测验证:

python -c "from calc import percent; print(percent(10**400, 10**400))"
OverflowError: int too large to convert to float

是真的。

背景:这个 math.isfinite() 是上一轮修 nan 问题时加的(提交 e02317b)。我引入它的时候没想到大整数会被转成 float。

三个结论:

  1. 审查能抓到"修复引入的新问题" —— 这是它比测试强的地方:测试只验已知行为,审查看改动本身。
  2. 它还跨出了声明的范围 —— 声明说"审未提交改动",但它把已提交的 e02317b 也看了。
  3. 正确修法它都给了:"A fix would only apply the check to float values."

用例 13-4 · 同一条命令,两次跑出不同条数

跑次 findings
第一次 1 条(精度)
第二次 2 条(精度 + OverflowError)

同一份代码、同一条命令。

结论:审查结果不是确定性的。 它不会漏掉大问题,但不能指望跑一次就等于全审过。

实用做法:

  • 重要改动跑两次
  • 或者用 high / max 提高覆盖
  • 报告只是线索,不是结论 —— 每条都要自己验(用例 13-3 就是验出来的)

用例 13-5 · high 多抓到的第三条:检查顺序改了异常类型

第三次跑(/code-review high)报了 3 条,前两条同用例 13-2 / 13-3,第三条是新的:

calc.py:50 [correctness] e02317b 把 isfinite 检查插在 whole == 0 检查之前,
改变了 part 为 nan/inf 且分母为 0 时抛出的异常类型。

实测验证:

python -c "from calc import percent; ..."
percent(nan, 0) -> ValueError           ← 变了
percent(inf, 0) -> ValueError           ← 变了
percent(1, 0)   -> ZeroDivisionError    ← 没变

问题在哪:

if not (is_number(part) and is_number(whole)):
    raise TypeError(...)
if not (math.isfinite(part) and math.isfinite(whole)):   # ← 插在这里
    raise ValueError(...)
if whole == 0:
    raise ZeroDivisionError("whole must not be zero")    # ← 永远轮不到

part=nan, whole=0 时,第二个判断先命中,走不到除零分支。

结论:

同一个"除数为 0",因为 part 是 nan 就换了异常类型。
调用方 except ZeroDivisionError 会漏掉这种情况。

这一条的教训比 bug 本身大:

加一个检查 你以为 实际
插在中间 只是多拦一种输入 改变了已有路径的分支顺序

新增校验时,位置和内容一样重要。


三层严格度的实测对比

跑法 findings 新增的是
默认(第 1 次) 1 精度回归
默认(第 2 次) 2 + OverflowError
high 3 + 异常类型改变

默认模式漏了第三条。 而第三条是"错误处理契约被改",属于典型的生产事故来源。

结论:对"改动了错误处理/异常分支"的变更,用 high。

2026-11-21 / 2.1.318

用例 13-6 · 修复的三个问题,以及"修完要验什么"

三条 finding → 三处代码改动

# 问题 改法
1 round(a/b, 2) 精度丢失 改回 4
2 math.isfinite() 误伤大整数 只对非 int 检查
3 有限性检查插在除零之前,改了异常类型 把 whole == 0 挪到前面

修完的 diff(关键两处)

-    if not (math.isfinite(part) and math.isfinite(whole)):
-        raise ValueError("percent() only accepts finite numbers")
     if whole == 0:
         raise ZeroDivisionError("whole must not be zero")
+    for value in (part, whole):
+        if not isinstance(value, int) and not math.isfinite(value):
+            raise ValueError("percent() only accepts finite numbers")

独立验证(不看它怎么说,自己跑)

divide(1, 3)      = 0.3333
percent(10**400)  = 100.0
percent(nan, 0)   -> ZeroDivisionError
percent(inf, 0)   -> ZeroDivisionError
percent(1, 0)     -> ZeroDivisionError
all assertions passed

最重要的产出不是修复,是这三条新断言

assert divide(1, 3) == 0.3333, "divide must round to 4 decimal places"
assert percent(10**400, 10**400) == 100, "percent must accept large integers"
# percent(float("nan"), 0) 应该抛 ZeroDivisionError

测试从 54 行涨到 60 行。

结论:

审查的产出应该是"新的断言",不是"改好的代码"。
只改代码不改测试,同一个坑下次还会踩。


一条完整的闭环

造 bug
  → 测试不报(用例 13-2)
  → 审查报出来(用例 13-2/13-3/13-5)
  → 自己验证每条 finding 属实
  → 修代码 + 补断言(用例 13-6)
  → 测试变绿,坑被锁住

注意中间那步"自己验证"不能省 —— high 报的三条我全跑了一遍才确认,也才敢改。

2026-11-21 / 2.1.318

还没验的

  • --fix(把发现直接应用到工作区)
  • --comment(贴到 PR)
  • --max-findings N
  • ultrareview(云端多智能体审查)

2026-11-21 / 2.1.318


14 后台任务

npm install 跑三分钟的时候,你不想干等着。
来源:教程 9.4 + 官方文档。【未实测】。


三种"后台",别混

入口 作用 最容易搞错的地方
Ctrl+B 把正在跑的这一条命令转后台 在 tmux 里要按两次
/tasks(别名 /bashes) 查看/停止后台任务和子代理 不是 /background
/background(/bg) 把整个会话转后台 不是"把命令放后台"

网上常见的 /background npm run dev 是误传。 那是错的用法。


我要把一条命令转后台

两种方式:

  1. 直接说:"在后台运行 npm run build"
  2. 它正在前台跑的时候,按 Ctrl+B

tmux 用户连按两次 Ctrl+B —— 因为 Ctrl+B 是 tmux 的前缀键。

超时会自动转后台

前台命令超时后,它不会杀掉,而是自动转后台。

例外:以 sleep 开头的命令不会转,直接停。


我要看后台在跑什么

/tasks

它列出:后台 shell 命令 + 子代理(包括已经结束的)。

三个入口的区别:

显示什么
/tasks 后台命令和子代理
Ctrl+T 待办清单,不是后台任务
/background 把当前会话整体转后台

我要把会话转后台

/background

含义是:把这个会话变成后台 agent,我释放终端,用 claude agents 去看它。

claude agents     # 列出后台会话
claude attach <id>  # 接回来
claude logs <id>    # 看输出
claude stop <id>    # 停掉

注意 claude agents 管的是后台会话,和"子代理"不是一回事(见 08)。


关键行为

行为 说明
输出写文件 不塞进上下文,需要时它才去读
退出时清理 退出 Claude Code 会清掉后台任务
会话转后台则继续 整会话转后台时,任务继续跑
输出上限 5GB 超过自动终止
无头场景有时限 -p、云端会话里的后台命令有时限;本地交互没有

想彻底关掉后台能力:

$env:CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

关掉之后 Ctrl+B 也就没了。


什么时候该用

场景 用不用
npm install / pip install 用
全量构建、完整测试套件 用
启动开发服务器,然后继续问别的事 用
一条 2 秒的 git status 不用,转后台反而更麻烦
需要看实时输出的命令 不用,后台输出是写文件的

坑

  • tmux 里要按两次 Ctrl+B
  • /background 不是"把命令放后台",别照着网上抄
  • Ctrl+T 是待办清单,不是任务列表
  • 后台输出在文件里,想看得让它读,不是自动显示
  • 退出会话会清掉后台任务,长任务要么别退,要么用会话转后台
  • -p 和云端会话有超时限制,跑长任务前先确认

实测用例

用例 14-1 · Ctrl+B 之后你会拿到什么

场景:用 ! 起一条跑 30 秒的命令,趁它还在跑按 Ctrl+B。

提示

Command was manually backgrounded by user with ID: bgdn6q6bj.
Output is being written to:
C:\Users\rainio\AppData\Local\Temp\claude\a17498664ecf9636\dd67dd44-...\tasks\bgdn6q6bj.output

弹出的面板

Shell details

Status:   running
Runtime:  15s
Command:  ping -n 30 127.0.0.1

Output:
╭────────────────────────────────────────────────┐
│ 来自 127.0.0.1 的回复: 字节=32 时间<1ms TTL=128 │
│ ...(十几行)                                   │
╰────────────────────────────────────────────────┘
Showing 9 lines of 974 bytes

← to go back · Esc/Enter/Space to close · x to stop

四个值得记的细节:

项 值
任务 ID 形态 bg + 8 位(bgdn6q6bj)
输出落在哪 %TEMP%\claude\<会话ID>\<uuid>\tasks\<任务ID>.output
面板快捷键 x 停止 / Esc 关闭 / ← 返回
面板显示范围 只显示尾部("9 lines of 974 bytes")

结论:

  1. 输出确实写到文件里,不塞进对话上下文——所以后台跑大输出不会撑爆上下文。
  2. 面板只给尾部,想看全部得去读那个 .output 文件。
  3. x 是停止键——这个键位在底部提示条里没有,只有打开面板才看得到。

用例 14-2 · /tasks 只列后台任务,前台的不显示

场景:用 ! 起一条 ping -n 60,不按 Ctrl+B,直接 /tasks。

结果

Background

No tasks currently running

↑/↓ to select · Enter to view · Esc to close

但那条 ping 明明在跑(输出一直在刷)。

结论:

/tasks 打开的是 Background 面板,只列已经转入后台的任务。

命令状态 /tasks 里看得到吗
前台正在跑 ❌ 看不到
按过 Ctrl+B、还在跑 ✅ 看得到
已经跑完的后台任务 ❌ 不显示(实测:两个任务都结束后,面板回到 "No tasks currently running")

所以 /tasks 不是"任务历史",是"当前活着的后台任务列表"。

任务结束后要回看,只能去读那个 .output 文件(见用例 14-3)。

所以:

  • 它不是"所有任务的列表",是"后台任务列表"
  • 前台命令想被管理,必须先 Ctrl+B

界面自己也提示了:前台命令跑着的时候,输出区会显示 (ctrl+b to run in background)。


用例 14-3 · 输出文件里有什么面板看不到的东西

面板给你的(Ctrl+B 后打开的那个):

Status:   running
Runtime:  26s
Output:   ...(9 行)
Showing 9 lines of 1.5KB

实际文件:

dir "$env:TEMP\claude\<会话ID>\<uuid>\tasks\*.output"
bgdn6q6bj.output    1701 字节   ← 第一次那个 30 秒的
bnotsqkj1.output    3171 字节   ← 第二次那个 60 秒的
wc -l bnotsqkj1.output     # 69 行
tail -3 bnotsqkj1.output
   最小 = 0ms,最长 = 0ms,平均 = 0ms

[exited with code 0]

结论:

面板 文件
只显示尾部 9 行 全文(69 行)
Status: running(当时) [exited with code N]
看不到退出码 退出码在最后一行

最重要的一条:

后台任务的成功/失败,看 .output 文件末尾的 [exited with code N]。

面板的 Status 只反映"当时"的状态,任务结束后面板就关掉了,你没法回看。

所以后台任务的正确用法:

  1. Ctrl+B 转后台,记下任务 ID
  2. 干别的事
  3. 需要时去看 %TEMP%\claude\<会话>\<uuid>\tasks\<ID>.output
  4. 看最后一行确认退出码

三个"后台"的真实区别(更新版)

入口 作用 实测状态
Ctrl+B 把当前这条命令转后台,给出任务 ID + 输出文件路径 ✅ 已验证
/tasks 打开 Background 面板,只列已转后台的 ✅ 已验证
/background 把整个会话转后台(释放终端) ❌ 未测

最容易搞错的:以为 /tasks 是"看所有任务"。它不是——前台运行的不显示。

第二容易搞错的:以为面板里的 Status 就是最终结果。最终结果在文件的最后一行。

还没验的

  • Ctrl+T(任务清单,和 /tasks 是不是一回事)
  • /background(整个会话转后台)
  • 后台任务结束后 /tasks 里显示什么
  • 退出会话时后台任务会不会被清掉

2026-11-21 / 2.1.318


15 Worktree

给每个会话一份独立的文件副本,互不覆盖。
状态:-w/--worktree、--tmux 两个参数【实测】来自 claude --help;具体行为【未实测】,依据官方 worktrees 文档与教程 35.4。


它解决什么问题

你想同时做两件事:一个会话改功能,一个会话修 bug。但在同一个目录里,两边会互相覆盖文件。

Worktree = 同一个 git 仓库、两份独立的工作目录。

同一个目录开两个会话 用 worktree
文件 共用,互相覆盖 各自一份
分支 只能在一个分支上 各自一个分支
git 历史 共享 共享(同一个 .git)
依赖/构建产物 共享 各自重装

一句话:文件隔离,历史共享。


最短做法

cd "D:\Workspace\your-project"
claude --worktree feature-auth     # 或 -w feature-auth

在另一个终端用不同的名字再跑一次,就得到第二个隔离会话。

先把 worktree 目录加进忽略:

Add-Content .gitignore "`n.claude/worktrees/"

关键参数

参数 作用
-w, --worktree [name] 为本会话建 worktree(不给名字会自动生成,如 bright-running-fox)
--tmux 为这个 worktree 开一个 tmux 会话(必须配合 --worktree)
claude rm <id> 删后台会话,在安全时连同它的 worktree 一起删

从 PR 创建(# 要加引号,否则被当成注释):

claude --worktree "#1234"

默认行为(要知道,否则会懵)

【未实测】官方描述:

项 默认
位置 .claude/worktrees/<name>/
分支 worktree-<name>
内容 全新检出:依赖、构建产物、.env 都不在
共享 .git 目录、项目级插件、权限批准记录
未跟踪的 `.claude/skills agents

最容易踩的一点:它是全新检出。 你主目录里装好的 node_modules、跑过的构建、本地的 .env,worktree 里都没有。第一次进去要重新装一遍。


基线分支怎么选

{
  "worktree": { "baseRef": "head" }
}
值 从哪开始
fresh(默认) 远程默认分支
head 当前本地 HEAD,带上未推送的提交

不接受分支名。 想从某个既有分支起步,直接用 git worktree add。


把 .env 带过去

全新检出没有 .env。在项目根放 .worktreeinclude,语法同 .gitignore,只有同时匹配且被 gitignore 的文件才会被复制:

.env
.env.local
config/secrets.json

验证

  • git worktree list 能看到新目录
  • 新 worktree 里 git branch --show-current 是 worktree-<name>
  • 在主目录改一个文件,worktree 里那个文件没变
  • .env 按预期存在或不存在

清理:

git worktree list
git worktree remove .claude/worktrees/<name>

坑

  • 它是全新检出:依赖、构建产物、.env 都没有,第一次要重新初始化
  • 交互式启动需要工作区信任:没在该目录跑过 claude 会报错退出;claude -p --worktree 会跳过信任检查
  • --tmux 必须配 --worktree,单独用没意义
  • worktree 不是并行调度器:它只做文件隔离。Agent Teams 的 teammate 不会自动各自进 worktree,要你按文件切分
  • hook 里的 ${CLAUDE_PROJECT_DIR} 仍指向会话启动时的项目根,只有 hook 输入 JSON 的 cwd 跟随 worktree —— 写 hook 时容易错
  • claude rm 删 worktree 有前提("when that is safe"),不确定就先 git worktree list 看一眼
  • 别把 .claude/worktrees/ 提交进仓库

什么时候真的需要

场景 用不用
同时改两个功能分支 用
一边重构一边修线上 bug 用
让子代理跑大规模机械重构,不污染主工作区 用
只是想让上下文干净 不用,/clear 就够
一个会话里连续做几件小事 不用

实测用例

用例 15-1 · 手敲 git worktree add:一个 69 字节的文件就是全部秘密

输入

cd "D:\Workspace\cc-demos\hello-project"
git worktree add ../wt-manual -b wt-test

输出

Preparing worktree (new branch 'wt-test')
HEAD is now at 5e38a1f fix: restore 4-decimal rounding...

它生成了什么

git worktree list
D:/Workspace/cc-demos/hello-project  5e38a1f [master]
D:/Workspace/cc-demos/wt-manual      5e38a1f [wt-test]

关键:wt-manual\.git 是个文件,不是目录

Get-Content ..\wt-manual\.git
gitdir: D:/Workspace/cc-demos/hello-project/.git/worktrees/wt-manual
(Get-Item -Force ..\wt-manual\.git).Length
69

对比:主 .git 目录里有 12 个条目(objects、refs、HEAD、index…)。

结论:

worktree 目录里那个 69 字节的 .git 文件,就是它与主仓库的唯一连接。
删了它,worktree 就变成一个普通目录。

(注意 Windows 上 .git 带隐藏属性,Get-Item 要加 -Force 才看得到。)


用例 15-2 · 双向隔离:改一边,另一边完全无感

A:改主目录

Add-Content calc.py "# 主目录的改动"
git status --short
git -C ..\wt-manual status --short
 M calc.py        ← 主目录脏了
(空)             ← worktree 干净

B:改 worktree

git -C ..\wt-manual checkout -- calc.py
Add-Content ..\wt-manual\calc.py "# worktree 提交"
git status --short
git -C ..\wt-manual status --short
(空)             ← 主目录干净
 M calc.py        ← worktree 脏了

结论:文件、暂存区、git status 三者全部独立。 这正是 worktree 的核心价值。


用例 15-3 · 历史共享:一个目录里的提交,另一个立刻可见

在 worktree 里提交

git -C ..\wt-manual add calc.py
git -C ..\wt-manual commit -m "feat: worktree 上的提交"
[wt-test efda9d9] feat: worktree 上的提交

回主目录看

git log --oneline -1
5e38a1f (HEAD -> master) ...

看不到 efda9d9——但这不代表历史没共享。

git log --oneline -1 wt-test
efda9d9 feat: worktree 上的提交
git cat-file -t efda9d9
commit

结论:

共享什么 证据
对象库 git cat-file 直接能查到那个提交
分支引用 主目录 git branch 里能看到 wt-test
当前分支 ❌ 各自独立(master vs wt-test)

git log 默认只显示 HEAD 的历史。
"看不到"只是视野限制,不是数据不共享。 加上分支名就看见了。

git log --all --oneline --graph 能一次看到两条线分叉的样子:

* D (wt-test)
* C
| * B (master)
| * A
|/
* 5e38a1f

用例 15-4 · git branch 里的 + 是什么意思

git branch
* master
+ wt-test
标记 意思
* 当前工作区所在的分支
+ 这个分支正被另一个 worktree 检出

这条很有用:想删分支却报 "branch is checked out",看 + 就知道是哪个被占着。


用例 15-5 · claude -w 和手敲 git 的三处差异

建

claude -w wt-demo

会话里的状态栏

[Opus 5 ◑ high] │ wt-demo git:(worktree-wt-demo) │ ...
                    ↑目录名        ↑分支名
git worktree add claude -w
位置 ../wt-manual(你指定) .claude/worktrees/wt-demo(固定在项目内)
分支名 wt-test(你指定) worktree-wt-demo(自动加前缀)
git 状态 需要自己加 .gitignore .gitignore 里本来就有 .claude/worktrees/

所以 git status 是干净的 —— 在项目内部却完全不干扰。


用例 15-6 · 退出 claude -w 后会留下一个空壳

/exit 之后

git worktree list
D:/Workspace/cc-demos/hello-project  5e38a1f [master]      ← 只剩一行
git branch
* master
  worktree-wt-demo        ← 分支还在,但前面的 + 没了

但目录还在

ls -A .claude/worktrees/wt-demo
.git                      ← 只有一个指针文件,没有工作文件
cat .claude/worktrees/wt-demo/.git
gitdir: D:/Workspace/cc-demos/hello-project/.git/worktrees/wt-demo
ls .git/worktrees/
(空)
git -C .claude/worktrees/wt-demo status
fatal: not a git repository: D:/Workspace/cc-demos/hello-project/.git/worktrees/wt-demo

结论:

claude -w 退出时清掉了工作文件和 git 注册,但留下了目录和分支。

留下什么 状态
.claude/worktrees/wt-demo/ 空壳,只有悬空的 .git 指针
分支 worktree-wt-demo 还在,指向原提交
.git/worktrees/wt-demo 已删除

清理办法:

rm -rf .claude/worktrees/wt-demo
git branch -D worktree-wt-demo

注意:用 git worktree remove 不行——git 已经不认它了。得手动删目录。


还没验的

  • .worktreeinclude 复制 .env 等被忽略的文件
  • 从 PR 建 worktree(claude -w "#1234")
  • worktree.baseRef: head 配置
  • 依赖重装的实际耗时

2026-11-21 / 2.1.318


16 MCP与Skills

接外部工具、把重复流程固化成命令。


MCP:接外部系统

MCP(Model Context Protocol)让它能访问项目之外的东西:文档、工单、数据库、浏览器。

常用命令

【实测】claude mcp --help 里的真实子命令:

add [options] <name> <commandOrUrl> [args...]   Add an MCP server
add-from-claude-desktop                         Import from Claude Desktop (Mac/WSL)
add-json <name> <json>                          Add with a JSON string
get <name>                                      Get details
list                                            List configured servers
login <name>                                    OAuth 认证
logout <name>                                   清除 OAuth 凭据
remove <name>                                   Remove
reset-project-choices                           重置本项目的审批状态
serve                                           启动 Claude Code 的 MCP 服务器

【实测】官方在 --help 里给了四种写法:

# HTTP 服务器
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# HTTP + 自定义头
claude mcp add --transport http corridor https://app.corridor.dev/api/mcp --header "Authorization: Bearer ..."

# stdio + 环境变量
claude mcp add my-server -e API_KEY=xxx -- npx my-mcp-server

# stdio + 子进程参数
claude mcp add my-server -- my-command --some-flag arg1

注意那个 --:它之前是给 Claude Code 的参数,之后是给 MCP 服务器自己的参数。

一个容易踩的点

⏸ Pending approval 只针对 .mcp.json(project scope)。

claude mcp list / get 的输出里,未审批的项目级服务器会显示 ⏸ Pending approval 并且不会连接。但你自己 claude mcp add -s local 加的服务器不需要审批,直接连。

所以"我加了但没生效"的原因分两种:

scope 可能原因
local 命令/参数错了,看 claude mcp get <name> 的 Status
project 多半是没批准

作用范围

scope 存哪 谁用得到
local(默认) ~/.claude.json,按项目分节(实测) 只有你 + 当前项目
project 项目里的 .mcp.json 团队共享(可进仓库)
user 用户级配置 你所有项目

会话里看状态

/mcp

它列出已连接的服务器、每个服务器提供了哪些工具。

工具名长什么样

mcp__<server>__<tool>

所以你在权限规则里放行 MCP 工具,写的是这个名字:

{
  "permissions": {
    "allow": ["mcp__docs__search"]
  }
}

Skills:把流程固化成 /命令

一个 Skill 就是一个带 SKILL.md 的目录。

.claude/skills/review-diff/
└── SKILL.md
---
name: review-diff
description: 审查当前 git diff,只报风险,不改代码
---

审查当前未提交的改动。

步骤:
1. 运行 `git diff`
2. 逐条列出风险:空指针、边界条件、错误处理、越界修改
3. 不要修改任何文件
4. 输出格式:文件:行号 - 问题 - 建议

用户附加要求:$ARGUMENTS

调用:

/review-diff 重点关注错误处理

$ARGUMENTS 会被替换成你跟在命令后面的文字。

放哪

位置 作用
.claude/skills/<name>/SKILL.md 项目级,进仓库,团队共享
~/.claude/skills/<name>/SKILL.md 用户级,你所有项目可用

【未实测】目录约定随版本可能调整,实际以 /help 里列出的自定义命令和官方 skills 文档为准。


什么时候用哪个

你想要 用
访问外部系统(文档、工单、数据库) MCP
把你的重复流程固化成一条命令 Skill
想让它在特定时机自动做事(改完文件跑格式化) Hook(本项目未展开)
想隔离"读一大堆文件"这件事 子代理

验证

MCP

  • /mcp 里能看到服务器,状态是已连接
  • 让它用一个 MCP 工具,真的返回了外部数据
  • 断开后 /mcp 能看出未连接(不是静默失败)

Skill

  • 输入 / 能看到你的命令
  • 调用后按你写的模板输出
  • 带参数时 $ARGUMENTS 被正确替换

坑

  • MCP 没连上时它可能"装作"知道 → 先 /mcp 确认连接状态
  • .mcp.json 会进仓库,别把带密钥的配置提交上去
  • MCP 工具需要单独授权 → 权限规则里写全 mcp__server__tool
  • Skill 的 description 决定它会不会被自动选中,写得太含糊就不会触发
  • Skill 里不要让模型"自由发挥" → 步骤写死,输出格式写死,否则每次结果都不一样
  • 自定义命令各版本有增删 → 记不住就敲 /help

实测用例

用例 06-1 · 写一个 Skill,看它有没有被加载

文件

.claude/skills/review-diff/SKILL.md
---
name: review-diff
description: 审查当前未提交的改动,只列风险点,不修改任何文件
---

审查当前工作区的未提交改动。

## 步骤
1. 运行 `git diff` 看未提交的改动
2. 逐条列出风险:边界条件、错误处理、越界修改
3. **不要修改任何文件**

## 输出格式
第一行必须原样输出:[SPARROW] 审查完成
第二行开始是一个 Markdown 列表:- 文件:行号 - 问题 - 建议

## 用户附加要求
$ARGUMENTS

验证方式:新开会话,输入 /,看菜单。

❯ /review-diff              审查当前未提交的改动,只列风险点,不修改任何文件 (project)
  /code-review (review)     Review the current diff or a PR for bugs and cleanups

结论:

  1. 名字后面标着 (project) —— 说明它来自项目的 .claude/skills/,不是全局。
  2. 它和内置的 /code-review 并列出现,两个是不同的东西。
  3. description 就是菜单里显示的那句话 —— 写清楚才能被认出来。

用例 06-2 · 调用它,验证模板和 $ARGUMENTS

输入

/review-diff 重点关注错误处理和边界条件

输出(真实,节选)

[SPARROW] 审查完成

- calc.py:69 - 新增的 # skill test line 看起来是技能测试留下的内容… - 提交前删除
- calc.py:28-42 - 本次改动没有触及 divide 的错误处理与边界逻辑… - 无需处理
- calc.py:45-52 - 相邻既有缺口(非本次改动):percent 对 float('nan') / float('inf')
  不做拦截… - 可以加上 math.isfinite 检查
- calc.py:55-67 - 相邻既有缺口:describe 只用 b != 0 做除法护栏,不校验 NaN…
- calc.py:51 - whole 为极小浮点数时… 结果虽受约束,但上层无法区分"真实 100%"与"溢出被截断"

未修改任何文件。

三条验证全部通过

验什么 证据
模板被执行 第一行 [SPARROW] 审查完成
$ARGUMENTS 被替换 内容确实围绕"错误处理 / 边界条件",不是泛泛而谈
没有改文件 输出末尾自述"未修改任何文件",git status 也确认

一个值得注意的好行为:它标注了 相邻既有缺口(非本次改动) —— 把"我这次改坏的"和"本来就有的"分开了。写 SKILL.md 时明确要求这种区分,能省掉很多误伤。


用例 06-3 · 它报的问题,实测全部成立

它说 percent 对 nan / inf 不做拦截。实测:

python -c "from calc import percent, describe; n=float('nan'); print(percent(n,10)); print(percent(float('inf'),10)); print(describe(1,n))"
0
100
1 + nan = nan; 1 - nan = nan; 1 / nan = nan

结论:三条都成立。

  • percent(nan, 10) 静默返回 0(应该报错或至少警告)
  • percent(inf, 10) 静默截断成 100
  • describe(1, nan) 输出 nan

根因:is_number 用 isinstance 放行,float('nan') 和 float('inf') 都是 float,所以通过了校验;然后 clamp 把 nan 吞成了 0。

这提醒一件事:isinstance(x, float) 不等于"这是个有效数字"。NaN 和 Inf 都是 float。


用例 06-4 · 添加一个 stdio MCP 服务器

输入

claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem "D:\Workspace\cc-demos\hello-project"

输出(原文)

Added stdio MCP server fs with command: npx -y @modelcontextprotocol/server-filesystem
D:\Workspace\cc-demos\hello-project to local config
File modified: C:\Users\rainio\.claude.json [project: D:/Workspace/cc-demos/hello-project]

两个重要结论:

  1. -- 之后全归服务器,不是 Claude Code 的参数。
  2. local scope 不写项目里的 .mcp.json,而是写进用户目录的 C:\Users\rainio\.claude.json,按项目分节。

后者和直觉相反——很多人以为"项目的 MCP 配置在项目里"。只有 -s project 才写 .mcp.json。


用例 06-5 · list 和 get 长什么样

claude mcp list
fs: npx -y @modelcontextprotocol/server-filesystem D:\Workspace\cc-demos\hello-project
- ✔ Connected
claude mcp get fs
fs:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: stdio
  Command: npx
  Args: -y @modelcontextprotocol/server-filesystem D:\Workspace\cc-demos\hello-project
  Environment:

注意:没有出现 ⏸ Pending approval。

因为 Pending approval 只针对 .mcp.json(project scope) 的服务器。local scope 是你自己加的,直接连。

这修正了书里原来那句笼统的"未审批就显示 Pending approval"。


用例 06-6 · /mcp 面板里的信息比文档多

Fs MCP Server

Status:           ✔ connected
Command:          npx -y @modelcontextprotocol/server-filesystem D:\Workspace\cc-demos\hello-project
Protocol:         2026-07-28
Config location:  C:\Users\rainio\.claude.json [project: D:/Workspace/cc-demos/hello-project]
Capabilities:     tools
Tools: 16 tools

❯ 1. View tools
  2. Reconnect
  3. Disable

三个值得记的字段:

字段 意思
Protocol: 2026-07-28 MCP 协议版本 —— 说明握手成功,不是"进程起来了"
Capabilities: tools 只声明了工具能力(没有 resources / prompts)。决定了你能不能用 @ 引用资源
Config location 再次确认配置实际存在哪

工具列表还带安全标注

read_file                   read-only
write_file                  destructive
edit_file                   destructive
list_directory              read-only
search_files                read-only
move_file                   destructive

read-only / destructive 是服务器自己声明的,不是 Claude Code 判断的。权限决策时可以参考,但别当成保证。


用例 06-7 · 工具全名:mcp__fs__list_directory

/mcp 菜单里显示的是短名(list_directory),但实际调用用的是全名。

怎么可靠地拿到全名——用 stream-json 抓:

claude -p "用 fs 列出当前目录下的文件" `
  --output-format stream-json --verbose `
  --permission-prompts none 2>$null | Select-String -Pattern '"name":"mcp__'

实测结果:

mcp__fs__list_directory

结论:命名格式 mcp__<server>__<tool> 确认成立。

所以权限规则和 --allowedTools 里要写:

{ "permissions": { "allow": ["mcp__fs__list_directory"] } }

写错名字 = 规则不生效,而且不会有任何提示。

用例 06-8 · 移除 MCP,以及它到底改了什么

输入

claude mcp remove fs -s local

输出

Removed MCP server fs from local config
File modified: C:\Users\rainio\.claude.json [project: D:/Workspace/cc-demos/hello-project]

它实际做的事:把 ~/.claude.json 里对应项目节点下的 mcpServers.fs 删掉。

{
  "projects": {
    "D:/Workspace/cc-demos/hello-project": {
      "mcpServers": {}          ← 空了
    }
  }
}

没有删的:npx 包缓存、会话记录、其他配置。所以这一步安全且可逆——重新 add 就回来了。

-s 必须和 add 时一致

scope 改哪个文件
local(默认) ~/.claude.json,按项目分节
project 项目里的 .mcp.json
user 用户级配置

给错 scope 会删不到,而且不会报"你删错地方了"。

顺带:.claude.json 里还存着什么

同一个项目节点下能看到这些键:

allowedTools
enabledMcpjsonServers      ← .mcp.json 服务器的"已批准"记录
disabledMcpjsonServers
hasTrustDialogAccepted     ← 工作区信任对话框只问一次,就靠它
lastCost / lastDuration

enabledMcpjsonServers 就是 ⏸ Pending approval 背后的东西。 项目级 .mcp.json 里的服务器,你批准后才写进这里。

这也解释了为什么 local scope 不需要批准——它压根不走这个审批流程。

2026-11-17 / 2.1.318


17 Hooks

让它在特定时刻自动做事:改完文件自动格式化、跑完命令自动检查、会话结束时记录。
状态:本节全部【未实测】,依据官方 hooks 文档与 claude --help。用之前先按文末的验证方法跑一遍。


它解决什么问题

你现在的做法 有 Hooks 之后
每次它改完代码,你手动跑 black / eslint 它一改完,自动跑
它跑完 git commit,你手动补测试 提交前自动拦一道
每次会话结束,你想记一笔 自动写进日志文件

Hooks 是"确定性的自动化",不是"再让 AI 判断一次"。 它执行的是你写死的命令,模型无法改变。


最短做法

在 .claude/settings.json(项目级)或 ~/.claude/settings.json(用户级)里加 hooks 段:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black ."
          }
        ]
      }
    ]
  }
}

意思:它每次用 Edit 或 Write 改完文件后,自动跑一次 black。


关键概念(只有三个)

1. 事件(什么时候触发)

【未实测】常见事件:

事件 触发时机
PreToolUse 用工具之前(可以拦住)
PostToolUse 用工具之后(改完文件就跑)
UserPromptSubmit 你按下回车、它开始回答之前
Stop 它回答结束时
SessionStart / SessionEnd 会话开始 / 结束
PreCompact 上下文压缩之前

日常 90% 的用法是 PostToolUse。

2. matcher(匹配哪个工具)

"matcher": "Edit|Write"      // 编辑器类工具
"matcher": "Bash"            // shell 命令
"matcher": "*"               // 全部

3. command(跑什么)

你写什么它就执行什么。这是 shell 命令,不是自然语言。

⚠️ 它会以你的用户权限执行。只放你信得过的命令,别从网上抄一段就往里塞。


怎么验证它真的生效(金丝雀法)

别猜,用文件当证据。

第一步,配一个"只会留下痕迹"的 hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          { "type": "command", "command": "echo HOOK_RAN >> D:/tmp/hook_canary.log" }
        ]
      }
    ]
  }
}

第二步,让它改一个文件(manual 模式,方便你控制)。

第三步:

Get-Content D:/tmp/hook_canary.log
结果 说明
文件里有 HOOK_RAN ✅ 生效了
文件不存在 / 是空的 没生效:配置位置错了、JSON 语法错了,或事件名不对

验证完把这段 canary 配置删掉,换成真命令。


配置不生效的排查顺序

  1. JSON 合法吗? 少个逗号整个 settings.json 就废了
  2. 文件放对了吗? 项目级 .claude/settings.json,用户级 ~/.claude/settings.json
  3. 重启会话了吗? 配置改动通常要新会话才生效
  4. matcher 写对了吗? Edit|Write 大写开头,和工具名一致
  5. --safe-mode 没开吧? 它会把所有自定义配置关掉

坑

  • Hook 是同步的:跑得慢会拖慢它每一次编辑。别在里面跑全量测试
  • 失败可能被静默吞掉:命令报错不一定提示,先手动跑一遍那条命令
  • PreToolUse 返回码 2 可以阻断(【未实测】以官方文档为准),这是唯一能"拦住"的时机
  • 它是 shell 命令,不是 AI:不写死就会出错
  • 别在 hook 里放 rm、git reset 这类命令 —— 它会在你没注意时反复执行
  • --safe-mode 会禁用所有 hooks,排查配置冲突时很有用

实测用例

用例 07-1 · 第一次尝试:cmd /c 写法的 Hook 没触发

配置

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "cmd /c echo hook-fired >> hook-canary.log" }]
    }]
  }
}

结果:让它改了 utils.py(git diff --stat 确认 utils.py | 1 +),但 hook-canary.log 根本没被创建。

排查:手动执行同一条命令

cmd /c "echo hook-fired >> hook-canary.log"

输出居然是 cmd 的欢迎横幅和一个交互提示符——/c 被 Git Bash 当成路径转换掉了(MSYS 会把 /c 转成 C:\)。

结论:这条命令本身在本机就跑不通。Hook 没触发,不代表 Hook 机制坏了——先把命令单独跑通。


用例 07-2 · 换成 PowerShell 写法,Hook 正常触发

配置

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "powershell -NoProfile -Command \"Add-Content -LiteralPath 'hook-canary.log' -Value 'hook-fired'\""
      }]
    }]
  }
}

运行(注意:这是 -p 模式,不是交互模式)

claude -p "在 README.md 末尾追加一行:<!-- hook test -->" `
  --permission-prompts none --allowedTools "Read" "Edit"

结果

Get-Content hook-canary.log
hook-fired

两个结论:

  1. Hook 生效了。
  2. Hook 的触发与权限模式无关。 这次是 -p + --permission-prompts none(比 auto 更严格,任何需要询问的操作直接拒绝),hook 照样执行。

权限模式管的是"动作前问不问人",hook 管的是"动作发生后跑什么"。两件事互不影响。


用例 07-3 · --debug=hooks 在 2.1.318 上没有可见输出

claude -p "只回答 OK" --debug=hooks 2>&1 | head -12

输出只有 OK,没有 hook 相关调试信息。

结论:--debug=hooks 在当前版本没有可观测输出(至少 -p 模式下)。排查 hook 别指望它,用金丝雀(写日志文件)更可靠。


用例 07-4 · 写 hook 配置时的一个坑:别用 shell heredoc 生成 JSON

用 <<'EOF' 往 settings.local.json 写 Windows 路径时,两个反斜杠会被折叠成一个,导致 JSON 非法:

json.decoder.JSONDecodeError: Invalid \escape: line 18 column 79

可靠做法:用脚本生成,不要手拼字符串。

import json, pathlib
cfg = {"hooks": {"PostToolUse": [{"matcher": "Edit|Write",
        "hooks": [{"type": "command", "command": "powershell -NoProfile -Command \"...\""}]}]}}
pathlib.Path(".claude/settings.local.json").write_text(
    json.dumps(cfg, ensure_ascii=False, indent=2), encoding="utf-8")

通用原则:任何含 Windows 路径或嵌套引号的 JSON,都不要靠 shell 拼接。


用例 07-5 · Hook 收到的完整负载(这是最有价值的一条)

guard 脚本把 stdin 原样记进 hook-trace.log,实际收到的是:

{
  "session_id": "57fea825-...",
  "transcript_path": "C:\Users\rainio\.claude\projects\...\57fea825....jsonl",
  "cwd": "D:\Workspace\cc-demos\hello-project",
  "prompt_id": "0d1e805b-...",
  "permission_mode": "default",
  "effort": { "level": "high" },
  "hook_event_name": "PreToolUse",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "D:\Workspace\cc-demos\hello-project\calc.py",
    "old_string": "def add(a, b):
    ...",
    "new_string": "def add(a, b):
    # hook integration test
    ...",
    "replace_all": false
  },
  "tool_use_id": "call_00_..."
}

能拿到什么:

字段 用途
hook_event_name 当前是哪个事件
tool_name / tool_input 要执行的动作和完整参数 —— 拦截逻辑就靠它
permission_mode 当前权限模式
cwd 工作目录
session_id / transcript_path 用于关联会话和日志
tool_use_id 同一次调用的唯一标识

这让 Hook 能做到的事比"跑个格式化"多得多——你可以在执行前看到它打算改哪个文件的哪一段。


用例 07-6 · exit 2 真的能阻断

配置:guard 命中目标文件时 exit 2。

输入

在 README.md 末尾追加一行 <!-- blocked test -->

结果:

  • README.md 没有被修改
  • 它明确说"我没有绕过它",并给出手动执行的备选方案
  • trace 里有 1 条记录,tool_name: Edit

结论:PreToolUse + exit 2 可以真正阻断工具调用,而且这道墙对模型是可见的——它不会装作成功,也不会改用 shell 绕过去(至少这次没有)。

和权限规则的区别:

权限规则(03) Hook(PreToolUse)
判定依据 工具名 + 命令/路径模式 任意逻辑(读 JSON,看内容)
能做什么 放行 / 询问 / 拒绝 能写脚本,任何判断都行
报错可读性 标准提示 你自己写的消息

想拦"改这个文件里这一行"这种细粒度条件,权限规则做不到,Hook 可以。


用例 07-7 · 致命坑:.ps1 里的中文注释会让脚本失效

脚本本来能跑,加了中文注释后:

不能对 Null 值表达式调用方法
+ $raw = $sr.ReadToEnd()

$sr 变成了 null —— 前面的构造函数调用没成功。

原因:Windows PowerShell 5.1 读取没有 BOM 的 UTF-8 文件时按 ANSI(GBK)解码,中文注释被拆成乱码,脚本解析出问题。

修法(任选其一):

  1. .ps1 里只写英文注释(最省事,推荐)
  2. 保存为 UTF-8 with BOM
  3. 用 PowerShell 7(pwsh) 而不是 powershell

这个坑很隐蔽:脚本"看起来"没问题,编辑器里显示正常,只有 PowerShell 执行时才炸,而且报错位置指向下一行。


用例 07-8 · powershell -File 下读不到管道输入

$raw = $input | Out-String          # ❌ 空
$raw = [Console]::In.ReadToEnd()    # ❌ 空

在 -File 模式下两者都拿不到 hook 传来的 JSON。

可靠写法:

$sr  = [System.IO.StreamReader]::new([Console]::OpenStandardInput(), [System.Text.Encoding]::UTF8)
$raw = $sr.ReadToEnd()

用 -Command 而不是 -File 时,$input 是可以的;但 OpenStandardInput 两种模式都对,直接用它。


一个被推翻的结论

第一次测试时 trace 文件没生成,我一度怀疑"settings.local.json 里的 hooks 不被读取"。

实际不是。 换成能跑通的脚本后,同一条 settings.local.json 里的 hook 正常执行了。

教训:Hook 不生效时,先证明命令本身能跑,再怀疑机制。


用例 07-9 · 真实会话里 Hook 触发的完整记录

手动测试时的记录(假的路径,只验证脚本逻辑):

{"tool_input":{"file_path":"D:/x/.env"}}

真实会话产生的记录(字段齐全):

{
  "session_id": "c7b8bbaa-d6d3-4481-aabf-7f8a4e4c207d",
  "transcript_path": "C:\Users\rainio\.claude\projects\D--Workspace-cc-demos-hello-project\c7b8bbaa-....jsonl",
  "cwd": "D:\Workspace\cc-demos\hello-project",
  "prompt_id": "be0b9930-a0cc-4550-9a2c-5334d4a56c64",
  "permission_mode": "default",
  "effort": { "level": "high" },
  "hook_event_name": "PreToolUse",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "D:\Workspace\cc-demos\hello-project\calc.py",
    "old_string": "    # ...
    if not (is_number(a) and is_number(b)):",
    "new_string": "    # ...
    # ...
    if not (is_number(a) and is_number(b)):",
    "replace_all": false
  },
  "tool_use_id": "call_00_q8opd17h8m5gvpju0lvbqyg5"
}

怎么区分这两种:看路径。D:/x/... 是手动 echo 的测试数据,带 session_id / transcript_path / cwd 的才是真实会话。

结论:Hook 在编辑发生前就拿到了完整的 before/after 内容,包括中文和换行( )。这意味着你可以在放行前做任意检查:改的是不是那个函数、有没有删掉某行、有没有引入敏感字符串。


用例 07-10 · 坑:Hook 日志里的中文会变乱码

同一个 trace 文件里:

"old_string":"    # ���ֶ����� hook
    ..."

但 git diff 里显示的是正常的 # 我手动测试 hook。

原因:Add-Content 不带 -Encoding 时,Windows PowerShell 5.1 按 ANSI 写文件;而 Claude Code 传进来的是 UTF-8。

后果:文件本身没问题,只有 hook 的日志坏了。

修法:

Add-Content -LiteralPath 'hook-trace.log' -Encoding UTF8 -Value $raw

同样,用 Set-Content / Out-File 写日志时也要显式指定 -Encoding UTF8。

这条的影响比看起来大:如果 hook 逻辑里用中文匹配(比如"如果 old_string 里有'删除'就拦下"),乱码会让匹配直接失效,而且不报错。


一条给自己的纪律

排查过程中,我因为只看到屏幕输出的片段,就断言"光标会话启动即退出",还编了个"auto mode 导致"的原因。

实际是对方把中间输出省略了。

不完整的输出,不足以支撑结论。 这和"模型说的只是主张"是同一条——只不过这次犯错的是人。


用例 07-11 · 被权限拒绝的调用,不会触发 PreToolUse

问题:deny 规则拦掉的调用,hook 能看到吗?

设置

{
  "permissions": { "deny": ["Read(./utils.py)"] },
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File .claude/hooks/log-only.ps1"
      }]
    }]
  }
}

运行

claude -p "读 utils.py,说说 is_number 为什么排除 bool" --permission-prompts none --allowedTools "Read"

trace 里只有一条(读配置文件那次),没有 utils.py。

但 transcript 证明它真的发起过:

# 解析 ~/.claude/projects/<项目目录名>/*.jsonl,列出所有 tool_use
Read -> D:\Workspace\cc-demos\hello-project\utils.py
Read -> D:\Workspace\cc-demos\hello-project\.claude\settings.local.json

两个调用都被发起了,只有放行的那个进了 trace。

结论:

顺序是:权限判定 → Hook → 执行。

情况 PreToolUse 会跑吗
放行 ✅ 会
被 deny ❌ 不会
需要询问但没人回答(-p + permission-prompts none) 视同拒绝,不会

两个推论:

  1. Hook 不能用来"记录模型尝试过的所有操作" —— 被拒绝的那些它根本看不见。
  2. Hook 不能推翻 deny —— deny 在它之前就判完了。

想记录全部尝试,只能看 transcript:~/.claude/projects/<项目目录名>/*.jsonl。


一个没查清的问题:Write 的 deny 模式没生效

试过:

{ "deny": ["Write(./deny-target.txt)"] }

结果文件被正常创建了,规则没拦住。

同一次配置里的 Read(./.env) 是有效的。所以可能 Write 的路径模式写法不同,也可能是 Write 压根不支持这种路径匹配。

【待核实】 下次可以试 Write(deny-target.txt)、绝对路径、或者改测 Edit 规则,确认到底哪种写法有效。


验证 Hook 的标准流程

  1. 先把命令单独跑通(在 shell 里手动执行一次)
  2. 配进 hooks
  3. 新开会话(配置改动要新会话生效)
  4. 制造一次匹配工具调用
  5. 看金丝雀文件

第 1 步最重要——跳过它,你分不清是"hook 没触发"还是"命令有问题"。

2026-11-18 / 2.1.318


18 子代理

把"读一大堆文件"这件事隔离出去,不污染主对话。


它解决什么问题

你在主会话里让它"看看这个模块有没问题",它读了 15 个文件——这 15 个文件的内容全进了你的上下文,而且再也出不去。

子代理的做法相反:开一个独立的上下文去读,只把结论带回来。

主会话直接读 用子代理
上下文占用 15 个文件全占 只占最后的结论
适合 你要自己看细节 你只要结论
可并行 不能 可以开多个

最短做法

【未实测】在项目里建 .claude/agents/,每个子代理一个文件:

---
name: reviewer
description: 只读代码审查。看代码质量、边界条件、错误处理。不修改文件。
tools: Read, Grep, Glob
model: sonnet
---

你是一个只读代码审查员。

审查时只看三件事:
1. 边界条件是否处理(空值、零、越界)
2. 错误处理是否完整
3. 有没有明显的逻辑错误

不要修改任何文件。输出格式:
文件:行号 - 问题 - 建议

然后在会话里用 @reviewer 或让它自己调度。

也可以用命令行动态定义(这个参数是真存在的,见 claude --help):

claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'

关键参数

字段 作用
name 调用名
description 决定它什么时候被自动选中,写具体
tools 它能用哪些工具。只读审查就只给 Read, Grep, Glob
model 用哪个模型(省成本时用便宜的)

tools 是最重要的一行:不给 Edit / Write,它物理上就改不了文件。这比在提示词里写"不要修改"可靠得多。


一个容易搞混的地方

命令 管的是什么
claude agents(子命令) 【实测,来自 --help】后台会话(background agents),不是子代理配置
/agents(斜杠命令) 会话里管理自定义子代理
--agents(标志) 命令行临时定义子代理

claude agents 和"子代理"不是一回事。 前者管的是长时间在后台跑的任务,后者是在一次回答里临时分工。


怎么验证它真的隔离了上下文

方法:对比 /context 前后的 Messages 占用。

  1. 主会话直接让它读 10 个文件 → /context 记下 Messages 数值
  2. /clear,改成用子代理读同样 10 个文件 → /context 再记一次

期望:第二次的 Messages 明显更小。

如果两次差不多,说明子代理没起作用,或者它把内容又全念了一遍。


坑

  • description 写得太含糊,它不会被自动选中 → 写清"什么时候用我"
  • 子代理的结论一样是"主张" → 它说"有问题"你还是要验
  • 给 tools 太多等于没隔离 → 只读审查就别给写权限
  • 子代理看不到主会话的上下文 → 它需要的信息要在任务描述里说全
  • 别开太多 → 每个子代理都是一次完整调用,成本是叠加的

实测用例

用例 08-1 · 子代理真的被调用了(两种证据)

定义:.claude/agents/scout.md

---
name: scout
description: 只读侦察兵。批量读取大量文件后只回报简短摘要,不修改任何文件。
tools: Read, Glob, Grep
---

你是一个只读侦察员。
1. 用 Glob 列出 bulk/ 下所有 .md 文件
2. 逐个 Read 读取
3. 汇总成简短报告

输出第一行必须原样输出:[SCOUT] 侦察完成

证据一:-p 的 JSON 里有 subagent_stats

claude -p "用 scout 子代理读 bulk/ 下所有文件" --output-format json
"subagent_stats": {
  "spawned": 1,
  "requested": { "foreground": 1 },
  "completed": 1,
  "by_type": { "scout": 1 }
}

这是确定性的证据——比看状态栏、比读 transcript 都直接。

证据二:transcript 里的 Agent 工具调用

tool_use: {'Bash': 3, 'Agent': 1}

别信"我用了一个子代理",去看 subagent_stats。


用例 08-2 · 子代理到底省了什么(精确测量)

材料:bulk/ 下 20 篇文档,每篇 60 行,内容各不相同(有表格、代码、章节结构),共 40 KB。

问法相同:"读 bulk/ 下所有文件,每个用一句话概括"

B 主会话读 C 子代理读
input_tokens 19,308 5,585
cache_read 70,784 46,720
output_tokens 2,212 1,565
total_cost_usd $0.187 $0.273

两个结论,方向相反:

  1. 主上下文的新增输入少了 3.4 倍(19.3k → 5.6k)。
    子代理在自己那边读了 20 个文件,主会话只收到一份摘要。
  2. 总成本反而高了 46%(​0.187 → 0.273)。
    因为子代理是一次完整的额外调用,它的 token 不算在主会话的 usage 里,但照样计费。

子代理省的是"主上下文",不是"钱"。

这意味着:

你想要 该不该用子代理
主对话别被淹、还能继续聊 ✅ 用
少花钱 ❌ 不用,反而更贵
并行做几件互不相关的事 ✅ 用
只是读一个文件 ❌ 不值得

注意:这是各跑一次的数据,缓存状态不同(B 的 cache_read 更高),成本差值只能看量级,不能当精确结论。


用例 08-3 · 定义了子代理,它本身就占上下文

/context 里有一个独立类目:

Custom agents: 18 tokens (0.0%)
Custom agents · .claude/agents/
└ 1 agent · 18 tokens

即使这次完全没用到它,定义也占了 18 tokens。

1–5 个可以忽略;定义 20 个就是几百 token,每次会话都付。所以子代理的正文要写短,description 要写准。


一个必须说清的测量教训:别用 /context 的 Messages

同一份材料,三次读 /context 的 Messages:

基线 1.2k  →  B 组 800  →  C 组 17

17 tokens —— 明显不可能是真实占用(刚聊完一整轮)。这个数字在剧烈抖动。

我最初就是用这个数字下判断的,结果得出"子代理几乎没差别"的错误结论。

正确做法:用 -p --output-format json 里的 usage 字段。

字段 含义
usage.input_tokens 本次新增输入的 token
usage.cache_read_input_tokens 缓存命中的 token(便宜)
usage.output_tokens 输出
total_cost_usd 本次花费
subagent_stats 子代理的确定性统计

为什么这个准:它是 API 返回的真实用量,不是界面估算。而且可脚本化、可重复。


还有一个意外发现:大输出会落到磁盘

B 组那次(用交互会话),它没有把 20 个文件全塞进上下文,而是:

1. ls bulk/
2. cat 所有文件                    ← 输出太大
3. sed -n '1,420p'  <tool-results/xxx.txt> | grep -v ...
4. sed -n '420,900p' ... | grep -v ...
5. sed -n '900,1400p' ... | grep -v ...

大输出被自动转存到 .claude/projects/<会话ID>/tool-results/*.txt,模型再用 sed/grep 分片取。

这推翻了一个直觉:读 20 个文件不等于上下文爆掉——工具结果太大时会落盘,模型按需切片读。

所以"上下文被撑爆"更多发生在:你反复让它读、每读一次都在对话里留一份,而不是单次读很多。

2026-11-18 / 2.1.318


19 插件

把 Skill、子代理、Hooks、MCP 打成一个包,装到别的项目里。


它解决什么问题

没有插件 有插件
每个项目都要复制一份 .claude/skills/、settings.json、.mcp.json 装一次,全项目可用
想分享给同事,得写一页安装说明 给个名字,claude plugin install
版本混乱,不知道谁在用哪版 有版本号、有清单、能校验

一句话:插件 = 可分发的一套配置。


最短做法

【实测】claude plugin --help 里真实存在的子命令:

claude plugin list                          # 已装了什么
claude plugin install <name>                # 装(可写 plugin@marketplace)
claude plugin uninstall <name>              # 卸载
claude plugin enable <name>                 # 启用
claude plugin disable <name>                # 禁用
claude plugin update <name>                 # 升级(需重启生效)
claude plugin details <name>                # 看它包含什么组件、占多少 token
claude plugin validate <path>               # 校验清单/技能/代理/命令
claude plugin init <name>                   # 脚手架,建在 ~/.claude/skills/<name>/
claude plugin marketplace                   # 管理市场

两个很实用的:

命令 什么时候用
plugin details <name> 装之前看它占多少 token、包含哪些组件
plugin validate <path> 自己写完插件,先校验再发布

一个插件里能装什么

【未实测】官方描述的组件:

组件 对应文件
Skills(斜杠命令) skills/<name>/SKILL.md
子代理 agents/*.md
Hooks 清单里的 hooks 段
MCP 服务器 清单里的 mcpServers 段
LSP(语言服务) 清单里的 lsp 段

清单文件:.claude-plugin/plugin.json


怎么验证插件真的装上了

claude plugin list
claude plugin details <name>

然后在新会话里:

/help

看它带的斜杠命令有没有出现。

金丝雀法:插件通常自带一个命令,直接调一次,能出结果就是装好了。


安全(这一节比用法重要)

插件能做的事比 Skill 多得多——它可以带 Hooks,而 Hooks 是以你的权限执行 shell 命令的。

所以:

  • 别装来源不明的插件
  • 装之前 claude plugin details 看清楚它带什么
  • 带 Hooks 的插件要格外小心,那是任意命令执行
  • plugin eval 能跑插件自带的测试,但官方明确说:测试通过不等于安全审计

坑

  • plugin update 之后要重启会话才生效
  • plugin init 建在 ~/.claude/skills/,不是当前项目,注意路径
  • 插件带 Hooks = 任意命令执行,只看名字就装很危险
  • 装太多插件会一直占上下文(/context 里 Skills 那一项会涨)
  • 校验通过 ≠ 安全,validate 只检查格式

实测用例

用例 19-1 · claude plugin init 生成的插件结构

输入

claude plugin init hello-kit --description "练习用插件:技能 + 子代理 + Hook" --with skills agents hooks

输出

✔ Created plugin "hello-kit" at ~\.claude\skills\hello-kit
  It will auto-load next session as hello-kit@skills-dir. Run /reload-plugins to load it now.
  Disable: claude plugin disable hello-kit@skills-dir. Remove: delete the directory.

生成的文件

.claude-plugin/plugin.json          ← 清单
SKILL.md                            ← 插件目录本身就是一个技能
skills/example/SKILL.md
agents/example.md
hooks/hooks.json
hooks-handlers/on-session-start.ts  ← TypeScript 处理脚本

三个要点:

  1. init 默认建在 ~/.claude/skills/<name>/,不在当前项目里。
  2. --with 决定生成哪些组件:skills / agents / hooks / mcp / lsp / output-style / channel。
  3. 目录里那份 SKILL.md 让插件本身成了一个技能 —— 所以装完就能 /hello-kit 调用。

清单长这样:

{
  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
  "name": "hello-kit",
  "version": "0.1.0",
  "description": "...",
  "author": { "name": "rainio", "email": "..." },
  "skills": ["./"]
}

Hook 配置用了两个变量:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "bun \"${CLAUDE_PLUGIN_ROOT}/hooks-handlers/on-session-start.ts\""
      }]
    }]
  }
}

${CLAUDE_PLUGIN_ROOT} 是插件被安装到哪的根目录——所以插件里的路径永远写相对这个变量,不能写死。

注意它默认用 bun 跑 .ts。没装 bun 的话这条 hook 会失败,得改成 powershell 或 python 的写法。


用例 19-2 · validate 通过了,但目录检查报 blocking

原始脚手架直接校验

claude plugin validate ~/.claude/skills/hello-kit --json
success: True

[error] BLOCKING README_MISSING: README missing
[error] BLOCKING LICENSE_MISSING: License missing
[warning] ICON_MISSING: No icon

这里有个关键区别:

含义
success: true 清单(plugin.json)本身合法
blocking: true 的 findings 发布到目录会被拒
退出码 仍然是 0(除非加 --profile directory)

结论:「校验通过」和「能发布」是两件事。 想在 CI 里卡住,要加 --profile directory;想把警告也当失败,加 --strict。


用例 19-3 · 补齐 README 和 license 之后

改动

  • 加 README.md(40 词以上,说明用途、组件、用法)
  • plugin.json 里加 "license": "MIT"

再验

claude plugin validate ~/.claude/skills/hello-kit --json
success: True
[warning] ICON_MISSING

blocking 全消,只剩图标警告。

加 --profile directory 会多给一条建议:

This README has no line that installs "hello-kit" from a marketplace.
Add the install line:
  /plugin install hello-kit --marketplace <owner>/<repo>
✔ Validation passed

结论:三种严格度对应三个场景——日常开发用默认,CI 用 --profile directory,最严用 --strict。


用例 19-4 · 验证插件真的加载并执行

把根 SKILL.md 的 TODO 换成带金丝雀的真技能

## 步骤
1. 原样输出:[HELLO-KIT] loaded v0.1.0
2. 再输出一行:plugin root = <当前插件目录>

第一次:只给命令

claude -p "/hello-kit"

结果:没触发。它回:"I don't see a request in that message — just session context."

第二次:命令 + 一句话

claude -p "/hello-kit 执行这个技能"

结果:

[HELLO-KIT] loaded v0.1.0

plugin root = C:\Users\rainio\.claude\skills\hello-kit

两个结论:

  1. 技能确实被加载并执行了,金丝雀是三处同时成立的证据(文件找到、frontmatter 解析、正文执行)。
  2. -p "/命令" 单发不够 —— 技能内容会被注入成上下文,但没有"任务"。后面得跟一句话。

这条对脚本化很重要:CI 里想调用某个 Skill,写成 -p "/my-skill 做某事",不要只写 /my-skill。


一个副作用:改完立即生效

我改完 SKILL.md 的描述后,当前会话里的技能描述立刻变成了新版(不需要重启)。

但插件列表里的版本号仍是 0.1.0 —— 改了内容不等于改了版本。分发时要手动升 version。


还没验的

  • claude plugin install <name>(需要 marketplace)
  • claude plugin details <name> 报的 token 成本
  • claude plugin disable/enable
  • 真正的 marketplace 发布流程

2026-11-21 / 2.1.318

用例 19-5 · 删掉 description,validate 一声不吭

操作:把根 SKILL.md 的 frontmatter 从

---
name: my-kit
description: 我的插件练习。用户说"试试 my-kit"时使用。
---

改成只剩 name。

然后跑三种严格度的 validate

命令 结果
validate . ✔ passed(只报 README / LICENSE)
validate . --strict ✔ passed
validate . --profile directory --strict ✘ failed,但原因还是 README / LICENSE

全文没有一处提到 description 或 frontmatter。

结论:

claude plugin validate 不检查技能的 frontmatter。
它查的是 plugin.json 清单 + 目录规范(README / LICENSE / icon)。

但插件本身会静默降级:技能列表里的描述变成了

my-kit: my-kit

——回退成了名字。

后果:技能还在、还能 /my-kit 调用,但自动匹配会变差——因为模型是靠 description 判断"什么时候该用它"的。

所以:

检查项 谁负责
清单合法、目录规范 validate
description 写得准不准 只能靠自己
技能真的能跑 金丝雀(-p "/my-kit 执行")

这三层缺一层,你都不知道自己漏了什么。


用例 19-6 · 技能内容被注入,但文件读不了

claude -p "/my-kit 执行" --output-format json 的输出里有:

"permission_denials": [{
  "tool_name": "Read",
  "tool_input": { "file_path": "C:\\Users\\rainio\\.claude\\skills\\my-kit\\SKILL.md" }
}]

它自己也说了:

我尝试直接打开 SKILL.md 核对原文时被读取权限拦下了,所以上面的来源判断依据的是已注入的 skill 内容

结论:

途径 能不能拿到
技能内容被注入到上下文 ✅ 能
用 Read 工具打开那个文件 ❌ 那是另一次工具调用,要单独授权

"它知道"和"它能查证"是两件事。

这也是为什么金丝雀必须能看到具体输出才可信——它复述的内容来自注入,不是它自己去核对的原文。

2026-11-21 / 2.1.318


20 多模态输入

贴截图、传图片。前端调试和"这张图为什么不对"的场景。


我要贴一张图

平台 按键
Windows / Linux Ctrl+V
Windows / WSL(终端拦截了 Ctrl+V 时) Alt+V
iTerm2(macOS) Cmd+V

粘贴后,输入框里会出现一个标记:

[Image #1]

然后像正常一样写你的问题,它会把这张图一起看。


我要给它一个文件

三种方式:

方式 写法
@ 补全 输入 @ 触发路径补全
直接写路径 看 D:\proj\screenshot.png
拖进终端 Windows Terminal 支持拖放路径

什么时候真的有用

场景 怎么说
界面不对 贴截图 + "这个按钮被挤到下一行了,CSS 在哪改"
报错看不懂 贴报错截图 + "这是什么错"
设计稿还原 贴设计图 + 贴当前实现截图 + "差在哪"
图表/流程图 贴图 + "把这个流程转成 mermaid"
终端输出太长 截图比复制大段文本更省事

注意:终端里的文本优先复制粘贴文字,别截图。文字可以被搜索、被精确引用,图片不行。


图片的成本

【实测】本机 JSON 输出里能看到 usage 字段,一次包含图片的请求 input_tokens 会明显更高。

经验规则:

  • 一张截图 ≈ 几百到上千 token
  • 连贴 5 张图 ≈ 一次完整对话的开销
  • 能截图局部就不要截全屏

验证它真的看到图了

问一个只有看图才能回答的问题:

这张图的背景是什么颜色?
结果 说明
答得出具体颜色/细节 ✅ 图进去了
说"我看不到图片" 没传进去,检查按键和终端
含糊其辞地编 ⚠️ 它没看到,但在猜

第三种最危险 —— 和"主张不是事实"是同一条。


坑

  • Ctrl+V 被终端占用 → 用 Alt+V
  • 它可能没收到图却在编内容 → 用一个只有看图能答的问题验一下
  • 截图里可能带密钥、token、客户数据 → 贴之前看一眼
  • 截全屏很贵 → 只截相关区域
  • 图片里的文字识别可能出错 → 关键代码/路径还是用文字给
  • 不是所有终端都支持图片 → 不支持就用文字描述或给路径

实测用例

用例 20-1 · 粘贴图片,输入框出现 [Image #N]

操作:会话里截一张图,按 Ctrl+V(Windows)。

输入框显示

[Image #1]
这张图里第三行写的是什么?

结论:粘贴成功后,输入框里会出现 [Image #N] 标记,编号自动递增。看到标记就说明图进了待发送队列。


用例 20-2 · 第一个测试是无效的(重要教训)

做法:截图 calc.py 的某一段,问"第三行是什么"。

它的回答:

Everything here is intentionally small and readable. Do not reuse it for

完全正确——但这个测试证明不了任何事。

为什么:calc.py 就在项目里。它完全可以不读图,直接 Read 文件拿到同样的内容。

python -c "print(open('calc.py').read().splitlines()[2])"

同样的答案,两种来源,你分不清。


用例 20-3 · 决定性测试:只用图里才有的内容

准备:生成一个磁盘上不存在的随机串

python -c "import secrets,string; print(''.join(secrets.choice(string.ascii_uppercase+string.digits) for _ in range(12)))"
2MRFLUSMER6G

步骤:

  1. notepad 打开记事本,输入 校验码 2MRFLUSMER6G
  2. 截图记事本窗口
  3. 关掉记事本,选"不保存"(确保这个串从来没落过盘)
  4. 在会话里粘贴截图,问:图里的校验码是什么?

它的回答

图上的校验码是:

2MRFLUSMER6G

一共 12 位。如果你要把它传给别的服务,建议从原处复制,别用这里转录出来的内容,
因为图上源码照字面转录时,O 和 0、I 和 l 这类字符容易看错。

结论:

图真的被读到了。

因为这个串不在磁盘任何地方,它答对只能是"看到了图",不可能是"读了文件"。

它还主动加了一条 OCR 风险提示 —— 这是好行为,但不代表它每次都这么谨慎。自己贴图时,关键字符(0/O、1/l)别指望它认对。


怎么设计"图片是否被读取"的测试

沿用全书一贯的金丝雀原则:

要验证 证据必须是
CLAUDE.md 被读到 只有它里面才有的代号
Skill 被加载 只有 SKILL.md 里才有的标记
图片被读到 只有图里才有的内容,磁盘上绝不能存在

反面教材(用例 20-2):拿项目里的代码截图去问 —— 它读文件也能答对。

一句话:

用一个"只可能从这一个来源拿到"的信息去问。 答对了才算证据。


还没验的

  • 一次能贴几张图([Image #1] [Image #2] 会不会同时存在)
  • 图片对 input_tokens 的实际影响(可以照 08 的方法量)
  • Alt+V 和 Ctrl+V 的实际差别(本机 Ctrl+V 直接可用)

2026-11-21 / 2.1.318


21 编辑器集成

在 VS Code 里用它,和在终端里用它,是两种体验。
来源:教程 2.2 + claude --help。扩展行为**【未实测】**(本机只装了 CLI)。


最容易搞错的一件事

装 VS Code 扩展,不会把 claude 装进系统终端。

扩展内置一份供面板使用的私有 CLI,但不写进 PATH。所以"装好了但终端里找不到 claude"不是故障——那是两个独立的东西。

能力 扩展 独立 CLI
在编辑器面板里对话 ✅ 需在集成终端跑
把选中的代码当上下文 ✅ 靠 IDE 集成
系统终端输入 claude ❌ ✅
命令行参数、脚本 部分不适用 ✅

结论:两个都装。 扩展管"边看边改",CLI 管脚本和终端工作流。


最短做法

  1. VS Code 扩展市场搜 Claude Code(官方标识 anthropic.claude-code)
  2. 要求 VS Code 1.94.0+
  3. 打开面板,按提示登录
  4. 在项目里打开一个文件,选中一段代码 → 直接提问

命令行让终端会话连上 IDE:

claude --ide

【实测】--help 原文:Automatically connect to IDE on startup if exactly one valid IDE is available。

"exactly one" 是关键:同时开着两个编辑器时它不自动连。


扩展给你的四件东西

能力 为什么值得用
选中代码当上下文 不用复制粘贴,也不用告诉它"那个函数"在哪
diff 审查 改动以图形 diff 呈现,比终端里滚文字清楚
计划审阅 Plan 模式的方案可以在编辑器里过一遍再批准
会话历史 图形化找回之前的会话

@ 引用

在提示词里用 @ 触发文件路径补全:

@calc.py 这个文件里 divide 的边界处理有问题吗

比手打路径快,也比"读一下 calc.py"更明确——@ 是显式指定,不会让它自己猜。


选哪个入口

场景 用
边看代码边改、要审 diff 编辑器扩展
跑脚本、CI、管道 CLI
大任务、长时间跑 CLI(可以 -w 开 worktree)
不熟悉的项目、想看清楚每一步 编辑器(diff 更直观)

坑

  • 扩展 ≠ CLI:终端里没有 claude 是正常的
  • --ide 需要"恰好一个"可用 IDE,开两个就不自动连
  • 扩展版本和 CLI 版本独立,可能出现"面板是新版、终端是旧版"
  • 不要在扩展里把权限全放开 —— 图形界面下更容易顺手点"总是允许"
  • 某些第三方编辑器(Trae 等)官方没有明确兼容承诺,装不上属于预期

实测用例

还没有。下次在 VS Code 里打开 hello-project:

  1. 选中 calc.py 的 divide 函数,问"这里的边界处理对不对"
  2. 让它改一处,看 diff 视图
  3. 记录扩展版本和 CLI 版本各是多少

22 语言服务器LSP

让它像编辑器一样知道类型和符号,而不是靠文本搜索猜。
来源:教程 26.3 + 官方文档。【未实测】。对开发者价值很高,但需要额外安装。


它解决什么问题

没有 LSP 时,它靠 grep 找引用、靠读代码猜类型。

有 LSP 之后:

能力 具体表现
改完即检 它每改一个文件,语言服务器就报出新的类型错误/警告——不用等构建
符号导航 查定义、查引用、查某位置的类型、列文件内符号、找接口实现、追调用层级

最值钱的是第一条:它引入一个类型错误,下一次编辑前就能被发现。


关键前提:默认不启用

LSP 工具要等你为对应语言装了 code intelligence 插件才会激活。

插件只告诉 Claude Code "用哪条命令启动语言服务器、处理哪些扩展名"——语言服务器二进制要你自己装,而且要在这个 shell 的 PATH 上。

装不上时插件会报:

Executable not found in $PATH

常用语言对照

语言 插件 需要的二进制
TypeScript / JavaScript typescript-lsp typescript-language-server
Python pyright-lsp pyright-langserver
Go gopls-lsp gopls
Rust rust-analyzer-lsp rust-analyzer
Java jdtls-lsp jdtls
C / C++ clangd-lsp clangd
C# csharp-lsp csharp-ls
Ruby ruby-lsp ruby-lsp
PHP php-lsp intelephense
Kotlin kotlin-lsp kotlin-lsp
Lua lua-lsp lua-language-server
Swift swift-lsp sourcekit-lsp

其他语言要自己写插件。


最短做法(以 Python 为例)

# 1. 装语言服务器二进制,确认在 PATH 上
pip install pyright

# 2. 装对应插件(用你装插件的方式)
#    claude plugin install pyright-lsp  (名称以插件市场为准)

# 3. 重启会话

验证:

pyright-langserver --version

出得来版本号,才算第一步成功。


验证它真的生效

金丝雀法:写一个明显的类型错误。

def double(x: int) -> int:
    return x * 2

double("abc")      # 类型错误

让它改/读这个文件,然后看它有没有主动提到类型错误。

结果 说明
主动指出类型不匹配 ✅ LSP 生效
只说"看起来没问题" 没生效,或服务器没启动

边界

  • LSP 工具是只读的,调用不需要权限批准
  • 云会话里不生效,插件的语言服务器不会在云端启动
  • 不是编译器的替代品:服务器没启动时,对该文件的 LSP 调用会返回错误结果
  • 没有万能支持:只覆盖装了插件的语言

坑

  • 插件装了但二进制没装 → Executable not found in $PATH
  • 二进制装在别的 shell 里 → 启动 claude 的那个 shell 找不到
  • 云会话用不了
  • 它报的类型错误也可能是过时的(文件没保存 / 服务器缓存)
  • 别指望它替代真正的构建和测试

实测用例

还没有。下次在 hello-project 里:

  1. 装 pyright + 插件
  2. 加一行 double("abc")
  3. 看它会不会主动报类型错误

23 Agent-SDK

把 Claude Code 当成库来用,写自己的 Agent。

状态:本节全部【未实测】。装包、写代码、跑起来都没在这台机器上验证过。这一篇只给你"知道它存在、知道什么时候需要"。


它解决什么问题

你已经会 Agent SDK 多给你什么
claude -p "..." 一问一答 自己控制循环、工具、状态
用现成的 Claude Code 把它嵌进自己的程序里
用配置文件做扩展 用代码做任意逻辑

判断标准:如果你只需要"跑一个任务拿结果",-p 就够了,不用 SDK。


什么时候才真的需要

  • 你要做一个给别人用的 AI 编程工具,不是自己用
  • 你需要多轮自动化,中间要插自己的业务逻辑
  • 你要把 Claude Code 嵌进 CI、机器人、后台服务

如果你还在问"我该不该用 SDK",答案是:还不该。


最短做法(【未实测】)

包名:@anthropic-ai/claude-agent-sdk

npm install @anthropic-ai/claude-agent-sdk

最小脚本(结构示意,具体 API 以官方文档为准):

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

for await (const message of query({
  prompt: "解释一下 calc.py 里 divide() 做了什么",
  options: { allowedTools: ["Read"] },
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

关键概念

概念 意思
query 一次对话,返回异步流
工具权限 和 CLI 一样,可以限定它能用什么
消息流 你能看到每一步,不只是一句答案
会话 可以续、可以恢复,和 CLI 一致

核心价值:你能在每一步之间插自己的代码。


怎么验证它跑通了

  • 装包成功,node -e "require('@anthropic-ai/claude-agent-sdk')" 不报错
  • 最小脚本能打印出一句结果
  • 限定 allowedTools: ["Read"] 后,它改不了文件
  • 能拿到成本/用量字段(对应 CLI 的 total_cost_usd)

坑

  • API 会变,网上抄的例子大概率过时 → 只信官方 agent-sdk 文档和你装的版本
  • 成本失控:程序里的循环比手工点贵得多,一定设上限
  • 不要在 SDK 里跳过权限 —— 程序没有人在旁边审查
  • 先别学:没有真实需求时学 SDK,学完也记不住

教程里对应的章节

  • 第8部分 第29章 构建自己的编程 Agent(6 篇)
  • 第10部分 第43章 Agent SDK 高级(6 篇)

24 沙箱与受限模式

想让它放开手跑,又怕它跑出界。

状态:本篇以【待核实】为主。 沙箱的具体行为、平台限制、开关方式随版本变化很大,用之前以官方 sandboxing 文档和 /help 为准。


先分清三件事

机制 管什么
权限模式(03) 这个动作允不允许做
权限规则(03) 这些命令/路径自动放行还是拦
沙箱 它执行命令时能碰到什么(文件、网络)

三者的关系:权限决定"做不做",沙箱决定"做了能造成多大影响"。


--restricted:确定存在的受限模式

【实测】claude --help 原文摘要:

移除内置的能执行命令或代码的工具(Bash、PowerShell 等)和 WebFetch(除非 --tools 点名),并忽略用户/项目/本地设置文件;把文件工具限制在工作目录内(含 --add-dir);拒绝 bypassPermissions;只允许人或配置的权限处理器批准对 settings、git 和工具配置文件 的写入。

一句话:能读能写文件,但基本不能执行命令,也不能改配置。

claude --restricted

适合:给别人演示、审查陌生仓库、只想让它读代码。


沙箱(【待核实】)

官方有独立的 sandboxing 机制,典型特征是:

特征 说明
默认关闭 要显式开启
主要作用于 shell 命令 文件工具另算
可能限制网络 沙箱内的命令默认可能无网,需要按域名放行
平台有差异 Linux/macOS/Windows 的实现和能力不同

这些细节我没有在本机验证过。 需要时先看官方 sandboxing 页,再用金丝雀法确认(让它跑一条需要联网的命令,看会不会被拦)。


--dangerously-skip-permissions 的正确认知

【实测】--help 原文:

Bypass all permission checks. Recommended only for sandboxes with no internet access.

它的意思不是"危险所以别用",而是:只有在已经被隔离、连不上网的环境里,全放开才是可接受的。

在没有沙箱的个人机器上用它,等于把所有安全检查关掉。


验证沙箱真的生效

金丝雀法:让它做一件"出界"的事,看会不会被拦。

测试 期望
让它读工作目录外的文件(如 C:\Windows\win.ini) 被拒
让它 curl 一个外部地址 被拒或超时
让它写系统目录 被拒
让它改 .claude/settings.json 被拒(--restricted 下)

能拦住才算生效。 拦不住就不是"沙箱大概开了",是没开。


按场景选

场景 建议
自己的项目、熟悉代码 普通权限模式即可
陌生仓库、别人给的代码 --restricted
演示 / 录屏 --restricted
CI、无人值守 --permission-prompts none + 只读工具(见 25)
无网沙箱内批量跑 才考虑 --dangerously-skip-permissions
生产机器 别在任何模式下放开

坑

  • 权限模式不是沙箱:manual 模式下你点"允许",它就能做任何允许范围里的事
  • --restricted 会忽略你的设置文件,团队配置不生效
  • bypassPermissions 在 --restricted 下被拒绝
  • 沙箱主要管命令,不管读文件,别以为开了沙箱就什么都安全
  • 平台差异大:Windows 上的能力和 Linux 不一样
  • --dangerously-skip-permissions 的前提是"没有网络",不是"我很急"

实测用例

【实测】--restricted 和 --dangerously-skip-permissions 两个参数在 2.1.318 的 --help 里确实存在,描述已摘录在上面。

沙箱本身未实测——下次可以拿 hello-project 跑一次"读工作目录外文件"的测试,把结果补在这里。


90 斜杠命令速查

会话里输入的命令,以 / 开头。
依据官方 Commands reference(https://code.claude.com/docs/en/commands),配合本机 2.1.318 核对。

命令只在消息开头才被识别;后面的文字成为它的参数。可以一次串多个技能:/skill-a /skill-b 做某事(最多 6 个)。


一句话用法

/命令 [参数]
  • 输入 / 看菜单,输入 / 加字母过滤
  • 不认识就敲 /help
  • 命令可用性随平台、套餐、环境变化——比如 /desktop 只在 macOS / x64 Windows + 订阅下出现

会话与上下文

命令 作用 例子
/clear [name] 清空上下文开新话题(给个名字方便在 /resume 里找回) /clear 换个任务
/compact [说明] 总结压缩,可给聚焦指令 /compact 重点保留接口约定
/context [all] 看上下文占用;all 展开明细 /context all
/resume [会话] 按 ID/名字恢复,或开会话选择器 /resume auth-refactor
/rename [名字] 给当前会话改名,显示在输入栏 /rename 修登录
/branch [名字] 从当前对话分叉,试另一条路 /branch 试试缓存方案
/fork [提示] 把对话复制成后台会话,这边继续 /fork 去查日志
/exit 退出(后台会话里是"脱离") /exit
/export [文件名] 导出对话为纯文本 /export chat.txt
/copy [N] 复制上一条回复到剪贴板,N 复制倒数第 N 条 /copy 2
/recap 生成一行会话总结 /recap

别名:/clear = /reset = /new;/resume = /continue;/exit = /quit


回退与检查点

命令 作用
/rewind 回退对话和/或代码到某个检查点,或从某条消息起总结

别名:/checkpoint、/undo

输入框为空时连按两次 Esc 也打开 Rewind 菜单。


项目与记忆

命令 作用 例子
/init 生成 CLAUDE.md(会直接写文件) /init
/memory 编辑 CLAUDE.md、开关 auto memory、看记忆条目 /memory
/add-dir <路径> 加一个可访问的工作目录 /add-dir ../shared
/cd <路径> 把会话切到另一个目录,对话保留 /cd ../other-proj

/add-dir 只是加文件访问权,不会自动加载那个目录的 .claude/ 配置。


代码与审查

命令 作用 例子
/diff 看工作区改动(含它自己改的) /diff
/code-review [级别] [参数] [目标] 审当前 diff / PR / 分支 / 路径的正确性问题 /code-review high --fix
/review 同 /code-review /review 1234
/simplify [目标] 只做清理和简化,不找 bug /simplify src/auth
/security-review 查安全漏洞(需要 origin 远程) /security-review
/verify 构建 + 运行应用,确认改动真的有用 /verify
/run 启动并驱动项目,看效果 /run

/code-review 参数:

/code-review [low|medium|high|xhigh|max|ultra] [--fix] [--comment] [--max-findings n|all] [pr#|branch|path]
  • --fix 把发现直接应用
  • --comment 贴到 GitHub PR / GitLab MR
  • ultra 走云端多智能体深审

权限与安全

命令 作用
/permissions 管理 allow / ask / deny 规则,看最近被拦的操作,编辑 auto mode 规则
/sandbox 开关沙箱模式(仅支持的平台)
/fewer-permission-prompts 扫历史记录,把常见只读命令加进放行清单

别名:/permissions = /allowed-tools


模型与成本

命令 作用 例子
/model [模型] 切模型并存为默认;s 键只切本次会话 /model opus
/effort [级别] low–xhigh / max / auto / status / ultracode /effort high
/advisor [模型|off] 开关 advisor(关键时刻问第二个模型) /advisor opus
/fast [on|off] 开关 fast mode /fast on
/usage 会话花费、套餐限额、活动统计 /usage
/cost 同 /usage /cost
/stats 同 /usage,直接开 Stats 页 /stats
/autocompact [auto|大小] 设置自动压缩窗口,如 500k /autocompact 500k
/rate-limit-options 被限额挡住时看选项 /rate-limit-options

扩展

命令 作用
/mcp [reconnect|enable|disable ...] 管理 MCP 连接和 OAuth
/hooks 查看 hook 配置
/skills 列技能,按 token 排序、切换可见性(t 排序,Enter 切换)
/reload-skills 重扫技能目录,不用重启
/reload-plugins [--force] 重载插件
/plugin [子命令] 管理插件(list / install / enable / disable)
/agents 提示你去 .claude/agents/ 管理子代理(v2.1.198+ 不再开界面)
/skill-doctor 看每个技能占多少上下文、用了多少次
/update-config [描述] 用自然语言改 settings.json

并行与后台

命令 作用 例子
/tasks 看当前会话的后台工作和子代理 /tasks
/background [提示] 把整个会话转后台,释放终端 /background
/subtask <任务> 派生一个继承上下文的子代理,结果回到本对话 /subtask 查这个报错
/batch <指令> 把大改动拆成 5–30 个单元,各开 worktree 并行做 /batch 把 src 从 JS 迁到 TS
/loop [间隔] [提示] 反复跑一个提示 /loop 5m 看部署完了没
/workflows 看工作流进度 /workflows

别名:/tasks = /bashes;/background = /bg;/loop = /proactive


状态与诊断

命令 作用
/status 状态页:版本、模型、账户、连接性
/help 帮助与可用命令
/doctor [prompt-audit] 体检,能提出并应用修复
/debug [描述] 开调试日志并排查
/recap 一行总结
/release-notes 看更新日志
/insights 生成使用分析 HTML 报告
/heapdump 内存快照(不在菜单里,要打全名)

别名:/doctor = /checkup


账户与界面

命令 作用
/login / /logout 登录 / 登出
/config [key=value] 设置界面;也可直接设值,如 /config theme=dark
/keybindings 打开键位配置文件
/statusline 配置状态行
/output-style [样式] 输出样式
/theme 换主题
/tui [classic|fullscreen] 换渲染器
/color [颜色] 输入栏配色
/terminal-setup 装 Shift+Enter 换行绑定
/focus 只显示最后一条提示 + 工具摘要 + 结论
/mobile 手机 App 二维码

别名:/config = /settings


反馈与上报

命令 作用
/bug [描述] 报 bug / 分享对话(发送前有同意页)
/feedback [描述] 产品反馈(同 /bug 对话框)

别名:/bug = /share


内置技能(也叫命令)

这些标着 Skill 的,本质是"打包好的一段指令",行为和内置命令并列:

命令 干什么
/batch 大范围并行改动
/loop 反复执行
/deep-research 多源检索并给带引用的报告
/run / /verify 启动应用 / 验证改动
/simplify 清理与简化
/dataviz 图表设计规范
/design / /slides 生成设计稿 / 演示稿 artifact
/claude-api 查 Claude API 与 Managed Agents 资料
/fewer-permission-prompts 减少权限弹框
/update-config 改设置
/workflow-authoring 写工作流脚本的参考

已移除

命令 情况
/vim v2.1.92 移除,改用 /config → Editor mode
/pr-comments v2.1.91 移除,直接让 Claude 查 PR 评论
/ultraplan 已移除,改用 plan 模式

坑

  • 斜杠命令只在会话里有效,在 shell 里敲 /clear 会报错。
  • 命令必须在消息开头,中间出现的 /xxx 不会被识别。
  • /clear 只清上下文,磁盘上的会话记录还在,可以用 /resume 或 Rewind 菜单找回。
  • /init 会直接写文件,写完 git status 看一眼。
  • 打错命令不会自动纠正:会显示 Unknown command,但把相近的列在菜单里。
  • 有些命令是隐藏的(如 /heapdump),必须打全名才出现。
  • 可用性随套餐/平台变化:/desktop 要订阅 + macOS/x64 Windows;/upgrade 在企业版不出现。
  • 别背清单,敲 /help:版本升级后增减很频繁。

实测用例

用例 90-1 · / 菜单会标出来源

输入 /revi:

❯ /review-diff        审查当前未提交的改动... (project)
  /code-review (review)  Review the current diff or a PR for bugs

形如 (project) 的后缀说明这个命令来自项目里的 .claude/skills/,不是内置的。


用例 90-2 · /keybindings 打开可编辑的 JSON

{
  "bindings": [
    { "context": "Chat", "bindings": { "ctrl+alt+g": "command:orca-agent-view" } }
  ]
}

键位可以自己改,格式是 context + "键位": "command:命令名"。


用例 90-3 · /rewind 的入口不止一个

输入框为空时连按两次 Esc,直接打开 Rewind 菜单:

Rewind

Nothing to rewind to yet.

输入框有字时,同样两下 Esc 是清空输入,不会开菜单。


用例 90-4 · /status 是五页面板

Settings  Status  Config  Usage  Stats
  • Status:版本、会话 ID、cwd、认证方式、端点 URL
  • Config:当前所有配置项的实际值
  • Usage:本次会话花费、代码改动行数、按模型拆 token
  • Stats:历史统计

2026-11-21 / 2.1.318


91 CLI参数速查

在 PowerShell / bash 里,claude 后面跟的参数。
依据官方 CLI reference(https://code.claude.com/docs/en/cli-reference),配合本机 2.1.318 核对。

⚠️ 官方原话:claude --help 不会列出全部参数。--help 里没有,不代表不存在。


一句话用法

claude [子命令] [参数] [提示词]
claude                          # 交互会话
claude -p "解释这个函数"          # 一问一答,打印后退出
claude -c                       # 接着当前目录上次的会话
claude -r "auth-refactor"       # 按名字/ID 恢复
claude --model sonnet --effort high

子命令

子命令 作用 例子
claude 开交互会话 claude
claude "query" 带初始提示开交互 claude "explain this project"
claude -p "query" 非交互,打印后退出 claude -p "解释这个函数"
claude -c 续当前目录最近一次会话 claude -c
claude -r "<id/name>" "query" 恢复指定会话 claude -r "auth-refactor" "继续"
claude update 升级(包管理器装的走包管理器) claude update
claude doctor 只读诊断安装与设置 claude doctor
claude install [version] 装/重装原生二进制,接受 stable/latest/版本号 claude install stable
claude auth login 登录;--email、--sso、--console claude auth login --console
claude auth logout 登出 claude auth logout
claude auth status 输出 JSON;--text 变人类可读;登录返回 0,未登录返回 1 claude auth status --text
claude mcp 管理 MCP 服务器 claude mcp add ...
claude mcp login <name> 跑某 MCP 服务器的 OAuth;SSH 上加 --no-browser claude mcp login sentry
claude mcp logout <name> 清掉该服务器的 OAuth 凭据 claude mcp logout sentry
claude plugin 管理插件(别名 claude plugins) claude plugin list
claude agents 后台会话视图;--json 输出数组 claude agents --json
claude attach <id> 在本终端接上某个后台会话 claude attach 7c5dcf5d
claude logs <id> 打印后台会话最近输出 claude logs 7c5dcf5d
claude stop <id> 停掉后台会话(也可 claude kill) claude stop 7c5dcf5d
claude rm <id> 从列表移除后台会话 claude rm 7c5dcf5d
claude respawn <id> 重启后台会话;--all 重启全部 claude respawn 7c5dcf5d
claude setup-token 生成 CI 用的长期 OAuth token(需订阅) claude setup-token
claude ultrareview [target] 云端多智能体审查;--json、--post、--timeout claude ultrareview 1234 --json
claude purge [path] 删掉某项目的本地数据;--dry-run、-y claude purge . --dry-run
claude import [source] 从 Codex/Gemini/Cursor 导入配置 claude import codex --dry-run
claude gateway --config x.yaml 起企业网关服务 claude gateway --config gateway.yaml
claude remote-control 起 Remote Control 服务(别名 claude rc) claude remote-control --name "我的项目"

打错子命令会提示最接近的并退出:claude udpate → Did you mean claude update?


会话控制

参数 作用 例子
-c, --continue 续当前目录最近一次;跳过 -p 和 SDK 创建的会话 claude -c
-r, --resume [value] 按 ID / 名字 / .jsonl 路径恢复;不带值弹选择器 claude -r auth-refactor
--fork-session 恢复时新建 session ID,不覆盖原会话 claude -r abc --fork-session
-n, --name <name> 给会话起名,/resume 里可见;能按名字恢复 claude -n "修登录"
--session-id <uuid> 指定会话 ID(必须是合法 UUID) claude --session-id 550e8400-...
--add-dir <dirs...> 额外可读写目录(不会自动发现那里的 .claude/ 配置) claude --add-dir ../apps ../lib
-w, --worktree [name] 在 <repo>/.claude/worktrees/<name> 开独立工作区 claude -w feature-auth
--tmux 给 worktree 开 tmux 会话(需配 -w) claude -w x --tmux
--from-pr <n|url> 打开与某个 PR 关联的会话 claude --from-pr 123

非交互 / 脚本

参数 作用 例子
-p, --print 打印后退出 claude -p "..."
--output-format <fmt> text / json / stream-json,仅 -p claude -p "..." --output-format json
--input-format <fmt> text / stream-json,仅 -p --input-format stream-json
--json-schema <schema> 强约束输出结构,仅 -p;schema 非法直接报错 claude -p --json-schema '{"type":"object"...}' "..."
--max-budget-usd <amt> 花费上限,仅 -p。是客户端估算,可能超;子代理花费计入;-c/-r 恢复的历史不计入 claude -p --max-budget-usd 5.00 "..."
--max-turns <n> 限制 agentic 轮数,仅 -p;默认无限 claude -p --max-turns 3 "..."
--no-session-persistence 不落盘、不能恢复,仅 -p claude -p --no-session-persistence "..."
--bare 极简模式:跳过 hooks/skills/插件/MCP/auto memory/CLAUDE.md claude --bare -p "..."
--verbose 逐轮完整输出 claude --verbose
--include-partial-messages 流式片段,需 -p + stream-json claude -p --output-format stream-json --verbose --include-partial-messages
--include-hook-events 输出里带 hook 生命周期事件,需 stream-json 同上
--forward-subagent-text 把子代理文本/思考也输出,需 -p + stream-json claude -p --output-format stream-json --verbose --forward-subagent-text

权限

参数 作用 例子
--permission-mode <mode> default / acceptEdits / plan / auto / dontAsk / bypassPermissions;manual 是 default 的别名(v2.1.200+),两个值都能用 claude --permission-mode plan
--allowedTools, --allowed-tools 预放行,不弹框;不是限制能力 "Bash(git log *)" "Read"
--disallowedTools, --disallowed-tools 裸工具名从上下文移除该工具;带作用域(如 Bash(rm *))只拒绝匹配的调用 "Edit" 移除编辑;"mcp__*" 移除所有 MCP 工具
--tools <tools...> 真正限制可用工具集;"" 全禁,"default" 默认集 claude --tools "Bash,Edit,Read"
--permission-prompts <host|none> -p 下谁回答权限提问;none = 没人答,直接拒(v2.1.259+) claude -p --permission-prompts none "..."
--permission-prompt-tool <mcp tool> 用某个 MCP 工具处理权限提问 --permission-prompt-tool mcp__permissions__approve
--dangerously-skip-permissions 跳过全部检查,等同 bypassPermissions claude --dangerously-skip-permissions
--allow-dangerously-skip-permissions 把它加进 Shift+Tab 循环,但不从它开始 claude --allow-dangerously-skip-permissions
--restricted 受限模式:移除能执行命令/代码的工具和 WebFetch,文件工具限制在工作目录,只加载托管设置与 --settings,拒绝 bypassPermissions claude --restricted -p "..."

模型与成本

参数 作用 例子
--model <model> sonnet / opus / haiku / fable 或完整名 claude --model claude-sonnet-5
--fallback-model <models> 主模型不可用时按顺序回退,逗号分隔 claude --fallback-model sonnet,haiku
--effort <level> low / medium / high / xhigh / max / ultracode;可用值取决于模型 claude --effort high
--advisor <model> 开启服务端 advisor 工具,关键时刻咨询第二个模型 claude --advisor opus
--autocompact <auto|tokens> 自动压缩窗口,如 500k claude --autocompact 500k

扩展

参数 作用 例子
--agents <json|file> 动态定义子代理;-p 下可给文件路径 claude --agents '{"reviewer":{...}}'
--agent <name> 本次会话用哪个子代理 claude --agent my-reviewer
--mcp-config <configs...> 从 JSON 文件/字符串加载 MCP claude --mcp-config ./mcp.json
--strict-mcp-config 只用 --mcp-config 里的,忽略其他来源 claude --strict-mcp-config --mcp-config ./mcp.json
--plugin-dir <path> 临时加载插件目录或 .zip(可重复) claude --plugin-dir ./my-plugin
--plugin-url <url> 临时从 URL 拉插件 .zip(可重复) claude --plugin-url https://x/p.zip
--disable-slash-commands 禁用所有 skills 和命令 claude --disable-slash-commands
--channels <list> (研究预览)监听哪些 MCP channel claude --channels plugin:x@y

系统提示

参数 作用
--system-prompt <text> 替换整个系统提示
--system-prompt-file <path> 从文件替换
--append-system-prompt <text> 追加到默认提示后
--append-system-prompt-file <path> 从文件追加
--system-prompt-snapshot <on|off> off = 每次请求重建提示(调提示词时用)
--append-subagent-system-prompt(-file) 给所有子代理的系统提示追加内容,仅 -p

经验法则:

  • 它还得是个编程助手,只是多了你几条规矩 → 用 append
  • 你要换成完全不同的身份/权限模型 → 用 replace(连工具指引和安全指令一起没了,出事自己负责)

配置与设置

参数 作用 例子
--settings <file-or-json> 加载额外设置,覆盖同名字段,但多数列表是合并 claude --settings ./s.json
--setting-sources <list> 只加载指定来源:user,project,local claude --setting-sources user,project
--safe-mode 关掉所有自定义(CLAUDE.md、skills、插件、hooks、MCP…),排查配置冲突 claude --safe-mode
--exclude-dynamic-system-prompt-sections 把每台机器不同的内容挪出系统提示,提高多用户缓存命中 claude -p --exclude-dynamic-system-prompt-sections "..."

调试

参数 作用
-d, --debug [filter] 调试输出,如 --debug='mcp,startup' 或 --debug='!mcp'(过滤只在 = 形式生效)
--debug-file <path> 调试日志写文件(隐含开启 debug)
--verbose 完整逐轮输出

后台与云端

参数 作用 例子
--bg, --background 会话转后台,立刻返回并打印 ID claude --bg "排查这个测试"
--exec 配合 --bg,后台跑一条 shell 命令而不是会话 claude --bg --exec 'pytest -x'
--cloud [...] 建云端会话,或往已有会话补消息 claude --cloud "Fix the login bug"
--remote-control, --rc 开 Remote Control 会话 claude --rc "My Project"
--teleport 把云端会话拉到本地终端 claude --teleport
--ide 启动时自动连唯一可用的 IDE claude --ide
--desktop 用 Claude Desktop 打开当前目录(macOS / x64 Windows) claude --desktop
--chrome / --no-chrome 开关浏览器集成 claude --chrome

其他

参数 作用
-v, --version 版本号
-h, --help 帮助(不列全部参数)
--betas <list> 附加 beta 头(仅 API key 用户)
--teammate-mode <mode> agent team 队友显示方式:in-process / auto / tmux / iterm2

坑

  • --help 不列全部参数。 找不到某个参数时,先查官方 CLI reference,别断定它不存在。
  • --allowedTools 不是限制。它只是"预先放行"。真要限制用 --tools 或 --disallowedTools。
  • --disallowedTools 两种语义:裸名(Edit)从上下文移除;带作用域(Bash(rm *))只是拒绝匹配的调用。
  • --max-budget-usd 是客户端估算,会超。留余量;-p 之外无效。
  • --output-format、--json-schema、--max-turns、--max-budget-usd 都只对 -p 有效。
  • --permission-mode 的 manual 和 default 是同一个东西,--help 只显示前者。
  • --tools 管不到 MCP 工具,要禁用 MCP 得用 --disallowedTools "mcp__*"。
  • --bg 不能和 -p 混用。
  • 版本门槛:--permission-prompts 要 v2.1.259+,--restricted 要 v2.1.248+,--max-turns 等老参数没有门槛。

实测用例

用例 91-1 · --help 不列全部参数

本机 claude --help 的 --permission-mode 只列出:

(choices: "acceptEdits", "auto", "bypassPermissions", "manual", ...)

但 default 也是合法值:

claude --permission-mode default -p "只回答 OK"
OK

结论:--help 是"常用子集",不是"完备清单"。找不到某个参数,去查官方 CLI reference。


用例 91-2 · 预算超限是"跑完再非零退出"

claude -p "..." --output-format json --max-budget-usd 0.30
{ "total_cost_usd": 0.32769, "result": "...完整答案..." }

退出码 1,但答案和 JSON 都拿到了。

结论:脚本里"退出码 ≠ 0"不能一律当成"调用失败"。要区分:

情况 表现
预算超限 有完整 JSON,total_cost_usd > 预算
真失败 没 JSON,或 is_error: true

用例 91-3 · --allowedTools 不限制能力

claude -p "..." --allowedTools "Read" "Edit" "Bash"

在 -p 里仍会因为 Bash 需要审批而被拒(--permission-prompts none 下)。

结论:--allowedTools 是"预放行清单",不是"能力边界"。要限制就用 --tools。

2026-11-21 / 2.1.318


99 踩过的坑

遇到怪事先翻这一页。 一条一行,Ctrl+F 搜症状。
只收真实遇到过的,不凑数。


装不上 / 找不到命令

症状 原因 处理
claude : 无法将"claude"项识别为... 没装,或 PATH 没刷新 重开终端;还不行重装
升级了但 --version 还是旧的 装了两份,PATH 上有两个 where.exe claude,卸掉多余的
claude doctor 报安装问题 包管理器/版本通道异常 按它给的提示修,别自己猜
python3 报错但 python 正常 Windows 上 python3 是坏的 Store 别名 一律用 python
&& 在 PowerShell 里报错 用了 Windows PowerShell 5.1 升级到 7,或改用 ;
启动时卡在 "Is this a project you trust?" 第一次进这个目录,要你确认工作区 看完目录再选;它会读、改、执行文件

它"看不见" / "不知道"

症状 原因 处理
说找不到某个文件 压根没读过,或不在启动目录 明确点名文件;确认 cd 对了
不知道项目约定 没有 CLAUDE.md /init 生成一份,改到几十行
写了 CLAUDE.md 它还是不遵守 位置/文件名不对,或没在新会话里验证 /memory 看加载了哪些;/context 看 Memory files 有没有涨
子目录 CLAUDE.md 有时生效有时不生效 它不保证自动加载,靠它判断相关性去搜 提示词里点名那个目录;重要的约定放根目录
/init 直接改了我的项目 它会直接写文件,不弹确认 写完先 git status,不满意 git checkout
越聊越笨、开始重复 上下文塞满 /compact;换话题就 /clear
换目录后 --continue 续不上 续的是"当前目录"的最近会话 cd 回原目录,或用 --resume 挑
/clear 之后它说"好像你刚才在改测试" 那是从 git 状态推断,不是记忆 能说原话才是记忆,只能说文件变了就是推断

改了 / 没改 / 改错

症状 原因 处理
它说改了,但文件没变 它只展示了方案 git diff --stat 确认
贴出来的 diff 缺行、内容错乱 终端渲染 / 复制截断 别拿贴的 diff 审,用 git diff
你没让它改的文件被动了 指令没约束住 明说"不要动 X",然后 --stat 检查
改坏了想退回 — git diff 看清 → git checkout -- <file>
回退把自己没提交的改动也冲了 git checkout -- 会丢未提交修改 用前先 git diff;想留就 git stash

权限 / 被拦住

症状 原因 处理
每条命令都弹确认 在 manual 模式 正常。别为省事切 auto,改用 allow 规则
刚切 manual,又变回 auto 了 权限框选了选项 3 永远选 1
明明配了 deny 还是读到了 规则没命中 / 写错 实际试一次,别假设生效
配了 allow 还是弹框 规则是精确匹配,它实际跑的是复合命令 写成 Bash(git status:*),别写 Bash(git status)
想知道哪条规则拦住了我 — /permissions → Recently blocked 页
它不动手,只出计划 plan 模式 Shift+Tab 切模式
-p 跑起来没有确认框 非交互模式跳过工作区信任 只在信任目录用
-p 下配置没生效 设置校验失败被静默忽略 检查 settings 语法

脚本 / CI

症状 原因 处理
--output-format json 没用 只在 -p 下生效 加 -p
命令挂住不退出 进了交互模式 加 -p
-p 感觉卡死 单次调用本来就要 10–20 秒 有动画就等;60 秒以上无反应再加 --permission-prompts none
喂了空输入,它却答得很像回事 空管道不会报错,它会自己另找目标 喂前检查长度;让它先复述收到什么
PowerShell 脚本里 claude 莫名其妙退出码 1 $ErrorActionPreference='Stop' 把 stderr 当致命错误 $PSNativeCommandUseErrorActionPreference = $false
ConvertFrom-Json 报 unexpected character 多行输出被逐行解析 ($raw | Out-String).Trim() | ConvertFrom-Json
中文输出乱码 外部程序 UTF-8,PowerShell 按 GBK 解码 [Console]::OutputEncoding = [UTF8]
ConvertFrom-Json 解析失败 stderr 的警告混进了管道(只在自定义模型路由时出现) ... --output-format json 2>$null | ConvertFrom-Json
输出解析不了 拿到的是给人读的文本 --output-format json
以为 --allowedTools 限制了能力 它只是预放行,工具仍然可见 真限制用 --disallowedTools 或 --tools
成本超过 --max-budget-usd 客户端估算,可能超限;超了也是跑完再非零退出 留 20% 余量;脚本里别把非零退出一律当失败
脚本输出格式突然变了 项目里新装的 Skill 被 -p 子进程加载了 要求稳定输出时加 --disable-slash-commands
--continue 没接上脚本里的会话 【待核实】交互续接通常跳过 -p 会话 用 --resume <id>

MCP / Skill

症状 原因 处理
/mcp 里没有我的服务器 没配上 / scope 不对 查 claude mcp list,确认 scope
MCP 工具调用被拒 权限规则没放行 allow 里写 mcp__server__tool
不知道 MCP 工具的真名 /mcp 菜单只显示短名 claude -p "..." --output-format stream-json --verbose 2>$null | Select-String "mcp__"
自定义命令 /xxx 不存在 Skill 没被加载 / 名字不符 /help 看当前可用列表
Skill 调用了但不按模板输出 步骤没写死 步骤和输出格式都写死,别交给它发挥

认知类(最容易犯)

症状 真相
"它说这里有个 bug,应该就是有吧" 它说的是主张。要改的东西先跑命令验
"行号对得很准,结论应该没错" 行号只证明它读过那行,不证明结论成立
"它跑过测试了,所以通过" 自己再跑一次。all assertions passed 要亲眼看到
"测试是绿的,说明测到了" 绿的可能是假测试。改坏代码看它会不会红
"它把 diff 给我看了,所以已经改了" 展示 ≠ 写入。git diff 说了算
"这句只是顺便提一句,应该没错" 越是不影响结论的旁注,越没人去查,也越容易是编的
"我改回来就没事了" 没有 git 基线就没有"改回来"
"把 CLAUDE.md 拆成多个文件能省上下文" @ 导入是加载时展开的,一点没省。省上下文靠按需加载(子目录 CLAUDE.md、Skill)
"教程里它直接出计划,我这里先被问了一轮" 你装的 skill(如 brainstorming)改了它做事的方式。装插件不只多命令,还改流程
"/clear 之后彻底没了" 【待核实】同一进程内可能还能从回退菜单恢复;但别依赖它

一条通用的排查顺序

  1. 版本 — claude --version、claude --help,确认这个命令/参数存在
  2. 体检 — claude doctor
  3. 位置 — 我在哪个目录?它看到的是不是这个目录?
  4. 模式 — 状态栏是哪个权限模式?
  5. 最小化 — 删到最小可复现
  6. 证据 — git diff、实际命令输出,而不是它说了什么
  7. 记下来 — 症状 + 原因 + 处理,回到这一页