ECC 实战指南：Claude Code 的 Skills、Hooks、子代理、MCP 与插件完整配置方法论

ECC 实战指南：Claude Code 的 Skills、Hooks、子代理、MCP 与插件完整配置方法论

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本文基于 ECC（Everything Claude Code）仓库中的《The Shorthand Guide to Everything Claude Code》整理扩展，系统讲解一套经过长期日常使用验证的 Claude Code 工程化配置体系：以 Skills 为工作流主体、Hooks 做事件自动化、子代理做任务分权、MCP 与插件做外部能力扩展。读完后你将掌握：如何组织~/.claude/skills/、~/.claude/agents/、~/.claude/rules/三大目录，如何写出可运行的 Hook 配置，以及如何管理 MCP 上下文窗口，避免“工具太多、性能下降”的常见陷阱。

Claude Code 中把多个 slash 命令串联起来执行

Skills 与 Commands：工作流的第一公民

Skills 是工作流的主要承载层。它们是有作用域的工作流包：可复用提示词、固定结构、支撑文件，以及在需要特定执行模式时附带 codemaps（帮助模型快速导航代码库、避免在探索阶段消耗大量上下文）。

典型场景：用 Opus 完成一轮长编码之后，想清理死代码和散落的.md文件？执行/refactor-clean。需要测试？/tdd、/e2e、/test-coverage。这些 slash 入口很方便，但真正持久的单元是底层的 skill。

ECC 仓库仍然维护一个commands/层，但官方定位很明确：它应当被视为迁移期的遗留 slash 入口兼容层，持久逻辑应放在 skills 中。仓库中这一点有直接证据：

• Skills：~/.claude/skills/—— 工作流的权威定义。对应仓库目录 skills/，内含数百个 skill，如 skills/refactor-clean/、skills/tdd-workflow/、skills/e2e-testing/ 等；
• Commands：~/.claude/commands/—— 当你仍需要 slash 入口时的兼容 shim。对应仓库目录 commands/，例如 commands/refactor-clean.md 只是一个带 frontmatter 描述（"Safely identify and remove dead code with verification after each change"）的入口文件，真正的检测工具表（knip/depcheck/ts-prune/vulture/deadcode/cargo-udeps）、安全分级（SAFE/CAUTION/DANGER）和删除循环流程都写在 skill 层。

推荐的 skills 目录结构：

# 示例 skill 结构 ~/.claude/skills/ pmx-guidelines.md # 项目特定的模式约定 coding-standards.md # 各语言最佳实践 tdd-workflow/ # 多文件 skill，入口为 SKILL.md security-review/ # 基于检查清单（checklist）的 skill

一个值得借鉴的细节：skill 不只是提示词，还可以是带脚本的执行器。例如仓库里的 skills/continuous-learning-v2/ 包含.sh、.py脚本和配置文件，说明 skill 是"提示词 + 支撑代码"的复合包。

Hooks：基于事件的自动化

Hooks 是在特定事件上触发的自动化。与 skills 不同，它们被约束在工具调用和生命周期事件上，适合做强制约束与提醒。

Hook 类型（6 种）：

1. PreToolUse—— 工具执行前（校验、提醒）
2. PostToolUse—— 工具执行后（格式化、反馈循环）
3. UserPromptSubmit—— 用户提交消息时
4. Stop—— Claude 完成一次回答后
5. PreCompact—— 上下文压缩之前
6. Notification—— 权限请求

示例：长命令执行前提醒使用 tmux

{ "PreToolUse": [ { "matcher": "tool == \"Bash\" && tool_input.command matches \"(npm|pnpm|yarn|cargo|pytest)\"", "hooks": [ { "type": "command", "command": "if [ -z \"$TMUX\" ]; then echo '[Hook] 建议使用 tmux 保证会话持久化' >&2; fi" } ] } ] }

在 Claude Code 中运行 PostToolUse hook 时得到的反馈示例

进阶提示：可以用hookify插件以对话方式创建 hooks，而不是手写 JSON——运行/hookify然后描述你想要什么即可。ECC 仓库为此提供了完整的命令与 skill：commands/hookify.md、skills/hookify-rules/。

结合 ECC 仓库看 Hook 的完整实现

仓库的 hooks/README.md 给出了比短指南更完整的 Hook 运行契约，值得直接抄进你的配置笔记：

• 执行顺序：用户请求 → Claude 选择工具 → PreToolUse hook → 工具执行 → PostToolUse hook；
• 拦截语义：PreToolUse hook 可以阻塞（exit code 2）或仅警告（写 stderr 不阻塞）；PostToolUse hook 只能分析输出、不能阻塞；Stop hook 在每次回答后运行；PreCompact 适合在压缩前保存状态。

而 hooks/hooks.json 展示了生产级 hook 图的实际形态——每一条都带id、description、timeout，例如：

这里有一个工程上很关键的取舍：ECC 把"格式化 + 类型检查"这类重活从 PostToolUse（每次 Edit 后）挪到了 Stop（每次回答后跑一次），stop:format-typecheck的描述写得很直白："runs once at Stop instead of after every Edit"。这正是短指南"Automate the repetitive"原则的落地方式——自动化不等于每个事件都跑全量检查。

Hook 的运行时控制

不修改hooks.json也能精细控制 hook 行为，通过环境变量即可（见 hooks/README.md）：

# 总开关。显式的环境变量值会覆盖插件偏好。 export ECC_HOOKS_ENABLED=true # minimal | standard | strict（默认 standard） export ECC_HOOK_PROFILE=standard # 禁用特定 hook ID（逗号分隔） export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck" # 安装/恢复期临时关闭 GateGuard export ECC_GATEGUARD=off # 限制 SessionStart 附加上下文（默认 8000 字符） export ECC_SESSION_START_MAX_CHARS=4000

三个 profile 的语义：minimal只保留关键生命周期与安全 hook；standard是默认的平衡档（质量 + 安全）；strict启用额外提醒和更严格的护栏。对应地，仓库内 hook 脚本普遍通过run-with-flags.js接收standard,strict之类的档位参数（见 hooks/hooks.json 中的命令字符串）。

安装方式上，仓库明确警告不要把仓库内hooks.json原样粘贴进~/.claude/settings.json——它是面向插件/仓库的，需要通过安装器重写路径：

bash ./install.sh --target claude --modules hooks-runtime --enable-hooks # Windows PowerShell: # pwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks

这会把解析后的 hooks 安装到~/.claude/hooks/hooks.json（Windows 为%USERPROFILE%\.claude）。

自己写一个 Hook：输入输出契约

Hook 是 shell 命令，从 stdin 收到工具的 JSON 输入，必须向 stdout 输出 JSON。最小骨架（摘自 hooks/README.md）：

// my-hook.js let data = ''; process.stdin.on('data', chunk => data += chunk); process.stdin.on('end', () => { const input = JSON.parse(data); const toolName = input.tool_name; // "Edit"、"Bash"、"Write" 等 const toolInput = input.tool_input; // 工具特定参数 const toolOutput = input.tool_output; // 仅 PostToolUse 可用 // 警告（不阻塞）：写 stderr console.error('[Hook] 警告信息会展示给 Claude'); // 阻塞（仅 PreToolUse）：以退出码 2 结束 // process.exit(2); // 始终把原始数据输出到 stdout console.log(data); });

退出码约定：0继续执行；2阻塞该次工具调用（仅 PreToolUse 有效）；其他非零值记录错误但不阻塞。异步 hook 用"async": true+"timeout"字段声明，运行在后台、不能阻塞主流程。

子代理：有界作用域的任务委派

子代理是主代理（编排者）可以委派任务的进程，作用域受限，可前台或后台运行，从而为主代理腾出上下文。它们与 skills 配合良好——一个能执行你 skills 子集的子代理，可以被委派任务并自主使用这些 skills，也可以用特定工具权限做沙箱隔离。

# 子代理示例结构 ~/.claude/agents/ planner.md # 功能实现规划 architect.md # 系统设计决策 tdd-guide.md # 测试驱动开发 code-reviewer.md # 质量/安全评审 security-reviewer.md # 漏洞分析 build-error-resolver.md e2e-runner.md refactor-cleaner.md

每个子代理都应单独配置允许的工具、MCP 与权限，以达成合理的 scope。ECC 仓库的 agents/ 目录正是这种实践的规模化版本（50+ 个代理定义，覆盖各语言 reviewer、planner、e2e-runner 等）。以 agents/planner.md 为例，其 frontmatter 展示了作用域约束的最小形态：

--- name: planner description: 复杂功能与重构的专家规划代理…… tools: Read, Grep, Glob model: opus ---

tools: Read, Grep, Glob意味着这个规划代理只有只读工具——它不能写文件，只能输出计划。这就是短指南强调的"limited scopes"的具体写法：工具白名单 + 模型选择（model: opus用于高价值规划任务）共同构成子代理的边界。仓库中还有专门的 agents/code-explorer.md 用于代码导航、agents/security-reviewer.md 用于漏洞分析，可与上表中的通用角色一一对应。

规则与记忆：CLAUDE.md 单文件 vs 规则目录

.rules（或仓库内的rules/目录）存放 Claude 必须始终遵守的.md规则文件。两种组织方式：

1. 单一 CLAUDE.md—— 全部约定写在一个文件里（用户级或项目级）；
2. 规则目录—— 按关注点拆分成模块化.md文件。

~/.claude/rules/ security.md # 禁止硬编码密钥，校验输入 coding-style.md # 不可变性、文件组织 testing.md # TDD 工作流、80% 覆盖率 git-workflow.md # commit 格式、PR 流程 agents.md # 何时委派给子代理 performance.md # 模型选择、上下文管理

规则示例（可直接抄）：

• 代码库中禁用 emoji
• 前端避免紫色系配色
• 部署前必须测试
• 模块化代码优先于巨型文件
• 永远不要提交console.log

ECC 仓库对"规则目录"给出了完整的参照实现：rules/ 按语言与关注点分层，包含 rules/common/（10 个跨语言规则，如 rules/common/hooks.md）以及rules/python/、rules/typescript/、rules/rust/、rules/react/、rules/vue/等 20+ 语言/框架子目录，每个子目录都是 5～8 个.md的模块化文件。而"单一 CLAUDE.md"路线的范例在 examples/ 下：examples/CLAUDE.md、examples/go-microservice-CLAUDE.md、examples/django-api-CLAUDE.md 等，都是面向具体技术栈的项目级 CLAUDE.md 模板，可以直接拷贝到项目根目录改造使用。

MCP（Model Context Protocol）：外部服务直连与上下文窗口管理

MCP 把 Claude 直接连接到外部服务。它不是 API 的替代品，而是围绕 API 的提示驱动封装层，让信息导航更灵活。典型例子：Supabase MCP 让 Claude 直接拉取特定数据、在上游执行 SQL，无需复制粘贴；数据库、部署平台同理。仓库的 mcp-configs/mcp-servers.json 提供了 30+ 个现成 MCP 定义（每个都带description字段说明用途），例如 Supabase 条目就是短指南里那个示例的直接落地：

"supabase": { "command": "npx", "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_PROJECT_REF"], "description": "Supabase database operations" }

关键警告：上下文窗口管理

对 MCP 要严格挑剔。短指南作者的做法是：所有 MCP 都保留在用户配置里，但禁用一切当前不用的——通过/plugins向下翻或运行/mcp查看状态。

你的 200k 上下文窗口，在开启过多工具后压缩前可能只剩 70k。性能会显著劣化。

经验法则：配置里可以放 20–30 个 MCP，但保持启用数 < 10 / 激活工具数 < 80。

# 查看已启用的 MCP /mcp # 在 ~/.claude/settings.json 或当前仓库的 .mcp.json 中禁用不用的

仓库侧对这一规则同样有硬约束：mcp-configs/mcp-servers.json 末尾的_comments明确写着"context_warning": "Keep under 10 MCPs enabled to preserve context window"，并给出禁用手段——ECC_DISABLED_MCPS=github,context7,...在安装/同步阶段禁用打包的 MCP，或在项目配置里用disabledMcpServers做项目级覆盖。另外 hooks/hooks.json 中的pre:mcp-health-check/post:mcp-health-check会检查 MCP 服务健康状态、拦截不健康的 MCP 调用并尝试重连——即"少启用 + 健康监测"是配套的。

Chrome in Claude：内置的浏览器控制插件，让 Claude 自主操作浏览器、点击探索功能行为；仓库配置中对应的能力由 Playwright / Browserbase / browser-use 等 MCP 提供（见 mcp-configs/mcp-servers.json 中playwright、browserbase条目）。

Plugins：打包好的工具集

插件把工具打包成"一次安装"而不是繁琐的手动配置。一个插件可以是 skill + MCP 的组合，也可以是 hooks/工具的捆绑。

安装插件：

# 添加一个 marketplace（以 mixedbread-ai 的 mgrep 插件为例，地址换成其官方仓库） claude plugin marketplace add <mgrep 官方仓库地址> # 打开 Claude，运行 /plugins，找到新 marketplace，从那里安装

LSP 类插件在你经常在编辑器外运行 Claude Code 时特别有用：Language Server Protocol 让 Claude 在没有打开 IDE 的情况下获得实时类型检查、跳转定义和智能补全。

# 已启用插件示例 typescript-lsp@claude-plugins-official # TypeScript 智能 pyright-lsp@claude-plugins-official # Python 类型检查 hookify@claude-plugins-official # 对话式创建 hooks mgrep@Mixedbread-Grep # 比 ripgrep 更强的搜索

与 MCP 同样的警告——盯住你的上下文窗口。ECC 仓库自身的插件层在 plugins/ 与 plugins/ecc/，配套的 schemas/plugin.schema.json 定义了插件清单结构，安装/更新流程可用ecc setup --mode claude-plugin（见 hooks/README.md）。

实用技巧（Tips & Tricks）

键盘快捷键

• Ctrl+U—— 删除整行（比狂按退格快）
• !—— 快速 bash 命令前缀
• @—— 文件搜索
• /—— 发起 slash 命令
• Shift+Enter—— 多行输入
• Tab—— 切换思考过程显示
• Esc Esc—— 中断 Claude / 恢复代码

并行工作流

• Fork（/fork）—— 分叉对话，让不重叠的任务并行执行，而不是在消息队列里排队；
• Git Worktrees—— 让互相重叠的多个 Claude 实例互不冲突。每个 worktree 是独立的 checkout：

git worktree add ../feature-branch feature-branch # 然后在每个 worktree 里跑独立的 Claude 实例

tmux 处理长命令

对 Claude 执行的日志/bash 进程做流式观察；断线后重连即可：

tmux new -s dev # Claude 在这里执行命令，你可以 detach 再 attach tmux attach -t dev

这条技巧与上一节的 hooks 呼应：ECC 的pre:bash:dispatcher中就内置了"dev server blocker（tmux 外阻塞npm run dev）+ tmux 提醒"两个 Bash 级检查（见 hooks/README.md 的 PreToolUse 表）。

mgrep > grep

mgrep相对 ripgrep/grep 是显著增强。通过插件 marketplace 安装后，用/mgrepskill 调用；本地与 web 搜索都支持：

mgrep "function handleSubmit" # 本地搜索 mgrep --web "Next.js 15 app router changes" # web 搜索

其他实用命令

• /rewind—— 回到之前的状态
• /statusline—— 自定义状态行（分支、上下文百分比、todos 等）
• /checkpoints—— 文件级撤销点
• /compact—— 手动触发上下文压缩

仓库对/compact有配套自动化：pre:edit-write:suggest-compacthook 会在约每 50 次工具调用后建议手动压缩，配合 skills/strategic-compact/ 与 skills/context-budget/、skills/token-budget-advisor/ 形成完整的上下文预算体系。

CI/CD 与 GitHub Actions

配合 GitHub Actions 在 PR 上自动触发代码评审，配置好后 Claude 可以自动 review PR。仓库对应能力包括 commands/code-review.md、commands/review-pr.md、agents/code-reviewer.md 以及面向 CI 的 tests/ci/ 测试集。

Sandboxing

高风险操作用 sandbox 模式——Claude 在受限环境中运行，不影响真实系统。

编辑器选择

编辑器选择会显著影响 Claude Code 的工作流。虽然 Claude Code 在任何终端都能跑，但配一个称手的编辑器能解锁实时文件跟踪、快速导航和集成命令执行。

Zed（原作者首选）

用 Rust 编写，真正快：瞬间打开、轻松处理超大代码库、几乎不占系统资源。

为什么 Zed + Claude Code 是好组合：

• 速度—— Claude 快速改文件时编辑器不掉队；
• Agent Panel 集成—— 实时跟踪 Claude 的文件变更，在 Claude 引用的文件间跳转而无需离开编辑器；
• CMD+Shift+R命令面板—— 以可搜索 UI 快速访问自定义 slash 命令、调试器、构建脚本；
• 资源占用极低—— 重型操作时不与 Claude 争抢 RAM/CPU（跑 Opus 时尤其重要）；
• Vim 模式—— 完整的 vim 键位。

编辑器无关的通用建议：

1. 分屏—— 一边终端跑 Claude Code，一边编辑器；
2. Ctrl+G—— 在 Zed 中快速打开 Claude 正在处理的文件；
3. 自动保存—— 保证 Claude 读到的文件永远是最新状态；
4. Git 集成—— 用编辑器的 git 功能在确认前审查 Claude 的改动；
5. 文件监视—— 大多数编辑器会自动重载被修改的文件，确认该功能已开启。

VSCode / Cursor

同样是可行选择，与 Claude Code 配合良好。可以走终端形态，通过\ide与编辑器自动同步（启用 LSP 能力，如今与 LSP 插件有些重叠）；也可以用与编辑器深度集成、UI 同风格的官方扩展。

作者的完整配置（My Setup）

插件

已安装（平时通常只启用其中 4–5 个）：

ralph-wiggum@claude-code-plugins # 循环自动化 frontend-patterns@claude-code-plugins # UI/UX 模式 commit-commands@claude-code-plugins # git 工作流 security-guidance@claude-code-plugins # 安全检查 pr-review-toolkit@claude-code-plugins # PR 自动化 typescript-lsp@claude-plugins-official # TS 智能 hookify@claude-plugins-official # 创建 hooks code-simplifier@claude-plugins-official feature-dev@claude-code-plugins explanatory-output-style@claude-code-plugins code-review@claude-code-plugins context7@claude-plugins-official # 实时文档 pyright-lsp@claude-plugins-official # Python 类型 mgrep@Mixedbread-Grep # 更强搜索

MCP 服务器

已配置（用户级）：

{ "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }, "firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"] }, "supabase": { "command": "npx", "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_REF"] }, "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] }, "sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] }, "vercel": { "type": "http", "url": "https://mcp.vercel.com" }, "railway": { "command": "npx", "args": ["-y", "@railway/mcp-server"] }, "cloudflare-docs": { "type": "http", "url": "https://docs.mcp.cloudflare.com/mcp" }, "cloudflare-workers-bindings": { "type": "http", "url": "https://bindings.mcp.cloudflare.com/mcp" }, "clickhouse": { "type": "http", "url": "https://mcp.clickhouse.cloud/mcp" }, "AbletonMCP": { "command": "uvx", "args": ["ableton-mcp"] }, "magic": { "command": "npx", "args": ["-y", "@magicuidesign/mcp@latest"] } }

这正是关键点：作者配置了十几个 MCP，但每个项目只启用约 5–6 个，从而保持上下文窗口健康。对比仓库的 mcp-configs/mcp-servers.json，可以看到 ECC 把这一策略扩展成了带描述、带占位符说明、带_comments使用指引的完整目录（github、firecrawl、supabase、memory、sequential-thinking、vercel等条目与上方个人配置高度重合，另含jira、exa-web-search、context7、playwright等更多选项，注释中提示"复制你需要的 servers 到你的~/.claude.json的mcpServers段"）。

关键 Hooks

{ "PreToolUse": [ { "matcher": "npm|pnpm|yarn|cargo|pytest", "hooks": ["tmux 提醒"] }, { "matcher": "Write && .md 文件", "hooks": ["除非是 README/CLAUDE 否则拦截"] }, { "matcher": "git push", "hooks": ["打开编辑器做评审"] } ], "PostToolUse": [ { "matcher": "Edit && .ts/.tsx/.js/.jsx", "hooks": ["prettier --write"] }, { "matcher": "Edit && .ts/.tsx", "hooks": ["tsc --noEmit"] }, { "matcher": "Edit", "hooks": ["console.log 警告"] } ], "Stop": [ { "matcher": "*", "hooks": ["检查被修改文件中的 console.log"] } ] }

这张"个人 hooks 清单"与仓库 hooks/README.md 中的官方 hook 表几乎逐项对应：tmux 提醒（warn）、文档文件警告（warn）、push 前提醒（warn）、Prettier 格式化、tsc --noEmit类型检查、console.log 检查——可以把它视为短指南作者个人配置与 ECC 内置 hook 集的共同最小核心。

自定义状态行

状态行展示用户、目录、带脏标记的 git 分支、剩余上下文百分比、模型、时间和 todo 数：

状态行示例（作者 Mac 根目录）

affoon:~ ctx:65% Opus 4.5 19:52 ▌▌ plan mode on (shift+tab to cycle)

ECC 仓库提供了一份可直接抄的 statusline 配置模板 examples/statusline.json：指向scripts/hooks/ecc-statusline.js，显示"模型 | 当前任务 | 花费$ 工具数 文件数 时长 | 目录 | 上下文进度条"，并按上下文使用率着色（<50% 绿、<65% 黄、<80% 橙、≥80% 红色闪烁）。注释中给出了输出样例：Opus 4.6 | Fixing auth bug | $1.23 47t 5f 15m | myproject ███████░░░ 68%，并说明完整指标显示需要同时安装配套的ecc-metrics-bridge.jsPostToolUse hook。把statusLine对象拷入~/.claude/settings.json并替换<plugin-root>即可。

规则目录结构

~/.claude/rules/ security.md # 强制安全检查 coding-style.md # 不可变性、文件大小上限 testing.md # TDD、80% 覆盖率 git-workflow.md # 约定式提交 agents.md # 子代理委派规则 patterns.md # API 响应格式 performance.md # 模型选择（Haiku vs Sonnet vs Opus） hooks.md # hooks 文档

子代理清单

~/.claude/agents/ planner.md # 拆解功能 architect.md # 系统设计 tdd-guide.md # 先写测试 code-reviewer.md # 质量评审 security-reviewer.md # 漏洞扫描 build-error-resolver.md e2e-runner.md # Playwright 测试 refactor-cleaner.md # 死代码清理 doc-updater.md # 保持文档同步

上述 9 个代理在仓库 agents/ 中全部有对应实现文件，且都遵循统一的 frontmatter 约定（name/description/tools/model），可作为自建子代理的模板。

关键结论（Key Takeaways）

1. 不要过度设计—— 把配置当作调优（fine-tuning），而不是架构工程；
2. 上下文窗口是稀缺资源—— 禁用不用的 MCP 和插件（启用数 < 10、工具数 < 80）；
3. 并行执行—— 分叉对话（/fork）+ git worktrees；
4. 自动化重复劳动—— 用 hooks 做格式化、lint、提醒（并注意把重检查挪到 Stop 事件批量执行）;
5. 约束子代理作用域—— 工具白名单 = 专注执行。

以上配置均基于 Claude Code 的插件体系（skills、hooks、subagents、MCP、plugins）；原文档在 Claude Code 官方文档的 Plugins、Hooks、Checkpointing、Interactive Mode、Memory、Subagents、MCP Overview 等章节中有对应的参考说明（可查阅 Claude Code 官方文档站）。如需更深入的进阶模式，可继续阅读仓库中的长文指南 docs/es/the-longform-guide.md（西班牙语版）或 the-longform-guide.md（英文版）。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC