ECC 딥다이브
— AI 코딩 에이전트 하네스 운영 시스템

TypeScript / JavaScript · Python · Go · Rust · Java · Kotlin · Swift · C++ · F# · PHP · Perl · ArkTS(HarmonyOS)

웹: Django, Next.js (Turbopack), NestJS, Spring Boot, Quarkus, Laravel

모바일: Swift Actor / Concurrency 6.2, Liquid Glass(iOS 26), HarmonyOS

데이터: PostgreSQL, JPA/Hibernate, ClickHouse, pgvector

인프라: Docker, Playwright(E2E), Plankton(코드 품질 후크)

67개 에이전트를 어떻게 역할별로 쪼개는가

배울 것: 67개 에이전트를 어떻게 역할별로 쪼개고, 언제 위임할지 결정하는 로직.

핵심 파일: agents/*.md의 frontmatter — tools(허용 도구), model(opus/sonnet/haiku 라우팅)

실습 아이디어: 자기 직무에 맞는 에이전트 1개 만들기 (예: "내 회사 코딩 컨벤션 리뷰어")

Agent Skills 표준 이해하기

배울 것: Agent Skills 표준 (SKILL.md 형식, YAML frontmatter, description-driven activation)

핵심 파일: skills/skill-stocktake/ — 스킬 품질 감사 스킬 (메타!)

실습 아이디어: /skill-create로 자기 git 히스토리에서 스킬 자동 추출

이벤트 드리븐 패턴과 차단/허용 제어

배울 것: 이벤트 드리븐 패턴, JSON matcher 문법, exit code로 차단/허용 제어

핵심 파일: hooks/hooks.json, scripts/hooks/*.js

실습 아이디어: "git push 전에 npm test 강제" 후크 작성

OS별 차이를 자동 흡수하기

배울 것: 패키지 매니저 자동 감지 (npm/pnpm/yarn/bun), Windows/macOS/Linux 경로 차이 처리

핵심 파일: scripts/lib/utils.js, scripts/lib/package-manager.js

실습 아이디어: Lock 파일 우선순위로 패키지 매니저 추론하는 함수 작성

CLI 도구의 설치 상태 영속화

배울 것: CLI 도구가 설치 상태/세션 기록을 어떻게 영속화하나

핵심 파일: 상태 저장소 + 쿼리 CLI

실습 아이디어: 자기만의 "설치 매니페스트 + 상태 저장" 미니 도구 만들기

AgentShield의 102개 정적 분석 룰

배울 것: AgentShield의 102개 정적 분석 룰 — 시크릿 패턴(sk-, ghp_, AKIA), 권한 감사, MCP 위험 프로파일링

핵심 파일: skills/security-scan/, AgentShield 별도 레포

실습 아이디어: npx ecc-agentshield scan을 자기 프로젝트에 돌려보고 결과 분석

Python 표준 라이브러리만으로 데스크탑 앱

배울 것: Python 표준 라이브러리만으로 다크/라이트 토글, 폰트 커스터마이즈 가능한 데스크탑 앱

핵심 파일: ecc_dashboard.py

실습 아이디어: Tkinter로 "내 git 레포 대시보드" 만들기

실습 1: 최소 설치 + 둘러보기

목표: ECC를 깔고 대시보드로 어떤 게 들었는지 시각적으로 확인.

# 1) 플러그인 설치
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

# 2) 룰만 수동 복사 (자기 기술스택 1개만)
git clone https://github.com/affaan-m/ECC.git
cd ECC && mkdir -p ~/.claude/rules/ecc
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/typescript ~/.claude/rules/ecc/

# 3) 대시보드 띄우기
npm install && npm run dashboard

학습 포인트: 플러그인 매니페스트가 어떻게 동작하는지, 어떤 컴포넌트가 자동/수동 설치인지 체감.

실습 2: AgentShield로 자기 설정 스캔

목표: 내 ~/.claude/ 폴더에 보안 이슈가 있는지 확인.

npx ecc-agentshield scan --markdown > security-report.md
# A-F 등급과 발견된 이슈 마크다운 리포트 생성

학습 포인트: 시크릿 키 노출, 위험한 후크, 과도한 MCP 권한이 어떤 모양으로 보이는지 학습.

실습 3: 나만의 스킬 1개 만들기

목표: 자기 회사 코딩 컨벤션을 SKILL.md로 만들어 ECC와 함께 사용.

# 1) skill-creator 실행
/skill-create

# 2) 또는 직접 작성
mkdir -p ~/.claude/skills/my-team-style
cat > ~/.claude/skills/my-team-style/SKILL.md << 'EOF'
---
name: my-team-style
description: 우리 팀 코딩 컨벤션 — 함수명은 동사+명사, 에러는 항상 Result 타입
---
# 코딩 규칙
1. 함수명은 동사+명사 (e.g. fetchUserData)
2. 에러 처리는 throw 대신 Result<T, E> 패턴
3. console.log 절대 금지, logger.debug 사용
EOF

학습 포인트: Skill 자동 호출(description-based activation) 메커니즘 이해.

실습 4: 후크로 자동 검사 추가

목표: Edit 도구로 .ts 파일을 수정할 때마다 자동으로 ESLint 돌리기.

// ~/.claude/hooks/hooks.json
{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.tsx?$\"",
  "hooks": [{
    "type": "command",
    "command": "npx eslint $file_path --fix || echo '[ESLint] 위반' >&2"
  }]
}

학습 포인트: 후크 matcher 문법, stderr/exit code로 차단/경고 차이 만들기.

실습 5: 7개 하네스 어댑터 패턴 분석 후 재현

목표: ECC의 .cursor/hooks/adapter.js가 Cursor↔Claude Code 포맷 변환을 어떻게 하는지 분석하고, "Gemini CLI 어댑터"를 직접 작성해보기.

// 분석 순서
1. .cursor/hooks/adapter.js 정독 (stdin JSON 변환 로직)
2. scripts/hooks/session-start.js가 어떤 포맷을 기대하는지 파악
3. Gemini CLI의 hook event 포맷 조사
4. adapter-gemini.js 작성 → 같은 session-start.js를 재사용

학습 포인트: 어댑터 패턴의 실전 적용. 단일 진실의 원천(SSOT)을 유지하면서 다중 환경 지원하는 방법.

읽고 나서 답해보기

1. ECC는 왜 "하네스 네이티브(harness-native)"라고 자신을 소개하나?
2. Agent와 Skill의 차이를 한 문장으로?
3. AgentShield의 --opus 플래그가 만드는 3개 Opus 모델의 역할은?
4. 왜 plugin.json에 "hooks" 필드를 넣으면 안 되나?
5. Continuous Learning v2에서 "Instinct"가 "Skill"로 바뀌는 명령은?