> 划重点：博主天天喊 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 缺的不是智力，是**约定**：那种你不必每次说出来、但被假定知道的事。这种约定不是单一维度。拆开看至少有五层： ```mermaid 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 里它还是没做对"这种抱怨的根因——**不是没写，是用错了工具**。 --- ## **核心论点** | 五大能力其实回答五类正交问题 ```mermaid 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 官方原话](https://code.claude.com/docs/en/agent-teams)： > "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 反而忽略一半。 [官方明文](https://code.claude.com/docs/en/best-practices)： > "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 时用。 [官方建议](https://code.claude.com/docs/en/skills)： > "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 博客原话](https://claude.com/blog/skills-explained)： > "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](https://blog.sshh.io/p/how-i-use-every-claude-code-feature)）：自定义 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% 时候忘了。 [官方原话](https://code.claude.com/docs/en/memory)： > "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，但实际根本没在并行。 [官方明文](https://code.claude.com/docs/en/agent-teams)： > "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](https://github.com/anthropics/claude-code/issues/16853) 仍 Open（2026-01-08 报告，标记"非回归 bug——从功能发布之日起就这样"）。 **误用 8** | path-scoped rule 强制新文件约定写"创建新 .md 文件首行必须加 `# created`"+ `paths: **/*.md`——Claude 创建新文件时**不触发**，编辑现有文件时才工作。证据：[GitHub Issue #23478](https://github.com/anthropics/claude-code/issues/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 实测](https://joseparreogarcia.substack.com/p/how-claude-code-rules-actually-work)）： > "Always verify what Claude actually loaded by requesting it explicitly—never assume automatic loading." 具体三步： 1. 用 `/context` 命令查看 Memory files 2. 显式问 Claude："你现在加载了哪些 rules？" 3. 写完 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 住一个中等复杂度的功能完整闭环。但**这两者不能结合使用**： 1. 都是基于文档驱动开发 2. 文档结构不一致，各自有各自的目录 3. 这种不一致性对项目长期维护不是好事实战派开发者更倾向用 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 不够强，是工具栈还没到那一步。 --- ## **决策树** | 任务 → 工具 ```mermaid 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 就该这样开**。 --- ## **参考链接** **主资料（官方文档）** - [How Claude remembers your project](https://code.claude.com/docs/en/memory) - [Extend Claude with skills](https://code.claude.com/docs/en/skills) - [Create custom subagents](https://code.claude.com/docs/en/sub-agents) - [Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams) - [Automate workflows with hooks](https://code.claude.com/docs/en/hooks-guide) - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) - [Skills explained: vs prompts/Projects/MCP/subagents](https://claude.com/blog/skills-explained) **社区视角** - [How I Use Every Claude Code Feature（sshh.io）](https://blog.sshh.io/p/how-i-use-every-claude-code-feature) - [Common Sub-Agent Anti-Patterns（stevekinney）](https://stevekinney.com/courses/ai-development/subagent-anti-patterns) - [How Claude Code rules actually work（joseparreogarcia）](https://joseparreogarcia.substack.com/p/how-claude-code-rules-actually-work) **实装坑（GitHub Issues）** - [#16853: Path-scoped rules in `.claude/rules/` not auto-loaded（Open）](https://github.com/anthropics/claude-code/issues/16853) - [#23478: Path-based rules not loaded on Write tool（Closed not planned）](https://github.com/anthropics/claude-code/issues/23478) **横向对比** - [Cursor Rules 官方文档](https://cursor.com/docs/context/rules) - [.cursorrules vs CLAUDE.md vs AGENTS.md](https://thepromptshelf.dev/blog/cursorrules-vs-claude-md/)