2026 年 1 月 2 日,Claude Code 的创建者 Boris Cherny 在 X 上发了一条 13 点的线程,开头说自己的配置「出乎意料地普通」。到 2026 年 11 月 8 日我们读取时,开头那条显示约 820 万次浏览,第 13 条约 57.5 万次。十个月对 Claude Code 来说很长:默认模型、默认权限模式、slash 命令的组织方式、本地会话与云端会话的切换方式都变了。所以本文不复述线程,而是把每一点放到当天的官方文档旁边逐条核对。
核对时我们用了官方最佳实践页给出的一把尺子:一条指令要么是非确定性的(写给模型看,由模型决定是否照做,例如提示词、CLAUDE.md、skill),要么是确定性的(由 Claude Code 这个 harness 执行,例如 hook、deny 规则、托管设置)。线程里有的做法属于前者,有的属于后者,两者的可靠程度完全不同。线程说得最重的一句是第 13 条:给 Claude 一条能验证自己工作的路径,最终质量会好两到三倍。本文的结构也围绕这个验证闭环展开。
边界先说清楚:我们没有运行 Claude Code,没有在任何真实仓库里启用这些 hook,所有 JSON、Markdown 与 shell 代码只做了离线语法检查。线程里提到的模型名、命令名与插件名,凡与现行文档不一致之处,文中均标注「线程描述」并指向当前页面。本文的几个数字(浏览量、文档版本号)都是 2026-11-08 当天的读数,不代表之后仍然如此。
1. 线程说了什么,我们核对了什么
线程的 13 点可以归成四组。第一组是会话编排:终端里并行跑 5 个本地 Claude、编号标签页、系统通知(第 1 点);再加 5 到 10 个 claude.ai/code 上的云端会话,用 & 把本地会话交给网页、偶尔用 --teleport 拉回来(第 2 点);全部用 Opus 4.5 加 thinking(第 3 点)。第二组是知识沉淀:团队共用一份进 git 的 CLAUDE.md,每周多次修改,Claude 一出错就加一条(第 4 点);代码评审时在同事的 PR 上 @ 提到 Claude,让 GitHub Action 顺手把经验写进 CLAUDE.md,作者称之为 compounding engineering(第 5 点)。
第三组是流程与权限:大多数会话从 Plan 模式开始,反复改计划,再切到自动接受编辑(第 6 点);每个高频内循环工作流都做成 slash 命令,放在 .claude/commands/(第 7 点);几个常用子代理,code-simplifier 在 Claude 做完后清理代码,verify-app 保存端到端测试说明(第 8 点);PostToolUse hook 负责格式化,处理模型漏掉的那约 10%(第 9 点);不用 --dangerously-skip-permissions,而是用 /permissions 预先放行安全命令并写进共享的 .claude/settings.json(第 10 点);Slack 走 MCP、BigQuery 走 bq CLI、Sentry 拉日志(第 11 点)。
第四组就是验证:长任务结束时让后台 agent 复核,或用 Stop hook 更确定地做这件事,或用 ralph-wiggum 插件(第 12 点);最后一条说验证可能是最重要的一件事,作者让 Claude 通过 Chrome 扩展测试 claude.ai/code 的每一次改动,打开浏览器、测 UI、迭代到可用为止,并强调验证手段因领域而异,可以是一条 bash 命令、一套测试、浏览器或手机模拟器(第 13 点)。我们核对的对象是 2026-11-08 的 code.claude.com 文档,下文凡写「现行文档」均指当天版本。
2. 13 点逐条对照:现行文档、机制类型与落地位置
下表是全文的索引。「机制」一列按最佳实践页的定义区分:模型决定,指 Claude 读到指令后自行判断;harness 强制,指 Claude Code 无论模型怎么想都会执行。注意同一个目标常常两种形式都有,例如「完成前必须通过类型检查」既可以写在 CLAUDE.md(模型决定),也可以做成 Stop hook(harness 强制),文档的建议是:如果你发现自己在 CLAUDE.md 里反复加重语气,这条就该变成 hook。
| 点 | 线程(2026-01) | 现行文档对应(2026-11-08) | 机制 | 落地文件或命令 |
|---|---|---|---|---|
| 1 | 5 个本地并行会话,编号标签页,系统通知 | 终端配置页:Ghostty、Kitty、iTerm2 可发桌面通知;并行工作建议每个会话用独立 worktree(claude -w) | 工具层,与模型无关 | claude -w feature-x;终端通知设置 |
| 2 | 5–10 个云端会话;用 & 交给网页;--teleport 拉回 | 云端会话页:--cloud 新建云端任务;--teleport 把云端会话拉回终端;CLI 不能把已有本地会话推到云端(线程描述的 & 交接未在文档找到) | 工具层 | claude --cloud ...;claude --teleport |
| 3 | Opus 4.5 加 thinking 处理一切 | 模型配置页:多数计划默认 Opus 5.5、medium effort;用 /effort 调节,不靠提示词措辞 | 模型决定(effort 影响思考量) | /model;/effort high |
| 4 | 团队共用一份进 git 的 CLAUDE.md,出错就加一条 | memory 页:CLAUDE.md 建议 200 行内;只写代码里找不到的;/init、/doctor、/doctor prompt-audit | 模型决定 | CLAUDE.md;.claude/rules/*.md |
| 5 | 评审时 @ Claude 把经验写进 CLAUDE.md,GitHub Action | GitHub Actions 页:/install-github-app 安装 App 与工作流;PR 或 issue 评论中 @claude 触发(线程写的是 /install-github-action) | 模型决定(Action 执行是确定的,内容是模型写的) | /install-github-app;.github/workflows/claude.yml |
| 6 | Plan 模式开局(Shift+Tab 两次),满意后切自动接受编辑 | 权限模式页:交互会话默认 auto 模式;Shift+Tab 从 auto 依次切到 default、acceptEdits、plan;或在提示前加 /plan;批准计划时选择之后的模式 | 模型决定(plan 模式下编辑被 harness 阻止) | Shift+Tab;/plan;claude --permission-mode plan |
| 7 | 每个内循环工作流做成 slash 命令,放 .claude/commands/ | skills 页:自定义命令已并入 skill;.claude/commands/*.md 仍可用;新写法 .claude/skills/<name>/SKILL.md,可加 disable-model-invocation | 模型决定(是否由你手动触发可配置) | .claude/skills/verify-app/SKILL.md |
| 8 | 子代理 code-simplifier、verify-app | 子代理页:.claude/agents/<name>.md,front matter 含 name、description、tools、model 等;tools 限制由 harness 强制 | 混合:触发由模型决定,工具范围由 harness 强制 | .claude/agents/code-simplifier.md |
| 9 | PostToolUse hook 格式化代码 | hooks 页与最佳实践页:matcher Edit|Write,命令读 .tool_input.file_path;可加 onFailure block | harness 强制 | .claude/settings.json hooks.PostToolUse |
| 10 | 不用 --dangerously-skip-permissions,用 /permissions 预放行并共享 settings.json | permissions 页:allow、ask、deny 规则;deny 在所有模式生效;共享文件的 allow 规则要等成员通过信任对话框 | harness 强制 | .claude/settings.json permissions |
| 11 | Slack MCP 进 .mcp.json;bq CLI;Sentry | 最佳实践页:有 CLI 先用 CLI;无 CLI 用 claude mcp add --transport http;/mcp 里关掉不用的服务器 | 工具层 | claude mcp add ...;.mcp.json |
| 12 | 长任务:后台 agent 复核,或 Stop hook,或 ralph-wiggum 插件 | hooks 页:Stop hook 以退出码 2 把 Claude 送回去,连续 8 次封顶,CLAUDE_CODE_STOP_HOOK_BLOCK_CAP 可调;/goal 是内置的替代;ralph-wiggum 插件在我们检查的仓库路径未找到 | Stop hook 为 harness 强制;/goal 由模型判定 | hooks.Stop;/goal <条件> |
| 13 | 给 Claude 验证路径,质量 2–3 倍;Chrome 扩展测 UI | 最佳实践页:给一个能返回通过或失败的检查;索要证据(命令与输出或截图);Chrome 页:claude --chrome,需要 Pro、Max、Ultra、Team 或 Enterprise 直连计划并用 /login | 检查本身确定,Claude 是否采信由模型决定;Stop hook 可强制 | scripts/verify.sh;claude --chrome;/verify |
Claude Code 文档:最佳实践 · Claude Code 文档:Hooks 参考 · Claude Code 文档:子代理 · Claude Code 文档:Memory 与 CLAUDE.md · Claude Code 文档:Skills(slash-commands 跳转至此) · Claude Code 文档:Chrome 集成 · Claude Code 文档:权限模式 · Claude Code 文档:权限规则 · Claude Code 文档:云端会话(--cloud 与 --teleport) · Claude Code 文档:GitHub Actions · Claude Code 文档:终端配置与通知 · Claude Code 文档:/goal · Claude Code 文档:模型配置
表里有三处与线程不一致,值得单独记住:第一,命令名从线程里的 /install-github-action 变成了现行文档的 /install-github-app;第二,线程说的「用 & 把本地会话交给网页」在云端会话文档里没有对应描述,文档明确写 CLI 的交接是单向的,只能用 --teleport 把云端会话拉回终端,--cloud 则是新建云端任务,桌面应用才能把本地会话发到云端;第三,ralph-wiggum 插件在我们检查的 anthropics/claude-code 仓库 plugins 目录下只剩一个 README,具体位置没有确认,所以本文只按「线程描述」提及,不给出安装方法。
Claude Code 文档:云端会话(--cloud 与 --teleport) · Claude Code 文档:GitHub Actions
3. 验证闭环:计划、实现、验证、证据、评审
把线程第 6、9、12、13 点连起来,就是一个完整的闭环:先在 Plan 模式里把「做什么」和「什么算完成」谈清楚;切到接受编辑后让 Claude 实现;每次编辑后 PostToolUse hook 自动格式化;Claude 准备结束时 Stop hook 跑类型检查或测试,不通过就把错误输出送回去继续改;通过后 Claude 给出证据,也就是它运行的命令、退出码与输出,或者一张浏览器截图;最后由没有参与编写的一方评审,可以是 /code-review 启动的全新子代理,也可以是另一位工程师。
闭环里哪几步是确定的?格式化 hook 和 Stop hook 由 harness 执行,测试与类型检查的结果由编译器与测试框架给出,这些不依赖模型的记忆。Plan 模式下「不许编辑源文件」也是 harness 挡住的。而「计划是否合理」「证据是否充分」「评审意见是否采纳」仍然是模型或人的判断。设计闭环时,把你绝对不能接受例外的那几步放进确定的一侧,其余交给模型。
最佳实践页对证据的要求很直接:「所有测试通过」这句话本身信息量很低,要看命令和输出;对于你没有盯着的会话,这是唯一的证据。第 8 节的 verify.sh 就是为这一步准备的,它把每次检查的退出码、耗时和日志路径写进一个带时间戳的 Markdown 文件,Claude、Stop hook 与评审者引用的是同一份东西。
- Plan 模式:读代码、提方案、约定「完成」的定义(Shift+Tab / /plan)
- 批准计划 → 切到 acceptEdits 或 auto,Claude 开始实现
- 每次 Edit/Write 后 PostToolUse hook 格式化(harness 强制)
- Claude 自己运行 CLAUDE.md 里写的检查命令,读输出,修到通过
- Claude 想结束 → Stop hook 跑 tsc / verify.sh,失败则退出码 2 送回(harness 强制,连续 8 次封顶)
- 通过 → 输出证据:命令、退出码、日志路径、截图(scripts/verify.sh 写入 .claude/evidence/)
- 独立评审:/code-review 的全新子代理,或另一位工程师对照计划读证据
- 合并由人批准;分支保护是最后一道确定性的闸门
Claude Code 文档:最佳实践 · Claude Code 文档:Hooks 参考 · Claude Code 文档:权限模式
4. CLAUDE.md:团队共用、出错即记、但要短
线程第 4 点的做法,现行 memory 页与最佳实践页都认可,但加了两条限制。其一是长度:memory 页写明每个 CLAUDE.md 文件目标 200 行以内,越长越占上下文、越降低遵循度;只对一部分代码有效的规则应移到 .claude/rules/ 下带 paths: front matter 的文件,只有 Claude 碰到匹配路径时才加载。其二是内容:只写 Claude 读代码读不出来的东西,例如会议上定的决策、只在某人脑子里的部署流程、集成测试需要的环境变量,以及你已经纠正过两次的事。架构和目录结构不用写,Claude 自己会读。
「Claude 一出错就加一条」仍然成立,但文档提醒了它的上限:CLAUDE.md 是非确定性的,无论语气多重,Claude 是否照做仍是它的判断。如果某条规则你已经反复加粗、加 IMPORTANT 还是会被漏掉,那它要么是因为文件太长而被淹没,要么就是一条不允许例外的规则,后者应改成 hook 或 deny 规则。下面是一份按这些原则写的示例文件,最后一段「完成的定义」是为第 3 节的证据要求服务的,它只能提高 Claude 给证据的概率,真正的强制在 Stop hook。
# Commands
- Install: pnpm install
- Typecheck: pnpm tsc --noEmit
- Run one test file: pnpm vitest run path/to/file.test.ts
- Full verification with evidence file: bash scripts/verify.sh
# Conventions
- Use the error helpers in src/lib/errors.ts; never throw raw strings
- src/legacy/ is still live, but do not copy its patterns into new code
# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
- src/gen/ is generated (2026-10-30: edited by hand once); run pnpm gen instead
# Definition of done
- Before saying a task is complete, show the command you ran and its output,
or the screenshot. "Tests pass" without output does not count.维护上有三个现成的命令:/init 从代码库生成初稿(已有文件时给改进建议而不是覆盖);/doctor 建议删掉 Claude 本来就能从代码看出来的行;/doctor prompt-audit 找出为旧模型写的、指向已不存在文件的、或互相矛盾的指令。会话里用 /context all 可以确认文件确实被加载。线程第 5 点的「在 PR 评审里让 Claude 顺手改 CLAUDE.md」依赖 GitHub Action:现行文档的安装命令是 /install-github-app,它安装 GitHub App、保存认证 secret、推一个包含工作流文件的分支并打开 PR;合并后在 issue 或 PR 评论里提 @claude 即可触发。注意这一步的产物是 Claude 写的文本,合不合进 CLAUDE.md 仍要人审。
Claude Code 文档:最佳实践 · Claude Code 文档:Memory 与 CLAUDE.md · Claude Code 文档:GitHub Actions
5. Plan 模式、权限规则与两条 hook:一个 settings.json 放齐
线程第 6 点说「Shift+Tab 两次进 Plan 模式」,这是 2026 年 1 月从默认手动模式出发的按键数。现行权限模式页写明,Claude Code v2.1.283 起交互式终端与 VS Code 会话默认从 auto 模式开始,一个分类器模型代替你审查有风险的动作;从 auto 按 Shift+Tab 依次切到 default(手动)、acceptEdits、plan。更省事的是在单条提示前加 /plan,或启动时用 claude --permission-mode plan。Plan 模式下 Claude 可以读文件、跑探索性命令、写计划,但不能改源码,这一点由 harness 保证;批准计划时你选择之后进入哪个模式,对应线程里「切到自动接受编辑」。
第 10 点的做法完整保留在 permissions 页:allow 规则预放行、ask 规则强制询问、deny 规则在所有模式下生效,包括 auto 与 bypassPermissions。两个边界要知道:Read(./.env) 这样的 deny 规则也会拦下 cat .env,因为 Claude Code 识别常见读文件命令,但拦不住一个打开该文件的脚本;WebFetch 的域名 deny 对 curl 无效,除非开了沙箱。另外,最佳实践页提醒 auto 模式的分类器是模型判断而非硬规则,你的「永远不许」应该放在 deny 规则或 hook 里。线程避开 --dangerously-skip-permissions 的态度与现行文档一致:文档把 bypassPermissions 限定在一次性容器里。
Claude Code 文档:最佳实践 · Claude Code 文档:权限规则 · Claude Code 文档:权限模式
{
"permissions": {
"allow": [
"Bash(pnpm tsc --noEmit)",
"Bash(pnpm vitest run *)",
"Bash(bash scripts/verify.sh)",
"Bash(git status *)",
"Bash(git diff *)"
],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\""
}
]
}
],
"Stop": [
{
"hooks": [
{ "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
]
}
]
}
}两条 hook 分别对应线程第 9 点与第 12 点。PostToolUse 的 matcher 是 Edit|Write,命令从 stdin 的 JSON 里用 jq 取 .tool_input.file_path 交给 prettier;文档注明,若文件是被 Bash 命令或外部进程改写的,这条 hook 不会触发,需要用 FileChanged 事件。Stop hook 的约定是退出码 2 阻止结束,stderr 的内容作为「还不能结束的原因」回给 Claude,所以示例把 tsc 的输出重定向到 stderr。hooks 页还给了两条安全阀:连续被 Stop hook 挡回 8 次(中间没有任何工具调用)后 Claude Code 会放行并结束本轮,环境变量 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP 可调;输入里的 stop_hook_active 字段为 true 表示本次已经是被 hook 送回来的,脚本应检查它,避免对永远无法满足的条件死循环。
如果 hook 本身挂了怎么办?默认情况下 hook 失败或超时时动作照常进行,只在记录里留一条错误。对于安全类 hook,可以加 onFailure: block,让 hook 启动失败也阻止动作;但 hooks 页特别指出,Stop 这类事件上 block 会把 Claude 送回去,而 Claude 修不好一条跑不起来的 hook,所以示例没有在 Stop hook 上加它。还要记住最佳实践页的提醒:被强制的规则集合要小,到了四十条,大多数大概是本来可以交给模型判断的偏好。
| 文件或位置 | 对谁生效 | 适合放什么 | 注意 |
|---|---|---|---|
| ~/.claude/settings.json | 你本人,这台机器上所有项目 | 主题、默认模型、个人 allow 规则、autoMode 配置 | autoMode 块只在这里生效,项目设置里会被分类器忽略 |
| .claude/settings.local.json | 你本人,仅此项目 | 个人覆盖;选「是,且不再询问」时规则存到这里 | Claude Code 创建时会自动加入 git 排除;手工创建需自己 gitignore |
| .claude/settings.json | 进入该目录的所有人 | 团队 allow/ask/deny、hooks、插件、环境变量 | deny 立即生效;allow 与 hooks 要等每位成员通过该目录的信任对话框 |
| 托管设置(managed-settings.json 等) | 组织内所有被下发的人 | 安全策略、合规要求 | 个人文件不能覆盖;是安全团队唯一该用的位置 |
| CLAUDE.md | 进入该目录的所有人 | 命令、约定、坑、团队决策 | 非确定性;建议 200 行内 |
| CLAUDE.local.md | 你本人,仅此项目 | 个人偏好、本地 URL、测试数据 | 加入 .gitignore;与 CLAUDE.md 一起加载 |
| .claude/rules/*.md | 所有人,但只在匹配路径时加载 | 某一目录或文件类型的规则 | paths: front matter 决定加载时机 |
| .claude/skills/、.claude/agents/ | 所有人 | 多步骤流程、子代理定义 | skill 可设 disable-model-invocation;子代理 tools 字段由 harness 强制 |
Claude Code 文档:设置文件与优先级 · Claude Code 文档:最佳实践 · Claude Code 文档:Memory 与 CLAUDE.md · Claude Code 文档:子代理 · Claude Code 文档:Skills(slash-commands 跳转至此)
6. Slash 命令变成 skill,子代理有了 front matter
线程第 7 点说命令放在 .claude/commands/。2026-11-08 的 slash-commands 文档地址直接跳到 skills 页,页首写明:自定义命令已并入 skill,.claude/commands/deploy.md 与 .claude/skills/deploy/SKILL.md 都生成 /deploy,老文件继续可用;新写法多了支持文件目录、front matter 与「由谁触发」的控制。对线程里「内循环工作流」这类有副作用或耗时的流程,文档的建议是加 disable-model-invocation: true,这样只有你输入 /verify-app 时才运行,Claude 不会自行触发。$ARGUMENTS 会被替换成你在命令后输入的参数。
下面这份 verify-app 对应线程第 8 点里保存端到端测试说明的那个子代理,但我们把它写成 skill 而不是子代理,原因是它需要在当前会话里操作浏览器并把证据交回来。allowed-tools 只在触发它的那一轮生效,预放行 verify.sh 与读取证据文件。内容上它要求 Claude 对每一步写下「做了什么、预期什么、看到什么」,并且禁止在没有证据时说「可用」。还要注意,现行 skills 页列出了内置的 /verify:它会构建并运行你的应用来确认改动,在没有记录过流程时会把成功的步骤写到 .claude/skills/verify/SKILL.md,仓库根目录下的这个记录会替代内置的 /verify,所以给自己的 skill 取名时避开 verify 这个名字。
---
name: verify-app
description: End-to-end check of the web app after a change. Runs the evidence script, drives the changed flow in the browser and reports what was seen. Use before opening a PR.
disable-model-invocation: true
argument-hint: [flow-name]
allowed-tools: Bash(bash scripts/verify.sh) Read
---
1. Run `bash scripts/verify.sh`, then read .claude/evidence/latest.md.
If any step shows a non-zero exit code, stop and report it.
2. Start the app with the command from CLAUDE.md and open it in the
connected browser (http://localhost:3000).
3. Exercise the flow named in $ARGUMENTS: the happy path, one invalid
input, one empty state.
4. For each step write down what you did, what you expected, what you saw.
Take a screenshot of the final state.
5. Report: commands with exit codes, the evidence file path, screenshot
paths, and every mismatch against the plan. Never write "works" without
attaching the evidence.子代理定义是 .claude/agents/ 下每个子代理一份的 Markdown 文件,项目级的进 git,个人级的放 ~/.claude/agents/。现行子代理页列出的 front matter 字段包括必填的 name 与 description,可选的 tools、disallowedTools、model、permissionMode、maxTurns、skills、memory、isolation 等。tools 一列是确定性的:写了 Read, Grep, Glob 的子代理就是一个不能改文件的评审者,这个限制由 Claude Code 执行而不是靠提示词请求。线程里的 code-simplifier 需要改文件和跑检查,所以下面给了 Edit 与 Bash;model: inherit 表示沿用主会话的模型。是否调用这个子代理由主会话的 Claude 根据 description 决定,你也可以在提示里直接点名。
---
name: code-simplifier
description: Simplifies code that was just written without changing behaviour. Use after the implementation passes its tests and before review.
tools: Read, Grep, Glob, Edit, Bash
model: inherit
---
You are cleaning up a diff you did not write. Work only on files changed
since the base branch: `git diff --name-only main...HEAD`.
- Remove dead code, duplicated helpers and abstraction layers used once.
- Keep public interfaces and observable behaviour identical. Add no features.
- After each file, run `pnpm tsc --noEmit` and the test file for that module.
- Finish with a table: file, lines before, lines after, commands run and
their exit codes. If a check fails, revert that file and say so.成本提醒来自最佳实践页:子代理的每次请求都计入你的用量,而且一个全新的子代理要先补上主会话已有的上下文,有时反而更慢;把同一任务交给子代理不会得到更聪明的答案,它带来的是并行、把长输出挡在主会话之外,以及一双没看过推理过程的眼睛。简单任务可以在定义里设 model: haiku 省钱。/usage 可以看每类子代理占了多少用量。
7. 验证手段因领域而异:哪种检查、什么证据、谁强制
线程第 13 点的核心不是 Chrome 扩展,而是「给 Claude 一个能返回通过或失败的东西」。最佳实践页列举的检查包括测试文件、构建的退出码、linter、把输出与 fixture 做 diff 的脚本、浏览器截图对照设计稿,并说如果仓库里已经有其中一种,CLAUDE.md 里最有用的一行就是运行它的命令。严格程度分四档:写在提示里(Claude 自己决定何时满意)、/goal(另一个模型在每轮后对照条件判定,适合长时间后台运行)、Stop hook(harness 强制,直到通过或触顶)、由没写代码的一方评审(/code-review 在全新子代理里看 diff)。
| 任务领域 | 检查手段 | 证据形式 | 谁强制 |
|---|---|---|---|
| 库 / 纯逻辑 | 单元测试、类型检查、lint | 命令、退出码、失败用例名 | 工具链判定;Stop hook 可保证执行 |
| CLI 工具 | 一条 bash 命令对照期望输出;diff fixture | 命令与 stdout/stderr 片段 | 脚本退出码;Stop hook |
| Web UI | Chrome 集成打开本地页面、填表、读控制台;/verify 构建并运行 | 截图、控制台错误清单、步骤记录 | 模型驱动浏览器;结果需人看截图 |
| 移动应用 | 模拟器中运行,按线程描述;文档未给出专门页面 | 截图、构建日志 | 模型决定;取决于你的工具链 |
| 数据 / 脚本 | 固定输入重跑,比对输出哈希或行数 | 输出文件哈希、行数、差异 | 脚本判定;可进 verify.sh |
| 长时间无人值守运行 | /goal 条件 + Stop hook + --max-turns | 证据文件 + PR 描述 | /goal 由模型判定;hook 与轮数上限由 harness |
Claude Code 文档:最佳实践 · Claude Code 文档:Chrome 集成 · Claude Code 文档:Skills(slash-commands 跳转至此) · Claude Code 文档:/goal
Chrome 这一项要单独核对前提。现行 Chrome 页写明:需要 Chrome、Edge 或其他 Chromium 浏览器与 Claude in Chrome 扩展 1.0.36 以上;需要 Pro、Max、Ultra、Team 或 Enterprise 的直连 Anthropic 计划并用 /login 登录,API key 或长期 token 认证时集成保持关闭,第三方云平台不支持;WSL 不支持。启动方式是 claude --chrome,或在 /chrome 里设为默认开启,但文档提醒默认开启会增加上下文占用。Claude 遇到登录页或验证码会暂停交给你处理。对线程里「测 claude.ai/code 每一次改动」的做法,你能复制的部分是:让 Claude 打开 localhost 上的页面、走一遍改动的流程、读控制台错误、截图;不能复制的是对方团队的具体测试内容。
无论哪一档,都要索要证据。最佳实践页的原话大意是:「所有测试通过」本身几乎没有信息量,读输出比你重跑更快,而对于没盯着的会话,它是唯一的证据。评审时还有一个反直觉的建议:让评审者「跳过风格」,否则一个被要求找问题的评审者总能找到点什么,照单全改会堆出多余的抽象层和不可能发生的用例的测试。
8. 证据脚本:一份文件给 Claude、Stop hook 与评审者共用
下面的 verify.sh 是本文的原创示例,离线做过 bash -n 语法检查,没有在真实项目中运行。它依次跑类型检查、测试与构建,把每一步的退出码、耗时和日志路径写进 .claude/evidence/<时间戳>.md,并把 latest.md 指向最新一份;最后把整份文件打到 stderr,这样作为 Stop hook 使用时(bash scripts/verify.sh || exit 2)Claude 看到的「不能结束的原因」就是这份证据。CLAUDE.md 第 1 段与 verify-app skill 都引用同一个命令,三处引用的是同一份输出。
#!/usr/bin/env bash
# scripts/verify.sh - run the project's checks and write an evidence file
# that Claude, a Stop hook and a human reviewer can all quote.
set -u
OUT_DIR=".claude/evidence"; mkdir -p "$OUT_DIR"
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
OUT="$OUT_DIR/$STAMP.md"
status=0
run() { # run <label> <command...>
local label="$1"; shift
local start; start=$(date +%s)
local rc=0
"$@" >"$OUT_DIR/$label.log" 2>&1 || rc=$?
printf -- '- %s: exit %s, %ss, log %s/%s.log\n' \
"$label" "$rc" "$(( $(date +%s) - start ))" "$OUT_DIR" "$label" >>"$OUT"
[ "$rc" -ne 0 ] && status=1
return 0
}
{
echo "# Verification evidence $STAMP"
echo "- commit: $(git rev-parse --short HEAD 2>/dev/null || echo none)"
echo "- changed files: $(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')"
} >"$OUT"
run typecheck pnpm tsc --noEmit
run tests pnpm vitest run
run build pnpm build
echo "- overall: $([ "$status" -eq 0 ] && echo PASS || echo FAIL)" >>"$OUT"
ln -sfn "$STAMP.md" "$OUT_DIR/latest.md"
cat "$OUT" >&2 # stderr, so "bash scripts/verify.sh || exit 2" works as a Stop hook
exit "$status"几个取舍说明。第一,是否把它整个挂成 Stop hook:每次 Claude 想结束都跑完整测试与构建可能很慢,第 5 节的 settings.json 只在 Stop 时跑 tsc,完整脚本由 skill 或提示词触发;如果你的套件只要一两分钟,直接挂上也行。第二,脚本有意不读 stop_hook_active,因为它每次都重新计算结果,不存在「永远无法满足」的条件,但如果你的检查依赖外部服务,就该在脚本开头读 stdin 的 JSON 并在 stop_hook_active 为 true 且连续失败时退出 0,把问题交回给人。第三,证据目录要不要进 git:建议 .gitignore 掉,只在 PR 描述里粘贴 latest.md 的内容,否则每次运行都会产生提交噪音。
把脚本与 CLAUDE.md 配合时,记住各自的角色:CLAUDE.md 告诉 Claude 这条命令存在,Claude 大概率会在做完后主动跑它;Stop hook 保证它在结束前至少跑过一次并通过;证据文件让人在不重跑的情况下核对。这正是最佳实践页所说的「typecheck 那一行只写命令」的原因:命令给模型用,强制交给 hook。
9. 从 1 月到 11 月,线程里哪些细节已经变了
线程第 1、2、3、11 点多是环境与工具选择,复制时要先看变化。第 3 点的 Opus 4.5 加 thinking 在当时是作者的选择;现行模型配置页写多数计划与提供方默认 Opus 5.5、medium effort,最佳实践页明确说 effort 是控制思考量的主开关,「think hard」之类措辞只是普通提示文本;线程里「更大更慢但少操心所以更快」的判断仍然值得参考,但模型名请以 /model 为准。第 1 点的并行会话现行文档的建议是每个会话用独立 worktree(claude -w feature-x),避免编辑冲突;通知方面终端配置页写 Ghostty、Kitty、iTerm2 可发桌面通知,iTerm2 需要先开启其提醒设置。
Claude Code 文档:模型配置 · Claude Code 文档:最佳实践 · Claude Code 文档:终端配置与通知
| 线程描述(2026-01) | 2026-11-08 文档状态 | 对团队的含义 |
|---|---|---|
| Opus 4.5 加 thinking | 默认 Opus 5.5、medium effort;/effort 调节 | 别把模型名写死进 CLAUDE.md;用 /effort 而不是提示词措辞 |
| Shift+Tab 两次进 Plan 模式 | 会话默认 auto;从 auto 要按三次,或直接 /plan | 文档里写 /plan 更稳 |
| 用 & 把本地会话交给网页 | CLI 交接单向:--cloud 新建,--teleport 拉回;桌面应用可发送本地会话 | 线程描述的 & 交接未在文档找到,按现行命令写流程 |
| .claude/commands/ 放 slash 命令 | 已并入 skill;老文件可用;新写法 SKILL.md | 新流程写 skill,可控制由谁触发 |
| /install-github-action | /install-github-app | 命令名已变 |
| --dangerously-skip-permissions 不用 | 仍存在;文档限定于一次性容器 | 态度一致;deny 规则在该模式下仍生效 |
| ralph-wiggum 插件 | 我们检查的仓库路径未找到 | 不要照线程安装;先确认来源 |
| 后台 agent 复核长任务 | 子代理默认后台运行;/goal 作为内置替代 | 长任务优先 /goal 或 Stop hook |
Claude Code 文档:模型配置 · Claude Code 文档:权限模式 · Claude Code 文档:云端会话(--cloud 与 --teleport) · Claude Code 文档:Skills(slash-commands 跳转至此) · Claude Code 文档:GitHub Actions · Claude Code 文档:Hooks 参考 · Claude Code 文档:子代理 · Claude Code 文档:/goal
第 11 点的工具接入原则没有变:有 CLI 先用 CLI,gh 装好登录后 Claude 不需要解释就会开 PR、读评审;没有 CLI 的系统用 MCP,命令是 claude mcp add --transport http 加上名称与服务器地址,之后在 /mcp 里可见。最佳实践页补了一条成本提醒:已连接的服务器即使不用也会把工具名和说明放进上下文,所以不用的要在 /mcp 里关掉。线程里 Slack 配置进 .mcp.json 共享的做法与此一致,但请把凭据放在环境变量而不是文件里。
10. 一周内在团队里复现:顺序与验收
按依赖关系排序,先做能被测试验证的部分。下面的顺序假设仓库已有测试或类型检查命令;如果没有,先补一条能返回通过或失败的命令,否则后面所有步骤都没有抓手。每一步都写了「怎么确认生效」,这些确认方法全部来自现行文档。
- 第 1 天:写 CLAUDE.md(第 4 节模板),只放命令、约定、坑、完成定义;/init 生成初稿后删到 200 行内;会话里 /context all 确认加载,/doctor 看建议。
- 第 2 天:提交 .claude/settings.json 的 permissions 部分;让每位成员在该目录通过信任对话框,否则 allow 规则不生效;用 /permissions 查看生效规则,故意让 Claude 读 .env 确认被拒。
- 第 3 天:加 PostToolUse 格式化 hook;让 Claude 往一个会被 prettier 处理的文件里加一行缩进错误的代码,保存后应被修正;用 /hooks 查看已注册的 hook。
- 第 4 天:加 scripts/verify.sh 与 Stop hook(先只挂 tsc);让 Claude 做一个会破坏类型的改动,它应该收到编译错误并继续修而不是结束;观察 8 次封顶是否出现,出现说明条件本身有问题。
- 第 5 天:加 verify-app skill 与 code-simplifier 子代理;用 /verify-app <流程名> 跑一次,核对证据文件与截图;让 Claude 调用 code-simplifier 并检查它汇报的命令退出码。
- 之后每周:评审时把反复出现的纠正写进 CLAUDE.md(或 GitHub Action 代劳);每月跑一次 /doctor prompt-audit;被强制的规则超过十来条时审视哪些其实是偏好。
Claude Code 文档:最佳实践 · Claude Code 文档:Hooks 参考 · Claude Code 文档:Memory 与 CLAUDE.md · Claude Code 文档:Skills(slash-commands 跳转至此) · Claude Code 文档:权限规则
验收标准建议只有一条:对任意一次由 Claude 完成的改动,评审者不重跑任何命令就能从 PR 描述或证据文件里看到跑了什么、退出码是什么、截图长什么样。做到这一条,线程第 13 点说的闭环就真正存在了;至于「质量 2 到 3 倍」是作者的经验判断,我们没有办法也没有尝试去复现这个倍数。
我们没有验证的事项:没有运行 Claude Code,因此没有观察到 Stop hook 的 8 次封顶、PostToolUse 的触发时机或 Chrome 集成的实际表现;没有确认 ralph-wiggum 插件的当前位置;线程中「用 & 把本地会话交给网页」的操作在现行文档中没有找到对应描述,我们无法判断它是否仍然可用;线程提到的浏览量是 2026-11-08 的读数;「质量提升 2 到 3 倍」是作者的个人经验,未经我们复现。本文分析的是 Anthropic 的公开文档与一位工程师的公开线程,本站与 Anthropic 没有任何关联;下方相关文章覆盖无人值守边界、账号邮箱外泄事件与研究者的使用报告。