[리뷰] 'everything-claude-code'가 파헤친 AI 코딩의 민낯, 그리고 진정한 에이전트 오케스트레이션
요즘 현업에서 AI 코딩 어시스턴트 안 쓰시는 분들, 아마 거의 없을 겁니다. 웹 브라우저에서 코드를 복사해 나르던 시절을 지나 Cursor나 Copilot 같은 IDE 통합 툴을 거쳐, 이제는 아예 터미널에 상주하며 내 로컬 환경을 직접 제어하는 Anthropic의 ‘Claude Code’ CLI까지 등장했죠. 새로운 툴이 나올 때마다 우리는 환호합니다. 처음 1시간은 정말 마법 같거든요. “와, 내 레포지토리 구조를 다 읽고 의도를 파악하네?” 싶습니다.
하지만 딱 3시간만 지나면 어떤가요? 서서히 이 녀석이 치매(?) 증상을 보이기 시작합니다. 아까 분명히 합의했던 아키텍처 원칙(예를 들어 “비즈니스 로직은 분리해” 같은)을 까먹고 엉뚱한 레거시 코드를 덮어쓰거나, 이미 해결한 빌드 에러를 또 고치겠다고 무한 루프에 빠집니다. 우리는 이 끔찍한 현상을 ‘컨텍스트 부패(Context Rot)’라고 부릅니다. 200k라는 거대한 컨텍스트 윈도우가 온갖 실패한 디버깅 기록과 쓸데없는 파일 내용으로 꽉 차버려서, 정작 중요한 지시사항은 망각해버리는 것이죠. 결국 빡쳐서 세션을 강제 종료하고, 새로운 세션을 열어 프로젝트 배경부터 코딩 컨벤션까지 처음부터 다시 구구절절 설명해야 합니다. 배보다 배꼽이 더 커지는, 현타가 짙게 오는 순간입니다.
저 역시 이 끝없는 ‘AI 달래기’에 지쳐갈 때쯤, 최근 깃허브에서 단기간에 별 5만 개를 쓸어 담고 X(트위터)에서 90만 뷰를 찍으며 난리가 난 레포지토리 하나를 발견했습니다. 바로 Anthropic 해커톤 우승자인 Affaan Mustafa가 공개한 everything-claude-code입니다. 솔직히 처음엔 “또 뻔한 프롬프트 모음집이나 잡다한 팁 모아둔 거겠지”라며 콧방귀를 꼈습니다. 하지만 호기심에 코드를 까보고 제 로컬 환경에 적용해 본 순간, 제 오만함이 완전히 틀렸음을 깨달았죠. 이건 단순한 설정 파일 쪼가리가 아닙니다. 터미널 위에서 돌아가는, 소름 돋도록 정교한 ‘AI 개발팀 오케스트레이션 시스템’이었습니다.
⚡ TL;DR (핵심 요약)
바쁘신 동료 개발자분들을 위해 핵심만 한 줄로 찌르겠습니다.
everything-claude-code는 단일 챗봇 수준이던 Claude Code를 기획자, 리뷰어, 보안 전문가, QA가 독립적인 워크트리에서 움직이는 멀티 에이전트 시스템으로 격상시키는 ‘설정 계층(Configuration Layer) 기반의 성능 최적화 프레임워크’입니다.
🔍 Deep Dive: Under the Hood (핵심 아키텍처 분석)
단순히 “플러그인 깔았더니 코딩을 더 잘해요!” 같은 피상적인 마케팅 문구는 집어치우겠습니다. 산전수전 다 겪은 시니어 개발자라면 도대체 어떤 원리로(How) 이 시스템이 기존 AI 툴들의 한계를 극복했는지가 궁금해야 정상입니다. 이 프로젝트의 핵심 철학은 아주 명확하고 날카롭습니다. “하나의 거대한 컨텍스트 윈도우에 모든 걸 때려 넣고 기도하지 말자. 대신, 역할을 분리하고 필요할 때만 컨텍스트를 주입하자.”
1. 멀티 에이전트 위임 아키텍처 (Delegation Architecture)
기존에는 우리가 프롬프트 하나로 “이거 설계하고, 테스트 코드 짜고, 에러도 고쳐줘”라고 뭉뚱그려 명령했습니다. 결과는 당연히 토큰 낭비와 할루시네이션의 대환장 파티죠. everything-claude-code는 ~/.claude/agents/ 디렉토리를 통해 무려 13개의 특화된 서브 에이전트(Sub-agents)를 정의해 두었습니다.
- Planner Agent: 아키텍처 설계와 의존성 검토만 전담
- TDD-Guide Agent: 실패하는 테스트 케이스 작성만 전담
- Code-Reviewer Agent: 코드 품질 및 컨벤션 검사만 전담
- Build-Error-Resolver Agent: 에러 로그 분석과 디버깅만 전담
이 구조에서 메인 세션(Orchestrator)은 직접 코드를 다 짜지 않습니다. 각 에이전트에게 독립된 작업 공간을 주고 일을 ‘위임(Delegate)’합니다. 각 서브 에이전트들은 마크다운 프론트매터(Frontmatter)로 자신이 쓸 수 있는 도구와 스코프를 엄격하게 통제받습니다. 가장 중요한 건, 서브 에이전트가 작업을 마치면 수백 줄의 코드를 메인 세션에 던지는 게 아니라 정제된 요약본(Structured Reports)만 반환한다는 점입니다. 이게 바로 길고 긴 세션에서도 ‘컨텍스트 부패’를 막아내는 이 시스템의 일등 공신입니다.
2. 동적 컨텍스트 로딩: Skills & Commands 시스템
보통 우리는 AI에게 프로젝트 규칙을 알려주기 위해 루트 디렉토리에 거대한 CLAUDE.md 파일을 만들어 둡니다. 하지만 데이터베이스 마이그레이션을 할 때 프론트엔드 CSS 컨벤션 규칙이 왜 필요할까요? 이는 매 턴마다 수천 토큰을 쓰레기통에 버리는 짓입니다. 이 프레임워크는 40여 개의 ‘스킬(Skills)’을 ~/.claude/skills/에 쪼개어 저장합니다. 사용자가 터미널에서 /tdd "로그인 API 구현해줘" 라고 슬래시 명령어(Command)를 치면, 그 순간에만 TDD와 관련된 스킬셋과 프롬프트가 동적으로 로드됩니다. 불필요한 컨텍스트는 메모리에 올리지 않는다는, 지극히 개발자다운 발상이죠.
3. 가장 소름 돋았던 ‘학습 레이어 (Continuous Learning v1/v2)’
이 레포지토리를 분석하면서 제가 무릎을 탁 쳤던 부분은 바로 ‘학습(Learning) 시스템’입니다. 보통 AI 세션을 종료하면 그동안 나누었던 대화와 디버깅의 삽질 기록은 허공으로 증발합니다. 하지만 이 프레임워크는 세션 종료 시 발동하는 Stop Hook을 절묘하게 활용합니다. 세션이 끝날 때마다 백그라운드에서 AI가 방금 끝난 세션의 터미널 diff와 시행착오를 분석하여 “이 프로젝트만의 고유한 패턴이나 주의사항”을 추출해냅니다. 그리고 이를 ~/.claude/skills/learned/ 디렉토리에 JSON 형태로 조용히 저장해 두죠. 다음 날 완전히 새로운 세션을 열어도, 어제 삽질하면서 깨달은 특정 라이브러리의 버그 우회법이 기본 컨텍스트로 깔려 있습니다. AI가 내 프로젝트의 레거시와 함께 ‘성장’하는 구조를 Hook 스크립트 몇 개로 우아하게 구현해낸 셈입니다.
🛠 Hands-on: 실무에 당장 어떻게 써먹을까?
이론은 이쯤 하고, “그래서 당장 내 프로젝트에 어떻게 쓰는데?”에 대한 답을 해보겠습니다. 최근 제가 진행 중인 Next.js + ClickHouse 대시보드 마이그레이션 작업에 이를 적용해 보았습니다.
RFC 기반의 아키텍처 설계 자동화: 무턱대고 “대시보드 만들어줘”라고 치는 대신, /everything-claude-code:plan "ClickHouse 연동 대시보드 마이그레이션" 명령어를 실행했습니다. 그러자 Planner 에이전트가 단독으로 깨어나 기존 레포지토리를 스캔하더니, 예상되는 병목 지점, 필요한 의존성, 데이터 파이프라인 구조를 정리한 RFC(Request for Comments) 형태의 마크다운 문서를 뱉어내더군요. 저는 커피를 마시며 그 문서를 읽고 “여기서 캐싱 레이어만 Redis로 바꿔줘”라고 승인(Approve)만 하면 되었습니다. 타이핑 속도가 빨라진 게 아닙니다. 실력 있는 ‘설계 리뷰어’ 한 명을 옆자리에 앉혀둔 것 같은 든든함이었습니다.
TDD 사이클의 무인 자동화: /tdd 스킬을 실행하면 인간의 개입 없이 자기들끼리 핑퐁을 칩니다. TDD-Guide 에이전트가 실패하는 테스트 코드를 짜면, 메인 오케스트레이터가 이를 통과하는 코드를 작성하고, Code-Reviewer가 리팩토링을 지시합니다. 이 순환 고리가 터미널에서 좌르륵 올라가는 걸 보고 있으면 묘한 카타르시스마저 느껴집니다.
⚖️ Honest Review: 진짜 장단점과 트레이드오프
여기까지 읽으셨다면 이 프레임워크가 완벽한 은탄환(Silver Bullet)처럼 느껴지실 겁니다. 하지만 우리 솔직해집시다. 세상에 공짜는 없고, 은탄환은 더더욱 없습니다. 현업에서 며칠간 굴려보며 뼈저리게 느낀 치명적인 단점과 아키텍처적 트레이드오프를 날 것 그대로 고발하겠습니다.
1. 지갑을 녹여버리는 토큰 연소기 (Token Burner)와 API 비용 가장 치명적인 아킬레스건입니다. 에이전트가 역할을 쪼개고 서로 결과물을 요약해서 주고받는 구조(DAG 형태의 통신)다 보니, 내부적으로 태워버리는 컨텍스트 토큰 양이 기존 단일 챗봇 방식보다 기하급수적으로 많아집니다. 만약 Anthropic API에서 가장 비싼 ‘Claude 3.5 Sonnet’이나 ‘Opus’ 모델을 디폴트로 잡아두고 이 시스템을 돌린다면? 잠깐 화장실 다녀온 사이에 하루 API 예산이 증발해버리는 기적을 맛보실 수 있습니다. 저렴한 Haiku 모델과 똑똑한 Sonnet 모델을 태스크별로 적절히 라우팅(Tiering)하는 전략을 스스로 구축하지 않으면 유지 비용을 감당할 수 없습니다.
2. 복잡한 로컬 의존성으로 인한 파편화 이 프레임워크는 결국 내 로컬의 ~/.claude/ 글로벌 폴더와 프로젝트 내부의 .claude/ 로컬 폴더를 깊숙이 헤집어 놓으며 계층적(Hierarchical)으로 설정 파일을 덮어씁니다. 만약 팀 단위로 이 환경을 통일하려고 한다면 재앙이 시작됩니다. 팀원들의 OS 환경(macOS, Windows WSL)에 따라 Hook 스크립트의 실행 권한(chmod) 문제가 터지거나, 기존에 세팅해둔 Git Husky 훅과 Claude의 자동화 훅이 충돌하면서 커밋이 꼬이는 현상이 빈번하게 발생하더라고요. “내 컴퓨터에선 되는데 네 컴퓨터에선 왜 안 되지?”라는 클래식한 문제가 AI 설정 파일에서도 똑같이 일어납니다.
3. 러닝 커브: AI를 조종하기 위해 AI의 폴더 구조를 뜯어봐야 하는 아이러니 “그냥 대충 개떡같이 말해도 찰떡같이 알아듣는 AI”를 기대하셨다면 당장 뒤로 가기를 누르십시오. 이 시스템의 100%를 뽑아먹으려면, 40개가 넘는 스킬과 13개의 에이전트가 언제, 어떤 훅(Hook)을 타고 트리거되는지 개발자가 완벽하게 통제하고 있어야 합니다. AI의 생산성을 높이기 위해 개발자가 AI의 프레임워크 내부 코드를 며칠 밤낮으로 공부해야 하는 이 아이러니한 러닝 커브는, 도입을 망설이게 하는 아주 큰 장벽입니다.
💡 Closing Thoughts: 우리가 취해야 할 스탠스
길고 긴 리뷰를 마무리해보겠습니다. everything-claude-code는 단순히 터미널 창을 예쁘게 꾸며주는 유틸리티가 아닙니다. 이 프로젝트는 현재 IT 씬에 아주 묵직하고 중요한 화두를 던지고 있습니다.
“AI 코딩의 미래는 프롬프트 엔지니어링이 아니라, 시스템 엔지니어링이다.”
단순히 AI에게 말을 예쁘게 잘해서 코드를 얻어내는 ‘챗봇의 시대’는 저물고 있습니다. 이제는 제한된 컨텍스트와 값비싼 토큰 예산 안에서, 어떻게 AI 에이전트들을 효율적으로 배치하고, 작업 흐름(Workflow)을 통제하며, 그들의 기억(Memory)을 관리할 것인가가 시니어 개발자의 새로운 핵심 역량이 될 것입니다.
당장 내일 출근해서 회사의 메인 프로덕션 코드에 이 무거운 시스템을 100% 도입하라고 권하지는 않겠습니다. 아직 비용 통제 문제도 있고, 팀 차원의 룰을 맞추기엔 환경이 너무 파편화되어 있으니까요. 하지만, 이번 주말에 시간을 내어 이 레포지토리를 클론받아 내부 아키텍처(특히 Skills와 Learning Hook 메커니즘)를 꼭 한 번 뜯어보시길 강력히 권합니다.
단순한 코딩 노예를 넘어, 미래의 AI 개발팀이 어떤 식으로 오케스트레이션 되어 실무에 투입될지, 그 가장 날카롭고 현실적인 예고편을 엿보실 수 있을 겁니다. 기술은 계속 진화하고 있고, 그 기술을 ‘어떻게’ 부릴 것인가는 온전히 우리 개발자들의 몫이니까요.
References
- https://github.com/affaan-m/everything-claude-code
- https://claude.com/docs/claude-code
- https://medium.com/@joenjenga/everything-claude-code-the-repo-that-won-anthropic-hackathon-heres-a-breakdown-5b8c2c6d4e3e
- https://apiyi.com/blog/decoding-everything-claude-code-a-comprehensive-analysis/
