"하네스 엔지니어링" - Everything Claude Code 리뷰 : 혼자서 팀처럼 개발하는 에이전트 셋업(ECC 하네스 셋업으로 생산성 2배 끌어올리기)
-
728x90
안녕하세요! 갓대희 입니다.
오늘은 GitHub에서 133,000+ Star(2026년 4월 3일 GitHub 기준)를 기록하며 폭발적인 관심을 받고 있는 Everything Claude Code (ECC) 프로젝트에 대해 알아보려고 한다.
ECC는 Claude Code, Cursor, Codex 등 AI 코딩 에이전트를 사용하는 개발자라면 알아두면 유용한 성능 최적화 시스템이다.
목차
Everything Claude Code 소개
프로젝트 개요
Anthropic 해커톤 우승 배경
왜 주목해야 하는가
프로젝트 전체 구조
디렉토리 구성
핵심 구성요소 한눈에 보기
3대 가이드 — Shortform / Longform / Security
Shortform Guide — 기본기 다지기
Longform Guide — 고급 패턴
Security Guide — 에이전트 보안
핵심 구성요소 상세
Agents (36개 전문 에이전트)
Skills (151개 워크플로우 스킬)
Commands (68개 레거시 슬래시 엔트리)
Hooks (자동화 훅 시스템)
Rules (12개 언어/생태계 규칙)
크로스 플랫폼 지원
Claude Code, Codex, Cursor, OpenCode 중심의 크로스 하네스 지원
AgentShield — 보안 스캐너
주요 기능
사용법
토큰 최적화 & Continuous Learning
모델 라우팅 전략
Instinct 시스템
컨텍스트 관리
설치 및 시작 가이드
설치 방법 4가지
프로파일 선택
실전 활용 팁
병렬 작업 패턴
Two-Instance Kickoff
주의사항
커뮤니티 반응과 주의사항
긍정적 반응
비판과 우려
결론
Everything Claude Code (ECC) 가이드 ECC는 단순한 설정 파일 모음이 아니다. 36개 전문 에이전트, 151개 워크플로우 스킬, 68개 레거시 슬래시 엔트리, 자동화 훅 시스템, 보안 스캐너까지 포함한 에이전트 하네스 성능 최적화 시스템이다. Claude Code, Codex, Cursor, OpenCode를 중심으로 Antigravity와 Gemini CLI(실험적)까지 문서화된 크로스 하네스 생태계를 갖추고 있다.
1. Everything Claude Code 소개
프로젝트 개요
Everything Claude Code (ECC)는 Affaan Mustafa가 만든 오픈소스 프로젝트로,
AI 코딩 에이전트의 성능을 체계적으로 끌어올리는 통합 시스템이다.
"에이전트 하네스(Agent Harness)"란?
테스트 하네스가 테스트 환경을 제어하듯, 에이전트 하네스는 AI 에이전트의 입력(프롬프트, 규칙), 출력(훅, 검증), 도구 접근(권한)을 체계적으로 관리하는 외부 프레임워크를 말한다. ECC는 스스로를 "에이전트 하네스 성능 최적화 시스템"이라고 정의한다.
제작자의 경고: "200K 컨텍스트 윈도우가 MCP 도구가 너무 많으면 실제로는 70K밖에 안 될 수 있다." 권장: 20~30개 설정하되, 동시 활성화는 10개 미만, 활성 도구는 80개 미만으로 유지한다.
제작자의 실제 셋업도 공개되어 있다. 14개 MCP 서버를 설정하되 프로젝트당 5~6개만 활성화하고, 커스텀 훅으로 포맷팅, 타입체크, console.log 경고 등을 자동화한다.
Longform Guide — 고급 패턴
Shortform을 읽은 뒤 진행하는 심화 가이드다. 핵심 내용:
MCP를 CLI로 대체하기
GitHub, Supabase, Vercel 등 많은 MCP는 기존 CLI를 래핑한 것에 불과하다. MCP 대신 CLI를 직접 사용하는 스킬/커맨드를 만들면 토큰 비용을 절감할 수 있다.
동적 시스템 프롬프트 주입
CLAUDE.md에 모든 것을 넣는 대신, --system-prompt 플래그로 상황에 맞는 컨텍스트를 동적으로 주입한다:
# 개발 모드
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'
# 코드 리뷰 모드
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'
# 리서치 모드
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'
서브에이전트 모델 라우팅
작업 유형에 따라 적절한 모델을 선택하여 비용을 최적화한다:
ex) 작업의 복잡도에 따라
ex) 비용과 성능에 따라
작업 유형
권장 모델
이유
탐색/검색
Haiku
빠르고 저렴하며, 파일 탐색에 충분
일반 코딩 (90%)
Sonnet
비용 대비 성능 최적
아키텍처/보안
Opus
깊은 추론 필요, 취약점 놓칠 수 없음
문서 작성
Haiku
구조가 단순한 작업
복잡한 디버깅
Opus
전체 시스템 맥락이 필요
mgrep — 토큰 절감 도구
ECC 공식 Longform Guide의 자체 벤치마크에 따르면, mgrep 플러그인은 기존 grep/ripgrep 대비 약 50% 수준의 토큰 절감을 목표로 설계됐다. 다만 이 수치는 ECC 측이 공개한 50개 작업 벤치마크 기반이므로, 독립적인 외부 검증 수치로 보기는 어렵다.
Security Guide — 에이전트 보안
AI 에이전트 보안에 대한 종합 가이드다. 실제 CVE와 공격 벡터를 다룬다.
주요 보안 이슈 (2025-2026)
CVE-2025-59536 (CVSS 8.7): Claude Code의 startup trust dialog 구현 버그로 인해 사용자가 신뢰를 승인하기 전에 프로젝트 내 코드가 실행될 수 있었던 취약점. v1.0.111에서 수정.
CVE-2026-21852: 악성 저장소가 프로젝트 로드 단계에서 ANTHROPIC_BASE_URL 등을 악용해 신뢰 확인 전에 API 요청을 보내고 키를 유출할 수 있었던 취약점. v2.0.65에서 수정.
Snyk ToxicSkills 보고서: 공개된 3,984개 스킬 중 36%에서 프롬프트 인젝션이 발견되었고, 1,467개의 악성 페이로드가 식별됨.
Security Guide가 제시하는 최소 보안 기준 체크리스트:
에이전트 ID를 개인 계정과 분리한다
단기 스코프 자격 증명을 사용한다
비신뢰 작업은 컨테이너/VM에서 격리하여 실행한다
아웃바운드 네트워크를 기본 차단한다
비밀 정보가 담긴 경로에 대한 읽기를 제한한다
파일/HTML/스크린샷은 권한 있는 에이전트에 전달하기 전에 정제(sanitize)한다
도구 호출, 승인, 네트워크 시도를 로깅한다
프로세스 그룹 킬(kill)과 하트비트 기반 데드맨 스위치를 구현한다
제작자의 보안 철학
"악의적인 텍스트가 컨텍스트에 들어올 것을 전제하고 만들어라. 도구 설명이 거짓말할 수 있다고 전제하고 만들어라. 저장소가 오염될 수 있다고 전제하고 만들어라. 그리고 모델이 악의적 입력에 설득당하더라도 시스템이 안전하게 동작하도록 만들어라."
4. 핵심 구성요소 상세
Agents — 36개 전문 에이전트
각 에이전트는 YAML 프론트매터가 포함된 Markdown 파일로 정의된다. name, description, tools(접근 가능한 도구), model(사용 모델)을 지정한다.
# agents/planner.md 예시
---
name: planner
description: Expert planning specialist for complex features
tools: ["Read", "Grep", "Glob"]
model: opus
---
구현 계획을 단계별로 수립합니다. 독립적으로 전달 가능한
단계로 나누고, 위험 요소를 식별합니다...
참고: model 프론트매터 우선순위
현재 Claude Code 공식 문서는 서브에이전트 frontmatter의 model 필드를 지원한다. 다만 실제 실행 모델은 CLAUDE_CODE_SUBAGENT_MODEL 환경 변수 → 호출 시 전달한 model → 에이전트 frontmatter의 model → 메인 대화 모델 순서로 결정된다. 즉, frontmatter만 믿기보다 상위 override가 있는지 함께 봐야 한다.
언어/생태계별: TypeScript, Python, Go, Swift, PHP, Java, Kotlin, C++, Rust, Perl 등 폭넓은 규칙 세트를 제공한다.
5. 크로스 플랫폼 지원
ECC의 특징 중 하나는 여러 AI 코딩 하네스를 가로지르는 설정/워크플로우를 제공한다는 점이다.
플랫폼
설정 디렉토리
비고
Claude Code
.claude/
주요 타깃. 플러그인 시스템 지원
Codex (OpenAI)
.codex/
AGENTS.md, agents/, config.toml
Cursor IDE
.cursor/
hooks, rules, skills
OpenCode
.opencode/
12 에이전트, 24 커맨드, 16 스킬, 3 네이티브 도구
Gemini CLI
.gemini/
실험적 project-local 지원
Antigravity
-
--target antigravity 플래그
6. AgentShield — 보안 스캐너
AgentShield는 Cerebral Valley x Anthropic 해커톤에서 탄생한 독립 npm 패키지(ecc-agentshield)다. AI 에이전트 설정의 보안 취약점을 스캔한다.
주요 기능
5개 스캔 카테고리: 시크릿 탐지(14개 패턴), 권한 감사, 훅 인젝션 분석, MCP 서버 위험 프로파일링, 에이전트 설정 검토
102개 정적 분석 규칙과 1,282개 테스트 (98% 커버리지)
--opus 플래그: 3개의 Claude Opus 에이전트가 레드팀/블루팀/감사자 파이프라인으로 심층 분석
CI 통합: 치명적 발견 시 종료 코드 2를 반환하여 빌드 게이트로 사용 가능
사용법
# 기본 스캔
npx ecc-agentshield scan
# 자동 수정 포함 스캔
npx ecc-agentshield scan --fix
# Opus 에이전트 심층 분석
npx ecc-agentshield scan --opus
# 프로젝트 초기화
npx ecc-agentshield init
출력 형식은 터미널(A~F 등급), JSON(CI용), Markdown, HTML을 지원한다.
7. 토큰 최적화 & Continuous Learning
Instinct 시스템 (Continuous Learning v2)
ECC의 자가 학습 시스템은 Instinct 개념을 중심으로 작동한다:
PreToolUse/PostToolUse 훅(observe.sh)이 도구 사용 패턴을 캡처한다
캡처된 패턴은 신뢰도 점수(0.3~0.9)와 도메인 태그(code-style, testing, git 등)를 가진 "Instinct"로 저장된다
프로젝트별로 스코핑되어(git remote URL 해시 기반) 프로젝트 간 오염을 방지한다
/evolve 명령어로 축적된 Instinct들을 클러스터링하여 새로운 스킬/커맨드/에이전트로 진화시킨다
관련 명령어
/instinct-status — 현재 학습된 Instinct 조회
/evolve — Instinct를 스킬로 진화
/instinct-export / /instinct-import — 팀 간 공유
/promote — 프로젝트 스코프에서 글로벌로 승격
/prune — 만료된 Instinct 정리
컨텍스트 관리 전략
ECC가 제안하는 컨텍스트 최적화 방법:
세션 파일 패턴: 진행 상황을 .claude/ 폴더의 임시 파일에 저장하고 다음 세션에서 로딩
전략적 컴팩션: 자동 컴팩션을 비활성화하고, 논리적 구간에서 수동으로 /compact 실행
메모리 퍼시스턴스 훅: PreCompact(상태 저장), Stop(학습 지속), SessionStart(컨텍스트 로딩)로 세션 간 연속성 보장
MCP를 CLI로 대체: 토큰 비용 절감을 위해 MCP 대신 CLI 래퍼 사용
8. 설치 및 시작 가이드
전제 조건
ECC는 Claude Code 위에 얹는 확장 생태계다. Claude Code가 먼저 설치되어 있어야 하며, 현재 공식 문서는 macOS/Linux/WSL에서 curl -fsSL https://claude.ai/install.sh | bash, Windows PowerShell에서 irm https://claude.ai/install.ps1 | iex, 또는 Homebrew/WinGet 설치를 안내한다. 계정은 보통 Claude 구독 또는 Anthropic Console 계정이 필요하며, Terminal CLI와 VS Code는 third-party provider도 지원한다. 개인 요금제는 현재 Pro 월 $20(연간 결제 시 월 환산 $17), Max 월 $100부터다. ECC 자체는 무료(MIT 라이선스)다.
ECC는 4가지 설치 방법을 제공한다. 제작자가 가장 권장하는 방법은 플러그인 설치다.
방법 1: 플러그인 (권장)
# Claude Code 마켓플레이스에서 추가
/plugin marketplace add affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code
주의
플러그인 시스템의 제한으로, Rules는 수동 설치가 필요하다. rules/ 디렉토리를 ~/.claude/rules/에 직접 복사해야 한다.
방법 2: npm
# 언어 지정 설치 (두 가지 형식 모두 가능)
npx ecc typescript
npx ecc-install typescript
npx ecc python golang swift php
방법 3: 셸 스크립트
# 저장소 클론 후 설치
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
./install.sh typescript python golang
# Cursor 대상 설치
./install.sh --target cursor typescript
방법 4: 수동 설치
저장소를 클론한 뒤 필요한 디렉토리(agents/, commands/, skills/, rules/)를 ~/.claude/에 직접 복사한다.
프로파일 선택
설치 시 5개 프로파일 중 선택할 수 있다:
프로파일
포함 내용
Core
규칙, 에이전트, 명령어, 훅, 플랫폼 설정, 품질 워크플로우
Developer
Core + 프레임워크 언어, 데이터베이스, 오케스트레이션
Security
Core + 전용 보안 모듈
Research
Core + 리서치 API, 비즈니스 콘텐츠, 소셜 배포
Full
전체 19개 모듈 포함
설치 팁
처음부터 모든 기능을 설치하기보다, 주로 사용하는 언어의 에이전트와 스킬만 먼저 선택적으로 설치하는 것을 권장한다. Shortform Guide를 가장 먼저 읽으면 전체 구조를 잡는 데 도움이 된다.
9. 실전 활용 팁
병렬 작업 패턴
ECC가 제시하는 병렬 작업의 핵심 원칙:
/fork: 코드 변경이 겹치지 않는 독립 작업에 사용. 메인 채팅은 코드 변경용, fork는 질문/리서치용으로 분리한다.
Git Worktrees: 코드 변경이 겹칠 수 있는 경우 필수. 워크트리별로 Claude 인스턴스를 배정한다.
Cascade Method: 새 작업을 오른쪽 탭에 열고, 왼쪽에서 오른쪽으로 스위핑한다. 동시 3~4개 작업이 적정 수준이다.
# Git Worktree로 병렬 Claude 인스턴스 실행
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
cd ../project-feature-a && claude
과도한 병렬화 경고
제작자는 "5개 이상의 인스턴스를 무작정 띄우지 말라"고 경고한다. "최소한의 병렬화로 얼마나 많은 작업을 처리할 수 있는가"가 올바른 목표다.
Two-Instance Kickoff 패턴
새 프로젝트를 시작할 때 2개의 Claude 인스턴스를 동시에 활용하는 패턴이다:
인스턴스 1 — 스캐폴딩 에이전트: 프로젝트 구조 생성, 설정 파일(CLAUDE.md, rules, agents) 셋업
인스턴스 2 — 딥 리서치 에이전트: 외부 서비스 연결, 웹 검색, 상세 PRD 작성, 아키텍처 다이어그램 생성
주의사항
과도한 설정 금지: "설정을 아키텍처가 아닌 미세 조정처럼 다뤄라." 복잡하게 만들면 오히려 역효과가 난다.
컨텍스트 윈도우 관리: 사용하지 않는 MCP와 플러그인은 반드시 비활성화한다.
서브에이전트 스코핑: 제한된 도구 = 집중된 실행. 서브에이전트에 모든 도구를 주지 않는다.
보안 인식: 외부 정보를 받아들이는 에이전트에는 반드시 격리/정제 단계를 거친다.
서브에이전트 컨텍스트 문제 해결
서브에이전트는 메인 에이전트의 의미적 맥락을 모른다. 해결책은 반복 검색 패턴이다: 1) 오케스트레이터가 서브에이전트의 반환값을 평가 → 2) 후속 질문 → 3) 서브에이전트가 추가 조사 후 반환 → 4) 충분해질 때까지 반복 (최대 3회). 핵심: 쿼리뿐 아니라 목적(objective context)을 함께 전달한다.
10. 커뮤니티 반응과 주의사항
ECC는 2026년 상반기 가장 빠르게 주목받은 AI coding harness 저장소 중 하나가 되었다. 하지만 커뮤니티에서는 긍정적 반응과 함께 의미 있는 비판도 제기되고 있다.
긍정적 반응
통합 시스템의 가치: awesome-claude-code 목록에서 "significant standalone value(독립적으로 의미 있는 가치)"가 있다고 평가
솔로 개발자의 팀 효과: 한국 커뮤니티에서는 "역할 기반 에이전트가 혼자서도 팀처럼 일할 수 있게 한다"는 점이 높은 호응
보안 의식: AgentShield와 Security Guide의 CVE 기반 실전 보안 가이드는 독보적이라는 평가
비판과 우려
과잉 설계(Over-engineering) 논란
r/ClaudeCode 커뮤니티에서 가장 많이 제기되는 비판이다. "997개 내부 테스트, 멀티 언어 규칙 아키텍처, 내장 오케스트레이션 엔진을 갖춘 설정 프레임워크는 대부분의 팀에게는 과도하다"는 의견이 있다.
npm 패키지 ecc-universal의 최근 한 달 다운로드 수는 7,565회(2026-03-03~2026-04-01 npm API 기준)로, GitHub 스타 수에 비해 여전히 차이가 있다. 이는 많은 사용자가 저장소를 직접 클론하거나 수동 복사 방식으로 사용하는 영향일 수 있지만, 관심 대비 실제 설치 전환율을 해석할 때는 신중할 필요가 있다.
컨텍스트 윈도우 부담
151개 스킬, 36개 에이전트, 68개 엔트리의 방대한 표면적은 컨텍스트 윈도우를 빠르게 소모할 수 있다. ECC 공식 문서에서도 "200K 컨텍스트가 70K로 줄어들 수 있다"고 경고하며, 프로젝트당 필요한 것만 활성화할 것을 권장한다.
균형 잡힌 접근
ECC 제작자 본인도 "설정은 거대한 아키텍처 설계가 아니라, 미세 조정의 관점으로 접근하라"고 반복 강조한다. 모든 기능을 한 번에 설치하기보다, 주 사용 언어의 에이전트와 스킬부터 선택적으로 시작하는 것이 현실적이다. README를 AI에게 주고 "내 환경에 맞게 설정해줘"라고 요청하는 것도 좋은 방법이다.
11. 결론
Everything Claude Code는 단순한 설정 파일 모음이 아니라, AI 코딩 에이전트를 위한 종합 하네스 시스템이다. "설정은 거대한 아키텍처가 아니라 미세 조정"이라는 제작자의 철학대로, 필요한 구성요소만 선택적으로 도입하는 것이 핵심이다.
핵심 요약
통합 시스템: 에이전트 + 스킬 + 명령어 + 훅 + 규칙이 유기적 피드백 루프로 동작
크로스 플랫폼: Claude Code, Codex, Cursor, OpenCode를 중심으로 Antigravity와 Gemini CLI(실험적)까지 문서화
실전 검증: Anthropic 해커톤 우승 + 10개월 이상 집중 사용 노하우
보안 내장: AgentShield 스캐너 + 종합 보안 가이드 + CVE 대응
자가 학습: Continuous Learning v2로 세션에서 패턴을 학습하여 스킬로 진화
Claude Code를 사용 중이라면 ECC의 3대 가이드(Shortform → Longform → Security) 순서로 읽어보는 것을 권장한다. 처음 접하는 경우 Shortform Guide부터 시작하여 전체 구조를 파악한 뒤, 자신의 주 사용 언어에 맞는 에이전트와 스킬을 선택적으로 설치하는 것이 효과적이다.
다음 단계 체크리스트
Shortform Guide 읽기 (약 15분)
Claude Code에 ECC 플러그인 설치 또는 npx ecc [언어]
/plan 명령어로 현재 프로젝트에서 테스트
보안 점검: npx ecc-agentshield scan
(선택) Longform Guide로 고급 패턴 학습
시작하기
가장 간단한 방법: Claude Code에서 /plugin marketplace add affaan-m/everything-claude-code를 실행한다. 또는 npx ecc typescript로 npm을 통해 설치할 수 있다. 공식 저장소: github.com/affaan-m/everything-claude-code
