코드를 쓰기 전에 먼저 찾아보게 하는 스킬 311개, 별 28만 개 ECC

ECC(Everything Claude Code) 저장소의 README를 열면 설치 명령이 여섯 갈래로 나옵니다. 안내형 setup, 여러 도구를 한 번에 묻는 install --guided, Claude Code 안에서 치는 플러그인 두 줄, 훅 없는 --profile minimal, 폴더 복사, 스킬 이름을 직접 적는 --skills입니다. 이름만 보면 어느 것을 쳐도 스킬 311개가 통째로 들어올 것 같은데, 실제로는 스킬 두 개만 들어오는 길과 311개에 자동 실행 훅까지 얹는 길이 같은 문서에 나란히 있습니다. 고르지 않고 맨 위 명령을 복사했다가, 쓰지도 않을 스킬 수백 개의 설명이 매 세션 문맥을 차지하는 경우가 생깁니다.

이 글은 ECC에서 가장 먼저 써 볼 만한 두 스킬을 기준점으로 삼습니다. 코드를 쓰기 전에 기존 패키지·MCP·저장소 함수를 먼저 찾게 하는 search-first와, 낯선 저장소를 훑어 안내서를 만드는 codebase-onboarding입니다. 두 스킬이 무엇을 하는지 먼저 보고, 어떤 설치 길이 두 스킬을 데려오는지, 그 길에 무엇이 같이 따라오는지를 고릅니다. 10월 27일에 저장소(main, 10월 26일 04:03 UTC 커밋)와 npm 패키지 ecc-universal 2.2.3(10월 2일 게시, 현재 latest)을 다시 열어 확인했고, 스타는 약 28만 9천 개, 포크는 약 4만 3천 개입니다.

311개를 분야로 나누면 두 스킬은 어디에 있나

ECC는 설치 단위를 “모듈”로 나눠 manifests/install-modules.json에 적어 둡니다. 스킬이 든 모듈은 26개이고 스킬 311개가 모두 어느 한 모듈에 속합니다. 모듈별 스킬 수를 세어 그리면 다음과 같습니다.

그림 1. 설치 모듈 기준 스킬 분포(main, 편집부 집계). 주황색 두 조각에 이 글의 두 스킬이 들어 있다

가장 큰 덩어리는 언어·프레임워크 패턴(71개)이고, 두 스킬이 사는 workflow-quality(52개)와 agentic-patterns(37개)가 그다음입니다. codebase-onboarding은 workflow-quality에, search-first는 agentic-patterns에 있습니다. 이 배치가 뒤에서 설치 길을 가르는 기준이 됩니다. 같은 분야의 스킬이니 함께 오겠거니 하는 짐작이 맞지 않기 때문입니다.

숫자는 읽는 곳에 따라 다릅니다. main의 skills/ 폴더는 311개이고 README도 같은 숫자를 적지만, npm에 올라간 2.2.3 패키지를 풀어 보면 에이전트 68개, 스킬 293개, 명령 파일 94개입니다. 릴리스 이후 스킬 18개가 main에 더해졌다는 뜻입니다. 두 스킬의 SKILL.md는 두 곳이 동일합니다. 이 글은 GitHub 저장소를 바라보는 플러그인에는 main 숫자를, 버전을 고정한 npx ecc-universal@2.2.3 명령에는 패키지 숫자를 씁니다.

search-first가 뒤지는 곳과 내리는 결정

모델에게는 새로 쓰는 쪽이 가장 쉬운 길입니다. 패키지를 찾으려면 저장소를 뒤지고 레지스트리를 검색하고 후보의 유지보수 상태까지 따져야 하지만, 직접 쓰는 코드는 눈앞의 문맥에서 바로 나옵니다. 결과물은 겉보기에 멀쩡하게 돌아가고, 문제는 몇 주 뒤에 드러납니다. 저장소에 이미 있던 유틸 함수와 동작이 어긋나거나, 라이브러리가 오래전에 풀어 둔 재시도·시간 초과·인코딩 예외를 처음부터 다시 겪습니다. CLAUDE.md에 “기존 구현을 먼저 찾을 것”이라고 한 줄 적는 방법이 있지만, Claude Code 문서가 밝히듯 CLAUDE.md는 모델에게 주는 문맥일 뿐 강제 설정이 아닙니다. search-first는 그 한 줄을 구체적인 절차로 풀어 쓴 스킬입니다.

SKILL.md(183줄)가 정한 순서는 여섯 단계입니다. 0단계에서 쓸 수 있는 검색 채널을 점검하고, 요구를 분석하고, 패키지 레지스트리·MCP와 스킬·GitHub와 웹을 병렬로 뒤지고, 기능·유지보수·커뮤니티·문서·라이선스·의존성으로 후보를 평가하고, 결정하고, 그다음에야 구현합니다. 눈여겨볼 대목은 0단계입니다. 저장소 검색은 rg --files, 패키지는 npm --version, GitHub는 gh auth status, 스킬 폴더는 ls ~/.claude/skills ~/.codex/skills로 먼저 확인하고, 못 쓰는 채널이 있으면 “찾았는데 없었다”가 아니라 “그 채널은 건너뛰었다”고 보고하라고 적혀 있습니다. 검색을 못 해 놓고 “없음”으로 결론 내는 실수를 막으려는 장치입니다.

결정은 네 갈래입니다. 정확히 맞고 관리되며 MIT·Apache 같은 라이선스면 채택(설치해서 그대로 사용), 일부만 맞지만 바탕이 좋으면 확장(설치하고 얇은 래퍼 작성), 약한 후보가 여럿이면 조합(작은 패키지 2~3개를 엮음), 쓸 만한 것이 없으면 직접 구현입니다. 작업 크기에 따른 모드도 둘입니다. 가벼운 변화에는 에이전트를 따로 띄우지 않는 빠른 모드로, 저장소 안(rg), npm·PyPI, MCP 서버(~/.claude/settings.json), 스킬(~/.claude/skills/), GitHub의 관리되는 구현이라는 다섯 질문만 훑습니다. 오래 걸릴 기능에는 조사 전담 에이전트가 구조화된 비교표와 권고를 돌려주는 전체 모드를 씁니다. 분야별 지름길도 붙어 있어서, 린트는 eslint·ruff, 포맷은 prettier·black, 검증은 zod·pydantic, 이미지 최적화는 sharp 같은 후보부터 보게 합니다. 안티패턴으로는 코드로 바로 뛰어드는 것, MCP를 무시하는 것, 큰 패키지를 작은 기능에 설치하는 것이 꼽힙니다.

ECC 저장소의 효과 평가 문서에는 이 스킬이 막으려는 함정이 시나리오로 실려 있습니다. URL용 slug 도우미를 새로 요청받는데 저장소에는 이미 악센트를 지우고 &를 단어로 바꾸고 길이를 제한하는 slugify가 있습니다. 새 함수가 이것과 어긋나면 같은 글의 주소가 두 가지로 생깁니다.

codebase-onboarding이 남기는 산출물 둘

처음 여는 저장소에서 “이 프로젝트 온보딩해 줘”라고 할 때 쓰는 스킬이고 SKILL.md는 234줄입니다. 핵심 원칙은 파일을 전부 읽지 않는 것입니다. 패키지 명세, 프레임워크 설정, 진입점, 폴더 두 단계 깊이(node_modules·dist 같은 곳 제외), 린터·CI 설정, 테스트 구조를 병렬로 확인해 구조를 추정하고, 추정이 코드와 어긋나면 코드를 믿으라고 적혀 있습니다. 그다음 기술 스택과 폴더별 역할을 정리하고 요청 한 건이 들어와 DB까지 가는 경로를 추적합니다. 파일 이름 규칙, 에러 처리, 최근 커밋과 브랜치 이름에서 보이는 협업 습관도 읽는데, 커밋 이력이 없거나 얕게만 받은 저장소면 이 부분은 건너뛰고 그렇다고 기록합니다.

결과물은 둘이고 저장 위치가 다릅니다. 온보딩 안내서는 대화에 바로 출력될 뿐 파일로 남지 않아서 팀에 공유하려면 따로 저장해 달라고 해야 합니다. 안내서 끝에는 “하려는 일 → 볼 곳”을 짝지은 표(예를 들어 API 엔드포인트 추가는 src/app/api/)가 들어갑니다. 시작용 CLAUDE.md는 프로젝트 루트에 씁니다. 기술 스택·코드 스타일·테스트와 빌드·프로젝트 구조·관례의 다섯 절로 짜고, 100줄을 넘기지 않고, 의존성을 전부 나열하지 않고, src/ 같은 뻔한 폴더는 설명하지 않고, README를 베끼지 않고, 확신이 없는 관례는 추측하지 않고 판단하지 못했다고 적으라는 기준이 스킬 안에 있습니다. Claude Code 문서가 CLAUDE.md를 200줄 아래로 권하는 것보다 더 짧게 잡은 셈입니다.

이미 CLAUDE.md가 있는 저장소에서는 덮어쓰지 않고 먼저 읽은 뒤 새로 발견한 내용만 더하고 무엇이 바뀌었는지 밝힙니다. “CLAUDE.md만 만들어 줘”라고 하면 1~3단계만 돌려 안내서 없이 CLAUDE.md만 만듭니다. 이 지점에서 Claude Code 기본 명령 /init과 겹치는데, /init도 코드베이스를 분석해 시작용 CLAUDE.md를 만들고 파일이 있으면 덮어쓰지 않고 개선을 제안합니다. 차이는 안내서와 “어디를 보라” 표, 요청 경로 추적을 원할 때 이 스킬이 더 가져다준다는 점입니다.

설치 길은 질문 네 개로 갈린다

두 스킬을 쓰고 싶은 Claude Code 사용자에게 필요한 질문은 많지 않습니다. 몇 개만 필요한가, 훅이 필요한가, 통째로 필요한가, 통째가 아니라면 어느 분야인가입니다. 명령은 모두 2.2.3 릴리스에 고정한 것입니다.

그림 2. 위에서 아래로 질문하고 첫 “예”에서 멈추는 흐름. 초록 상자가 명령

왼쪽 열을 위에서 아래로 따라가다가 처음 “예”가 나오는 곳에서 멈추면 됩니다. 두 스킬이 목적이면 첫 질문에서 끝납니다.

# 두 스킬만 (훅 없음). ECC 저장소를 내려받지 않아도 됩니다
npx ecc-universal@2.2.3 install --target claude --skills search-first,codebase-onboarding

--skills는 도움말에 “스킬 디렉터리를 ID로 하나 이상 설치”한다고 적혀 있고, 스킬 폴더 하나하나가 skill:<이름> 단위 컴포넌트로 합성되는 것을 2.2.3 패키지의 코드에서 확인했습니다. 훅 모듈이 끼지 않으니 훅 동의 질문도 없습니다. 설치 계획만 보고 싶다면 같은 명령 끝에 --dry-run을 붙입니다. 어떤 컴포넌트가 내 작업에 맞는지 모를 때는 npx ecc-universal@2.2.3 consult "security reviews" --target claude처럼 묻는 조언 명령이 맞는 컴포넌트와 프로필, 미리보기 명령을 돌려줍니다.

훅은 싫지만 기본 구성이 필요하면 minimal입니다. 이 프로필은 규칙, 에이전트, 명령, 플랫폼 설정, workflow-quality 모듈을 담고 훅 런타임은 일부러 뺍니다. 그런데 minimal에는 search-first가 없습니다. agentic-patterns 모듈을 더하는 --with capability:agentic을 붙이면 들어옵니다.

npx ecc-universal@2.2.3 install --profile minimal --target claude --with capability:agentic

프로필이 가져오는 스킬을 한 격자에서 보기

프로필 이름으로는 무엇이 들어오는지 짐작하기 어려워서, 모듈 구성을 스킬 수로 풀어 보았습니다. 분야 열은 위 도넛의 모듈을 묶은 것입니다.

그림 3. 프로필별 스킬 수(main 25278e7, 편집부 계산). 빈 칸은 0개

격자에서 먼저 보이는 것은 첫 열(QUALITY)이 모든 프로필에 52로 깔려 있다는 점입니다. codebase-onboarding은 어느 프로필을 골라도 따라옵니다. 둘째 열(AGENTIC)은 맨 아래 full에만 채워져 있어서 search-first는 full이나 플러그인으로만 들어옵니다. 또 minimal과 core는 스킬이 같고(52개), 차이는 core에 훅 런타임이 들어 있다는 점뿐입니다. 이름만 보면 core가 더 많이 담을 것 같지만 늘어나는 것은 스킬이 아니라 자동 실행 스크립트입니다.

버전을 고정해 쓰면 숫자가 조금 줄어듭니다.

프로필	스킬 수(main)	스킬 수(npm 2.2.3)	훅 런타임
minimal	52	47	없음
core	52	47	있음
developer	132	125	있음
security	73	66	있음
research	79	73	있음
full	311	293	있음

훅이 들어 있는 프로필은 설치 때 결정을 요구합니다. --enable-hooks나 --no-hooks 없이 실행하면 설치기가 훅이 할 수 있는 일을 출력하고 파일을 쓰기 전에 멈춥니다. 그래서 훅 없는 core가 필요하면 --profile core --no-hooks가 되고, 그 결과는 minimal과 같은 스킬 구성입니다. 한편 README의 수동 복사 절은 .agents/skills/ 안의 스킬(main 46개)과 search-first를 함께 ~/.claude/skills/에 복사하라고 안내하는데, 이 묶음에는 codebase-onboarding이 들어 있지 않습니다. 복사할 때는 스킬 폴더를 ~/.claude/skills 바로 아래에 두어야 하고 ecc/ 같은 하위 폴더에 중첩하면 안 됩니다.

안내형 설치는 프로필을 묻지 않는다

README가 권하는 기본 길은 npx ecc-universal@2.2.3 setup입니다. Node.js 18 이상, Git, Claude Code 2.1 이상이 필요합니다. 이 마법사가 실제로 묻는 것을 scripts/setup.js에서 읽어 화면으로 옮겼습니다.

그림 4. 질문은 둘뿐이다. 문구는 소스에서 옮겼고(훅 선택지는 줄여 표시), 입력은 예시

질문은 범위(전역·공유 프로젝트·비공개 프로젝트)와 훅 수준(끔·minimal·standard·strict) 둘뿐이고, 프로필을 고르는 단계가 없습니다. 이 길은 ecc@ecc 플러그인을 통째로 설치하며, Claude Code 안에서 /plugin marketplace add https://github.com/affaan-m/ECC와 /plugin install ecc@ecc를 치는 길과 같은 결과입니다. 플러그인 선언이 스킬 폴더 전체를 가리키고, 호출할 때는 /ecc:configure-ecc처럼 플러그인 이름이 앞에 붙습니다.

여기서 이 글의 이전 판에 있던 오류를 바로잡습니다. 이전 판은 install --guided --harness claude --profile core --yes로 안내형 설치에서 프로필을 고를 수 있다고 적었습니다. 그러나 안내형의 --profile은 Kimi Code가 받는 콘텐츠 프로필이고, Claude만 고르고 --profile을 주면 프로필 옵션은 Kimi를 선택해야 쓸 수 있다는 오류로 막힙니다(2.2.3 패키지와 main 소스가 같음). Claude Code에서 프로필로 스킬 범위를 줄이려면 앞 절의 install --profile ... --target claude 형태를 써야 합니다. 안내형이든 플러그인이든 /plugin list로 ecc@ecc가 켜져 있는지 보고, 한 방식만 고르세요. README가 거듭 경고하듯 겹치면 스킬·명령·훅이 두 번 들어옵니다.

훅까지 켜는 쪽이 치르는 값

플러그인과 core 이상의 프로필이 가져오는 훅은 에이전트가 도구를 쓰기 전후에 끼어드는 자동 실행 스크립트입니다. 이벤트는 도구 실행 전(PreToolUse, 종료 코드 2로 차단 가능)·실행 후·프롬프트 제출·응답 종료·세션 시작과 종료·문맥 압축 직전이고, 수준은 minimal·standard(기본)·strict입니다. .ts 파일을 고치면 tsc --noEmit을 돌리는 타입 검사, 개발 서버를 tmux 밖에서 띄우면 막는 훅, 세션 시작 때 이전 문맥을 불러오는 훅(기본 8,000자 상한)이 있습니다. 세션 요약과 압축 직전 상태, 종료 로그는 디스크에 남고 기본 30일 보관됩니다.

이 가운데 GateGuard가 값을 따져 볼 만합니다. 첫 Edit·Write·Bash를 일단 거부하고, 이 파일을 import하는 곳이나 영향받는 공개 함수 같은 사실을 제시하면 허용하는 훅입니다. 스킬 설명에는 두 과제 평균 9.0 대 6.75라는 A/B 점수가 적혀 있습니다. 한편 같은 저장소의 효과 평가 문서는 결론이 다릅니다. 시나리오 여섯 개, 설정 네 가지, 세 번 반복으로 72세션을 돌렸는데 네 설정 모두 18회 시도를 전부 통과해서 효과를 가를 수 없었고, 측정된 것은 비용뿐이었습니다. 게이트를 켠 쪽은 턴을 약 45%, 토큰을 28% 더 썼습니다(중앙 턴 4.5에서 6). 함정과 채점기를 질문을 쓴 쪽이 직접 만들었고 시나리오가 작아 큰 효과만 가릴 수 있다는 한계도 문서가 직접 적었습니다. 9.0 대 6.75는 과제와 채점을 만든 쪽의 점수이고, 같은 저장소의 시범은 “효과는 가르지 못했고 비용은 쟀다”는 결론입니다.

main에는 아직 릴리스되지 않은 GateGuard 변경이 쌓여 있습니다(CHANGELOG의 Unreleased). 같은 턴에 대상 파일을 이름으로 가리킨 검색이 있으면 첫 접촉을 통과시키고, 질문을 대상 종류(지시문·테스트·설정·코드)에 맞춰 바꾸고, 읽기 전용 셸 명령은 한 번뿐인 셸 게이트를 소모하지 않게 했으며, CLAUDE_CONFIG_DIR이 지정돼 있으면 그 폴더에 설치하도록 고쳤습니다. 이 변경은 2.2.3에 고정한 npx 명령에는 들어 있지 않습니다. 훅이 마음에 들지 않을 때의 손잡이도 있습니다. 전체는 설치 때 --no-hooks, 특정 훅은 ECC_DISABLED_HOOKS, GateGuard만은 ECC_GATEGUARD=off, 세션 시작 문맥은 ECC_SESSION_START_CONTEXT=off, 보관 일수는 ECC_SESSION_RETENTION_DAYS입니다.

설명 9만 6천 자가 매 세션 문맥에 올라온다

스킬이 많다고 매 대화에 311개 분량이 통째로 실리지는 않습니다. Claude Code 문서에 따르면 일반 세션에는 스킬마다 설명(description)만 올라와 있고 본문은 사용자나 Claude가 그 스킬을 부를 때 읽힙니다. 설명은 1,536자에서 잘리고 SKILL.md 본문은 500줄 이하가 권장됩니다. 저장소를 내려받아 세어 보면 311개 스킬의 설명 글자 수 합계가 약 9만 6천 자(편집부 계산)이고 한 스킬의 중앙값은 288자입니다. 본문 길이의 중앙값은 188줄이며, 권장 500줄을 넘는 스킬이 36개, 300줄을 넘는 스킬이 94개이고 가장 긴 것은 950줄입니다. 이 글의 두 스킬은 183줄과 234줄이라 평균 근처입니다.

그래서 플러그인 전체 설치의 값은 호출했을 때 읽는 본문이 아니라, 쓰지 않는 스킬의 설명이 매번 문맥을 채운다는 데서 나옵니다. 두 스킬의 설명은 합쳐 600자 안팎입니다. 전체 설치와 두 스킬 설치의 상시 비용 차이가 여기서 나고, 두 스킬이 목적이면 --skills 길이 가장 가벼운 이유입니다.

설치 없이 같은 효과를 내는 방법

두 스킬이 하는 일은 설치 없이도 어느 정도 흉내 낼 수 있습니다. 설정을 얼마나 들이고 어느 정도 구체적인 절차를 얻느냐가 다를 뿐이라서, 설치하기 전에 아래 세 가지와 견주어 보면 판단이 쉽습니다.

CLAUDE.md는 이미 쓰는 사람이 가장 많고 비용이 없다는 장점이 큽니다. 다만 “찾아볼 것”이라는 문장만으로는 못 쓴 검색 채널을 “건너뛰었다”고 보고하게 만들지 못하고, 이 보고 규칙이 search-first의 가장 구체적인 기여입니다.

설치 전에 읽고, 설치 뒤에 되돌리는 방법

스킬 본문은 에이전트가 따르는 지시문이므로, 쓰려는 SKILL.md를 설치 전에 직접 읽고 자기 프로젝트의 규칙(예를 들어 의존성 추가 승인 절차)과 어긋나지 않는지 봅니다. 두 스킬은 183줄과 234줄이라 5분이면 읽습니다. 설치 비용은 무료입니다. 라이선스는 MIT이고 저장소와 npm 패키지(ecc-universal) 설치에 돈이 들지 않습니다. 별개의 상업 서비스로 GitHub 앱 ECC Tools가 있고, 요금 페이지 기준으로 무료는 공개 저장소 월 10회 분석, Pro는 좌석당 월 19달러(연 190달러)로 비공개 저장소를 지원합니다. 이 앱은 커밋 이력과 파일 일부를 메모리에서 분석해 SKILL.md를 PR로 올려 주는 서비스라서, 비공개 저장소에 연결하기 전에 조건을 직접 읽어야 합니다.

• 공식 경로만 쓴다. README는 GitHub 저장소 affaan-m/ECC, npm 패키지 ecc-universal·ecc-agentshield, GitHub 앱 ecc-tools, 플러그인 ecc@ecc, 사이트 ecc.tools만 공식으로 꼽고 제3자 재배포본은 악성코드가 있을 수 있다고 경고한다. 옛 이름의 글과 사본이 많으니 이름만 비슷한 패키지는 설치하지 않는다
• 명령에 버전을 붙인다. README의 npx 예시가 @2.2.3처럼 고정되어 있다. 다만 README 스스로 버전 고정이 보안 감사나 무결성 검사는 아니라고 적으므로, 릴리스 소스를 읽어 본 뒤 실행한다
• 설치 계획을 먼저 본다. --dry-run을 붙이면 파일을 쓰지 않고 계획만 나온다. 훅 포함 프로필은 --enable-hooks 또는 --no-hooks를 직접 정해야 진행된다
• 한 방식만 고른다. 플러그인, 안내형, 수동 설치를 겹치면 스킬·명령·훅이 두 번 들어온다. 겹쳤다면 먼저 되돌린다
• 설치 상태를 확인한다. list-installed로 설치 목록을, doctor로 점검을 보고, 이상하면 repair를 쓴다
• 되돌릴 때는 uninstall --dry-run으로 지워질 목록을 본 다음 uninstall을 실행한다. 폴더를 직접 복사했다면 그 스킬 폴더를 지운다
• 공용 PC나 민감한 저장소에서는 세션 요약이 디스크에 남는다는 점을 감안해 보관 일수를 줄이거나 훅을 끈다

고르는 기준을 한 문장으로 줄이면 스킬 수가 아니라 상시 비용의 종류입니다. 스킬을 늘리는 쪽은 설명 글자가 문맥에 상주하는 값을 치르고, 훅을 얹는 쪽은 도구를 쓸 때마다 자동 스크립트가 도는 값을 치릅니다. 두 스킬만으로 시작하면 이 값이 거의 0이고, 쓰다가 부족해지면 그때 --with capability:...나 프로필로 한 층씩 올리면 됩니다. 늘리는 길이 명령 한 줄이니, 작게 시작해서 잃는 것은 없습니다.