模型是支点，
harness 才是杠杆

上下文：输入、保留与清理

内容只要仍在对话里，就会随后续每一轮再次发送。这包括 Claude 读过的文件和命令输出。一轮是指你或工具给出输入、模型作出回应的一次完整往返。命中缓存会降低重复发送的成本，但不等于免费；这些内容也持续占用上下文，模型每一轮都要处理。一次会话的成本可以从三个方面来看：

会话启动时已经加载的内容，可以用 /context 查看。CLAUDE.md 只保留具体指令，特定工作流的指令放进按需加载的 skill；本次不用的 MCP server 则用 /mcp 关闭。会话开始后，新增内容几乎都是工具结果。Claude 需要读取多少材料，很大程度上取决于任务描述留下了多少信息需要它自行查找：

用 @ 附加文件与让 Claude 读取文件，占用的上下文空间一样大。一个会话里 @ 一次就够，再 @ 一次通常会附上第二份。

另一类持续占用上下文的内容是命令输出。测试、构建和 git log 的输出，会像读入的文件一样追加到对话里，并随后续轮次反复发送。它们如何留在对话中，取决于是否超过输出阈值：

Claude 常会自行添加 flag，或用 tail 缩短命令输出。需要固定控制时，官方文档提供了一个 hook，在命令执行前改写命令，只返回要紧的行。也可以把每天反复使用的那两三条命令连同 quiet flag 一起写进 CLAUDE.md，保留平时实际输入的形式。例如，跑单个测试文件用 npx vitest run --reporter=dot，既省一轮交互，也省掉之后每个会话里几百行输出。

内容停留的轮数同样影响成本。同样的工作放在一个长会话里，比拆成几个短会话更贵。因此，开始新任务时用 /clear，避免继续携带上一项任务的上下文；同一任务的前半段完成后，则可以用 /compact 清理已经不再需要的细节。

如果之后还需要回到当前会话，可以在 /clear 前先用 /rename 命名。运行 /compact 时说明需要保留什么；如果每次要求相同，就在 CLAUDE.md 里写一段 Compact instructions。

使用 1M 模型时，如果希望把自动 compact 的触发位置恢复到原来的水平，可以用 /autocompact 200k。这需要 Claude Code v2.1.221 及以上，v2.1.288 起会按模型分别记住该设置。

没有手动输入时，会话也可能继续产生轮次。/loop 每次触发，都会在设置它的会话里运行完整一轮，并携带整段对话；距上一轮超过一小时，还会发生一次 cache miss。因此，可以在另一个终端开启新会话，专门运行这个 loop。/loop 只在本机运行，一次最长 3 天；合上电脑后仍需继续运行的任务，则使用云端的 /schedule。两者的分工见 官方给 loop 下定义。

Claude Code 提供了现成的 loop，也就是 agent 主循环。上下文是使用过程中需要管理的一项重要资源：输入什么、保留什么、何时清理，都会影响后续工作。Claude 每完成一步，都有 5 个选择，其中 4 个直接用于调整上下文：

compaction 会把整段对话总结成摘要，模型随后在全新窗口里基于摘要继续工作，因此它是一种有损压缩。风险之一在于自动触发的时机：窗口接近上限时，上下文已经变长，模型需要在可靠度下降的状态下决定哪些信息应当保留：

Claude 已读完 5 个文件，尝试方案 A 失败，接下来准备改用 B。此时可以直接纠正，也可以回退到尝试 A 之前：

配套的 "Summarize from here" 可以让 Claude 把已经学到的内容写成一条交接消息，例如「我试了 A，因……行不通」。将尝试过的方案和失败原因留下，有助于减少后续会话重复同样的尝试。

回退最后几轮时，rewind 的缓存成本也更低。它只从末尾移除这些轮次，前面仍有效的缓存可以继续复用，不会因回退而产生缓存重建费用。/compact 则需要生成摘要，后续请求使用的对话前缀也会改变，因此仍有成本。如果只是最后几轮走偏，适合 rewind 到它们之前，而不是用 /compact 整理整段对话。

分叉与 rewind 处理的是不同需求。rewind 把当前会话退回到此前的位置；/branch（命令行用 claude --resume <session-id> --fork-session）则从当前会话复制出一条新支线，原会话保持不变。需要尝试不确定的方向、同时保留当前进展时，可以使用分叉。

/compact 把对话压缩成摘要，/clear 清空对话后重新开始。两者的关键区别在于由谁决定保留什么：

新任务适合新会话。关联度高的任务可以继续当前会话，省去重读材料的开销；关联度低则适合 /clear。

是否使用 subagent，可以从所需结果来判断：「我要的是工具输出本身，还是只要结论？」只需结论时，可以把工作交给 subagent，让中间输出留在它的独立上下文里。但它没有主会话的对话，有时需要重读主会话已有的材料，这些轮次也消耗用量。小任务交出去可能只增加开销，主会话也只能拿回它选择汇报的部分。

同类、输出较多的任务如果需要反复委派，可以建立专用的 subagent 定义，写上 model: haiku；未指定时，它会沿用主会话当前的模型。

知识与工具：各自放在合适的位置

知识如何组织、工具如何配置，是 harness 影响工作结果的重要部分。除了模型能力，harness 本身也值得投入。Claude Code 找代码用的是 agentic search，即调用工具直接探索当前代码库，而不是依靠预建索引的 RAG（检索增强生成）：

直接探索代码库也需要足够的起始上下文，让 Claude 知道从哪里开始找。导航质量取决于 codebase setup，也就是代码库的上下文与导航配置。投入 codebase setup 的团队能拿到更好的结果。

2.2 从能力配置的角度组织七项能力；具体指令放在哪种载体，则是另一个问题。官方把可用载体归为七种，选择时可以比较四个方面：何时加载、压缩后是否还在、上下文成本，以及强制力。

Rules 是其中一种约束载体，放在 .claude/rules/。通过 paths: 字段限定作用域后，规则只在 Claude 读到匹配路径的文件时加载。不限定路径范围的规则，会像 root CLAUDE.md 一样全程常驻并占用 token；paths 的作用就是缩小加载范围。某个目录的约定适合放在嵌套的 CLAUDE.md 中；横跨多个目录的约束，如「所有 handler 先校验输入」，则更适合用 path-scoped rule，也就是按路径限定范围的规则。

---
paths:
  - "src/api/**"
  - "**/*.handler.ts"
---
All API handlers must validate input with Zod before processing.

绿色列「压缩后还在？」说明了载体在长会话中的保留方式。指令如果放在会被压缩丢弃的载体里，到会话后半程可能已不在上下文中。子目录 CLAUDE.md 在对应目录不再被访问时也会丢失。

哪些 CLAUDE.md 会在启动时加载，取决于会话的启动目录。启动时会加载 ~/.claude/ 中的用户级约定，以及通向启动目录的祖先链上每个 CLAUDE.md / CLAUDE.local.md；只有启动目录以下的子目录文件才按需加载。从子目录启动，会把整条链上的约定一并预载，既能获得所需的局部上下文，也会增加启动时的上下文负担。

Output styles 和 Append-system-prompt 多数情况下无需使用。Output styles 会覆盖默认系统提示；除非设置 keep-coding-instructions: true，原有的「你是软件工程助手」角色设定及其安全与验证习惯也会被移除。调整风格可以先考虑内置的 Proactive / Concise / Explanatory / Learning。其中，后加入的 Concise 会先给结果，省去开场白和复述。Append-system-prompt 只对本次调用生效，以叠加方式添加指令，不改变角色，但叠加的指令越多，遵从度越容易下降。

指令的内容也能帮助判断该用哪种载体。前面的表格比较各类载体的属性；「症状 → 换载体」速查则从 CLAUDE.md 中的内容出发，判断哪些指令适合移到其他位置。

「绝不能发生 X」需要 hook 加权限来约束，组织级强制约束则依靠 managed settings。只适用于 src/api/** 的规则，如果没有设置 paths:，仍会像写进根目录 CLAUDE.md 一样常驻上下文。

自动记忆与团队约定

过去，用户通过 # 热键把内容写进 CLAUDE.md 充当记忆；现在，Claude 会自动保存与工作和用户相关的记忆。自动记忆写在 ~/.claude/projects/<project>/memory/，每个 git 仓库根目录一份，与手写的 ~/.claude/CLAUDE.md、./CLAUDE.md 分开存储。/memory 用于配置，/dream 负责整理；后者的名字取自 REM 睡眠将短期记忆巩固为长期记忆的过程。

官方技巧合集也保留了团队的长期做法：纠正错误后，让 Claude「更新 CLAUDE.md，别再犯」；或在 PR 评论里 @claude，把 review 结论写进去。后者需要先运行 /install-github-app，团队称这种做法为 Compounding Engineering。被反复纠正、全团队都应遵守的具体约定，适合进入签入 git 的 CLAUDE.md；个人偏好和零散上下文则交给自动记忆。官方删减的是为防最坏情况而累积的宽泛禁令，不是具体的纠错记录。

Skill 是一个文件夹，SKILL.md 是它的入口。除 SKILL.md 外，文件夹里还可以放脚本、参考资料、模板，甚至专用的 hooks。它承载的不只是一段提示词，还包括执行流程所需的材料与工具。

每个 skill 的名字和描述都放在系统提示里，供 Claude 判断何时使用。选定 skill 后，Claude 通过一次普通的 Bash 调用，用 cat 读取对应的 SKILL.md，正文才进入上下文。文件中引用的 references/api.md 等资料，也等到实际需要时再用 cat 读取。正文和参考资料都由 Claude 通过通用工具按需获取，不由框架预先全部加载。

官方将 Skills 的常见用途归为九类，覆盖文档查询、开发工作流和运维：

Anthropic 从内部上百个 Skills 的实践中总结了九条最佳实践：

小团队可以把 skill 签入 .claude/skills 共享；规模化分发则使用 plugin marketplace，并做好质量筛选。PreToolUse hook 可以记录调用量，帮助了解哪些 skill 更常用。好 skill 往往从几行说明开始，再随着实际遇到的问题逐步完善。

用具体材料表达规格

rich references 关注的则是如何用具体材料表达规格，包括四种形态：artifacts 功能生成的 HTML artifact、一套详细的测试套件、另一个代码库里待移植的函数，以及一份 rubric，也就是评分标准。借助 dynamic workflows（动态工作流），可以启动 verifier agent（核验智能体），按评分标准核对某个领域中什么算做得好；官方举的例子是怎样的 API 设计才算好。作者认为代码通常优于文字描述和图片：“For example, a HTML mockup of a design will generally produce better results than a description of the design or a screenshot.”

Hook 可以挂在不同的事件上。截至 2026 年 10 月，已有三十多个事件，包括 PostToolUseFailure、PermissionDenied、PreModelSwitch / PostModelSwitch、InstructionsLoaded、ConfigChange、FileChanged。v2.1.295 起，还可以设置 onFailure: "block"，在 hook 自身出错时阻断操作。官方帮助中心的技巧合集列出了团队最常用的六种组合，其中 PermissionRequest 用于处理权限请求，让审批本身也能自动化。

"PostToolUse": [
  {
    "matcher": "Write|Edit",
    "hooks": [{ "type": "command", "command": "bun run format || true" }]
  }
]

Hook 的触发点覆盖 agentic loop，也就是智能体执行任务的循环过程，从 SessionStart 延伸到 SessionEnd。每轮工具调用都会经过 PreToolUse → 工具执行 → PostToolUse。Hook 配置保存在主上下文之外，不随 compaction（上下文压缩）被压缩；其中 PreToolUse 可以在工具执行前确定性地阻断调用，hook 以 exit code 2 退出即可拦下这次调用。图中右侧的虚线簇表示旁路或异步事件，它们独立于主流程触发。

MCP 用于把外部数据源和系统接入会话。这里讨论接入侧的使用，不涉及 MCP server 的设计。接入侧有两项降低开销的能力，都由客户端提供：

MCP 与 Skills 互补：MCP 提供工具和数据，Skills 提供操作知识，两者可以配合使用。（MCP server 五大设计模式不在本文范围。）

2026 年 7 月 24 日，Anthropic 随 Claude Opus 5 发布了 Thariq Shihipar 撰写的官方博客，给出了一份减少过度约束的具体清单。面向 Opus 5 与 Fable 5，Anthropic 删掉了系统提示词中 80% 以上的内容，自家的编码评测没有出现可测量的下滑。作者这样概括原因：“Overall, we found that we were overconstraining Claude Code, both through our system prompt and in our CLAUDE.md files and skills.”

问题不只是提示词太长，也在于旧指令彼此冲突。指令本身会占用上下文；冲突指令还会带来注意力成本，模型必须先消解矛盾，才能开始执行任务。

渐进式揭露不只用于 skill，也用于工具。Claude Code 的部分工具采用 deferred loading（延迟加载），agent 必须先用 ToolSearch 找到完整定义，才能调用。官方列举的例子是自家的 Task tools。这样，系统可以挂载更多工具，而完整定义在实际使用前不会占用上下文。2.7 节讨论的是 MCP 客户端如何降低外部工具的上下文开销，同一机制也用于 Claude Code 的内建工具。

早期模型有时需要重复提醒，也更倾向于遵从上下文末尾的指令，因此系统提示词会重复工具说明。现在这些重复内容可以删去，把用法直接保留在工具描述里。

官方提供了命令 claude doctor 来执行这类检查。在 Claude Code 中可以运行 /doctor，它现在是内置 skill，别名为 /checkup。它会从上下文成本出发，检查用不到的 skill、MCP server 和 plugin，也检查 CLAUDE.md 的重复内容与体量，以及拖慢会话的 hook。v2.1.283 起，还提供了 /doctor prompt-audit。

编排：计划该交给谁

编排要解决的是：任务计划由谁保存和推进，是让 Claude 在对话中逐回合决定下一步，还是交给脚本管理。基本原则是：小任务不拆分，大任务不让模型在上下文中独自记忆整个计划。

编排可以从自然语言开始，再把反复出现的做法固化下来：先对话，后自动化。

自定义 agent 既能接受委派，也能直接作为主会话运行。用 claude --agent <name> 按它的定义启动，或在 settings.json 中通过 "agent" 将它设为默认，就能为主会话指定相应的系统提示词。每个定义还可以单独设置 color、可用与禁用的工具、permission mode 和 model。官方给出的只读 agent 示例只开放 Read 工具：

# .claude/agents/ReadOnly.md
---
name: ReadOnly
description: Read-only agent restricted to the Read tool only
color: blue
tools: Read
---

You are a read-only agent that cannot edit files or run bash.

除了在单个会话内编排任务，也可以同时运行多个会话。官方帮助中心的技巧合集于 2026-10-16 更新，汇集了 Claude Code 团队工程师的日常用法。合集将这项做法称为最大的效率提升：同时跑 3 到 5 个会话，每个放在自己的 git worktree 里。每个会话使用独立的工作目录，避免同时修改同一份工作文件。

# .claude/agents/worktree-worker.md
---
name: worktree-worker
model: haiku
isolation: worktree
---

多个会话并行时，还需要能区分各自的任务和状态。团队会给 worktree 起名，用 za/zb/zc 这类 shell 别名切换目录，并为终端标签配色；/color 可以改变输入框颜色。终端通知则用于提醒哪个 Claude 需要人工处理。不少工程师还会专门保留一个 analysis worktree，只用于看日志、跑查询。

并行的前提仍是子任务彼此独立。worktree 可以隔离两个会话对工作文件的修改，却不能消除任务本身的顺序依赖（见 3.2 反模式）。合集将验证列为首要做法：每个并行 agent 都应能运行检查，为自己的改动提供验证依据。执行者自测与独立验收是不同的环节。

并行和长时间运行需要减少不必要的人工中断。权限清单、自动审批和沙箱各有作用，减少确认仍需以明确的权限边界为前提。

官方推荐预先放行安全操作，作为跳过权限检查的替代方案。这样既能减少弹窗，也保留了可审计的放行清单。规则支持完整通配，例如 "Bash(bun run *)"、"Edit(/docs/**)"。Claude Code 自带一小组预先批准的安全命令，/permissions 中添加的规则叠加在这组基线之上。整套权限机制包含提示注入检测、静态分析、沙箱和人工监督等层次。

/sandbox 提供三种模式：沙箱化 BashTool 并自动放行；沙箱化 BashTool，但保留常规权限检查；不用沙箱。沙箱、远程控制和云端定时任务默认关闭，也可能被组织策略禁用。命令返回 "not available" 时，多半是管理员尚未开放。

与 2.6 的权限边界一致：需要强制执行的约束应落实到权限和 hook 中，而不能只写在指令里。

编排：从委派到脚本

Subagent、Skill 与 Workflow 的区别，不只在任务规模，还在于那枚标着 PLAN 的方块由谁持有。使用 Subagent 或 Skill 时，Claude 逐回合推进计划，中间结果进入上下文；使用 Workflow 时，脚本持有计划和中间结果，Claude 只接收最终答案。

Workflow 与 Skill 分别解决编排和知识问题，可以组合使用。Skill 改变「模型知道什么」，Workflow 改变「如何确定性地编排」。一个 workflow 可以并行派出多个 agent，这些 agent 也可以先加载 skill，再执行各自的任务。

默认 harness 将规划与执行放在同一上下文中。长时间运行、大规模并行或对抗性任务，会暴露出三类失败模式。把计划交给脚本管理，正是为了减少这些风险：

Workflow 为这三类问题提供了结构上的约束：脚本保存完整清单，循环未遍历到末尾就不算完成，以此减少遗漏任务却提前结束的情况；验证交给另一个独立 agent，减少执行者对自己产出的偏袒；目标保存在脚本中，减少对 compaction 后对话记忆的依赖，降低目标漂移的风险。

循环以满足收敛条件为终点，不预设固定轮数。Workflow 可以通过 prompt 直接触发，例如写 ultracode 或说「use a workflow」；也可以用 /effort ultracode 打开 Ultracode 设置，或运行已保存的 command。它还自带 /deep-research。单次 parallel() 或 pipeline() 最多处理 4,096 项。

截至 2026 年 10 月，所有付费套餐，以及 Anthropic API、Bedrock、Google Cloud、Microsoft Foundry 都可使用 Workflow；Pro 需在 /config 中开启。组织可通过 managed settings 中的 "disableWorkflows": true 整体关闭。Workflow 的 token 消耗远高于普通会话，适合先用小任务试验。大 run 开始前，可通过 /model 将不需要最强模型的阶段路由到小模型。

成对比较（comparative judgment），即把两个候选放在一起判断，通常比逐个给出绝对分数更可靠，尤其适合排序类任务。

Workflow 的用途不限于编写代码。官方列出的九个用例中，过半与写代码无关：

并非每个任务都需要 Workflow。它的 token 消耗高得多，是否采用，取决于任务是否确实需要更多算力。多数传统编程任务并不需要一个五人评审团。

使用时，详细的 prompt 最关键。小任务可以采用 quick workflow，也可以配合 /loop、/goal，或写入 use 10k tokens 设置上限。满意的 run 可按 s 保存到 ~/.claude/workflows，或纳入 skill，作为继续探索其他用法的基础。

在脚本、CI 或 SDK 中调用 Claude Code，需要明确它会加载哪些配置。claude -p 以及 TypeScript / Python SDK 默认会搜索本地的 CLAUDE.md、settings 和 MCP。非交互场景应通过 --system-prompt、--mcp-config、--settings 显式传入配置，并加上 --bare，启动快约 10 倍：

claude -p "summarize this codebase" \
    --output-format=stream-json \
    --verbose \
    --bare

显式配置可以避免脚本中的 Claude 意外继承开发机上的个人设置，也让调用条件更容易复现。跨仓库工作时，用 --add-dir 指定其他目录的访问和权限，会话内则用 /add-dir。团队固定需要访问的目录，可以写入 settings.json 的 "additionalDirectories"。

云端会话和 Desktop 还支持 setup 脚本，用于在每次新建云端会话前安装依赖、修改设置、设置环境变量；resume 时跳过。