Chapter 15 · Domain 3（本章 skill 权重合计 3.1%）

Claude Code Operation
五件套、会话命令与三种运行方式

本章只解决一个考场动作：看到一个需求，立刻把它放回正确的 Claude Code 组件、目录或运行 flag。TS 3.1 点名 Rules、Skills、Commands、Agents、Agent Memory，以及 session management、slash commands、headless、streaming、auto mode、repository initialization、CLAUDE.md 与 settings.json；权重虽薄，名词密度却是全书最高。

与 ch04 的分界 — ch04 讲 settings / CLAUDE.md 的文件层级、优先级与版本管理；本章讲 Claude Code 运行时如何调用组件。这里会给出启动所需的最小层级速查，但不重复配置体系的完整推导。

一、五件套：先看载体，再看何时进入运行

guide 把五个名词并列，并不表示它们是五种同形配置。Rules 与 Skills 都是指令，却分别服务于「按主题／路径持续生效」和「按任务调用」；Commands 是会话入口；Agents 隔离执行上下文；Agent Memory 才让某个 subagent 跨 conversation 积累自己的知识。

组件	它是什么	project 载体	进入运行的时机
Rules	按主题拆开的 project instructions，可用 `paths` 限定文件范围	`.claude/rules/*/.md`	无 `paths` 的启动加载；带 `paths` 的在 Claude 处理匹配文件时适用
Skills	可复用的指令包；Claude 可按相关性调用，用户也可键入 `/skill-name`	`.claude/skills/<name>/SKILL.md`	默认先加载 description，使用时才加载正文
Commands	会话内的 `/name` 入口；built-in 多为 CLI 固定逻辑，custom command 已并入 Skills 机制	新流程优先用 Skill；旧式单文件仍可放 `.claude/commands/<name>.md`	用户键入对应 slash command 时
Agents	自带 system prompt、可限制工具的 custom subagent；定义是 YAML frontmatter 加 Markdown 正文	`.claude/agents/<name>.md`	Claude 委派或用户显式调用时，在自己的 context window 中运行
Agent Memory	由 subagent frontmatter 的 `memory` 开启的独立持久目录	`.claude/agent-memory/<agent>/`（`project` scope）	启动该 subagent 时，把其 `MEMORY.md` 前 200 行或 25KB 中先到的部分放入 system prompt

文件形态要成组记。Skill 必须有 SKILL.md，内容由 YAML frontmatter 与 Markdown instructions 组成，directory name（或你在 frontmatter 里设了的 name）是 slash command 名，description 帮 Claude 判断是否自动加载。Agent 也是 frontmatter 加 Markdown，但正文是 subagent 的 system prompt，只有 name 与 description 必填。旧式 command 文件支持 Skill 的 frontmatter，但 name 与 paths 在 command file 里会被忽略；它按文件名调用。

Agent Memory 不是主会话 auto memory 的别名。普通 subagent 不自动加载主 conversation 的 auto memory；要让它跨 conversation 记住东西，应在自己的 definition 里设置 memory: user、project 或 local。三者依次落在 ~/.claude/agent-memory/<agent>/、.claude/agent-memory/<agent>/ 与 .claude/agent-memory-local/<agent>/；其中 project 可进版本控制，local 用于不应提交的项目内知识。

真伪速查 1 · 五件套的真实落点

.claude/rules/**/*.md                    ✔ Rules · project，递归发现 Markdown
.claude/skills/<name>/SKILL.md           ✔ Skills · project
~/.claude/skills/<name>/SKILL.md         ✔ Skills · personal
.claude/commands/<name>.md               ✔ legacy custom command · 仍受支持
.claude/agents/<name>.md                 ✔ Agent · project
~/.claude/agents/<name>.md               ✔ Agent · personal
.claude/agent-memory/<agent>/            ✔ Agent Memory · project scope
.claude/agent-memory-local/<agent>/      ✔ Agent Memory · local scope

settings.json · "rulesDirectory"         ✘ 不存在 · 自制干扰项
settings.json · "commandsDirectory"      ✘ 不存在 · 自制干扰项
settings.json · "agentMemoryPath"        ✘ 不存在 · 自制干扰项

二、会话与 slash commands：继续、切换、清空、初始化

Claude Code session 是与 project directory 绑定、工作时持续本地保存的 conversation。恢复入口要按动作区分：claude --continue 直接续上当前目录最近的 interactive session；claude --resume 打开 picker；claude --resume <name> 按名字恢复；运行中的 /resume 则切到另一个 session。

/clear 是「开始一个新 session」，不是删除历史 transcript。要回到旧工作用 resume；要在同一长会话里减少 context，则是 /compact 的职责，见 ch11。把「换 conversation」与「压缩 conversation」分开，是会话管理题的第一刀。

slash commands 也有两种执行形态。多数 built-in command 的行为写在 CLI 里；bundled Skill 与你自建的 Skill 则是交给 Claude 的 prompt。对 custom slash command，当前官方推荐用 .claude/skills/<name>/SKILL.md；.claude/commands/deploy.md 与 Skill 目录都能生成 /deploy，旧文件继续可用，但 Skill 还能打包 supporting files，并控制是用户调用还是 Claude 自动调用。

repository initialization 的准确动作只有一个：/init 分析 codebase，生成一份包含它发现的 build commands、test instructions 与 project conventions 的 starter CLAUDE.md；若 CLAUDE.md 已存在，它提出改进建议而不是覆盖。因此它不是 package manager initializer，也不是创建 settings.json、Rules、Agents 的万能脚手架。

真伪速查 2 · 会话与初始化入口

claude --continue                         ✔ 续上当前目录最近的 interactive session
claude --resume                           ✔ 打开 session picker
claude --resume <name>                    ✔ 按名字恢复 session
/resume                                   ✔ 在 active session 内切换到另一个 session
/clear                                    ✔ 开始新 session
/init                                     ✔ 生成或改进 starter CLAUDE.md

claude --resume-latest                    ✘ 不存在 · 自制干扰项
claude --new-session                      ✘ 不存在 · 自制干扰项

三、headless、streaming、auto mode：三条轴不要串

headless 是交互形态，streaming 是输出形态，auto mode 是权限形态。三者可以组合，却互不替代。把它们压成一条「自动运行模式」是本章最危险的记忆法。

Headless：给任意 claude 命令加 -p（或 --print）即可 non-interactive 运行，官方把它定位为 scripts / CI/CD 的 CLI 入口。默认输出是 plain text；要一次拿结构化结果用 --output-format json，其中含 result、session ID 与 metadata。

Streaming：--output-format stream-json 表示 newline-delimited JSON 的实时流；若 consumer 要收到逐 token 的 partial messages，完整组合是 --verbose --include-partial-messages。最后一行仍是 result message，带 final response、cost 与 session metadata。这不是 Messages API 的 SSE 格式；前者是 Claude Code CLI 的 NDJSON 输出，后者见 ch02。

Auto mode：准确入口是 --permission-mode auto。独立 classifier 在动作运行前审查，阻止超出用户请求、指向未识别基础设施或疑似由 hostile content 驱动的动作；显式 ask rule 仍会强制 prompt，而且官方明确警告 auto mode 不保证安全。更关键的分层是：classifier 在 permissions system 之后运行；绝不能发生的动作应由 managed settings 的 permissions.deny 先行阻断，classifier 与用户 intent 都不能覆盖。这正是 P3「拦得住的才叫控制」在 auto mode 上的落点。

真伪速查 3 · 运行 flags 与 settings 键

claude -p "…"                            ✔ non-interactive / headless
claude --print "…"                       ✔ -p 的长写法
--output-format json                      ✔ 单次结构化 JSON
--output-format stream-json --verbose \
  --include-partial-messages              ✔ 逐 token 的 NDJSON 事件流
--permission-mode auto                    ✔ classifier 审查动作

claude --headless "…"                    ✘ 不存在 · 自制干扰项
claude --stream "…"                      ✘ 不存在 · 自制干扰项
claude --stream-tokens "…"               ✘ 不存在 · 自制干扰项

settings.json · "model"                  ✔ 会话起始模型
settings.json · "env"                    ✔ 会话及子进程环境变量
settings.json · "permissions"            ✔ allow / ask / deny 与起始 permission mode
settings.json · "hooks"                  ✔ 生命周期 hook
settings.json · "enabledPlugins"         ✔ 按 scope 开关 plugin

settings.json · "headless"               ✘ 不存在 · 自制干扰项
settings.json · "streaming"              ✘ 不存在 · 自制干扰项
settings.json · "sessionStore"           ✘ 不存在 · 自制干扰项

最后把 ch04 的两条边界带回运行现场。CLAUDE.md 的 user / project / local 路径分别是 ~/.claude/CLAUDE.md、./CLAUDE.md 或 ./.claude/CLAUDE.md、./CLAUDE.local.md；发现到的文件会按从宽到窄拼接进 context，不是互相覆盖。settings 则由 user、shared project、project local、managed 等来源组成，标量冲突取高优先级来源，list 型键会跨层合并。目录与优先级的完整表见 ch04；本章只要求你把运行入口放对。

考点回链 — 本章覆盖：TS 3.1（Rules / Skills / Commands / Agents / Agent Memory 五件套；session management；built-in 与 custom slash commands；headless / streaming / auto mode；CLAUDE.md hierarchy；/init；settings.json）。相邻考点：配置文件体系与优先级见 ch04；context compaction 与 subagent 隔离见 ch11；agent customization 的载体取舍见 ch13。

本章题组

QUESTION 01 · TS 3.1 · PATH-SCOPED RULES

A monorepo has .claude/rules/api.md with paths: ["services/api/**/*.ts"]. In a fresh session launched from the repository root, the team asks only about a README and notices that the API conventions are absent from context. They want those conventions to remain conditional rather than consume every session. What should they do?

正确 B带 paths 的 Rules 本来就是条件式指令：只有 Claude 正在处理匹配 pattern 的文件时才适用；无 paths 的 Rules 才与 .claude/CLAUDE.md 同级在 launch 时加载。README 场景没有触发 API rule，恰好证明配置按预期工作。

D5 错层承载违反 P4A：command 是 /name 入口，不是 path-scoped project instruction。旧 command 文件虽继续可用，却按文件名被调用；paths 在 command frontmatter 里还会被忽略。

D5 错层承载违反 P4C：Agent Memory 是某个 subagent 自己的持久目录，主 conversation 的 auto memory 与 subagent memory 也彼此分开；它不是所有会话共享的条件规则总线。

D1 凭空捏造违反 P5D：rulesDirectory 是本书自制的配置键。真实机制已经约定项目 Rules 放在 .claude/rules/ 并递归发现 Markdown，不需要另设目录键。

QUESTION 02 · TS 3.1 · CUSTOM COMMANDS

A team has a working .claude/commands/deploy.md that creates /deploy. The workflow now needs a checked-in checklist, a template, and automatic invocation when a release task is clearly relevant. What is the best next change?

正确 Ccustom commands 已并入 Skills：两种载体都能创建同名 /deploy，旧 command 继续可用；但 Skill 的目录能捆绑 supporting files，并支持控制 Claude 是否按相关性调用。project Skill 的准确入口是 .claude/skills/<name>/SKILL.md。

D6 半对半错违反 P5A：command frontmatter 确实复用 Skill 的大部分字段，但官方明确列出两个例外：name 与 paths 在 command file 里被忽略。真实载体配上无效字段，仍然不会得到题干要的行为。

D1 凭空捏造违反 P5B：builtIn 是本书自制的 settings 键。built-in command 的行为写在 CLI 逻辑里，不能靠一个项目配置把 Markdown prompt「晋升」成产品内置逻辑。

D5 错层承载违反 P9D：CLAUDE.md 每个 session 都进 context；而 Skill body 只在使用时加载。把模板与整套流程常驻，只为偶发 release task 服务，正是把 context 当仓库。

QUESTION 03 · TS 3.1 · AGENT MEMORY SCOPE

A checked-in .claude/agents/code-reviewer.md should remember repository-specific conventions across future conversations. The knowledge must be shared with teammates through version control, must not leak into unrelated repositories, and must remain separate from the main session's auto memory. Which configuration fits?

正确 Amemory: project 的真实目录就是 .claude/agent-memory/<agent>/，用途是 project-specific 且可经 version control 分享的 subagent knowledge；它与主 conversation 的 auto memory 分开。

D6 半对半错违反 P4B：memory: user 的确持久，但它落在 ~/.claude/agent-memory/<agent>/，设计用途就是跨所有项目保留 learnings。题干明说不能越过 repository boundary，scope 选反了。

D5 错层承载违反 P4C：普通 subagent 不加载 main conversation 的 auto memory；要给 subagent 自己的持久记忆，入口是 agent definition 的 memory 字段。把内容写去主 memory，住错载体。

D1 凭空捏造违反 P5D：agentMemoryPath 是本书自制的 settings 键。真实目录由 agent 的 memory scope 与 name 决定，不靠全局路径键；而且题干要的是隔离，不是所有 agents 共用一个 store。

QUESTION 04 · TS 3.1 · NAMED SESSION RESUME

A developer has five saved conversations for the same repository. The most recent one is a documentation task, but the work to continue is the session explicitly named checkout-refactor. They are currently back at the shell. Which invocation selects the intended conversation directly?

正确 Dclaude --resume <name> 直接恢复 named session；题干已经给出精确名字，不需要 picker。

D6 半对半错违反 P5A：--continue 是真实 flag，但其职责是恢复当前目录最近的 interactive session，不是解析一个 name。这里最近的是 documentation task，正会续错对象。

D6 半对半错违反 P5B：无参数 --resume 确实存在，但它打开 session picker，不会因为某个 session 有名字就自动选中。这是把真实入口的交互行为说错。

D1 凭空捏造违反 P5C：--resume-latest 是本书自制的 flag。官方已经用 --continue 表达「最近」，用 --resume <name> 表达「指定」，无需拼出第三种写法。

QUESTION 05 · TS 3.1 · REPOSITORY INITIALIZATION

A mature repository already has a carefully reviewed CLAUDE.md. After a build-system migration, the team wants Claude Code to inspect the codebase and suggest missing build and test instructions without erasing the reviewed policy. What should they do first?

正确 D官方给了精确边界：/init 会分析 codebase 并生成 starter CLAUDE.md；已有文件时则提出 improvements，rather than overwriting it。题干正好需要后半条。

D7 过度工程违反 P10A：无需先破坏再重建。轻量入口本身就能在不覆盖现有文件的前提下给建议；归档、删除、重建、手工回拼把一个命令能完成的事放大成高风险迁移。

D1 凭空捏造违反 P5B：/init --force 是本书自制的 flag，所描述的 section-aware merge 行为也没有官方支撑。真实的 /init 无需这个 flag 就不会覆盖已有 CLAUDE.md。

D2 无关杠杆违反 P1C：/clear 的职责是开始新 session，不是 repository initialization，也没有生成或改写 CLAUDE.md 的职责。它作用在 conversation 轴，不在文件初始化轴。

QUESTION 06 · TS 3.1 · HEADLESS JSON

A CI job must ask Claude Code to review one patch, exit without an interactive prompt, and hand one structured object containing the final result and session metadata to the next step. The consumer does not need token-by-token updates. Which command shape matches all three constraints?

正确 B-p（或 --print）进入 non-interactive mode；--output-format json 返回带 result、session ID 与 metadata 的结构化 JSON，正好满足单次调用与单对象消费。

D2 无关杠杆违反 P1A：重定向只改变 stdout 去向，不会把 interactive launch 变成 task 要求的 non-interactive mode，更不会把默认 plain text 变成 JSON。正确的两个控制面分别是 -p 与 --output-format。

D6 半对半错违反 P1C：这套命令能 headless 且能 stream，但 stdout 是一行一个 event 的 NDJSON，并以 final result line 收尾，不是 downstream 要的「一个 JSON object」。真实机制多做了题干明确不要的事。

D1 凭空捏造违反 P5D：--headless 是本书自制的 flag。官方的准确入口是 -p 或 --print。

QUESTION 07 · TS 3.1 · TOKEN STREAM

A terminal dashboard runs Claude Code non-interactively. It must render text deltas as they are generated, parse one JSON event per line, and still receive a final line with response, cost, and session metadata. Which invocation provides that contract?

正确 A官方给出的逐 token 组合就是 --output-format stream-json 加 --verbose 与 --include-partial-messages；每行一个 JSON event，最后一行是带 final response、cost 与 session metadata 的 result。

D6 半对半错违反 P5B：--output-format json 是真实格式，但它返回的是单次结构化结果，不是会被就地更新的可轮询对象；实时 NDJSON 对应的是 stream-json。

D6 半对半错违反 P5C：stream-json 选对了输出容器，后半句却删掉了逐 token 所需的两个 flags。官方原句把 --verbose 与 --include-partial-messages 明确放进同一调用形状。

D1 凭空捏造违反 P5D：--stream-tokens 是本书自制的 flag。streaming 在 Claude Code CLI 里由 --output-format stream-json 选择，不是另开一个简写开关。

QUESTION 08 · TS 3.1 · AUTO MODE IS A SECOND GATE

A platform team wants long Claude Code tasks to proceed without routine prompts, but production deletion must remain impossible even when a user explicitly asks for it. Managed settings already contain a matching permissions.deny rule. Which design preserves both requirements?

正确 C--permission-mode auto 让 classifier 代替 routine prompts 审查大多数动作；managed permissions.deny 在 classifier 之前阻断，且不能被覆盖。一条管减少提示，一条管硬边界。

D3 措辞冒充控制违反 P3A：CLAUDE.md 是 context，不是 enforced configuration；生产删除的失守代价要求硬闸门。删掉 deny 后，只剩一条会影响倾向的文字，达不到「即使用户要求也不可能」的约束。

D1 凭空捏造违反 P5B：--auto-mode 是本书自制的 flag，真实入口是 --permission-mode auto；而且 classifier 是 permissions 之后的 second gate，不会替代 permissions layer。

D6 半对半错违反 P3D：前半句保留了正确两层，后半句却把 deny 的语义说反。managed permissions.deny 在 classifier 被咨询前就阻断，classifier 与 user intent 都不能 override。

Claude Code Operation五件套、会话命令与三种运行方式