HS-ECC：打造开箱即用的生产级 AI Agent 初始部署标准配置库

一、痛点：为什么盲目复制开源配置无法真正落地？

在 Agentic Engineering 迅速发展的 2026 年，各大开源社区涌现了许多优秀的 AI Agent 配置模板。其中最著名的当属顶流开源库 Everything Claude Code (ECC)。

然而，当开发者试图将原版 ECC 直接应用于真实生产项目时，往往会面临严重的落地障碍：

臃肿与冗余：原版 ECC 包含了 67 个单独的 Agent 文件（如针对 TypeScript、Python、Go、Rust 各自独立写一套 Reviewer），极其繁重；
幽灵引用与死链：直接复制的模板中充斥着指向不存在技能和废弃规则的路径；
强硬编码外部工具：硬编码了某些特定第三方付费 MCP 工具（如 Exa / Context7），在标准无依赖环境下频繁报错；
缺少跨会话动态记忆：重新启动 CLI 或执行 /compact 后，中途确定的架构选型与 Gotchas 避坑经验全盘丢失。

“好的 AI 工程师配置不应该是一堆冗长堆叠的 Demo 脚本，而应该是一套简洁克制、防 AI 偷懒、开箱即用的生产级基础设施。”

— 寒松（HS-ECC 架构师）

二、三源合一：HS-ECC 的底层融合设计理念

针对上述痛点，我们推出了 HS-ECC (Everything Claude Code - Hansong Edition)。这是一个经过第一性原理剪枝与重构的企业级 AI Agent 标准配置库，其底层汲取了三大顶流开源源头的精髓：

开源源头	核心借鉴与提取明细	HS-ECC 改进与再重构
Everything Claude Code (ECC)	规则下推（Rule Propagation）与 Agent-First 团队协同模式	将 67 个庞杂 Agent 提炼收敛为 9 大专职角色，统一加前缀 `hs_` 避免冲突
Andrej Karpathy 4 Principles	编码前思考、简洁优先、外科手术式修改、目标驱动验证 4 大铁律	作为物理规则注入 `AGENTS.md`，杜绝 AI 乱改无关代码或过度抽象
Google agent-skills (Addy Osmani)	“防 AI 偷懒反驳条款”与全生命周期 Quality Gate 质量门禁	重构 DoD（完成定义），与原生斜杠命令（`/plan`, `/build`, `/ship`）深度绑定

三、核心能力架构 (Core Capabilities Architecture)

HS-ECC 融合三大开源源头，提炼出 5 大企业级核心能力柱石。其中 “Agent 团队编排与并发协同” 是解决传统 AI 编程“单打独斗、易发盲区、串行低效”的技术核心。

3.1 核心重点：Agent 团队编排与并发协同深度解读

通过配置文件 .claude/rules/common/agents.md，HS-ECC 为系统注入了一套完整的 Agent 多代理协同调度体系：

1. 9 大专职 Agent 角色矩阵

Agent 名称	专职角色	核心职责	权限与工具限制
`hs_architect`	系统架构师	编码前负责模块设计、技术选型与 API 接口契约定义	Read, Grep, Glob, Bash
`hs_planner`	需求规划师	将复杂需求拆解为渐进式落地的 Step-by-step 任务清单	Read, Grep, Glob
`hs_tdd-guide`	TDD 导向专家	严格执行测试先行（RED-GREEN-REFACTOR）方法论，保障 80%+ 覆盖率	Read, Edit, Write, Bash
`hs_code-explorer`	只读探索者	无侵入分析代码库、梳理模块依赖与调用图谱	Read, Grep, Glob
`hs_code-reviewer`	代码审查员	提交前审查代码质量、可读性与潜在逻辑漏洞（置信度>80%方才上报）	Read, Grep, Glob, Bash (只读)
`hs_security-reviewer`	安全审查员	专职检查 SQL 注入、XSS、未校验输入及硬编码凭证	Read, Grep, Glob
`hs_build-error-resolver`	构建修复员	编译报错、Types 缺失与 Lint 错误时专职排查根因	Read, Edit, Bash
`hs_refactor-cleaner`	重构清理员	需求完成后清理调试日志、未使用的 Import 及死代码	Read, Edit, Write
`hs_web-performance-auditor`	性能审计员	专注于 Core Web Vitals、渲染性能与打包体积审计	Read, Grep, Bash

2. 生效机制与触发时机 (Triggering)

隐式/场景自动触发（零提示词学习成本）：
- 当用户提出 复杂功能需求 时 → 自动触发 hs_planner 拆解任务；
- 当代码 刚刚编写/修改完成 时 → 自动触发 hs_code-reviewer 进行质量审查；
- 当进行 Bug 修复或新功能开发 时 → 自动触发 hs_tdd-guide 开启测试先行；
- 当面临 架构或设计决策 时 → 自动触发 hs_architect。
显式斜杠命令触发：开发者亦可在终端中随时输入 /plan, /spec, /test, /review, /security-scan 等命令精细化调度。

3. 并发调度与闭环收尾契约 (Delegation Completion Contract)

独立任务并行并发 (Parallel Task Execution)：对于相互独立的操作（如同时进行安全分析、性能审计与类型检查），系统强制并行启动子 Task 代理并发处理，节省 60%+ 验证时间。
收尾闭环契约 (Delegation Completion Contract)：严格规定“谁委托，谁收尾”。主控 AI 启动子代理后，必须在当前轮次等待并汇总所有子任务结果后统一呈现，严禁回复“正在等待后台任务完成”等悬挂任务（Zombie Tasks）。

架构重构案例：基于第一性原理与“简洁优先 (Simplicity First)”的 Agent 体系瘦身

原版 ECC 包含 67 个独立 Agent 文件（按语言冗余定义了 50+ 个语言 Reviewer）。HS-ECC 基于第一性原理分析：现代大模型自身已具备优异的多语言理解能力。因此果断裁撤 50+ 语言特定 Agent，收敛为 9 个通用专职 Agent，并重构 .claude/rules/common/code-review.md 路由，实现“单 Agent 结合项目上下文自适应多语言”，Token 消耗与配置复杂度降低 80%。

3.2 其他 4 大企业级能力柱石

1. 防御性安全与 Hook 自动化拦截防线 (Defensive Security & Hook Enforcement)

依托 SECURITY.md 与 .claude/hooks/hooks.json 的 PreToolUse 静默拦截链。自动拦截硬编码 Key、生产配置文件与锁文件的误改，配合静态安全审计命令（/security-scan），实现零信任的安全合规保障。

2. 测试驱动开发与完成定义门禁 (TDD & Definition of Done Quality Gates)

严格遵循 .claude/rules/common/testing.md 与 definition-of-done.md。强制执行“测试先行 (RED-GREEN-REFACTOR)”开发循环与 80%+ 测试覆盖率要求；通过 /quality-gate 命令自检，确保未经测试与类型校验的代码绝不合入。

3. 双轨制跨会话记忆与 Token 上下文治理体系 (Two-Tier Memory & Context Governance System)

HS-ECC 首创了“静态全局规则 + 动态项目记忆板 (MEMORY.md) + 策略性上下文压缩”的三位一体记忆治理架构：

静态全局规则 (AGENTS.md)：固化全局编码规范、通信偏好与防偷懒门禁。
动态项目记忆板 (.claude/MEMORY.md)：提供跨会话持久化 Scratchpad，包含 4 大结构化板块（架构决策 ADRs、隐式环境约定、已知避坑 Gotchas、推进中大任务状态）。
记忆治理规范 (memory-management.md)：控制记忆板在 200 行以内，防腐衰防污染。
动态 Token 压缩 (hs_strategic-compact)：配合 hs_context-budget 提供长对话 Token 预警与阶段性清理。

4. 规范驱动与源码存证生命周期 (Spec-Driven & Source-Driven Lifecycle)

提供覆盖软件开发全生命周期的 13 个原生斜杠命令，配合 hs_source-driven 与 hs_interview-me 技能。形成从需求澄清追问（/spec）、任务拆解（/plan）到增量构建（/build）与发布（/ship）的标准闭环，杜绝 API 参数幻觉。

四、目录树视图与文件作用详解

4.1 目录结构概览

HS-ECC/
├── AGENTS.md                           # 全局主规则文件 (通用沟通偏好、Karpathy 原则与防偷懒表)
├── CLAUDE.md                           # Claude Code 主入口文件 (自动载入 AGENTS.md)
├── SECURITY.md                         # 全局安全防线规范
├── README.md                           # 英文主文档
├── README.zh-CN.md                     # 中文主文档
├── .mcp.json                           # MCP 配置文件 (集成 filesystem 与 git 节点)
├── .gitleaksignore                     # GitLeaks 安全忽略配置
├── .codex/                             # OpenAI Codex 专门配置目录
│   └── config.toml                     # Codex 运行参数 (多 Agent 授权与沙箱模式)
└── .claude/                            # Claude Code 专门配置目录
    ├── settings.json                   # 运行设置 (环境变量与环境隔离)
    ├── MEMORY.md                       # 项目动态记忆板 (跨会话架构决策与 Gotchas)
    ├── hooks/
    │   └── hooks.json                  # 防御性 Hook 拦截规则 (Pre/PostToolUse)
    ├── rules/
    │   └── common/                     # 共享模块化规则库 (12 个核心规则规范)
    ├── agents/                         # 精选 Agents 代理库 (9 个专职代理)
    ├── commands/                       # 精选 Commands 命令库 (13 个生命周期命令)
    └── skills/                         # 精选 Skills 技能库 (15 个核心技能)
        

4.2 核心配置文件解析

文件路径	配置文件名	作用与核心逻辑说明
`AGENTS.md`	全局主控制文件	跨工具通用规则库。融入沟通偏好、Karpathy 4 原则、Google 防偷懒反驳表、授权边界与完成标准。
`CLAUDE.md`	Claude 入口文件	包含指令 `@AGENTS.md`，使 Claude Code 自动共享加载 AGENTS.md 规则。
`SECURITY.md`	安全防线指南	声明硬编码 API Key 零容忍、生产环境锁死以及敏感数据防泄露原则。
`.mcp.json`	通用 MCP 声明	声明本地 filesystem 与 git 节点，为 Agent 提供基本的文件读写与版本检索支持。
`.codex/config.toml`	Codex 运行配置	设置 approval_policy = "on-request" 与沙箱写权限，启用多 Agent 模式。
`.claude/settings.json`	Claude 运行配置	设定包管理器环境变量 (pnpm) 并屏蔽膨胀的第三方 MCP 服务。
`.claude/hooks/hooks.json`	防御性 Hook 逻辑	PreToolUse 拦截修改生产配置文件/锁文件；PostToolUse 提示清理残留 console.log。

4.3 核心组件清单速查 (9 Agents / 13 Commands / 15 Skills)

🤖 9 大 Agents 代理

hs_architect (系统架构师)
hs_planner (需求规划师)
hs_tdd-guide (TDD 导向专家)
hs_code-explorer (只读探索者)
hs_code-reviewer (代码审查员)
hs_security-reviewer (安全审查员)
hs_build-error-resolver (构建修复员)
hs_refactor-cleaner (重构清理员)
hs_web-performance-auditor (性能审计员)

⚡ 13 个 Commands 命令

/spec (需求明确规范)
/plan (步骤拆解规划)
/build (增量构建开发)
/test (测试运行验证)
/review (综合质量审查)
/ship (门禁检查与发布)
/quality-gate (综合质量自检)
/code-simplify (简洁重构)
/build-fix (编译报错修复)
/refactor-clean (死代码清理)
/security-scan (静态安全审计)
/checkpoint (状态保存快照)
/code-review (PR/变更审查)

🛠️ 15 个 Skills 技能

hs_interview-me (需求逐项追问)
hs_source-driven (权威文档/源码驱动)
hs_code-simplification (切斯特顿篱笆重构)
hs_doubt-driven (对抗性疑虑自查)
hs_web-performance (性能优化与审计)
hs_search-first (先搜索后编写)
hs_coding-standards (通用编码规范)
hs_api-design (API 设计标准)
hs_tdd-workflow (TDD 工作流)
hs_e2e-testing (E2E 自动化测试)
hs_verification-loop (自动化持续验证)
hs_context-budget (Token 预算管理)
hs_strategic-compact (策略性上下文压缩)
hs_security-review (安全自查清单)
hs_security-scan (静态代码审计)

五、开源项目地址与 GitHub 发布

HS-ECC 配置库现已正式在 GitHub 开源发布！你可以直接 Clone 仓库或将其作为子模块/模板引入到你的任何工程项目中，享受开箱即用的 AI Agent 初始化体验。

图：HS-ECC 开源仓库在 GitHub 上的完整文件树与配置架构

前往 GitHub 浏览与 Star HS-ECC 项目 (https://github.com/SauronHan/HS-ECC)

六、三大 AI 工具的一键部署与初始化指引

⚠️ 全局部署防污染警示：

AGENTS.md、agents/、skills/ 和 rules/ 可以部署为全局共享资源；但 .claude/MEMORY.md 属于项目专属记忆板，切勿复制到全局家目录 (~/.claude/ 或 ~/.codex/)，以防将特定项目的数据库选型或 Gotchas 污染到其他项目中。

6.1 Claude Code 部署说明

对于新项目，只需将 HS-ECC 的配置文件复制到工程根目录：

# 克隆 HS-ECC 仓库
git clone https://github.com/SauronHan/HS-ECC.git

# 为具体新工程初始化配置与专属动态记忆板
cp -r HS-ECC/.claude /path/to/your-project/
cp HS-ECC/AGENTS.md /path/to/your-project/
        

6.2 OpenAI Codex 部署说明

在工程根目录下放置 AGENTS.md 及 .codex/config.toml；全局部署只需复制至 ~/.codex/ 目录。

6.3 Google Antigravity (CLI & IDE) 部署说明

在工作区 .agents/ 目录放置 AGENTS.md，或复制至 ~/.gemini/config/AGENTS.md 并复用 HS-ECC 的 Skill 模组。

6.4 跨平台 Agent 角色激活示范

在非 Claude Code 工具（Codex / Antigravity / Cursor）中，遵循渐进增强原则，只需在对话框中呼叫 Agent 角色即可：

请作为 hs_architect 架构师，帮我分析此模块的依赖并设计 API 接口。
请作为 hs_planner 规划师，把这个需求拆解为 Step-by-step 任务清单。
请作为 hs_code-reviewer 审查员，对本次修改做质量与安全审查。

七、结语

真正的工程效率提升，来自于对规则与工具的精准驯服。HS-ECC 不仅是一个配置文件合集，更是我们在 Agentic Engineering 道路上沉淀出的确定性工作流。它为个体开发者提供了开箱即用、防 AI 偷懒、具备严密安全防线的标准配置体系。欢迎体验、使用与提交 Issue！

核心定位与开箱体验

一、 痛点：为什么盲目复制开源配置无法真正落地？

二、 三源合一：HS-ECC 的底层融合设计理念

三、 核心能力架构 (Core Capabilities Architecture)