24. 附录5-扩展能力选择指南

来源：Claude Code

核对日期：2026-09-30
适用范围：Claude Code 命令行；以个人项目和本课程 MealCraft 为例。

Claude Code 的内置文件读取、搜索、编辑和命令执行工具已经能完成多数编码任务。扩展能力不是越多越好：它们会增加上下文、配置、权限、费用或供应链负担。

最稳妥的顺序是：先用一次普通提示词；重复出现明确需求后，再选择最小的扩展。

一、先看结论

你真正缺少什么	优先选择	何时加载或触发	它能否强制执行
当前只做一次的说明	普通提示词	当前对话	不能
每次进入项目都要知道的事实或约定	CLAUDE.md	会话开始；嵌套文件按目录发现	不能，只是指令
只对某类文件生效的约定	.claude/rules/	会话开始或访问匹配路径时	不能，只是指令
偶尔使用的知识、清单或多步流程	Skill	手动调用或被模型匹配时	不能；由 Claude 解释执行
某个生命周期事件一到就运行同一动作	Hook	匹配事件发生时	触发是确定的；处理器仍需正确实现
限制可用工具、命令或文件边界	权限规则、Sandbox，必要时配合 Hook	工具调用前	可以建立实际边界
大量调查不想挤占主对话	Subagent	主 Agent 或用户按需启动	独立上下文；权限仍需配置
暂时离开、稍后查看一个完整任务	后台会话 / Agent view	用户启动独立会话	不是扩展；是另一段完整会话
多个独立会话需要共同维护任务与互相协调	Agent Team	显式创建团队时	成本和协调复杂度较高，初学阶段少用
读取仓库之外的数据或执行外部动作	MCP	连接后，具体工具按需调用	取决于服务端与权限配置
多个项目要安装同一组 Skill、Hook、Agent 或 MCP	Plugin	安装或临时加载插件时	只是打包层，不自动提高安全性
大型、强类型项目需要符号导航和实时诊断	Code intelligence / LSP	安装对应语言插件后按需使用	提供代码证据，不替代测试

“必须遵守”不能只写进提示词、CLAUDE.md、Rule 或 Skill。需要阻止危险动作时，用权限 deny、Sandbox 或经过测试的 PreToolUse Hook；需要保护数据时，还要保留 Git、备份和人工审批。

二、七步选择法

按顺序回答，遇到第一个“是”就先用该方案，不必一次装齐。

1. 内置工具能直接完成吗？ 能，就用普通提示词；一次性任务不需要沉淀配置。
2. 是长期知识吗？ 全项目每次都要知道，放 CLAUDE.md；只对应路径，放 Rule；只在特定任务需要，做 Skill。
3. 是事件自动化或安全边界吗？ 自动格式化、记录和检查用 Hook；真正限制工具、命令或文件访问，用权限和 Sandbox。
4. 需要隔离工作吗？ 一项高输出调查用 Subagent；一个完整任务要稍后查看，用后台会话；只有多个独立会话必须互相协调时才考虑 Agent Team。
5. 缺少外部数据或动作吗？ 本地文件能读就不要接 MCP；确实要访问数据库、浏览器或在线服务时再接。
6. 需要跨项目安装吗？ 先在一个项目的 .claude/ 中迭代；第二个项目也稳定需要时，再打包 Plugin。
7. 普通搜索无法可靠处理大型强类型代码吗？ 再安装对应语言的代码智能插件；小型 Python 项目通常不必为了完整而安装。

如果两个选项都像答案，先选配置更少、权限更窄、清理更容易的那个，并为它写一条可观察的验证。

三、知识放在哪里：CLAUDE.md、Rules 还是 Skill

三者都向 Claude 提供指令或知识，但加载时机不同。

问题	CLAUDE.md	.claude/rules/	Skill
典型内容	项目结构、固定命令、通用约定	测试、前端或特定目录约定	发布清单、审查流程、领域资料
作用范围	整个项目	可用 paths 限定路径	当前被调用的任务
上下文成本	全文随会话使用	无条件或匹配路径时加载	描述常驻；正文使用时加载
用户入口	自动加载	自动匹配	/<skill-name>，也可由模型匹配
最容易犯的错	塞入很长的参考手册	路径模式没有命中	描述含糊、意外自动触发

选择原则：

• “每次写代码都用 python3 -m unittest”放 CLAUDE.md；
• “修改 tests/** 时不得删除失败断言”放带 paths 的 Rule；
• “生成本周菜单并逐项检查库存”做成 weekly-menu Skill；
• 有副作用的 Skill 可设 disable-model-invocation: true，只允许用户显式调用；
• allowed-tools 只表示调用该 Skill 的那一轮可预批准哪些工具，不是全局工具白名单。

Skill 也可设置 context: fork，在隔离上下文运行后把结果带回。它适合“固定工作流本身需要隔离”；如果你需要一个长期可复用、具有独立提示词、工具、模型、权限和预加载 Skills 的角色，则定义自定义 Subagent。

四、流程自动化：Skill、Hook 还是权限

用三个问题区分：

1. 需要 Claude 判断怎样完成吗？ 用 Skill。例如“根据本周菜谱生成采购检查报告”。
2. 事件发生时必须自动运行吗？ 用 Hook。例如每次编辑 Python 文件后运行格式或静态检查。
3. 不满足条件时必须阻止调用吗？ 优先用权限规则或 Sandbox；只有需要检查动态输入时，再使用 PreToolUse Hook。

Hook 的“确定性”只指匹配事件一定会触发，不代表脚本一定正确，也不代表所有 Hook 都会阻止动作。必须验证：

• matcher 是否真的匹配目标工具；
• 脚本在 macOS、Linux、WSL2 或 Windows 的运行方式；
• 正常输入的退出码和输出；
• 阻止输入的退出码、错误信息和 Claude Code 行为；
• Hook 失败后的最小停用方法。

可复现实操见第 11 篇，完整配置片段见附录 03。

五、隔离工作：四种方式不要混用

1. Skill 的 context: fork

固定 Skill 在父对话的分支上下文中执行，适合把一个稳定工作流的中间材料隔离出去。它首先仍是“可复用流程”，不是一个单独维护的专家角色。

2. Subagent

Subagent 有自己的上下文，完成后向调用它的主 Agent 返回摘要。适合：

• 阅读很多文件后只返回结论；
• 独立审查、调查或验证一个窄问题；
• 用工具白名单限制一个专门角色；
• 多项互不写同一文件的工作并行进行。

每个模型 Agent 都会消耗用量。并行并不会让依赖关系消失；同一文件、多步串行修改或很小的任务通常由主 Agent 完成更可靠。

3. 后台会话 / Agent view

这是完整、独立的 Claude Code 会话，适合启动一个任务后离开，再用 claude agents、claude attach、claude logs 或 claude stop 查看和管理。它不是 Subagent：主对话不会自动得到一份简短返回值，工作目录和变更也可能与其他会话发生冲突。

4. Agent Team

Agent Team 让多个独立 Claude Code 会话共享任务并互相协调。只有任务能真正拆成独立工作流、协调收益高于额外用量和冲突风险时才使用。

对 MealCraft 这种个人项目，默认不需要 Agent Team。先掌握一个主会话、一个只读 Subagent 和一个后台会话，已经覆盖绝大多数学习场景。

需求	选择
固定流程，但不想让中间内容留在主上下文	Skill context: fork
一次窄调查，完成后主 Agent 要拿到摘要	Subagent
一个完整任务要长期运行或稍后手动接管	后台会话
多个会话必须共享任务、持续互相沟通	Agent Team，进阶选学

Subagent 完整练习见第 13 篇，后台会话练习见第 10 篇。

六、访问外部世界：MCP 还是内置工具

当前仓库中的源码、JSON、Markdown 和命令不需要 MCP。内置 Read、Glob、Grep、Edit 和 Bash 已能处理。

只有出现下面的真实缺口才接 MCP：

• 数据只存在于外部服务或独立数据库；
• 某动作需要服务的专用 API；
• 需要一个内置工具没有的受控能力。

第一次连接遵循四步：

1. 从本地、只读、测试数据或测试账户开始；
2. 检查服务来源、启动命令、凭据范围和会产生的费用；
3. 用 /mcp 确认连接状态，并只调用一个无副作用工具；
4. 验证输出后再开放写操作，最后练习 disable、reconnect 或 remove。

MCP 提供“连接和工具”，Skill 提供“怎样正确使用这些工具的知识”。两者可以组合，但不要用 Skill 冒充外部连接，也不要为了保存一段检查清单搭建 MCP。可运行示例见第 12 篇。

七、何时才值得打包 Plugin

Plugin 是分发层，可以打包 Skills、Hooks、Subagents、MCP 服务等组件。它不是新的执行模型，也不会自动解决权限问题。

满足以下条件再打包：

• 能力已在单个项目的 .claude/ 中稳定运行；
• 至少第二个项目需要相同组合；
• 组件有版本、来源、验证和停用方法；
• 使用者知道插件可能运行 Hook、启动 MCP 或暴露工具。

个人项目的推荐顺序：

项目内配置 -> 完整验证 -> 第二个项目复用 -> 本地插件 -> 再考虑分发

安装第三方插件前，阅读 manifest 和所含 Hook、MCP 启动命令；不要因为它来自 marketplace 就默认可信。练习插件时先临时加载，用 claude plugin validate 检查结构，再验证命名空间调用和停用路径。

八、代码智能何时有价值

Code intelligence 通过语言服务器提供符号定义、引用和编辑后的类型诊断。只有安装对应语言的代码智能插件后，LSP 工具才会启用。

适合：大型 TypeScript、Go、Rust、Java 等强类型代码库，或同名符号很多、普通文本搜索难以判断真实引用的项目。

不适合：为了“功能齐全”给 MealCraft 这样的轻量 Python 教学项目额外安装复杂工具链。即使用了 LSP，也要运行真实测试；类型诊断不能证明用户路径正确。

九、MealCraft 的最小演进路线

不要一次把九种能力全装进去。MealCraft 可以按出现的需求逐层增加：

1. 普通提示词：第一次规划、实现和修复。
2. CLAUDE.md：固定启动、测试、验收命令和项目边界。
3. Rule：只在修改测试文件时加载测试约定。
4. Skill：把“生成周菜单并检查结果”做成手动调用流程。
5. Hook：每次相关编辑后自动记录或运行快速检查。
6. Subagent：只读审查菜谱换算和购物清单，不污染主上下文。
7. MCP：只有库存来自外部服务时才连接 pantry；本地 JSON 继续用内置工具。
8. Plugin：上述 Skill、Hook、Agent、MCP 在第二个个人项目也需要时再打包。

这条路线不需要 Agent Team，也不需要 LSP。能力少并不落后；每项都能说明目的、边界和验证方法才是完成。

十、五分钟验证表

添加任何能力后，不要只问 Claude“加载成功了吗”。使用独立入口检查：

能力	首个检查	通过标准
CLAUDE.md / Rule	/context，再开一个新会话做只读提问	文件在正确来源出现；新会话能引用真实约定
Skill	/skills，必要时 /reload-skills，再显式调用	名称可见；输入、输出和副作用符合约定
Hook	/hooks，分别运行正常和阻止样例	matcher 命中；两条路径退出行为正确
Subagent	claude agents --json 或会话内显式调用	定义可发现；工具、权限和返回格式受控
后台会话	claude agents，再查看日志或 attach	能定位正确会话，磁盘变更可核对
MCP	/mcp，调用只读探针	状态已连接；结果来自预期服务和测试数据
Plugin	claude plugin validate <路径> --strict，再临时加载	结构检查通过；组件用预期命名空间出现
Code intelligence	查询一个已知符号并制造可恢复的类型错误	定义/引用位置正确；诊断能出现并在恢复后消失

如果验证失败，先停用刚添加的一层，再检查作用域、文件名、frontmatter、JSON、路径和当前版本帮助。不要同时改多个扩展，否则无法判断是哪一层造成问题。

十一、成本与安全检查

采用某项能力前，逐项回答：

• 它会不会让更多说明常驻上下文？
• 它会不会启动额外模型 Agent，增加用量？
• 它能读取哪些文件、环境变量或外部数据？
• 它能写文件、发请求、修改数据库或触发费用吗？
• 来源是否可信，启动命令是否已读过？
• 如何独立证明它工作正常？
• 如何在一分钟内停用或移除？

答不出最后两项时，不要把它加入日常项目。

十二、官方资料

• 扩展能力总览与选择比较
• Skills
• Hooks
• Subagents
• 后台会话与 Agent view
• Agent Teams
• MCP
• Plugins
• 工具与代码智能参考

官方行为会随版本变化。命令不可用时，先运行 claude --help、对应子命令的 --help，并查看当前官方页面；不要用旧教程中的截图猜测。