在用 Claude Code 做项目工程化配置时，绝大多数开发者都会踩同一个坑：规则、执行流程、自动化脚本、外部接入能力胡乱堆砌在 CLAUDE.md、Skills、Hooks 各个配置文件里，后续修改无从下手。
Claude Code Harness 提出的 五层分层设计，提供了一套标准化内容归属判断法，把项目配置拆分为 Rules、Skills、Commands、Hooks、MCP 五大模块，各司其职，从架构层面根治配置杂乱问题。
一、五层定位：各司其职，互不越界
五层并非并列功能，而是按照 约束 → 方法 → 入口 → 自动化 → 外部接入 的逻辑分层。每一层都有明确边界，不能互相替代。核心分工如下：
| 层级 | 核心职责 | 落地文件位置 | 适用内容 |
|---|---|---|---|
| Rules | 全项目长期行为底线 | .claude/rules/*.md |
安全约束、代码修改红线、校验强制规则 |
| Skills | 单类任务标准化方法论 | .claude/skills/ |
Debug、TDD、代码评审、安全审计流程 |
| Commands | 高频操作固定触发入口 | .claude/commands/*.md |
/plan、/review、/verify 等指令 |
| Hooks | 被动自动化治理动作 | .claude/hooks/ |
保存自动格式化、编译自检、会话收尾汇总 |
| MCP | 打通外部软硬件资源 | .mcp.json |
数据库、浏览器、第三方平台 API、大模型 API 接入 |
很多项目配置崩盘，本质就是混淆五层边界：把长期安全规则塞进 Skill，把自动化校验逻辑写进 Command，把业务执行流程放进 Hooks，把外部能力接入和项目说明混在 CLAUDE.md 里。短期看似方便，长期就会导致配置文件越来越臃肿，后续维护成本快速上升。
Claude Code Harness 的价值，就是先把“什么内容应该放在哪里”这件事标准化。新增一条行为约束时，应该去 Rules；沉淀一个任务流程时，应该去 Skills；设计一个高频触发入口时，应该去 Commands；处理机械自动化动作时，应该去 Hooks；接入外部工具或服务时，才应该考虑 MCP。
二、逐层拆解落地标准，附规范代码示例
1. Rules：划定不可突破的项目底线
Rules 负责定义全项目长期生效的行为底线。它不是项目说明书，也不是开发建议集合，而是 Claude Code 在任何任务中都必须遵守的硬性边界。
Rule 拒绝空泛的“代码要优雅”“尽量保持简洁”这类倡议。只有同时满足以下三个条件的内容，才适合归入 Rules：
- 长期生效；
- 全任务通用；
- 用于划定不可突破的边界。
规范示例：
## Rules规范示例
- Do not widen scope without explicit confirmation.
- Do not weaken lint, typecheck, or test configuration to make checks pass.
- For multi-file or ambiguous work, start with a plan before editing code.
- Do not manually edit files under `src/generated/`.
这类规则的共同特点是：它们不依赖某一次任务，也不只服务于某一种开发流程，而是所有任务都必须遵守的项目底线。
例如，“不要为了让测试通过而降低 lint、typecheck 或 test 配置”，就明显属于 Rules；而“修 Bug 时先复现，再写失败测试，最后做最小修复”，则更适合放进 Skill，因为它属于某一类任务的方法论。
Rules 的判断标准可以简单理解为：如果这条内容是任何任务都不能突破的红线，就放 Rules；如果它只在某类任务中生效，就不要放 Rules。
2. Skills：固化任务执行步骤，承载落地方法论
Skills 聚焦的是 某一类问题的固定处理流程，它解决的是“遇到某类任务时应该怎么做”的问题。
它不能被写成项目百科，也不能替代 Rules 存放通用约束。一个好的 Skill 应该具备明确的适用场景、执行步骤和注意事项。
以 Bug 修复流程为例，标准 Skill 可以这样写：
# Bugfix Workflow
When to use:
- A bug is reproducible
- Existing behavior regressed
- Scope should remain minimal
How it works:
1. Reproduce
2. Write failing test
3. Identify minimal fix
4. Run targeted verification
5. Summarize root cause and regression coverage
Gotchas:
- Do not refactor unrelated modules while fixing the bug
这段 Skill 的职责非常清晰：它不是告诉 Claude Code “项目里有哪些规则”，而是告诉它“当处理 Bugfix 任务时，应该按照什么步骤执行”。
因此，Debug、TDD、代码评审、安全审计、性能排查、依赖升级等具有稳定流程的任务，都适合抽象成 Skill。
比如代码评审可以封装成 Code Review Skill，安全检查可以封装成 Security Audit Skill，测试驱动开发可以封装成 TDD Skill。这样一来，团队中的所有成员在使用 Claude Code 时，都能调用同一套标准流程，避免每个人都用不同提示词描述同一件事。
Skills 的价值在于把经验沉淀为流程，而不是把流程散落在一次次聊天上下文里。
3. Commands：固定高频入口，统一启动路径
Commands 解决的是“如何快速触发某个标准动作”的问题。
Command 和 Skill 不是重复关系，而是 入口与方法 的组合关系。例如：
/review是 Command，负责触发代码评审；- Code Review Workflow 是 Skill，负责定义评审流程；
/verify是 Command，负责启动验证动作；- Verification Workflow 是 Skill，负责定义验证步骤。
如果某个操作你已经重复口头强调过很多次，例如“先帮我制定计划”“帮我做一次代码审查”“帮我检查改动是否安全”，就可以考虑封装成 Command。
这样做的好处是，团队成员不需要每次都重新描述完整需求，只需要使用统一入口即可触发标准流程。
例如：
# /review
Use this command to review the current code changes.
Steps:
1. Load the Code Review Skill.
2. Check changed files only.
3. Focus on correctness, security, maintainability.
4. Summarize risks and required fixes.
Command 本身不应该写得太重。它只需要定义触发入口和基本执行方向，具体复杂方法仍然应该交给 Skill。
换句话说，Command 是按钮，Skill 是按钮背后的执行手册。按钮越清晰，团队协作成本越低；执行手册越稳定，任务结果越一致。
4. Hooks：自动化替代人工记忆
Hooks 负责处理那些 高频、机械、易遗漏 的自动化动作。
例如：
- 文件保存后自动格式化；
- 修改 TypeScript 文件后自动执行类型检查；
- 会话结束时自动生成操作摘要；
- 提交前自动运行 lint；
- 修改配置文件后自动触发校验脚本。
这类动作有一个共同特点：它们不需要复杂推理，也不需要 Claude Code 进行多轮判断，只要满足触发条件，就应该自动执行。
适合做 Hook 的动作，一般满足三个条件：
- 高频发生；
- 机械重复；
- 人工容易忘记。
但是，复杂全链路流程不应该放入 Hooks。比如“完成需求分析 → 修改代码 → 编写测试 → 生成文档 → 提交 PR”这种多步骤任务，就不适合交给 Hook 自动执行。它应该由 Command 显式触发，再通过 Skill 规定执行流程。
Hooks 的价值，是把“人不该记的机械动作”交给系统，而不是把复杂业务流程塞进自动化脚本里。
如果 Hooks 承担了过多逻辑，反而会带来新的问题：触发时机不可控、错误难以定位、执行结果不可预测，甚至可能在开发者不知情的情况下修改重要文件。
因此，Hooks 应该保持克制，只做明确、稳定、可重复的自动化治理动作。
5. MCP：仅做外部能力接入，不承载业务流程
MCP 负责打通数据库、浏览器、文件系统、第三方平台 API、大模型 API 等外部资源。它解决的是“Claude Code 能访问哪些外部能力”的问题，而不是“某个业务流程应该怎么执行”的问题。
因此，业务的 Code Review 流程、Debug 流程、安全审计流程，仍然应该放在 Skill 或 Command 中，而不是塞进 MCP 配置里。
MCP 的边界可以这样理解：
MCP：提供外部能力
Skill：定义任务方法
Command：提供触发入口
Rules：约束行为边界
Hooks：执行机械自动化动作
在多模型接入场景下，如果项目需要同时调用 OpenAI、Claude、千问、GLM 等不同大模型 API，可以通过 TreeRouter 这类大模型 API 聚合平台统一模型调用入口。这样 Claude Code 侧只需要在 MCP 中接入一个相对统一的大模型能力来源，而不必在每个项目里分别维护多个模型厂商的 API 调用方式，从而降低多模型接入时的重复配置成本。
这里需要注意，MCP 仍然只负责“接入外部能力”，TreeRouter 也只是提供大模型 API 聚合能力。真正的业务流程，例如如何做代码审查、如何排查 Bug、如何进行安全审计，依然应该由 Skills 和 Commands 承载。
这也是五层分层设计最重要的边界之一：外部能力接入归 MCP，任务执行方法归 Skill，高频触发入口归 Command。
三、内容归属快速判断 + 四大避坑误区
1. 快速判断口诀
为了避免配置混乱，可以用下面这套口诀快速判断内容应该放在哪里：
长期约束 → Rules
任务方法 → Skills
高频入口 → Commands
自动巡检 → Hooks
外部接入 → MCP
项目总述 → CLAUDE.md
这套判断方式能解决大多数归属问题。
例如：
- “禁止修改 generated 文件”属于长期约束，放 Rules；
- “修复 Bug 时先复现再写测试”属于任务方法，放 Skills；
- “以后我要输入 /review 就开始代码审查”属于高频入口，放 Commands；
- “保存后自动格式化”属于自动巡检，放 Hooks；
- “接入数据库、浏览器或大模型 API”属于外部接入，放 MCP；
- “项目背景、目录结构、启动方式”属于项目总述，放 CLAUDE.md。
2. 高频配置错误
错误一：Skill 泛规则化
很多团队会把通用规范全部塞进 Skill，导致 Skill 变成项目说明书。
例如：
# Bad Skill
- 代码要简洁
- 不要修改核心模块
- 所有任务都要先确认
- 不要删除测试
- 遵守项目规范
这种内容没有明确任务场景，也没有具体执行步骤，更适合拆分到 Rules 或 CLAUDE.md，而不是放进 Skill。
正确做法是：长期硬性约束放 Rules，项目背景说明放 CLAUDE.md，只有具体任务方法才放 Skills。
错误二：Command 文档化
Command 的职责是提供固定入口，而不是承载大量业务说明。
如果一个 /review Command 里写了几千字代码评审方法、项目背景、规范说明和异常处理策略，那么它就已经失去了“入口”的属性。
正确做法应该是：
Command 负责触发
Skill 负责流程
Rules 负责边界
CLAUDE.md 负责背景
这样每一层都保持清晰，不会互相污染。
Command 应该尽量短，重点是告诉 Claude Code：这个指令触发什么任务、加载哪个 Skill、输出什么结果。
错误三：Hooks 承载复杂流程
Hooks 适合处理简单、机械、可预测的动作，不适合承载复杂任务流。
例如，下面这类逻辑就不适合放入 Hook：
代码保存后：
1. 自动分析需求
2. 自动修改多个模块
3. 自动补测试
4. 自动生成文档
5. 自动提交 Git
这种流程太复杂，容易误触发，也难以审计。更合理的方式，是用 Command 显式触发，再用 Skill 约束执行步骤。
Hooks 应该只做自动格式化、类型检查、简单验证、会话汇总这类明确动作，而不是替代开发者完成完整任务链路。
错误四：MCP 万能化
MCP 很容易被误用成“万能扩展入口”。一遇到需求，就想新增一个 MCP 服务，最后导致项目配置越来越臃肿。
但实际上，很多需求并不需要 MCP。
例如：
- 固定代码审查流程，不需要 MCP，应该用 Skill；
- 高频触发入口，不需要 MCP，应该用 Command；
- 保存自动格式化，不需要 MCP，应该用 Hook；
- 长期安全规则，不需要 MCP，应该用 Rules。
只有当 Claude Code 确实需要访问外部资源，例如数据库、浏览器、搜索服务、内部 API、第三方平台或大模型 API 时，才应该考虑 MCP。
MCP 的核心职责是“让 Claude Code 能访问外部能力”，不是“把所有工作流都外部化”。
四、总结
Claude Code 五层架构的核心价值，是 实现配置资产结构化管理。
Rules、Skills、Commands、Hooks、MCP 分别承担不同职责：
Rules：长期行为底线
Skills：任务执行方法
Commands：高频触发入口
Hooks：被动自动化治理
MCP：外部能力接入
遵循这套分层规范后，后续新增规则、流程、指令、自动化脚本或外部能力时，都可以快速定位应该修改哪个配置文件，避免配置四处散落。
对于 AI 工程化落地团队来说，这套分层思路可以作为团队协作规范，统一所有人的配置编写习惯，大幅降低项目长期维护成本。
更重要的是，它能帮助团队建立一套清晰的配置资产管理方式： 什么是长期规则，什么是任务方法，什么是快捷入口，什么是自动化动作，什么是外部能力接入，都可以被明确归类。
当项目规模变大、成员变多、外部能力接入变复杂时，这种分层设计可以避免 Claude Code 配置从“辅助工具”变成“维护负担”。真正稳定的 AI 工程化配置，不是把所有东西都写进一个文件，而是让每一类能力都放在它应该出现的位置。
