코딩 에이전트가 ‘한 세션에 잘 짜는 도구’에서 ‘하루 종일 돌아가는 엔지니어링 런타임’으로 바뀌면서, 병목은 모델이 아니라 하네스(harness) 쪽으로 이동했다. 프롬프트를 매번 다시 쓰고, 리뷰·보안·기억·학습을 세션마다 수작업으로 붙이는 비용이 커진다. affaan-m/ECC(Everything Claude Code)는 그 비용을 OS 레이어처럼 흡수하려는 프로젝트다. 슬로건은 단순하다 — Optimize the context window. Persist everything else.
2026-10-16 기준 GitHub API는 약 28만 스타·4만+ 포크를 보고했고, npm 패키지 ecc-universal@2.2.3(MIT)가 공식 배포 채널이다. 홈페이지는 ecc.tools. 이 글은 초보 튜토리얼이 아니라, 실무자가 설치 전에 봐야 할 아키텍처·카탈로그·멀티하네스 트레이드오프·보안 표면·박스 스모크를 중심으로 해부한다. (아침 Opensource 슬롯의 caveman 토큰 게이트웨이와는 문제 공간이 다르다.)
한 줄 정의와 오늘 체크아웃
| 항목 | 값 |
|---|---|
| 저장소 | https://github.com/affaan-m/ECC |
| 라이선스 | MIT (Copyright 2026 Affaan Mustafa) |
| 릴리스/태그 | v2.2.3 (2026-10-01) · VERSION 파일 일치 |
| 체크아웃 | 76aaa77 · 2026-10-15 15:17 EDT (2026-10-16 04:17 KST) |
| 주 언어 표면 | JS/TS CLI + Markdown skills/agents + Python dashboard 일부 |
| npm 런타임 | ecc-universal@2.2.3 · bin: ecc / ecc-install / ecc-memory-mcp … |
| 보안 패키지 | ecc-agentshield@1.6.0 |
| 카탈로그(README) | 71 agents · 311 skills · 97 commands · rules/hooks/memory |
공식 경고가 먼저다. 설치는 GitHub·npm(ecc-universal/ecc-agentshield)·GitHub App·플러그인 슬러그 ecc@ecc·ecc.tools만 신뢰한다. 미러/재업로드는 멀웨어 위험으로 명시됐다. OSS는 MIT로 남고, 프라이빗 레포용 호스티드 레이어는 ECC Pro(GitHub App)로 분리된다.
무엇을 해결하려는가
ECC가 가정하는 루프는 다음이다.
plan -> test -> implement -> review -> verify -> remember -> improve
모델에게 ‘잘 짜라’고만 하는 대신, 계획·TDD·구현·교차 리뷰·검증·기억·학습을 하네스 기본값으로 올린다. 컨텍스트 창에는 지금 필요한 것만 남기고, 나머지는 Memory Vault·instinct·skill로 영속화한다.
| 통증 | ECC의 대응 |
|---|---|
| 매번 프롬프트에 넣던 워크플로 | skills / agents / commands(shim)로 설치 한 번 |
| 세션 끝나며 사라지는 교훈 | instinct(confidence) → evolve → skill/agent |
| 하네스마다 다른 설정 파일 | 어댑터 + Memory Vault handoff |
| 에이전트 설정 보안 사각 | AgentShield 스캔 · GateGuard first-touch |
| 컨텍스트 폭주 | SessionStart 캡·instinct 주입 상한·selective profile |
아키텍처: 카탈로그가 아니라 하네스 OS
docs/ECC-2.0-REFERENCE-ARCHITECTURE.md는 ECC 2.0을 ‘커맨드/스킬 모음’이 아니라 harness operating system으로 정의한다. 레이어는 대략 다음과 같다.
- Operator Surface — CLI(
ecc), 플러그인, control-pane, 릴리스/PR 게이트 - Harness Adapter Layer — Claude Code / Codex / OpenCode / Cursor / Gemini / Zed / …
- Worktree·Session·Queue Runtime — 세션, 할 일, 머지/충돌 큐, handoff
- Observability·Eval Loop — JSONL 트레이스, harness audit, verifier/playbook
- Security·Platform — AgentShield(SARIF), ECC Tools 체크, 엔터프라이즈 리포트
실무적으로 중요한 함의: Claude Code에서 완전한 훅·스킬 디스커버리를 기대하고, 다른 하네스에서는 기능 패리티를 가정하지 말라는 것이다. README의 Platform Support가 ‘stable / beta / experimental / instruction-only’를 마케팅 티어가 아니라 능력 서술로 쓰라고 못 박는다.
레포 레이아웃(실무용 지도)
| 경로 | 역할 |
|---|---|
| skills/ | 311개 스킬 디렉터리 — 각 SKILL.md가 정본 워크플로 |
| agents/ | 71개 서브에이전트 정의(planner, code-reviewer, harness-optimizer…) |
| commands/ | 97개 slash 엔트리 — skills-first 이행기의 호환 표면 |
| hooks/ | hooks.json + 하네스별 어댑터(codex/qoder/hermes…) |
| rules/ | 언어/프로젝트 always-on 표준(선택 설치) |
| manifests/ | install profiles·modules·pi-core 큐레이션 목록 |
| scripts/ | ecc.js CLI, install-apply, memory-mcp, GateGuard, audits |
| plugins/ · .claude-plugin/ | Claude/Codex/Qoder 등 네이티브 플러그인 패키징 |
| docs/ | 아키텍처·하네스 가이드·로드맵·보안 |
| pi/core/ | 훅/네트워크 없는 포터블 큐레이션 프로필(123 skills 등) |
| the-*-guide.md | shortform/longform/security — 운영 철학 문서 |
카탈로그 숫자는 체크아웃에 따라 변할 수 있다. README도 “고정 합계를 가정하지 말고 현재 inventory를 세라”고 적는다. 이번 박스 shallow clone 기준은 agents 71 / skills 311 / commands 97 / rules 23 / hooks.json 이벤트 엔트리 27(PreToolUse 10, Stop 8 등)이었다.
핵심 추상: Skills · Agents · Hooks · Rules
Skills가 정본, Commands는 shim
shortform 가이드의 말하듯, slash 커맨드는 편의 입구이고 내구성 있는 단위는 skill이다. 스킬은 프롬프트·구조·보조 파일·codemap을 묶은 워크플로 번들이다. Claude Code에 수동 설치할 때 ~/.claude/skills/의 직접 자식만 로드되므로, ~/.claude/skills/ecc/처럼 한 단계 더 중첩하면 안 보인다 — README가 강조하는 함정이다.
| 계열(예시) | 스킬 디렉터리 예 |
|---|---|
| TDD / 품질 | tdd-workflow, test-coverage, ai-regression-testing, eval-harness |
| 보안 | security-scan, agent-security-hardening, safety-guard, gateguard |
| 프론트/프레임워크 | frontend-patterns, nextjs-turbopack, fastapi-patterns, rails-patterns |
| 운영/하네스 | harness-optimizer, github-ops, token-budget-advisor, knowledge-ops |
| 학습 | continuous-learning-v2 (instinct → evolve) |
| 리서치 | deep-research, search-first, exa-search |
Agents: 역할이 분리된 서브프로세스
오케스트레이터(메인 세션)가 컨텍스트를 지키려면, 계획·리뷰·빌드 수리·보안을 도구 권한이 제한된 서브에이전트에 위임해야 한다. AgentShield 스모크에서도 여러 agent 파일이 Write/Edit/Bash 없는 allow list를 ‘Recognized Defense’로 집계했다 — 읽기 전용 리뷰어 패턴이 카탈로그에 실제로 박혀 있다는 신호다.
| 역할군 | 에이전트 예 |
|---|---|
| 계획/설계 | planner, architect, code-architect, a11y-architect |
| 품질/리뷰 | code-reviewer, commit-reviewer, database-reviewer, *-reviewer |
| 수리 | build-error-resolver, *-build-resolver, refactor 계열 |
| 평가/루프 | agent-evaluator, gan-evaluator, loop-operator, harness-optimizer |
| 도메인 | healthcare-reviewer, homelab-architect, marketing-agent … |
Hooks: 라이프사이클에 강제력
훅은 스킬과 달리 도구 호출/세션 이벤트에 묶인다. Claude 쪽 기본 이벤트 예: PreToolUse, UserPromptSubmit, PreCompact, SessionStart, PostToolUse, PostToolUseFailure, Stop, SessionEnd. 대표 운영 장치:
- GateGuard — 민감/신규 경로 first-touch 시 질문·거부. CHANGELOG(Unreleased)에 비용(약 +45% 턴)·효과 측정 하네스까지 문서화.
- continuous-learning-v2 — Pre/PostToolUse 관찰 → instinct 생성.
- SessionStart 컨텍스트 주입 — instinct/요약 주입량 캡(
ECC_SESSION_START_MAX_CHARS,ECC_MAX_INJECTED_INSTINCTS).
| 환경변수 | 효과 |
|---|---|
| ECC_HOOK_PROFILE | standard(기본) 등 엄격도 프로필 |
| ECC_DISABLED_HOOKS | 특정 hook ID 콤마 비활성 |
| ECC_SESSION_START_MAX_CHARS | SessionStart 추가 컨텍스트 상한(기본 8000) |
| ECC_SESSION_START_CONTEXT | off면 SessionStart 추가 컨텍스트 전체 끔(로컬/소형 모델용) |
| ECC_MAX_INJECTED_INSTINCTS | 주입 instinct 개수 상한(기본 6) |
| ECC_INSTINCT_CONFIDENCE_THRESHOLD | 주입 최소 confidence(기본 0.7) |
| ECC_INSTINCT_RELEVANCE_RANKING | 프로젝트/스택 관련성 가산 랭킹(기본 on) |
Instincts와 Memory Vault
Instinct = 원자 단위 학습
skills/continuous-learning-v2(metadata v2.1.0)는 세션 관찰을 곧바로 거대 스킬로 만들지 않고, confidence가 달린 작은 YAML instinct로 쪼갠다. v2.1은 프로젝트 스코프(${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/)를 기본으로 넣어 크로스 프로젝트 오염을 줄이고, 2개 이상 프로젝트에서 보이면 global로 promote한다.
| 차원 | v1 | v2/v2.1 |
|---|---|---|
| 관찰 | v1: Stop 훅 | v2: Pre/PostToolUse(+Stop) |
| 분석 | 메인 컨텍스트 | 백그라운드(Haiku 등) |
| 단위 | 풀 스킬 | atomic instinct |
| 신뢰도 | 없음 | 0.3–0.9 weighted |
| 진화 | 바로 스킬 | cluster → skill/command/agent |
| 공유 | 없음 | export/import · promote |
| 스코프(v2.1) | 전역만 | project + global |
Memory Vault: 하네스 간 검사 가능한 Markdown
통합 메모리는 벤더 트랜스크립트를 복사하지 않고 ecc.memory.v1 Markdown으로 남긴다. 프로젝트/팀: .ecc/memory/, 유저: ~/.ecc/memory/. CLI:
npx ecc-universal@2.2.3 memory init --scope project ecc memory handoff --from claude --target codex --title "…" --stdin ecc memory search "authentication migration" --target-harness codex ecc memory doctor
도구가 만든 메모리는 항상 unreviewed context이며 실행 정책이 아니다. 쓰기는 create-only이고 알려진 credential shape는 거부한다. 프로젝트 메모리는 fail-closed .gitignore로 보호하고, team 스코프는 사람이 검수한 뒤에만 VCS로 공유하라는 모델이다. 플러그인-only/minimal 설치는 Memory Vault 런타임을 PATH에 안 넣을 수 있어, CLI·옵션 MCP(ecc-memory-mcp)는 npm 런타임을 따로 깔아야 한다.
설치 경로와 프로필 — 하나를 고르라
권장 엔트리는 유니버설 가이드 셋업이다(Node ≥18, Claude 플러그인 경로에는 Git + Claude Code ≥2.1).
npx ecc-universal@2.2.3 setup # 멀티 하네스 위저드 npx ecc-universal@2.2.3 install --guided --harness claude --harness codex --harness kimi npx ecc-universal@2.2.3 install --guided --harness codex --dry-run
같은 하네스에 설치 방법을 겹치지 말 것. 스킬/훅/설정이 이중으로 붙는다. 여러 하네스에 각각 한 번씩 까는 것은 허용된다.
| profile | modules | 의도 |
|---|---|---|
| minimal | 5 | 훅 런타임 없음 — 저컨텍스트 Claude |
| opencode | 3 | 기본 OpenCode(hooks-runtime 제외, 옵션) |
| core | 6 | 커맨드+훅+플랫폼 최소 베이스 |
| developer | 9 | 일반 앱 코드베이스 기본 |
| security | 7 | 보안 가중 가이드+베이스 런타임 |
| research | 9 | 조사·합성·퍼블리싱 |
| full | 27 | 현재 분류된 모듈 전부 |
| 하네스 | 상태 | 실무 메모 |
|---|---|---|
| Claude Code | Stable primary | 플러그인/선택 설치 — 카탈로그가 모델에 광고되므로 컨텍스트 민감하면 selective |
| Codex | Supported native | 마켓플레이스/리포 설정 — 훅 trust 별도, Claude hook profile 비공유 |
| Qoder | Supported native | 스킬·에이전트·MCP 로드, SessionStart 훅만 리뷰드 |
| Cursor | Beta adapter | .cursor/ 선택 설치 — 풀 패리티 비주장 |
| OpenCode | Beta plugin | 카탈로그 서브셋 + 프로바이더/모델 선택 필요 |
| Copilot Chat | Instruction-only | 지시문/프롬프트 파일 — 훅 없음 |
| Copilot CLI | Beta | skills/agents → .github/ — hooks/rules/commands 미설치 |
| Gemini/Zed/Kimi/… | Experimental | 파일 배치·지시 이식 위주 |
| OS | 상태 | 제한 |
|---|---|---|
| Linux | Supported core | 옵션 기능에 Bash/Python/프로바이더 도구 필요할 수 있음 |
| macOS | Supported core | 단독 GAN 셸은 시스템 Bash 3.2와 비호환·스코어 파싱 이슈(#2674) |
| Windows+WSL | Supported core | WSL=리눅스 경로, 호스트 통합은 하네스별 |
| Windows native | Limitations | continuous-learning observer·memory-vault 쓰기 결함 오픈(#2489,#2626) |
보안 표면: AgentShield · GateGuard · 공급망
에이전트 설정은 곧 공격면이다. ECC는 (1) 설정 감사기 AgentShield, (2) 런타임 first-touch GateGuard, (3) security-ioc-scan 같은 공급망 IOC 스캔, (4) 공식 채널만 쓰라는 배포 정책을 같이 둔다. security guide는 Claude Code 쪽 CVE-2025-59536(트러스트 다이얼로그 전 실행)·CVE-2026-21852(ANTHROPIC_BASE_URL 하이재킹)를 인용하며 ‘클론만 해도’ 생기는 클래스를 강조한다.
| agentshield 명령 | 용도 |
|---|---|
| scan | Claude/에이전트 설정 디렉터리 취약·오구성·인젝션 위험 |
| init | 보안 베이스라인 설정 생성 |
| baseline / watch | 드리프트 기준선·연속 감시 |
| runtime | PreToolUse 정책 강제 훅 |
| policy | 조직 단위 정책 |
| miniclaw | 최소 샌드박스 에이전트 런타임 |
| evidence-pack | 증거 번들 검증 |
박스 스모크 주의: 우리는 사용자 홈의 Claude 설정이 아니라 ECC 깃 체크아웃 전체에 agentshield scan을 돌렸다. 결과 요약은 Findings 2518(critical 237 등). 다만 상위 critical 다수가 package-lock.json integrity 해시를 Azure storage key 정규식에 걸린 오탐 패턴이었고, 동시에 read-only agent allow list 등 Recognized Defenses 46건을 크레딧했다. 즉 “ECC가 위험하다”는 결론이 아니라, 스캐너를 락파일/벤더 트리에 그대로 들이대면 노이즈가 폭발한다는 운영 교훈에 가깝다. 실사용은 ~/.claude 또는 프로젝트 에이전트 설정 경로에 맞추고, 락파일은 제외/튜닝이 필요하다.
유사 도구와 비교
같은 ‘에이전트 보강’ 선반에 올려도 문제 정의가 갈린다.
| 프로젝트 | 초점 | 강점 | 라이선스 | 한계/차이 |
|---|---|---|---|---|
| ECC | 하네스 OS(스킬·훅·기억·학습·보안) | Claude 중심 멀티하네스 | MIT | 카탈로그+런타임 무거움 |
| caveman | 토큰/프록시 압축 게이트웨이 | proxy·engine·CCR | Apache-2.0 | 워크플로 OS 아님(오늘 아침 포스트) |
| vercel-labs/skills | 스킬 배포/심링크 CLI | 다수 런타임 장착 | — | 학습·훅 OS 레이어 약함 |
| ruflo | 멀티에이전트 스웜 하네스 | 페더레이션·RAG | MIT | ECC와 겹치나 스웜 중심 |
| claude-plugins-official | 공식 플러그인 디렉터리 | Anthropic 관리 | Apache-2.0 | 단일 생태계 카탈로그 |
| K-Dense scientific-agent-skills | 과학 도메인 SKILL.md 177 | 과학 에이전트 | MIT | 도메인 특화(어제 오후) |
| iFixAi | 에이전트 감사/정책 eval | 검사 하네스 | — | 빌드 OS라기보다 audit |
| 목표가 | 우선 후보 |
|---|---|
| 팀 표준 워크플로를 하네스에 고정 | ECC developer/security profile |
| 출력 토큰·툴 로그 폭주만 문제 | caveman / 전용 compressor |
| 스킬 파일만 여러 IDE에 배포 | skills CLI |
| 장시간 자율 스웜·페더레이션 | ruflo 등 스웜 하네스 |
| 과학 분석 절차 지식 | scientific-agent-skills |
박스에서 돌린 것 / 안 돌린 것
| 명령 | 결과 |
|---|---|
| node/npm | v20.19.2 / 9.2.0 |
| npm view ecc-universal | 2.2.3 · MIT |
| npm view ecc-agentshield | 1.6.0 |
| npx ecc-universal@2.2.3 –help | OK — setup/install/memory/catalog/doctor/… |
| ecc catalog profiles | minimal…full 7개 확인 |
| ecc memory –help | OK |
| ecc doctor | install-state 없음(스모크만, 예상) |
| agentshield scan (repo root) | 실행됨 · 락파일 FP 노이즈 다수 |
| ecc setup → ~/.claude | 의도적으로 미실행(사용자 하네스 변형 금지) |
운영 트레이드오프와 주의점
| 리스크 | 완화 |
|---|---|
| 컨텍스트 풋프린트 | 풀 카탈로그는 모델에 ‘광고’됨 → selective/manual·low-hooks |
| 패리티 착각 | Cursor/Gemini 등에서 Claude급 훅을 기대한면 깨짐 |
| 이중 설치 | 같은 하네스에 plugin+manual 스택 → 중복 스킬/훅 |
| Windows native | instinct observer·vault 쓰기 이슈 — WSL 권장 구간 |
| Memory trust | team memory도 커밋 전 사람 검수 — 실행 정책 취급 금지 |
| 보안 스캔 해석 | 락파일/벤더 트리 스캔은 FP 폭발 — 설정 경로에 조준 |
| 공급망 | 비공식 미러 금지 · 버전 핀(@2.2.3) 권장 |
| GateGuard 비용 | 파일 first-touch 질문으로 턴 수 증가 가능(파일럿 ~+45%) |
누구에게 맞나
- 맞다: Claude Code(또는 Codex)를 주력으로 쓰고, TDD·리뷰·보안·세션 학습을 팀 기본값으로 고정하고 싶은 엔지니어링 조직.
- 조건부: Cursor/OpenCode 중심 팀 — 어댑터로 스킬·지시 이식은 가능하나 훅 패리티를 전제하지 말 것.
- 비권장(단독): ‘토큰만 줄이면 된다’는 문제, 또는 GPU 추론 엔진이 필요한 문제(그건 TokenSpeed·vLLM 쪽).
설치 한 줄로 끝내고 싶다면 공식 경로만 기억하면 된다.
npx ecc-universal@2.2.3 setup # 이후 새 Claude Code 세션에서 /plugin list 로 ecc@ecc 확인
ECC는 모델을 바꾸지 않는다. 모델이 일하는 운영체제를 바꾼다. 그 차이가 28만 스타급 관심을 만든 이유이자, 풀 설치 전에 selective profile과 보안 스캔 범위를 먼저 설계해야 하는 이유이기도 하다.