EP03. "Claude Code 进阶实战：长任务、CLAUDE.md 精简化、自动化与插件"

• Anthropic 官方 Claude Code in Action 课程，9 节课 + 1 个结业测验，官方标注约 1 小时，主题是「怎么放心跑没人盯着的长任务」——从怎么带一场长会话，到怎么把检查、CI、插件都变成能信任的自动化
• 这门课比 EP02 那篇 Claude Code 101 更进阶：权限模式从 4 种细分成 6 种、Hooks 从「怎么设」讲到「JSON 决策怎么写」，还多了 Routines/Headless/GitHub Actions/Plugins 这几个 101 完全没提到的自动化功能，建议先看完 EP02 再看这篇
• 前置知识：已经会用 Claude Code 的基本操作（Plan Mode、权限模式切换、CLAUDE.md、Hooks 基础），这些在 EP02 都讲过，这篇不重复

重点内容

---

长任务怎么带：起手 Scope 清楚 + 中途会引导

起手先用 Plan Mode 把范围定清楚：让 Claude 先做只读研究——读代码库、列出要改的地方，写出一份结构完整的计划再给你看。官方原话：「计划写得越详细，Claude 真正动手时你撞见的意外就越少」——花时间在计划阶段来回改，比放手让它跑、跑完再收拾烂摊子快得多。

中途怎么引导，三个工具：

1. /compact 可以带方向——不是干等它自动总结，在指令后面直接写清楚要保留什么：

/compact Focus on the --version flag implementation

（压缩时重点保留 --version 这个参数的实现细节）

2. Rewind（回退）菜单——发现 Claude 走偏了，与其写一大段话纠正，直接在空 prompt 上连按两次 Esc 打开回退菜单，选：

3. /goal 定完成标准，让 Claude 自己跑多轮——描述清楚「做到什么算完成」，Claude 会持续工作直到一个快速评估器确认条件达成：

/goal all tests in src/billing pass, and the type checker reports zero errors

（billing 目录下所有测试通过，且类型检查器报零错误） 用 /goal clear 取消。⚠️ 限制：评估器只读对话记录（transcript），所以你定的条件必须是能从 Claude 实际产出的东西里检查出来的，不能是它看不到的外部状态。

/loop：让 Claude 按固定或自适应的间隔重复跑某个 prompt，适合盯着 CI 跑没跑完、部署有没有变化这类需要持续监控外部状态的场景，按 Esc 停止。

多个会话同时跑，用 Worktrees 避免冲突：好几个 Claude 会话同时碰同一个代码库时，每个 agent 用 worktree 拿到自己独立的文件树，不会互相覆盖改动。仓库根目录放一个 .worktreeinclude 文件，能指定哪些被 git 忽略的文件（比如环境变量、本地配置）要复制进每个 worktree——这些东西每个 worktree 都要用到，但又不该进版本控制。

---

CLAUDE.md 怎么写才「读得动」

先问一句：这条规则真的该放 CLAUDE.md 吗——CLAUDE.md 不是强制配置，是建议，每一行都在跟其他行抢 Claude 的注意力，文件越写越长，Claude 反而会漏看。规则分两类：

• 引导性规则（约定、软性偏好）：适合放 CLAUDE.md
• 绝对不能踩的红线（关键安全规则）：不适合放 CLAUDE.md

举例：「绝不能 push 到 main」这种规则放 CLAUDE.md 不够可靠——「大部分时候」照做是不够的。这类规则该写成 PreToolUse hook：hook 是在 Claude 真正采取行动之前跑的代码，能真正拦下动作，就算 Claude 真的想 push 到 main，hook 会挡下来——这是真正的强制执行，不是「礼貌请求」。

CLAUDE.md 有四层，启动时全部一起载入：

大文件可以用 import 语法拆分，方便管理：

@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md

⚠️ 重要：import 是启动时原样展开进去的，全部内容照样要一次性载入，不会减少 Claude 要读的上下文量——import 只是用来整理文件结构，不是用来省上下文。

规则要写得让 Claude「守得住」，三个技巧：

• 写具体、写得能检查：「遵守 API 路由的最佳实践」太模糊；改成「新 API 路由放 src/api/handlers，一个文件一个路由」——具体到你一眼就能核对有没有照做
• 禁止的同时要给替代方案：只写「不要用 default exports」留了解读空间；改成「用 named exports，不要用 default exports」，把该用什么也一起讲清楚
• 强调词是有限预算：IMPORTANT、YOU MUST 这类词只是相对提高优先级——每条规则都在喊，等于没有规则在喊，强调词留给最关键的两三条就好

当成活文档持续改：Claude 犯的错，当成一份「bug report」——直接叫它把这次纠正补进 CLAUDE.md，让文件跟着实际用的过程持续进化。

---

Verification Skill：把「检查」变成自动化的第一步

为什么先做这个：正常情况下要靠你自己记得去跑测试、review 代码，一忘记这一步，烂代码就混进去了。Verification Skill 让这套检查在满足条件时自动触发：跑测试套件、检查代码改动、确认测试没有被悄悄削弱（跳过/放宽断言）、附证据报告结果。这个思路不只适用于代码重构，任何要重复走一遍的流程（发布清单、数据迁移）都适用。

Skill 文件夹不只一个 SKILL.md：

• reference.md：详细说明，只有真正用到才载入，平时不占上下文
• check.sh 这类可执行脚本：跑实际的验证关卡

这样主 Skill 文件能保持精简，复杂的内容分开存放。

三个「指令层」怎么分工：

---

权限模式：六种精细版

EP02 讲过 4 种日常模式，这门课把权限模式拆得更细，一共 6 种：

Shift + Tab 只在日常四种（Manual／Accept edits／Plan／Auto）之间循环切换，当前模式会显示在状态栏。

Auto 模式的分类器具体拦什么：会拦截——生产环境部署和 migration、force push、把下载下来的代码直接 pipe 进 shell 执行、把敏感数据发到外部、删掉 session 文件；会放行——本地改动、装依赖、push 到个人分支这类日常工作。

⚠️ 分类器的局限：它判断的是「意图」，不是「代码对不对」——它拦不住逻辑错误、跑不通的代码。Auto 模式最好搭配一个跑测试的 Stop hook 一起用，才是完整的防护。

Don't ask 模式适合完全没人在场批准的场景（CI 流水线、排程任务）——只有预先批准的工具能跑，其他一律自动拒绝。

---

Hooks 进阶：JSON 决策与全套事件

Hooks 的核心价值还是「确定性」——这是在循环里固定时间点跑的代码，能保证行为，不是「希望」Claude 照做。整个会话里 Claude Code 大概会触发 30 个左右的 hook 事件，几个关键的：

PreToolUse 用 JSON 回传决策：通过 exit code 0 配合 JSON 输出沟通，permissionDecision 字段可以是：

• allow——放行
• deny——拦下
• ask——转给用户决定
• defer——只在非交互式跑法里才用得到

JSON 结构里还有 updatedInput 字段，可以改写指令内容而不是直接拦掉——但要把没改动的字段也照样传回去，不然会丢数据。实例：Bash 指令里如果出现 sk_live_ 开头这种像是 API key 的字符串，hook 可以用 updatedInput 把它打码掉，指令照样放行执行，但敏感信息不外泄。

Exit code 对照（不用 JSON 的简单 hook）：

⚠️ 注意 exit code 1 不会阻断——要拦下动作必须用 exit code 2。

压缩后怎么保住关键状态：SessionStart hook 配 compact 这个 matcher，能在压缩完成后打印一份文件摘要重新塞回上下文，避免 Claude 压缩完就忘了最近在做什么。

---

Routines vs Headless vs Agent SDK：自动化怎么选

四种自动化方式，由「省心」到「可控」排列：

Routines（云端跑的固定 prompt）：打包 prompt + 目标 repo + 需要的 connector，跑在 Anthropic 自己托管的基础设施上，不用自己维护服务器或工作流。触发方式：cron 排程（比如每天早上 9 点）、HTTP POST 打 API、GitHub 事件（比如有新 PR）。常见用途：早晨依赖审计、PR 分诊、每天扫一遍 Sentry 工单。建法两种：网页 claude.ai/code/routines（填名字、说明、选 repo、选触发方式），或直接在终端用 /schedule daily dependency audit at 9am。

Headless 模式（-p flag）：一次性命令跑法，没有交互式界面，能像标准 shell 工具一样被 pipe：

claude -p "summarize the changes in this diff"

为了启动更快，会跳过 hooks/skills/plugins/MCP server/CLAUDE.md 的自动发现。

要结构化输出，配 JSON schema：

claude -p "Extract the exported function names from src/core/style.js" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output.functions'

结构化数据会出现在 structured_output 字段，方便接下游处理。

多步骤自动化用 session 续跑：先拿到上一次的 session id，再用 claude --resume "$(jq -r .session_id /tmp/plan.json)" 续接——适合「先规划、再执行」这种分好几轮的工作流。

CI 要结果每次完全一致，用 --bare：这个 flag 开启确定性模式，让同一个流水线每次跑出来的输出可预测、可重复。

Agent SDK：把 Claude Code 嵌进自己的产品：TypeScript/Python 都能用，暴露 allowedTools（能力控制）、system prompt、权限模式这些参数，底层引擎跟 CLI 版一样，能在自己的 app 里直接调用、以消息流的方式接收结果。

怎么选：

---

GitHub 集成：Managed Code Review vs 自建 GitHub Action

方式一：托管的 Code Review 服务——设置流程：组织管理员在 Claude Code 管理后台找到「Code review」区块，点 Configure 连接 repo，装 Claude GitHub app，选要监控的 repo，选触发时机（PR 一开就跑／每次 push 到 PR 都跑／只在有人评论 @claude review 时跑）。运作方式：一组 review agent 会拿这次的 diff 对照整个代码库分析，不是只孤立看改动的那几行；发现的问题以行内评论呈现，标严重程度，check run 里还有一份汇总表。

这个服务不会做的事：不会批准或拦截 PR——最终判断权还是在人；没有托管式自动修复，只负责报告问题；目前是 research preview，只有 team 和 enterprise 方案能用。想把发现的问题应用到本地代码，用 /code-review --fix 拉下改动后在本地跑。

方式二：自建 GitHub Action——适合「自定义 CI：照评论内容实作改动、跑排程报告，任何你平常会自己写 workflow 的场景」。设置：跑 /install-github-app（需要 repo 管理员权限）装 app、设 Anthropic API key secret。

引用方式：anthropics/claude-code-action@v1，主要参数：

响应 @claude 提及的 workflow 范例：

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    github_token: ${{ secrets.GITHUB_TOKEN }}
    trigger_phrase: "@claude"
    prompt: "Your instructions here"
    claude_args: "--max-turns 5 --model claude-sonnet-5"

有人在 PR 上写「@claude implement the spec in the linked Linear issue」（照 Linear 里链接的那个 issue 实作），这个 action 就会启动，Claude push commit、发评论说明做了什么。

同一个 action 也能配 cron 排程执行（比如每天 UTC 9 点），加 workflow_dispatch 能在 Actions 分页手动触发；跑的过程用标准 GitHub Actions 界面逐步查看。

用 claude_args 调参数：--max-turns 5 限制 agent 循环轮数，避免无限跑；给无人值守的任务选合适的权限模式，避免中途卡住等批准；只给必要的工具白名单（比如纯报告类任务只给只读工具）。

怎么选：PR review 用托管服务，启用服务 + 装 app + 有问题本地用 /code-review --fix 修；一旦需要 Claude 在 CI 里真的做点什么（不只是留评论），换成自建 GitHub Action，用 /install-github-app 设置，为 @claude 提及和排程任务写 workflow，用 claude_args 调参数。

---

怎么信任没人盯着的跑法：Verification 四件套

核心原则：验证的严格程度，要跟你给这次跑法多大自由度成正比。

1. 无人监督的跑法用 Auto 模式，不要用 Bypass permissions——分类器至少会审每个动作有没有安全风险（虽然不判断代码对不对），验证标准始终不变：给的自由度越大，越要认真验证
2. 从 diff 看起，不要只信摘要：跑 /code-review 系统性检查改动；直接看 git diff 的实际输出；检查有没有计划外被改到的文件；一份写得漂亮的总结不等于代码真的干净
3. 把测试变成硬性关卡，不是「说好了要跑」：用一个 Stop hook 跑测试，测试失败就不让它结束这一轮；用一个 PostToolUse hook 在编辑后跑 lint 和类型检查；靠 exit code 2 把失败结果传回给 Claude 自动修——这样每一次跑都会被检查，不靠人记得
4. 找一个「冷」的第二意见：换一个全新的 agent 或会话、不知道原本是怎么做的，独立审查一遍——这样才能抓到原本那次跑法里自己没意识到的「合理化」判断

综合起来：手动看 diff + 测试 hook 当关卡 + headless 跑法核对 JSON 结果和 exit code + 重要的工作再加一层独立第二意见。

---

Plugins：把 Skills/Subagents/Hooks/MCP 打包成一个单位

Plugin 是什么：一个可安装的整体单位，把原本要手动分享的东西都打包进去——skills、subagents、hooks、MCP server 配置，还有 LSP server、背景监控、主题、一部分 settings.json 这类周边配置。

装一个 plugin：

/plugin install github@claude-plugins-official

装完要跑 /reload-plugins 让改动生效。

团队用法：建私有 marketplace：

/plugin marketplace add your-org/claude-plugins

marketplace 是 plugin 解析来源的共享入口，团队因此拿到集中式的发现、版本追踪、统一更新，不用散落在每个人自己电脑上各装各的。Discover 分页能浏览、搜索现成的 plugin。

⚠️ 装之前先看清楚：plugin 是拿你的权限在你机器上跑代码，它的 hooks 会在每次匹配到的工具调用时触发——社区来源的 plugin 可能藏着没在配置里写明的网络请求。装之前先看它的详情页（会列出要装什么、大概占多少上下文），也会有一句直白的提醒：Anthropic 不控管第三方 plugin 里面到底装了什么。来源分两条线：应用内提交表单发到社区 marketplace（经过自动审核）；官方 marketplace 走独立的审核流程。只从真正信任的来源装 plugin、加 marketplace，装之前先搞清楚它实际会做什么。

Plugin 的组件是「叠加」运行，不是覆盖你原本的配置：

• Hooks 会叠加——plugin 的 PreToolUse hook 和你自己的 PreToolUse hook 每次工具调用都会一起触发
• Skills/agents/commands 会用 plugin 名字做命名空间隔离，避免撞名
• settings.json：plugin 能带自己的一份，但 Claude Code 只认里面两个 key——agent 和 subagent 的状态栏 key；agent 这个 key 比较关键，设了它会把 plugin 里的某个 subagent 直接提升成主线程，连同它的 system prompt、工具限制、模型一起生效——等于装了这个 plugin，Claude Code 的默认行为可能就变了

装好的 plugin 能在 plugin 面板管理、卸载。

打包自己的 Plugin：已经有一份跑得通的 .claude 目录，团队规模变大就该打包成 plugin，而不是继续手动复制文件——不用重新组织结构，plugin 用的就是同一套 .claude 结构：一个 skill 一个文件夹，agents 底下一个 subagent 一个 markdown 文件，plugin 根目录放 hooks/hooks.json 和 .mcp.json。目录结构本身就承担了大部分工作，Claude Code 靠约定发现各个组件。

可选的 manifest，放在 .claude-plugin/plugin.json：

{
  "name": "svg-splitter-review",
  "version": "0.1.0",
  "description": "Reviews the SVG Splitter repo",
  "author": {
    "name": "Lewis Menelaws"
  }
}

只有 name 是必填，会把 skill 命名成 company-name:skill-name 这种格式避免撞名；版本号方便团队追更新；就算不写 manifest，Claude Code 一样能靠目录约定发现各个组件。

常见错误

• ❌ 「绝不能 push 到 main」这类关键安全规则只写进 CLAUDE.md 就以为够了——CLAUDE.md 是建议不是强制，真正不能有例外的规则要用 PreToolUse hook 拦
• ❌ 用 import 语法拆分 CLAUDE.md 之后以为省了上下文——import 只是启动时原样展开，用来整理结构，不会减少 Claude 要读的总量
• ❌ 无人值守的自动化任务图省事直接开 Bypass permissions——至少应该用 Auto 模式，让分类器还能拦掉明显危险的动作，Bypass 等于完全不设防
• ❌ 只信 Claude 给的改动摘要就直接信任这次无监督的跑法——摘要写得漂亮不等于代码干净，一定要看实际 git diff 或跑 /code-review
• ❌ 期待「跑测试」这件事靠 Claude 自觉执行——不写成 Stop hook 强制拦，测试步骤就只是「说好了要做」，不是真正的关卡
• ❌ 装社区来源的 plugin 之前不看它的 hooks/agents/MCP 配置——plugin 是拿你的权限跑代码，装之前一定要先看清楚它实际会做什么
• 💡 自动化怎么选别想太多，从 Routines 开始最省心，真的需要更细粒度控制（要 pipe 数据、CI 要求结果完全一致、要嵌进自己产品）才往下切换到 Headless/--bare/Agent SDK

Sources

官方文档：

1. Claude Code in Action（课程总览）— https://academy.claude.com/courses/claude-code-in-action
2. Steering long sessions — https://academy.claude.com/courses/claude-code-in-action/steering-long-sessions
3. A CLAUDE.md that follows — https://academy.claude.com/courses/claude-code-in-action/a-claude-md-that-follows
4. Verification skills — https://academy.claude.com/courses/claude-code-in-action/verification-skills
5. Permission modes — https://academy.claude.com/courses/claude-code-in-action/permission-modes
6. Hooks — https://academy.claude.com/courses/claude-code-in-action/hooks
7. Routines and headless — https://academy.claude.com/courses/claude-code-in-action/routines-and-headless
8. GitHub Actions and Code Review — https://academy.claude.com/courses/claude-code-in-action/github-actions-and-code-review
9. Trust it: Verifying unsupervised runs — https://academy.claude.com/courses/claude-code-in-action/trust-it-verifying-unsupervised-runs
10. Plugins — https://academy.claude.com/courses/claude-code-in-action/plugins