深入理解 Claude Code 的五大核心概念:结合 ECC 看懂 Agent、Skill、Command、Hook 与 Rule
本文将深入解析 Claude Code 的五个核心概念:Agent、Skill、Command、Hook 与 Rule,厘清它们的职责、区别和协作方式。文章以 ECC(Everything Claude Code) 的实际配置为例,说明这些概念如何落地到开发流程中。
核对日期:2026-10-25。本文依据 Claude Code 官方文档与 ECC 的
main分支,核查时 ECC 插件清单标记版本为2.2.3。文中会区分仓库现有实现和基于 ECC 编写的教学配置;源码路径不等同于安装后的路径。
为什么用 ECC 学习 Claude Code?
ECC,全称 Everything Claude Code,是由社区开发者 Affaan Mustafa 维护的开源项目。它把子代理、Skills、命令入口、Hooks、规则和辅助脚本组织在同一个仓库中,将需求规划、测试驱动开发、代码审查等实践沉淀成可以阅读、修改和组合的配置。ECC 项目介绍
对于想学习 Claude Code 配置语法的人,ECC 是一个很好的实例库。 官方文档解释字段的含义,ECC 则展示这些字段如何用在具体任务中:Markdown 文件顶部的 YAML 怎样描述角色与工具,SKILL.md 怎样组织技能,JSON 怎样注册 Hook 事件,以及规则文件怎样表达项目约定。把文档和实际文件对照起来,比只记住概念名称更容易理解。
阅读时,可以先比较 agents/planner.md 与 skills/tdd-workflow/SKILL.md,看清子代理和技能的定义方式;再查看 commands/plan.md、hooks/hooks.json 与 rules/,理解工作流入口、事件自动化和项目规范各自如何配置。本文也会沿着这些实例展开,让你既能读懂配置,也能判断自己的项目应该使用哪一种机制。
ECC 展示的是社区项目的工程实践,具体字段的语义与兼容性仍以 Claude Code 官方文档为准。例如,/ecc:plan 来自 ECC 配置,不能当成 Claude Code 在任何环境下都有的内置命令。
先用一张表看清分工
| 概念 | 解决的问题 | 在 ECC 中的例子 |
|---|---|---|
| Agent(此处以 Subagent 为例) | 由哪个执行者承担任务,使用哪些工具 | agents/planner.md、agents/tdd-guide.md |
| Skill | 这类工作按什么步骤、知识和检查清单完成 | skills/tdd-workflow/、skills/security-review/ |
| Command | 用户如何快速进入一个操作或工作流 | commands/plan.md 提供规划入口 |
| Hook | 哪个事件发生时,自动运行哪些检查或动作 | hooks/hooks.json 注册工具调用与会话事件 |
| Rule | 项目中哪些约定需要持续提供给 Claude | rules/common/security.md 等规则文件 |
这张表描述的是职责。尤其要注意:如今自定义 Command 与 Skill 已经合并到统一机制中,不能再把它们解释成两套互不相干的系统。 后文会单独说明这一变化。
1. Agent:先区分通用语境与 Claude Code 中的具体含义
Agent 这个词容易引起误解,因为它在不同语境下指向的对象不完全相同。理解 ECC 之前,需要先把这两个层次分开。
通用语境:Claude Code、Codex 这类能够调用工具的智能软件
当我们说“Claude Code、Codex 都是编程 Agent”时,指的是能够围绕目标推理、调用工具并持续采取行动的软件系统。例如,调用 Windows 上的系统工具、读写文件、运行终端命令,或访问外部服务。
这里的 Agent 指向完整的智能软件系统:模型负责理解和决策,软件提供工具调用、上下文管理与执行环境。它的关键特征,是能形成“获取信息 → 执行动作 → 观察结果 → 决定下一步”的循环。Claude Code 官方工作机制说明
Claude Code 配置语境:agents/ 目录中放的是 Subagents
进入 Claude Code 的具体配置后,还需要区分主 Agent与 Subagent(子代理):主 Agent 是当前会话中直接与你协作、统筹任务的执行者;Subagent 则接受它委派的任务,在自己的上下文中工作,再返回结果。
Claude Code 的 .claude/agents/、~/.claude/agents/,以及 ECC 仓库中的 agents/,存放的是子代理的定义文件。 这些 Markdown 文件配置子代理的角色、工具、模型等信息;实际运行的是根据这些配置启动的子代理。官方 Subagents 文档
因此,看到“使用一个 Agent”时,要先判断上下文:讨论工具产品时,可能指 Claude Code、Codex 这样的完整软件;讨论 ECC 的 agents/planner.md 时,指的就是 Claude Code 内部的一个子代理定义。下文涉及 ECC 配置时,Agent 主要指 Subagent;涉及当前会话的统筹者时,会明确称为主 Agent。
子代理可以理解为团队中的专门角色。以 ECC 的实际配置为例:
| 子代理 | 主要职责 | 配置中的工具范围 |
|---|---|---|
planner | 分析需求、拆解步骤、识别依赖与风险 | Read, Grep, Glob |
tdd-guide | 指导测试先行、实现与重构 | Read, Write, Edit, Bash, Grep |
code-reviewer | 审查代码质量、安全与可维护性 | Read, Grep, Glob, Bash |
这里值得观察的是工具配置:planner 没有 Write 和 Edit,而 tdd-guide 可以修改文件。角色之间的差异,既体现在提示词,也体现在可使用的工具上。配置可直接查看 planner、tdd-guide 和 code-reviewer。
不过,“独立上下文”不代表“独立机器”或“自动隔离文件修改”。普通子代理通常仍在同一个项目中工作;需要文件隔离时,应另外配置工作树等机制。子代理也会消耗模型调用资源,适合职责明确或需要隔离大量中间信息的工作。官方 Subagents 文档
2. Skill:可以反复使用的专业方法
如果 Agent 是承担工作的工程师,Skill 就是可以带给不同工程师使用的操作手册。
但这本“手册”可以包含更多东西:任务步骤、检查清单、参考文档、模板,以及按需使用的脚本。Skill 本身不是一个持续运行的助手;它为执行任务的 Agent 提供知识和方法。
在 ECC 中,两项容易理解的技能是:
tdd-workflow:把测试驱动开发组织为先验证失败,再实现通过,最后重构的工作流。security-review:提供密钥管理、输入校验、注入防护、身份认证等方面的检查清单与示例。
它们都以 SKILL.md 为入口,放在各自的技能目录中。Claude 通常先看到技能的名称与简介,相关时再加载正文,支持文件则按需读取。这种渐进加载方式,避免把所有操作手册一次塞进上下文。Anthropic 对 Skills 的解释
技能能否被自动选中,也取决于简介、调用设置和当前任务,不能把它理解成“只要出现某种代码就必定触发”。对于必须明确启动的流程,可以直接输入对应的 /技能名。
Agent 与 Skill 到底有什么区别?
ECC 同时存在 tdd-guide 子代理和 tdd-workflow Skill,恰好说明这两个概念为什么需要分开。
tdd-guide 定义一个测试驱动开发角色;tdd-workflow 则沉淀这类工作的具体方法。主 Agent 可以直接使用这项 Skill,其他负责实现功能的 Agent 也可以复用它。
| 比较维度 | Agent / Subagent | Skill |
|---|---|---|
| 核心职责 | 承担任务、推理并使用工具 | 提供可复用的知识、步骤和资源 |
| 上下文 | 子代理有自己的上下文 | 默认加载到当前执行者的上下文 |
| 配置重点 | 角色、工具范围、模型等 | 使用时机、工作步骤、支持材料等 |
| 组合方式 | 一个 Agent 可以使用多项 Skills | 一项 Skill 可以服务多个 Agents |
| 适用场景 | 需要明确分工或隔离中间信息 | 同一套方法需要反复使用 |
这里的“默认”很关键:Skill 也可以通过 context: fork 指定在子代理中执行,并用 agent 选择执行者。因此,Skill 和 Agent 可以组合,二者并不是互相替代的关系。官方扩展机制概览
如何让 Agent 自带指定的 Skills?
Claude Code 为此提供了明确的配置字段:在 Agent 的 YAML frontmatter 中填写 skills。
以下示例基于 ECC 的技能做扩展,不是 ECC 原始 Agent 文件的逐字复制。先确保两项 ECC Skills 已作为项目技能安装并可被发现,目录结构如下:
your-project/
└── .claude/
├── agents/
│ └── ecc-tdd.md
└── skills/
├── tdd-workflow/
│ └── SKILL.md
└── security-review/
└── SKILL.md
这里只展示关键文件。安装技能时还要保留它们依赖的支持材料,并按项目适配测试命令与脚本路径;不要把 ECC 仓库根目录中的脚本路径当成任何业务项目都已有的文件。
然后创建 .claude/agents/ecc-tdd.md:
---
name: ecc-tdd
description: 为新增接口、缺陷修复和重构执行测试驱动开发,并检查安全问题。
tools: Read, Write, Edit, Bash, Grep, Glob, Skill
model: inherit
skills:
- tdd-workflow
- security-review
---
你是本项目的测试驱动开发助手。
结合预加载的技能完成委派任务:
1. 阅读相关实现,确认验收条件和项目实际使用的测试命令。
2. 先编写测试并验证失败原因,再完成最小实现。
3. 测试通过后重构,检查输入校验、权限和敏感信息处理。
4. 返回修改文件、验证结果以及尚未解决的问题。
保存配置后,在新会话中通过 /agents 检查 ecc-tdd 是否可见,再明确提出委派请求:
请让 ecc-tdd 子代理实现密码重置接口。
验收条件:令牌只能使用一次,过期令牌被拒绝,响应不泄露邮箱是否已注册。
这段配置的含义是:
description告诉主 Agent,什么时候适合把任务交给这个子代理。tools配置它可使用的工具;具体动作仍受会话权限约束。skills在子代理启动时注入指定技能的完整正文,让它从开始就获得这些方法。
预加载技能,不等于执行其中的全部脚本,也不等于自动取得额外权限。 此外,skills 是预加载列表,并非技能访问白名单;在工具与策略允许时,子代理仍可通过 Skill 工具发现、调用其他技能。官方预加载说明
还有三个容易踩坑的细节:
- 普通子代理不会自动继承父会话已加载的 Skill 正文;需要的信息应通过任务说明传递,或在自己的
skills中预加载。 - 设为
disable-model-invocation: true的技能不能用于这种预加载;名称不存在或技能被禁用时,也不会成功注入。 - 本例使用项目本地技能名。插件安装后的斜杠入口带有命名空间,不能把
/ecc:tdd-workflow原样当成本例的本地技能名。
回头看 ECC 源码还有一个有意思的细节:核查时,agents/tdd-guide.md 在正文中提示参考 skill: tdd-workflow,但没有在 YAML 中声明 skills。正文引用与启动预加载是两种不同的写法,不要仅凭一句引用就认定技能已经注入。ECC tdd-guide 源码
3. Command:调用入口还在,自定义命令已向 Skills 统一
现在回答最容易过时的问题:Command 是不是正在被废弃?
准确的说法是:自定义斜杠命令已并入 Skills,旧的 commands 格式继续兼容;斜杠调用入口与内置命令没有整体废弃。
Claude Code 在 v2.1.3 版本记录中宣布合并 slash commands 与 skills。当前文档也明确说明,下面两种定义都能提供 /review:
旧格式:.claude/commands/review.md
Skill: .claude/skills/review/SKILL.md
因此,不宜再用“Command 只能手动调用、Skill 只能自动触发”来区分它们。Skill 既能由用户直接调用,也能在配置允许时由 Claude 选择使用;同名的 Skill 与旧命令文件同时存在时,Skill 优先。官方 Skills 文档
需要分清三个层次:
| 你看到的东西 | 当前应该怎样理解 |
|---|---|
/help、/compact 等内置命令 | Claude Code 提供的产品操作,继续存在 |
.claude/commands/*.md | 仍兼容的自定义命令旧格式 |
.claude/skills/<name>/SKILL.md | 新建可复用工作流时优先采用的形式 |
官方对插件同样建议新内容采用 Skills,保留 commands/ 主要用于迁移已有命令。现有配置可以继续使用,无需因为目录名较旧就立即全部重写。官方插件组件说明
ECC 为什么还保留 commands?
因为向 Skills 统一,并不意味着所有现有入口都要立即删除。
ECC 的 README 将 Skills 定位为主要工作流入口,同时保留部分命令与兼容入口;它还明确指出,旧的 /tdd 等短名称已经移到 legacy-command-shims/,需要主动选择使用。阅读旧教程时,应先确认自己安装的版本与实际可用入口。ECC README
插件安装后,可以使用这样的命名空间形式:
/ecc:plan 为项目增加密码重置功能
/ecc:tdd-workflow
如果是把相应配置直接安装到项目本地,入口通常是 /plan、/tdd-workflow。两种安装方式不要在示例中混用。
另一个需要纠正的常见说法是“/plan 一定调用 planner Agent”。核查时,ECC 的 commands/plan.md明确要求默认在当前会话中规划;只有具备相应子代理且用户明确要求委派时,才使用可选的 planner。一个命令背后是否调用 Agent,要看它实际写了什么。
4. Hook:在事件发生时运行自动化动作
Skill 规定“这类任务应该怎么做”,Hook 则把某个动作接到明确的事件上:工具执行前检查参数、执行后运行质量检查,或在会话生命周期节点保存状态。
常见的命令型 Hook 由 Claude Code 触发脚本,减少对模型临时记起某个步骤的依赖。Hook 也有使用模型判断的类型,因此不能把所有 Hook 的内部逻辑都说成完全确定。官方 Hooks 指南
在 ECC 中,可以沿着 hooks/hooks.json 找到这些实际配置:
| 事件 | ECC 中的脚本入口 | 理解重点 |
|---|---|---|
PreToolUse,匹配 Bash | pre-bash-dispatcher.js | 在命令执行前进入检查流程 |
PostToolUse | posttooluse-dispatcher.js | 工具成功后分派质量检查、变更记录等动作 |
Stop | stop-format-typecheck.js 等 | 在 Claude 准备结束本轮响应时处理检查 |
SessionEnd | session-end-marker.js | 会话结束时记录相应状态 |
配置见 ECC hooks.json,分派逻辑可看 PreToolUse 入口与 PostToolUse 入口。具体哪些检查运行,还受 Hook 配置、匹配条件和 ECC 所选 profile 影响。
理解 Hook,尤其要区分两个时间点:
- 执行前拦截:
PreToolUse可以拒绝尚未发生的工具调用。 - 执行后反馈:
PostToolUse面对的是已经成功执行的动作;发现问题不等于自动撤销刚才的修改。
另外,匹配 Edit|Write 的 Hook 只覆盖这些工具调用,不能自动覆盖 Bash 或外部程序造成的所有文件修改。Hook 的保障范围取决于它接在哪个事件、检查了什么。官方 Hook 事件说明
5. Rule:持续提供给 Claude 的项目约定
Rule 适合放那些跨任务成立的要求:使用什么包管理器、代码遵循什么约定、哪些目录不能修改、敏感信息如何处理。
在 Claude Code 中,常见载体是 CLAUDE.md 和 .claude/rules/ 下的 Markdown 文件。Rule.md 并不是一个具有特殊魔法的固定文件名。
ECC 将规则分为通用要求和语言、框架要求。例如,rules/common/security.md 规定密钥不得硬编码、输入需要校验等要求;rules/typescript/ 则补充对应技术栈的约定。ECC 安全规则、ECC Rules 结构说明
把它与 security-review Skill 对照,就能看清分工:规则持续表达安全要求,Skill 提供执行安全检查时使用的方法和示例。
规则并不一定全部全局加载
常见位置包括个人级 ~/.claude/rules/ 和项目级 .claude/rules/。规则还可以通过 YAML 的 paths 字段限定文件范围。例如,下面是一条自行编写的 API 规则:
---
paths:
- "src/api/**/*.ts"
---
# API 开发约定
- 校验来自客户端的输入。
- 对错误使用项目统一的响应格式。
- 处理用户数据前检查身份与权限。
这样的规则按匹配文件加载,不能概括成“所有规则在启动时无条件生效”。路径匹配与具体加载规则见官方项目记忆文档。
更关键的是,Rule 属于模型上下文,不等于程序层面保证执行的约束。 对必须执行的检查,应配合权限、适当的 Hook 和 CI。写一句“禁止提交密钥”可以表达要求;若要在提交或合并时拦截密钥,还需要实际的扫描与阻断机制。官方对持久指令的说明
使用 ECC 插件时,也不要默认规则包已同步安装。ECC README 明确要求按需补充规则;项目级规则可以采用 .claude/rules/ecc/common/、.claude/rules/ecc/typescript/ 这样的目录,保留通用层与技术栈层的结构。ECC 规则安装说明
把五个概念放进一次真实开发流程
假设现在要给 TypeScript 项目增加密码重置功能。沿用前面的 ECC 配置,我们可以这样组织工作:
第一步,用规则提供项目背景。 CLAUDE.md 说明目录与测试命令,项目规则说明输入校验、错误处理和密钥管理要求。
第二步,从规划入口启动。 输入 /ecc:plan,让当前会话梳理接口、令牌有效期、邮件发送依赖和验收条件。按 ECC 该入口的设计,确认计划后再进入实现。
第三步,将实现委派给配置好的执行者。 明确要求由自定义的 ecc-tdd 子代理处理,并传入计划和验收条件。它启动时预加载本地安装的 tdd-workflow 与 security-review,按照测试先行的方法推进,同时检查认证与输入处理。
第四步,在工具事件上运行自动化检查。 如果 ECC Hooks 已启用,符合匹配条件的工具调用会进入对应检查流程;需要修正的问题再交给 Agent 处理。
第五步,检查结果。 可以通过 /ecc:code-review 发起对本地改动的审查,结合测试、类型检查与实际行为确认结果。这是 ECC 提供的审查入口;若希望由某个专门子代理审查,应明确提出委派要求,而不是只凭命令名推断。ECC code-review 实现
下面这张图描述上述组合方式,并不表示 ECC 默认把所有环节自动串好了:
实际配置时,可以按问题选择机制:需要长期提供的项目约定,放进 Rule;重复使用的方法,整理为 Skill;需要独立职责与上下文,定义 Agent;需要便捷入口,通过 / 调用 Skill,并兼容已有 Command;需要在事件发生时运行检查,配置 Hook。
对于多数项目,从少量清晰的规则和一两个高频 Skills 开始,就足以改善协作。等到任务确实需要分工,再增加 Agent;等到某项检查需要稳定触发,再接入 Hook。读懂 ECC 的重点,是知道每个配置解决什么问题,以及它实际何时参与工作。