---
title: Claude Code 项目协作操作规范：开工前、会话中、中断前与脱手运行
description: 按项目与会话生命周期整理的必须遵守的规则，每条给出原因、保证方式与出处，基于 Claude Code 2.1.322
date: 2026-09-25
updated: 2026-11-10
author: DS-Dev
tags:
  - Claude Code
  - AI 工程
  - Workflow
  - Subagent
featured: true
---

前三篇 Claude Code 文章各有一个组织轴：[《成本优先的 Subagent 与 Workflow 调度实践》](/blog/fable-5-workflow/)写机制是什么，[《多代理调度 Prompt 与 Agent 配置模板库》](/blog/claude-code-agent-workflow-prompts/)写配置长什么样，[《我的 AI Agent Prompt Tips》](/blog/personal-ai-agent-prompt-tips/)写某个场景用哪段 Prompt。没有一篇按"人在什么时刻必须做什么"来组织，必须遵守的细节散落在分析段落里，读者能查到机制，却拿不到一份可执行的规范。

本文只做这一件事：按项目与会话的生命周期，把在项目中必须严格注意、在研发过程中与 AI 配合必须遵守的规则列出来。每条规则给四样东西：规则本身、为什么、由什么保证、出处。"由什么保证"这一栏要诚实：只有派发这一块是 Hook 和 settings 硬保证的，会话生命周期的规则大多靠习惯；本文随之新增了两个把习惯变成机制的东西，全局 `CLAUDE.md` 的 Compact instructions 和个人 `handoff` skill。

本文以本机 Claude Code 2.1.322 为基线，环境是 Max 20x 订阅、直连 Anthropic API、Windows 11、`defaultMode: auto`。主会话默认模型自 2026-09-25 起是 `opus` 别名所指的 Opus 5.5，Fable（2.1.321 起 `fable` 别名指 Fable 5.2）按会话切换：`/model` 打开选择器在 Fable 行按 `s`（仅本会话），或用 `claude --model fable` 启动；直接输入 `/model fable` 会把 `model: fable` 写进用户设置，之后的新会话都从 Fable 开始。档位按模型保存在 `modelSettings`，自 2026-11-10 起 Opus 5.5 与 Fable 5.2 都是 medium，Opus 的自动压缩窗口另设为 40 万 token。这些规则大部分来自实际使用中踩过的坑，机制与数字则逐条核对过官方文档。

## 一、开工前：一次性把规范定死

**1. 项目级 `CLAUDE.md` 控制在 200 行内，只写五件事。** 产品边界、架构、命令、变更政策、验收标准。模板在模板文章第五节。为什么：`CLAUDE.md` 每个会话和每个 Worker 都会加载，写进去的每一行都是长期成本，而且 Claude 与 auto 模式分类器读的是同一份，"never force push"这类规则写一次两边生效。保证方式：习惯，`/init` 起草后按模板裁剪。出处：costs 文档"Aim to keep CLAUDE.md under 200 lines"，auto-mode-config 文档"The classifier reads the same CLAUDE.md content Claude itself loads"。

**2. 路径专用规范进 `.claude/rules/*.md`，固定任务写成 `.claude/workflows/*.js`，Agent 角色沿用全局定义。** 为什么：路径规则只在 Claude 读、写或编辑匹配文件时（含 Bash 里对单个文件的 cat/head 等查看）才加载，不占常驻上下文；Saved Workflow 是审过的脚本，比每次让模型现写便宜也稳定；角色定义在 `~/.claude/agents/` 已经带模型、effort、工具集和 Hook 允许集，项目层重写只会制造第二套真相。保证方式：模板文章第六、八、九节；Hook 对 Workflow 脚本的模型检查。

**3. 授权边界在开工前写死，goal 不扩权。** 哪些动作本项目允许 Claude 自行执行（stage、commit、push、publish、破坏性操作各自单独列），哪些必须当轮授权。为什么：auto 模式默认允许推送到当前仓库任何分支并创建 PR，本机 `Bash(git:*)` 与 `PowerShell(git:*)` 这类 allow 规则又在分类器之前直接放行，所以 git 授权只由 `CLAUDE.md` 约束；`/goal` 条件写了"提交"，评估器就会把提交纳入终态。保证方式：全局 `CLAUDE.md` 的 Delivery and Git 段；需要硬门禁时同时加 `Bash(git push *)` 与 `PowerShell(git push *)` 两条 `permissions.ask` 规则（本机以 PowerShell 为主 shell，Bash 规则管不到 PowerShell 工具），任何模式都会弹窗。出处：auto-mode-config 文档 Common boundaries 与 Add a human checkpoint。

**4. 验收方式先定：test、lint、typecheck、build 的命令，以及"完成"的定义。** 为什么：这是三样东西的共同来源：`/goal` 条件里的验收命令、handoff 文件里的 Verification 段、Worker 定义里的 required verification。没有它，模型会自己定义"做完了"。保证方式：项目 `CLAUDE.md` 的 Acceptance 段。

**5. 按会话类型定模型与档位，写进项目文档。** 本机的分法：需要判断力的设计、评审、疑难排查会话用 Fable 5.2，从 medium 起步，不够时本会话 `/effort high`（在滑块上按 `s` 只作用于本会话）；脱手协调会话用 coordinator profile 的 Opus 5.5/high；日常实现会话用全局默认 Opus 5.5/medium，排查变难时本会话升到 high。这是官方选型指南的起点：Opus 5.5 与 Fable 5.2 都从 medium 开始，验证跟不上再升一级。为什么见第六节。保证方式：`settings.json` 的 `model` 与 `modelSettings`，`profiles/coordinator.json`。

**6. 第一次开工前跑一遍模板文章第十一节"落地前检查"。** 为什么：复制模板不等于形成硬控制，版本、Hook、profile、effort 档位每一项都要在本机验证过一次。保证方式：习惯。

## 二、每次会话开始

**7. 先定模型和 effort，之后不动。** 为什么：每个模型有独立的 prompt cache，中途 `/model` 让下一个请求把整段历史按未缓存输入重算；Opus 5.5、Sonnet 5.5、Haiku 5.5 与 Fable 5.1 及之后的 Fable 模型（含 Fable 5.2）在 API key 或订阅账户下改 effort 保留缓存（Bedrock、Agent Platform 与 apps gateway 不在此列），其他大多数模型改 effort 后下一个请求同样重算整段历史。在交互终端经 Anthropic API 时，提示里输入 `ultrathink` 会把当回合升到 xhigh（2.1.311 起，上述 Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.2、Fable 5.1 五个模型），不想要时设 `CLAUDE_CODE_DISABLE_ULTRATHINK`（2.1.316）。保证方式：习惯；缓存还热时 `/model` 会先确认。出处：prompt-caching 文档 Switching models、Changing effort level。

**8. 一句话说清任务、等级、验收方式；复杂任务先进 plan mode。** 为什么：模糊的请求触发全库扫描，plan mode 让方向错误在实现之前被纠正。保证方式：习惯；Tips 文章第二节的最小覆盖 Prompt。出处：costs 文档 Write specific prompts、Use plan mode for complex tasks。

**9. 首次委派前加载 `dispatch-policy`，L2 起先报账本再派发。** 派发计划由用户给角色，Claude 在计划内填账本，不设 Worker 数量的硬上限，但每一次启动都要有理由。为什么：Worker 数量本身不是成本，"启动次数 × 每个 Worker 装入的上下文 × 模型档 × effort"才是，所以约束的是加权启动总数而不是个数。保证方式：`dispatch-policy` skill 的 L0–L4 预算与账本规则；Hook 强制每次派发显式模型并拦截 Workflow 里的 Fable。下面这段可以直接放在任务 Prompt 里：

```text
Dispatch plan for this task. Fill the ledger inside it and do not add roles I did not list:
- Level: L2.
- implementer (opus/high) owns <files>.
- qa (sonnet/high) runs <verification commands> and reports raw results.
- reviewer (sonnet/high) reviews the final diff adversarially.
- Weighted total: 2 of the 4 Opus-equivalent starts. Explore starts on haiku may be added within the remaining budget.
Show the ledger before the first dispatch and update it only when the level or the remaining budget changes.
```

**10. 不相关的任务之间 `/clear`，先 `/rename` 便于回找。** 为什么：`/clear` 不花钱，而陈旧上下文让之后每一条消息都更贵。保证方式：习惯。出处：costs 文档 Manage context proactively。

## 三、会话进行中

**11. 中途不切模型、不打开 fast mode，tool search 不延迟加载工具时也不开关 MCP。** 为什么：切模型和打开 fast mode 必定让下一轮把整段历史重算一次，fast mode 那次重算还按 fast mode 费率计；连接或主动移除 MCP 服务器、开关提供 MCP 的插件，只在 tool search 没有延迟加载工具时才有同样代价（支持的模型上默认延迟加载）；插件的 skills、命令、Agent、Hook 等其他组件从不让缓存失效。保证方式：习惯；`/usage` 的 `Prompt cache (main)` 行会给出最近一次 miss 的可能原因。出处：prompt-caching 文档 Actions that invalidate the cache。

**12. 放弃一条路径用 `/rewind`，不是 `/compact`。** 为什么：`/rewind` 截回到一个已缓存的前缀，下一轮直接命中；`/compact` 生成新的更短历史，要重建。保证方式：习惯。出处：prompt-caching 文档 Rewinding the conversation。

**13. 给出可验证的目标，增量推进，走偏就按 Escape。** 为什么：Claude 能自证的工作，错误在你复查之前就被抓住；一次写一个文件、测一次，比整批返工便宜。保证方式：习惯；Worker 定义里的 required verification。出处：costs 文档 Work efficiently on complex tasks。

**14. 冗长的操作交给 Subagent，主会话只收摘要。** 跑测试、拉文档、翻日志都算。为什么：输出留在 Subagent 自己的上下文里，主会话不背这份长期成本。保证方式：`dispatch-policy` 的角色路由，qa 角色即为此设。出处：costs 文档 Delegate verbose operations to subagents。

**15. 长会话定期看 `/usage`。** 关注两处：`Prompt cache (main)` 行的命中率、miss 次数与 warm/cold；behavior flags 里的 long context 与 cache misses，占最近用量 10% 以上会被标出。为什么：这是唯一能把"额度怎么没的"落到具体行为上的证据。保证方式：习惯。

## 四、中断前与恢复：总结要趁热做

这一节纠正一个常见误解。缓存过期后恢复旧会话确实贵，但机制不是"之后每一轮都贵"，而是下一个请求把全部历史按未缓存输入重算一次并写回缓存，之后又回到缓存读取。sessions 文档写明，Pro/Max 上恢复一个闲置超过约 1 小时、超过 10 万 token 的会话会弹出对话框，无论选 Resume from summary 还是 Resume as-is，下一个请求都要把完整历史处理一次，因为生成总结本身就是一次全量读取。2.1.304 起 Pro/Max 上若恢复一个闲置会话会用掉 5 小时额度的明显份额，还会先给出警告，可以选择照样恢复，或者开一个新对话（之后提到旧对话时 Claude 能去查它）。真正省的是之后每一轮携带的上下文变小，而这一点在任何时候都成立。

主会话缓存的有效期：订阅账户在套餐额度内是 1 小时，开始扣 usage credits 后降到 5 分钟，API key 与云厂商默认 5 分钟。Subagent、Workflow、compaction 这类主会话之外的请求默认 5 分钟，本机用 `subagentPromptCacheTtl: "1h"` 延长。"30 分钟"是 `/goal` 等待后台任务时的 check-in 默认间隔，不是缓存有效期。

冷重建的代价按模型差别很大。下表是 API 标价，单位美元每百万 token，订阅额度的消耗大致同比：

| 模型      | 未缓存输入 | 1 小时缓存写入 | 缓存读取 |
| --------- | ---------- | -------------- | -------- |
| Fable 5.2 | 8          | 16             | 0.20     |
| Opus 5.5  | 4          | 8              | 0.20     |

一次 30 万 token 会话的冷重建，在 Fable 上约等于 80 轮热请求的缓存读取，在 Opus 5.5 上约 40 轮，而两者热请求的读取价相同。Fable 被中断惩罚得更狠，原因是它的缓存折扣更陡。主会话开 1M 上下文时，自动压缩窗口决定会话能长到多大，冷重建的代价随之放大。本机顶层是 `autoCompactWindow: 750000`；2026-11-10 起 `modelSettings` 给 Opus 5.5 单独写了 `autoCompactWindow: 400000`，per-model 值在该模型上优先于同一文件里的顶层键（`/autocompact` 写的也是 per-model 值），所以 Opus 主会话到 40 万压缩，其他模型仍到 75 万。依据是本机记录：2026-10-11 以来 30,365 次 Opus 主线程请求里 11,266 次超过 40 万 token，峰值 71.7 万，37 个会话越过 40 万；40 万以上那部分的缓存读取按 API 标价约 314 美元，这只是节省的下限，因为压缩后的会话从小上下文重新长起。官方选型指南的说法是"a lean main context matters more the bigger the main model is"。Subagent 也继承这个窗口；本机自 2026-10-15 起在 implementer 定义里写 `autoCompactWindow: 300000`（2.1.296 起可用，只能调低），因为一个月里约 13% 的 implementer 运行超过 30 万 token。

**16. 预计离开超过 1 小时且会话已超过 10 万 token，离开前先 `/handoff` 或 `/compact <重点>`，趁热做。** 为什么：缓存还热时 compact 只按缓存读取价计费，"只花上下文规模的一小部分"；冷了以后再做就是全价，"恢复旧会话时的 compact 最贵"。保证方式：`handoff` skill 与全局 `CLAUDE.md` 的 Compact instructions，见下文。交互会话里 20 万 token 以上的情况自 2.1.314 起由 Claude Code 自带的 idle compaction 处理：关闭 telemetry 也能运行，在最后一次请求后到一小时缓存窗口的 0.9（约 54 分钟）时压缩，接近用量上限时不动作。本机 2026-10-15 写的 `idle-compact` mod（当时内置功能依赖远程特性标志，关了 telemetry 用不上）保留为兜底：2.1.314 之后的会话记录里内置功能压缩 11 次，mod 只在内置功能没有触发的两次空闲里各压缩一次，没有重复压缩，而关闭 telemetry 时看不出内置功能为何没触发。`CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` 可以把交互会话的阈值降到最低 10 万，本机保持默认 20 万，所以 10 万到 20 万之间的会话以及需要一份交接文件时，仍靠这条规则；`-p` 会话内置功能与 mod 都不覆盖。过去一个月本机有 137 次在 10 万 token 以上空闲超过一小时才回来，冷重建的缓存写入按 API 标价约 556 美元。出处：prompt-caching 文档 Compacting the conversation；settings-reference 文档 idleCompaction；changelog 2.1.314。

**17. 回来时若已冷且会话大，选 Resume from summary；不选 as-is；永远不选 Don't ask me again。** 小会话直接继续，冷重建很便宜。2.1.304 起若先出现额度警告，不需要完整历史时可以开新对话、读 handoff 文件接着做（规则 18）。为什么：as-is 之后每一轮都携带全部历史；Don't ask me again 让对话框永久消失。出处：sessions 文档 Resume from a summary。

**18. 新会话第一句读 handoff 文件，不重推已记录的结论。**

```text
Read C:\Users\DS\.claude\projects\<project>\handoff\HANDOFF.md and continue from its Next steps. Treat its Decisions as settled and do not re-derive what it records. Before the first edit, run the Verification commands it lists and report their results.
```

**19. 开始扣 usage credits 后，主会话 TTL 自动降到 5 分钟。** 要保持 1 小时需设 `promptCacheTtl: "1h"`，但 1 小时缓存写入按更高费率计，短促的会话反而更贵。本机不设，因为常态在套餐额度内。出处：prompt-caching 文档 Which TTL each request gets、Choose the TTL yourself。

**20. 两个机制。** 第一个是全局 `CLAUDE.md` 新增的 Compact instructions 段：压缩时逐字保留任务与验收标准、验证命令及最新结果、每个改动文件及其改动、待授权与被阻断的动作、派发账本、当前 handoff 文件路径，丢掉能由文件或命令复现的工具输出；它对手动 `/compact` 和自动压缩都生效。第二个是 `~/.claude/skills/handoff/SKILL.md`，`/handoff` 按固定结构写 `~/.claude/projects/<project>/handoff/HANDOFF.md`，与 auto memory 目录并列、不进仓库：

```markdown
1. Header: task title, written at, repository and branch, model and effort, Claude Code version
2. Goal and acceptance, with authorized and explicitly unauthorized actions
3. Done, each step with its evidence
4. In progress, exact state of unfinished work
5. Decisions and why, including rejected options
6. Next steps, ordered, smallest first
7. Blocked or needs the user
8. Working tree: git status --short, files changed, user-owned dirty files
9. Dispatch ledger
10. Verification: exact commands and their last result
```

## 五、脱手长程任务：Goal + Workflow + Subagent

**21. 只在方案与目标都明确时脱手。** 为什么：goal 评估器只看对话里已出现的证据，不会自己跑命令；模糊的目标让它在"未满足"与"不可能"之间反复。保证方式：习惯；Tips 文章第三节的启动模板。出处：goal 文档 Write an effective condition。

**22. `/goal` 条件四要素：终态、验收命令、轮次或时间上限、授权边界。** 为什么：评估器按对话内容判断"or stop after 20 turns"这类条款；条件里没写的授权不存在。示例：

```text
/goal Complete W1-W7. Success means <verification commands> pass and the intended changes are staged but uncommitted, or stop after 30 turns. If the only remaining step lacks authorization, report that step and end.
```

**23. 派发计划由用户写，Claude 在计划内填账本。** 与规则 9 相同，脱手时更要在启动前看到账本。为什么：脱手会话没有人在中途纠偏，计划就是唯一的纠偏点。保证方式：`dispatch-policy`；Hook。

**24. 脱手会话用 coordinator profile 跑 Opus 5.5/high。** `claude --settings ~/.claude/profiles/coordinator.json`，主线程没有写入与 Shell 工具，只统筹不实现。为什么：脱手主会话的工作是拆解与验收，不是难题推理；Opus 5.5 的冷重建只要 Fable 5.2 的一半，而脱手运行恰恰最容易碰上冷缓存，见下一条。保证方式：profile 文件；`--settings` 位于用户设置之上，profile 顶层的 `effortLevel: high` 对所有模型生效，并压过用户设置里按模型保存的 medium。2.1.322 起另有一个待做的对照实验：同一 profile 加 `--model fable --effort medium`，让 Fable 5.2 统筹一次 L3 任务（`-p` 实测会话跑在 Fable 5.2、effort medium、agent 为 coordinator）。支持它的是官方选型指南把"leading many subagents"放在 Fable 5.2 一行，Fable 5.2 提示指南也说早期测试者用它做"planner and orchestrator for other models"效果好；反过来，同一份指南说它在鼓励委派的环境里"delegates readily"，而单价是 Opus 5.5 的 2 倍。实验要看两样：启动数是否守住预算，以及是否提前停下（coordinator 自己的提示替换了默认系统提示，没有 Claude Code 为 Fable 5.2 加的 Finishing work 段）。结论出来前默认仍是 Opus/high。

**25. check-in 会自己制造冷缓存。** 后台任务让 goal 等待时，check-in 在 30 分钟、之后 1 小时、之后每 2 小时各发一次，每次把完整上下文发一遍，两次 prompt 之间最多 3 次 idle check-in。第一次在 1 小时 TTL 内，后两次大概率是冷的；Workflow 超过 1 小时才结束时，结果送达那一轮也是冷的。两个缓解：把 `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` 设到 12 左右，让 12、24、48 分钟的 check-in 持续给缓存续期，这是从文档推导的做法，不是官方建议；或者接受一次冷重建，并按规则 24 让它发生在 Opus 5.5 上。设 0 会同时关掉 check-in 和自动重试。出处：goal 文档 Background work defers evaluation、costs 文档 Goal check-ins。

**26. 结束报告固定格式，不自动提交。** 证据、改动文件、失败的检查、剩余风险、未用的启动。为什么：脱手运行的产出必须能被验收而不是被相信；提交是授权动作。保证方式：全局 `CLAUDE.md`；Tips 文章第三节模板已含此格式。

**27. 碰到用量上限的行为要知道。** Workflow 碰到上限会暂停而不是让 Agent 失败；goal 碰到 usage limit 会 pause，`/rate-limit-options` 可以选择自动等待重置后继续，但 2.1.314 起在你没有新 prompt 的情况下最多自动继续 3 次，跨多个重置窗口的 `/goal` 也算在内。出处：goal 文档 Other errors retry or pause the goal、interactive-mode 文档。

## 六、模型与额度纪律

**28. 主会话默认 Opus 5.5，Fable 只用于需要判断力的会话。** 为什么：Max 上 Fable 5 系列（含 5.2）走常规周额度，最多占周额度 50%，且官方写明"消耗比其他模型快"；Opus 5.5 是 Max 的默认模型，Fable 在任何套餐都不是默认；两者热请求的缓存读取价相同，但 Fable 5.2 的未缓存输入与输出都是 Opus 5.5 的 2 倍。effort 是主会话消耗的另一半：2026-10-15 以来本机主会话 28,937 次请求里 28,891 次跑在 xhigh，其中 28,858 次 Opus 主线程请求按 API 标价约 3,104 美元。官方选型指南让 Opus 5.5 从 medium 起步，model-config 文档也写明"Opus 5.5 at `medium` matches or exceeds Opus 5 at `high`"，所以 2026-11-10 起 Opus 存为 medium；省下多少还不知道，因为历史里几乎没有 medium 回合可比，要用 `/model` 加 `/usage` 在同一任务上对比。Fable 5.2 也存为 medium：它的提示指南说 xhigh 只"raised scores slightly and used many more tokens"，并要求换代后重新试档，不沿用 Fable 5.1 的设置。它在 medium 更容易提前收尾，2.1.322 的默认系统提示已为 Fable 5.2 加了一段 Finishing work（本机 `-p` 实测，Opus 5.5 与自定义 agent 的提示里没有）。保证方式：`settings.json` 的 `model: "opus"`，`modelSettings` 里 Opus 5.5 为 medium（窗口 40 万）、Fable 5.2 为 medium。出处：Claude Fable models on your plan 支持文章、model-config 文档、prompt-caching 定价表、Which Claude model should you build with、Prompting Claude Fable 5.2。

**29. 派发按 `dispatch-policy` 的角色表，Fable Worker 只做一次关键判断。** 这是既有闸门，本文不重复；见调度实践文章第七节。

**30. 定期 `/usage`，偶尔 `/insights`。** attribution 能看出 skills、subagents、插件、MCP 各占多少；`/insights` 看的是工作方式而不是 token 数。为什么：主会话消耗快的原因通常不止一个，本机能想到的三个是高档 effort 的思考（含输入 `ultrathink` 的回合，规则 28 有本机数字）、主会话逐字读 Subagent 报告、以及 2.1.282 之前 `DISABLE_TELEMETRY=1` 的 auto 模式不走服务端审查而本地跑分类器（2.1.282 起默认走服务端），只有 `/usage` 能分清是哪一个。2.1.319 起关闭 telemetry 的 auto 模式不再回退到本地分类器：服务端审查不了的调用在交互会话里改为询问，在 Subagent 与 `-p` 里直接拒绝（`-p` 随之以 1 退出）；只有 `CLAUDE_CODE_AUTO_MODE_SERVER=0` 还能用本地分类器。本机经本地 HTTP 代理的 `-p` 实测拿到了服务端结论，这个变量保持不设。

## 七、Claude Code 升级后

**31. 升级只在下次启动生效，升级后第一次会话缓存从头建。** 这是正常现象，不要在长会话中途重启。出处：prompt-caching 文档 Upgrading Claude Code。

**32. 每次升级后复核一轮。** 步骤固定：读 changelog；下载受影响的文档页；从 `claude.exe` 提取 bundled `workflow-authoring` 文本与覆盖版比对；跑 Hook 用例；更新四篇文章与 `ds/` 仓库的版本行。本轮记录：2.1.281 与 2.1.282 的 bundled 文本与 2.1.280 只差运行时占位符，Hook 116 个用例全部通过；两版直接相关的条目是恢复会话时重发历史的多处修复（避免 prompt cache 被打断、丢失早先的推理）、`--continue` 与 `--resume` 恢复大会话更快、compaction 请求被拒绝时改用回退模型重试、`attribution: false` 简写、telemetry 关闭时 auto 模式默认改为服务端分类器（`CLAUDE_CODE_AUTO_MODE_SERVER=0` 退出）、`AGENTS.md` 在 telemetry 关闭的会话里也生效、`--agents` 接受 JSON 文件路径、`/workflows` 里 `x` 可停止运行且提示栏显示 Agent 数与 token 数。2026-10-11 复核 2.1.283 至 2.1.296 的记录：`sonnet` 与 `haiku` 别名改指 Sonnet 5.5（2.1.284）与 Haiku 5.5（2.1.293），两者与 Opus 5.5 一样默认 medium，改 effort 也保留缓存；Agent 工具新增按调用的 `effort` 参数（2.1.292），覆盖定义里的 effort，Hook 在 Fable 角色上拒绝它；`CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL`（2.1.296）设为 `inherit` 以外的值时就丢弃每个 workflow agent 的 `model`，本机保持不设；`onFailure: "block"`（2.1.295）单独使用时，脚本路径写错的 `powershell.exe -File` 退出码低字节为 0，仍被记为成功，所以 Hook 注册改为 `-Command` 包装并加 `onFailure: "block"`；`/autocompact` 改为按模型保存（2.1.288）；model-config 文档写明 Subagent 内分类器命中会不经询问回退到类别回退模型（2.1.318 起改为失败，见下）；in-process Teammate 采用具名定义里的 effort；同时带 `script` 与 `scriptPath` 的 Workflow 调用实测执行的是内联脚本，与文档相反，Hook 改为拒绝同时带多个来源的调用。Hook 130 个用例全部通过。2026-10-15 检查 2.1.299 与 2.1.300：内置的空闲压缩依赖特性标志，本机改用 `idle-compact` mod；implementer 加 `autoCompactWindow: 300000`；压缩后技能列表不再重发，需要时用 `/reload-skills`（2.1.299；2.1.304 起压缩后会重发技能列表，`/reload-skills` 只发新增或改动的技能）；其余条目不影响本文规则。2026-11-09 复核 2.1.301 至 2.1.319（2.1.313 与 2.1.315 未发布）：内置空闲压缩自 2.1.314 起在关闭 telemetry 时也运行，通常先于 mod 触发，`idle-compact` mod 保留为兜底（规则 16）；2.1.318 起在 `switchModelsOnFlag: false` 下，Agent 工具派发的 Subagent 被分类器标记后直接失败，不再在回退模型上重跑，Fable Worker 因此改为在对应常规角色上以 opus/high 重跑一次，再被标记就交给用户；未设 effort 的 Subagent 与 Teammate 只在主会话同一模型上继承会话 effort（2.1.317），`CLAUDE_CODE_SUBAGENT_EFFORT`（2.1.316）保持不设；关闭 telemetry 的 auto 模式不再回退到本地分类器（2.1.319，规则 30）；用量上限自动继续最多 3 次（2.1.314，规则 27）；Pro/Max 恢复闲置会话前的额度警告（2.1.304，第四节）。Hook 130 个用例在 2.1.319 上全部通过。2026-11-10 复核 2.1.321 与 2.1.322（2.1.320 未发布），并对照官方选型指南"Which Claude model should you build with"：2.1.321 把 `fable` 别名改指 Fable 5.2（每百万 token 8/40 美元，缓存读取 0.20），按 `claude-fable-5-1` 保存的 xhigh 不再匹配，Fable 会话因此悄悄落到 5.2 的默认 medium；重新定档后 Opus 5.5 与 Fable 5.2 都存为 medium，Opus 的自动压缩窗口降到 40 万（规则 5、28，第四节）；`dispatch-policy` 的 fable 权重从 2.5 改为 2，升级顺序改为指南的三步：先确认 Worker 能用测试、构建或脚本验证自己的工作，再升一级 effort，最后换大一号模型并从更低 effort 起步，关键 Fable 角色例外，保持 high；2.1.321 与 2.1.322 的 bundled 文本与 2.1.319 只差压缩后的标识符；Hook 130 个用例与 mod 7 个用例在 2.1.322 上全部通过。

## 八、速查表

| 时机 | 规则 | 保证方式 |
| --- | --- | --- |
| 开工前 | 项目 `CLAUDE.md` 200 行内，只写边界、架构、命令、政策、验收 | 习惯 |
| 开工前 | 授权边界写死，goal 不扩权 | 全局 `CLAUDE.md`；`permissions.ask` |
| 开工前 | 验收命令与"完成"的定义先定 | 项目 `CLAUDE.md` |
| 开工前 | 按会话类型定模型与档位 | `settings.json`；coordinator profile |
| 会话开始 | 先定模型与 effort，之后不动 | 习惯；`/model` 热缓存确认 |
| 会话开始 | 首次委派前加载 dispatch-policy，L2 起先报账本 | skill；Hook |
| 会话开始 | 不相关任务之间 `/clear` | 习惯 |
| 会话中 | 不切模型、不开 fast mode；无延迟加载时不开关 MCP | 习惯；`/usage` miss 原因 |
| 会话中 | 放弃路径用 `/rewind` | 习惯 |
| 会话中 | 冗长操作交给 Subagent | dispatch-policy 角色路由 |
| 中断前 | 离开超过 1 小时且会话大：先 `/handoff` 或 `/compact` | handoff skill；Compact instructions；20 万以上由内置 idle compaction 处理、idle-compact mod 兜底 |
| 恢复时 | 冷且大选 Resume from summary，不选 as-is | 习惯 |
| 脱手 | 条件四要素；派发计划由用户写；coordinator profile 跑 Opus | goal 评估器；dispatch-policy；profile |
| 脱手 | check-in 间隔与 1 小时 TTL 对齐，或接受一次冷重建 | `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` |
| 额度 | 主会话 Opus 5.5/medium（窗口 40 万），Fable 5.2 只用于判断会话，占周额度上限 50% | `settings.json` 的 `modelSettings` |
| 升级后 | 复核 changelog、文档、bundled skill、Hook 用例 | 习惯；`ds/CHANGELOG.md` |

## 参考资料

- [How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching)
- [Manage sessions](https://code.claude.com/docs/en/sessions)
- [Manage costs effectively](https://code.claude.com/docs/en/costs)
- [Keep Claude working toward a goal](https://code.claude.com/docs/en/goal)
- [Configure auto mode](https://code.claude.com/docs/en/auto-mode-config)
- [Choose a permission mode](https://code.claude.com/docs/en/permission-modes)
- [Model configuration](https://code.claude.com/docs/en/model-config)
- [Claude Fable models on your plan](https://support.claude.com/en/articles/15424964-claude-fable-models-on-your-plan)
- [Prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with)
- [Prompting Claude Fable 5.2](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2)
- [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
- [Dongshan-git/skills ds/](https://github.com/Dongshan-git/skills/blob/main/ds)