你大概率没用对 Claude Code 的五大能力

划重点：博主天天喊 AI 已经能做 OPC，但工程师连 CLAUDE.md 该写什么、.claude/rules/ 与 Skills 怎么分都还说不清。本文不讲怎么做 OPC------讲在被这套叙事忽悠之前，先把五个能力分别用对。

截至 2026 年 5 月，Claude Code 的官方与社区 marketplace 已经有 4200+ skills、770+ MCP servers、2500+ marketplaces 在册。

听起来很多。

把数字摊开看，会发现一个尴尬的事实：工具数量爆炸 ≠ 使用效果爆炸。

多数人装了 plugin 后从没用过；多数人写过 CLAUDE.md 后再也没回去 review;多数人在 Plan Mode 跑跑就完事，从没用 Skills 编排过任何复杂流程。

那五大能力（CLAUDE.md / .claude/rules/ / Skills / Subagents / Agent Teams）到底分别该用在哪儿？

官方文档把每一项各自讲清楚了。但没把"五个能力之间的关系"讲清楚------这是大多数人用错的根因。

认知前提 | 人为什么协作能省话，AI 不能

老板让你做新功能，你能自动兼顾兼容性、稳定性、工程化建设。这是工程师的基本素养，也是你和老板的默契。

但同样一句话给 AI------"实现 X 功能"------产出通常达不到预期。

AI 缺的不是智力，是约定：那种你不必每次说出来、但被假定知道的事。

这种约定不是单一维度。拆开看至少有五层：

flowchart LR A["A 事实层 build/test 命令 API 调用方式"] B["B 过程层 RFC 流程 code review 走法"] C["C 强制层 上线必跑 e2e CI 红灯不合并"] D["D 判断层 性能 vs 可读性 向后兼容权衡"] E["E 协商层 认知不一致拉个会 spike 验证"] A --> B --> C --> D --> E classDef layer fill:#fef3c7,stroke:#92400e,color:#000 class A,B,C,D,E layer

第一反应可能是：那把这些都写到 CLAUDE.md 里不就行了？

不行。

CLAUDE.md 只装得下 A 类（事实）的一部分，装不下 D（判断）和 E（协商）。

写"性能比可读性重要"------这是在 D 层放了一个静态权重------但真实判断要看具体场景：这块代码是热路径吗？这次重构的目标是什么？

CLAUDE.md 给不出"看场景"的能力，因为它是贴在墙上的备忘录，不是参与会议的同事。

这就是"我都写在 CLAUDE.md 里它还是没做对"这种抱怨的根因------不是没写，是用错了工具。

核心论点 | 五大能力其实回答五类正交问题

flowchart LR Q1["问题1 项目知识 带入每次对话?"] Q2["问题2 按需调用 多步流程?"] Q3["问题3 噪声任务 隔离主对话?"] Q4["问题4 强制某些事 一定发生?"] Q5["问题5 并行讨论 仿真团队协作?"] Q1 --> A1[CLAUDE.md / .claude/rules/ ] Q2 --> A2[Skills] Q3 --> A3[Subagents] Q4 --> A4[Hooks] Q5 --> A5[Agent Teams] classDef q fill:#fef3c7,stroke:#92400e,color:#000 classDef a fill:#dbeafe,stroke:#1e3a8a,color:#000 class Q1,Q2,Q3,Q4,Q5 q class A1,A2,A3,A4,A5 a

三个最容易被误解的澄清：

澄清 1 | 这五个问题是正交的，不是一个谱系上的五个梯度。

很多人以为：CLAUDE.md 是基础、Skills 是进阶、Subagent 是高级、Agent Teams 是顶级。

错。它们各自回答不同的问题。把高级工具拿来解基础问题，结果是大力出悲剧。

澄清 2 | "Context 经济学"只是问题 1/2/3 的视角，cover 不住 4 和 5。

Hooks 是 shell 命令，根本不进 context。

Agent Teams 故意花更多 context（每个 teammate 一个独立 session）来换并行讨论效率------它反context 经济学。

澄清 3 | Subagent 和 Agent Teams 不是一个东西。

维度	Subagent	Agent Teams
设计目的	防御------把噪声隔离主对话	进攻------并行讨论、协作仿真
何时用	副任务污染 context（搜索、跑测、读日志）	多视角研究、PR review、对抗性假设、跨层协作
token 成本	低（结果摘要返回）	高（每个 teammate 独立 session）
通信	只回主 agent	teammates 之间直接互发消息

Anthropic 官方原话：

"Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own."

把 Agent Teams 当 Subagent 升级版用------这是大类误用。

误用图谱 | 把 X 工具用来解 Y 问题

挑 8 条最常见的，按"问题分组"排：

问题 1：项目知识进对话

误用 1 | CLAUDE.md 当垃圾桶

500 行 CLAUDE.md，写满"务必、一定、绝对"，结果 Claude 反而忽略一半。

官方明文：

"If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise."

正解 | 200 行硬上限。路径相关拆到 .claude/rules/；多步流程拆到 Skills；必须执行的拆到 Hooks。

误用 2 | 把"过程"写进 CLAUDE.md

"如何 review PR：先看 X、再看 Y、再看 Z"------这一段每次启动都被加载，但只在偶尔 review PR 时用。

官方建议：

"Create a skill when ... a section of CLAUDE.md has grown into a procedure rather than a fact."

正解 | 多步流程一律写成 Skill，按需调用。Skill 的 description 进 context，body 在被调用时才注入------这是 context 经济学的核心实践。

问题 2：按需多步流程

误用 3 | 混淆 Skills 与 Subagents 的边界

把"读 200 个文件做架构梳理"做成 Skill------结果 Skill body + 200 个文件读取记录全在主 context；或反过来，把"团队 API 命名规范"做成 Subagent，每次都 spawn 一个新 session 浪费 token。

Anthropic 博客原话：

"Use Skills to teach expertise that any agent can apply; use subagents when you need independent task execution."

问题 3：隔离噪声任务

误用 4 | 滥用自定义 Subagents

把"写代码""写测试""写文档""写 commit"四个角色都做成自定义 Subagent。结果：

启动开销叠加
description 自动委派匹配不可靠
工具白名单画太细------Claude 该用 A 工具时只有 B-agent 工具集，硬用 B 凑合

社区有反对声音（sshh.io）：自定义 Subagent "gatekeep context"------你画一条 sub-agent 边界 = 替 Claude 决定了它能用什么工具，反而限制自主规划。

正解 | 少写自定义、多用 built-in 隔离工具调用：

偶尔一次的副任务：直接用 built-in Explore / Plan / general-purpose
反复 spawn 的同类工人：才写自定义
会污染主对话的任务（搜索、跑测、读日志、grep）一律委派给 built-in subagent，主 Agent 只看摘要

这是单条最重要的 context 经济学实践------主对话不该关心调用工具的过程，只该看结果。

问题 4：强制必发生

误用 5 | 该用 Hooks 时不用，把"必须做"写成"建议做"

CLAUDE.md 里写"重要：commit 前必须跑 bun test"------Claude 80% 时候记得，20% 时候忘了。

官方原话：

"If the instruction is something that must run at a specific point ... write it as a hook instead."

正解 | PreToolUse hook + matcher "Bash" + 检查 git commit + exit 2 阻断。Hooks 在 permission-mode 之前触发，bypass 模式下也生效------不可绕过的执行层。

json 复制代码

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "Bash(git commit *)",
      "hooks": [{ "type": "command", "command": ".claude/hooks/check-tests.sh" }]
    }]
  }
}

记住一条简单的判别：如果它必须发生，就不能依赖 LLM 的决策。

问题 5：并行讨论

误用 6 | 把 Agent Teams 当 Subagents 用

用 Agent Teams 跑顺序任务（一个 teammate 完成才能下一个开始），每个 teammate 都是独立 session 烧着 token，但实际根本没在并行。

官方明文：

"For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective."

正解 | Agent Teams 的核心目的不是省 context，是提效。强场景：研究、PR review、并行模块、对抗性假设、跨层协作。顺序任务用 Subagent。

横切类：Rules 实装坑

误用 7 | path-scoped rule 写在子目录

把规则放在 .claude/rules/api/、.claude/rules/frontend/ 子目录加 paths:------以为按目录划分更整洁，实际完全不加载到 context。

证据：GitHub Issue #16853 仍 Open（2026-01-08 报告，标记"非回归 bug------从功能发布之日起就这样"）。

误用 8 | path-scoped rule 强制新文件约定

写"创建新 .md 文件首行必须加 # created"+ paths: **/*.md------Claude 创建新文件时不触发，编辑现有文件时才工作。

证据：GitHub Issue #23478 Closed as not planned------官方决定不修。

正解 | 这种"创建时强制 X"改写成 PostToolUse hook（matcher "Write" + 直接修改文件）------又一个回到 Hooks 兜底的例子。

关键现实 | 文档承诺 ≠ 实际行为

.claude/rules/ 的 path-scoped 功能在两个最常见场景下不工作：

Issue #16853（Open） | 子目录里完全不加载------"非回归 bug，从功能发布之日起就这样"
Issue #23478（Closed not planned） | 仅 Read 工具触发，Write/Edit/MultiEdit 不触发------官方决定不修

如果你严格按文档写------把 rules 按目录组织、加 paths:------你会以为它在工作，其实没有。

验证手段 （joseparreogarcia 实测）：

"Always verify what Claude actually loaded by requesting it explicitly---never assume automatic loading."

具体三步：

用 /context 命令查看 Memory files
显式问 Claude："你现在加载了哪些 rules？"
写完 rule 后跑一个最小复现，验证它真的在工作

横向对比：Cursor 的 rules 有 4 种激活模式（Always / Auto-Attached / Agent-Requested / Manual）；Claude Code 的 .claude/rules/ 实际只有前两种，且 Auto-Attached 实装有 bug。

Cursor 的 Agent-Requested（按 description 决策）在 Claude Code 里不在 rules 里 ------它对应的是 Skills 的 description 字段。

Rules 这层抽象在 Claude Code 里还没成熟到 Cursor 的水平。这是事实，没必要替它讳言。

OPC 现实对照 | 单方向 OK，跨方向远不行

回扣开头。我们已经分清五大能力了，那 OPC 真的能做吗？

社区两个最主流的"编排框架"------Superpower 和 OpenSpec------已有大量实战经验：

OpenSpec | 适合解决单元类小问题，流程简单、易用------把一个具体的小需求（写一个 endpoint、加一个 validation）走完一个完整文档驱动迭代。

Superpower | 更适合 Feature 级别项目迭代，把控力更好------把 brainstorming / planning / executing / reviewing 几个 skill 链起来，能 hold 住一个中等复杂度的功能完整闭环。

但这两者不能结合使用：

都是基于文档驱动开发
文档结构不一致，各自有各自的目录
这种不一致性对项目长期维护不是好事

实战派开发者更倾向用 Superpower 管项目迭代。但对于复杂的、大型的完整项目（前后端分离、多角色协作） ，这两者都无法胜任。

把这个一手报告外推：

当前 marketplace 上没有真正解决跨方向编排的开源方案------Superpower / OpenSpec 是单方向项目内的编排，不是跨前端 / 后端 / 设计 / 测试 / CI 的协作编排
Anthropic 自己博客只敢说 multi-agent research，没说过 multi-agent shipping------这条沉默就是答案
Agent Teams 至今还是 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 实验性，且明文不适合"sequential tasks, same-file edits, work with many dependencies"------这恰恰是企业项目的常态

OPC 真正难的部分不是写代码------是让"前端的改动 / 后端的契约 / 测试的覆盖 / CI 的部署 / 文档的同步"这五件事自洽地推进。

这要求工具能仿真一支跨职能小团队，而不只是给你一个会写代码的工程师。

当前 Agent 工具能给你一个会写代码的工程师，但还不能给你一支团队。这就是 OPC 焦虑叙事和现实之间的鸿沟。

"AI 能独立做 OPC"要拆开看：单方向 SaaS toy，能；跨方向真实产品，不能。被博客忽悠去尝试后者然后失败的人，痛点不是 AI 不够强，是工具栈还没到那一步。

决策树 | 任务 → 工具

flowchart TD Start(["AI 协作的需求"]) Q1{"每次对话 都要 Claude 知道?"} Q2{"路径相关、 按主题切?"} Q3{"多步流程、 按需触发?"} Q4{"必须确定性发生?"} Q5{"副任务噪声大?"} Q6{"需要并行讨论?"} Start --> Q1 Q1 -- 是 --> Q2 Q1 -- 否 --> Q3 Q2 -- 是 --> R1[".claude/rules/ 注意 path-scoped bug"] Q2 -- 否 --> R2["CLAUDE.md < 200 行硬上限"] Q3 -- 是 --> R3["Skills 用 paths 限定触发"] Q3 -- 否 --> Q4 Q4 -- 是 --> R4["Hooks PreToolUse 阻断"] Q4 -- 否 --> Q5 Q5 -- 是 --> R5["Subagent built-in 优先"] Q5 -- 否 --> Q6 Q6 -- 是 --> R6["Agent Teams 仅研究/review"] Q6 -- 否 --> R7["主对话直接做"] classDef startNode fill:#fef3c7,stroke:#92400e,color:#000 classDef qNode fill:#fff,stroke:#666,color:#000 classDef rNode fill:#bbf7d0,stroke:#166534,color:#000 class Start startNode class Q1,Q2,Q3,Q4,Q5,Q6 qNode class R1,R2,R3,R4,R5,R6,R7 rNode

三句送行

别再让 CLAUDE.md 越长越长 | 超过 200 行就拆。拆到 .claude/rules/ 顶层、按文件名组织，不要嵌子目录。

别再装一堆没用过的 Skill | 每装一个就在 context 里多一份描述。让 Subagent 持有 Skill，让主 Agent 保持轻。

别再被 OPC 叙事忽悠 | 单方向能做的事自己做，跨方向还不行的事别假装能做。先把基础用对，比模仿 demo 更接近终点。

One More Thing

如果你的团队同时用 Claude Code、Cursor、Codex，建议关注 AGENTS.md 跨工具标准。

Claude Code 不读 AGENTS.md，但可以在 CLAUDE.md 里 @AGENTS.md 引入；Cursor、Codex CLI、Continue.dev 等工具直接支持。

n8n、awesome-go 等大型开源项目已经把 AGENTS.md 作为单一事实来源------多工具团队的 day 1 就该这样开。

参考链接

主资料（官方文档）

社区视角

实装坑（GitHub Issues）

横向对比