开源 Agent 套件 ECC 的三本指南：一套系统三种密度，分别写给谁

本文基于 ECC 仓库 commit 591ab5c（2026-07-29）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/affaan-m/ECC 最新代码与文档为准。

这三本指南不是同一篇文章的长中短三个版本，而是三种失败模式各配了一份文档：装不起来、用得太贵、出了事。 把它们当”详略不同的同一份说明书”去读，你会在第二本里觉得重复，在第三本里觉得跑题，然后哪一本都没读完。

ECC 仓库根目录并排放着 the-shortform-guide.md、the-longform-guide.md、the-security-guide.md 三个文件，README 里有一个 Guides 区块把它们摆成一排，并写了一句定位：这个仓库是原料，指南负责解释。原料是 agents/ 下的 67 个 agent、skills/ 下的 281 个技能、commands/ 下的 94 个命令，加上 hooks、rules、记忆与安全扫描。你光看目录树是读不出”该先动哪个”的，三本指南就是干这个的。

一、三本各站在哪一层

短指南，文件名是 the-shortform-guide.md，标题却写着 The Shorthand Guide to Everything Claude Code——文件名和标题的用词不一致，别被这点小事绊住。它是一次配置面板巡礼：skills 与 commands 各是什么、hooks 有哪几种触发点（PreToolUse、PostToolUse、UserPromptSubmit、Stop、PreCompact、Notification）、subagent 怎么划范围、rules 与记忆放哪、MCP 与插件怎么管，外加快捷键、git worktree、tmux、编辑器搭配这些边角。

短指南里有一句判断值得先记住：commands/ 这一层被明确定位成迁移期的 legacy slash-entry 兼容层，耐久的逻辑应该住在 skills 里。这句话决定了你自己往里加东西时该加在哪。

长指南 the-longform-guide.md 开头就写了前置条件：先读短指南，后面的内容默认你已经把 skills、agents、hooks、MCP 配好在跑。它讲的是长时间会话里那些具体的疼：可被替代的 MCP 用 CLI 加 skill 顶掉、用 claude --system-prompt 按场景动态注入上下文、PreCompact 与 Stop 与 SessionStart 三个钩子怎么把状态跨会话续上、把重复踩到的坑沉淀成新技能、按任务难度分层选模型、pass@k 与 pass^k 两种验收口径的区别、worktree 与 cascade 式并行、以及 orchestrator 分阶段推进（RESEARCH、PLAN、IMPLEMENT、REVIEW、VERIFY）时每个阶段一进一出的规矩。

安全指南 the-security-guide.md 的标题是 The Shorthand Guide to Everything Agentic Security，主题换了：进入上下文窗口的一切文本都是可执行的，“数据”和”指令”在模型眼里没有边界；工具描述本身可以撒谎；技能、钩子、MCP 配置都属于供应链产物。它给出的动作是容器与网络隔离、权限 deny 基线、审批边界（作者管这叫 least agency，最小行动权）、日志该记哪几个字段、怎么杀进程组和挂心跳看门狗、持久记忆要保持窄且可丢弃，最后收在一份”最低门槛清单”上。作者在这本里点名，AgentShield 就是为这个问题域做的。

二、把文档和目录对上

三本指南最有用的读法，是每读到一个技巧就去仓库里找它的落点。下面这张表是我按这次快照对出来的：

你手上的东西	它负责什么	仓库里的位置	你什么时候会碰到它
短指南	配置面板巡礼，装起来能跑	the-shortform-guide.md	第一天
长指南	上下文经济、记忆、评测、并行	the-longform-guide.md	会话开始变卡变贵之后
安全指南	攻击面、隔离、审批与日志	the-security-guide.md	准备放手让它自己跑之前
三本的入口	并排索引与一句定位	README.md 的 Guides 区块	每次找不到该读哪本
跨会话记忆钩子	会话生命周期上的存取	hooks/memory-persistence/	读长指南的记忆那节
持续学习	把重复踩坑沉淀成技能	skills/continuous-learning/	同一个问题第三次复述时
场景化上下文	动态注入的三份系统提示	contexts/dev.md、contexts/review.md、contexts/research.md	想按模式切换而不是堆一个大文件
主动压缩与评测	手动压缩建议与验证循环	skills/strategic-compact/、skills/eval-harness/、skills/verification-loop/	关掉自动压缩之后
安全扫描	扫钩子、提示注入、权限、密钥	skills/security-scan/、commands/security-scan.md	装了别人的技能之后
原料本体	可选装的能力集合	agents/、skills/、commands/	挑装的时候

对到这一步你会发现，长指南几乎每讲一个技巧，仓库里都能指到一个具体目录。这不是巧合，是文档与代码同仓带来的好处——改代码时顺手能改文档，读文档时能当场验伪。

三、按什么顺序读，以及什么时候该换顺序

默认顺序就是作者铺的那条：短、长、安全。长指南自己写了前置声明，安全指南结尾也在提示你补前两篇。

两种情况要换顺序。

第一种，你打算在装着生产凭据、公司代码或客户数据的机器上跑长时间自动化。那就先读安全指南的隔离和最低门槛两节，再回头装。理由很直白：装完再补隔离，等于先把门开了再研究锁怎么买。

第二种，你已经用编码 Agent 半年以上，配置早就齐了。短指南对你只有两处有增量：commands 与 skills 的分工定位，以及 MCP 数量与可用上下文的换算关系。看完这两处直接进长指南。

顺带说清这篇和站内几篇的分工。AI 编程学习路线 讲的是学习顺序怎么排，用 AI 写文档 讲的是拿 AI 产出文档的通用方法，两篇都是方法论层面的。这篇不重复方法论，只做一件事：拆一个真实的开源项目，看这些道理具体落到了哪几个文件、哪几个目录、哪几个参数上。你可以边读边把仓库 clone 下来逐条核对。

四、分层写文档这件事本身值多少

一份文档只能锚定一种读者状态。这是分层的全部理由。

装机那天你要的是”下一步点哪”，任何解释性内容都是噪音；用了两个月你要的是”为什么我的会话两小时就开始胡说”，这时候你需要的是机制而不是步骤；准备无人值守时你要的是”最坏能坏到什么程度”，这时候前两本的乐观语气反而有害。三种状态对信息密度的要求是冲突的，硬塞进一篇，结果是三种读者都读得难受。

第二个好处是可核对性。技巧句子后面挂一个仓库路径，读者随时能验证你有没有吹牛。上面那张表能对出来，就是因为长指南写得足够具体。反过来，如果一份文档通篇讲理念、一个路径都不给，那它的可信度只能靠作者名气撑着。

第三个好处是可以单独派发。安全那本剥离出来之后，可以直接甩给不写代码的人看——负责合规的、负责运维的、拍板要不要在公司机器上装的。它不需要读者先理解 skills 是什么。

这套做法你能直接搬到自己的项目上，成本很低：写三份文档，分别回答”怎么跑起来""怎么用得省""最坏会怎样”；每份只锚定一种读者状态，不做完整性承诺；每个技巧后面挂一个真实路径；三份文档和代码放同一个仓库，一起提交。如果你还没想清楚 skills 和 hooks 各该承担什么，可以先看站内的 Claude Code 技能机制 和 Claude Code 钩子 两篇打底，再回来读这三本会顺很多。

五、边界与代价：这套东西放弃了什么

这是三份单人视角的实践笔记，不是评测报告。 短指南里成段的编辑器偏好、插件清单、MCP 清单，是作者自己机器上的配置快照。你照抄，抄到的是别人的口味和别人的项目结构。它们值得看的是取舍逻辑，不是清单本身。

短指南里相当一部分内容是 harness 自带的能力，不是这个套件提供的东西。 快捷键、worktree、手动压缩这些，你不装 ECC 也有。读的时候要自己分栏记，否则会把 harness 功能记成套件功能，换个工具就懵。

安全指南给的是基线，不是策略。 它在权限 deny 那段自己写了一句：这不是一份完整策略。它不提供威胁建模流程、不提供合规映射、不管你团队的审批流怎么设计。它的定位是让你从”完全没有”挪到”及格”。

文档滞后于代码是常态。 这个仓库迭代很快，指南里出现的示例路径未必和你 clone 到的一致——长指南讲跨会话记忆那节，链到的会话存档示例落在 examples/sessions，我在这次快照的 examples/ 下没找到这个目录；同一节里提到的 hooks/memory-persistence 和 skills/continuous-learning 倒是都在。凡是指南和仓库打架，以仓库为准，别对着文档里的路径怀疑自己 clone 错了。

三本都不管的事：多人团队怎么共享和治理这套配置、成本怎么核算与分摊、非 Claude Code 的 harness 具体怎么适配（这些散在 docs/ 下，比如 docs/MANUAL-ADAPTATION-GUIDE.md），以及模型服务商的额度与计费规则——各家规则不同且会调整，以官方最新说明为准。

最实的一条代价：这类套件会往你的用户目录写文件。 install.sh 的默认安装目标是 ~/.claude/，并且从 git clone 直接跑时，它会先自动执行 npm install 拉依赖，再把活交给 scripts/install-apply.js。这没什么阴谋，但你要清楚自己在做什么：你把一批可执行文本，放进了 agent 每次会话都会加载的位置。安全指南自己就把这类文件归为供应链产物。装之前先想清楚这台机器上有什么、agent 拿到的身份能碰到什么，这个思路可以配合站内的 最小权限设计 一起过一遍。

六、上手与避坑清单

一上来就装最全的那档。 会踩是因为 README 明晃晃摆着 67、281、94 三个数字，人的直觉是”都要”。怎么避：档位不在帮助文本里，帮助文本只说明 --profile <name> 这个参数存在，真正的清单在 manifests/install-profiles.json 里——minimal、opencode、core、developer、security、research、full 七档，每档自带一句说明（比如 minimal 那档明确写了不含钩子运行时，opencode 那档也默认排除钩子运行时、要用就显式加）。先读这个文件挑档，再用 --dry-run 把安装计划打出来看一遍，选一档小的起步，然后用 --with 和 --without 增删单个组件。装多了的直接代价是每次会话都在为你不用的东西付上下文。

没看清安装目标写到哪。 会踩是因为默认目标是 claude，写进 ~/.claude/，而你以为是项目内。怎么避：要项目级就显式指定 --target claude-project，它会写到当前目录的 ./.claude/。装之前用 --dry-run 确认路径，比装完再清干净省事。

把 commands/ 当主入口来扩展。 会踩是因为 slash 命令手感最好，新人第一反应就是照着加。怎么避：短指南把这层定位成迁移期兼容层，耐久逻辑放 skills。你自己写新能力时直接写成技能，命令只当入口壳。

MCP 装一个开一个，装完全忘了关。 会踩是因为试用时一个个接，没人回头收拾。怎么避：短指南的原则是配置里可以留着、不用的一律关掉；长指南给了更狠的替代路径——GitHub、数据库、部署平台这些大多本来就有 CLI，MCP 只是包了一层，把 CLI 包成技能或命令，省下的是常驻上下文。

只读完短指南就开无人值守循环。 会踩是因为短指南读完的感觉是”我会了”，而它确实没打算吓唬你。怎么避：把安全指南那份最低门槛清单当准入条件——agent 身份与你本人账号分离、用短时且限定范围的凭据、不受信任的活儿进容器、默认拒绝出网、敏感路径禁读、越界动作要人批、工具调用与审批留日志、能杀整个进程组并挂心跳看门狗、持久记忆保持窄且可丢弃。这些不做齐，autonomy 只是没有刹车。

把别人的技能当无害文本。 会踩是因为它就是 md 文件，看上去人畜无害。怎么避：安全指南给了低成本的首轮扫描思路——用 ripgrep 搜零宽字符与双向控制字符、HTML 注释、内嵌 base64，再搜一遍 curl、wget、ssh、scp 这类外联命令和会放宽权限的配置键。仓库自带 skills/security-scan/ 和 commands/security-scan.md 这条现成路径。安全指南里那段权限基线可以照抄一份先挡着：

{
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(**/.env*)",
      "Write(~/.ssh/**)",
      "Write(~/.aws/**)",
      "Bash(curl * | bash)",
      "Bash(ssh *)",
      "Bash(scp *)",
      "Bash(nc *)"
    ]
  }
}

拿指南当 API 文档抠参数。 会踩是因为它写得像手册，语气很确定。怎么避：把指南当索引用，具体命名和参数以仓库文件为准。安装脚本的 --help 输出、manifests/ 下的组件与 profile 清单，这些比正文可靠，因为它们跟着代码走。

收束

读完这三本，你手上应该能回答三个问题：这套东西会往我机器的哪些位置写什么；我这台机器上跑它，最坏能坏到什么程度；以及我打算用它的哪几个技能，其余的为什么不装。三个都答得上来再装，答不上来就先用 --dry-run 看计划。

接下来该读哪个文件，看你卡在哪一步：想知道有哪些命令，读 COMMANDS-QUICK-REF.md；不用 Claude Code 而想接到别的 harness，读 docs/MANUAL-ADAPTATION-GUIDE.md；关心这个项目自己怎么处理漏洞报告，读 SECURITY.md。项目采用 MIT 许可证，这些文件全都在仓库里躺着，你不必信我，自己开一眼就知道。

本文属于 ECC 开源 Agent 套件专题（共 40 篇，从选择性安装一直拆到内部机制）。同一批还写了另一种取向的项目——不给你资产、只给你纪律的 superpowers 方法论专题。