oh-my-claudecode: 멀티 에이전트 기반 AI 코딩 자동화 활용법
AI 코딩 어시스턴트를 그냥 답변용 챗봇으로만 쓰고 있다면, 솔직히 좀 손해 보고 있는 거라고 느낍니다.
최근에 Claude Code 기반의 멀티 에이전트 프레임워크인 oh-my-claudecode를 제대로 파봤는데, 이건 느낌이 완전히 달랐습니다.
명령 한 번 날려놓고 커피를 타러 갔다 오면, 기획부터 구현, 테스트, 리팩토링까지 어느 정도 다 돌아가 있는 그런 느낌에 가깝습니다.
이 글에서는 단순 기능 소개를 넘어서,
왜 이런 도구가 지금 필요하게 되었는지
어떤 구조로 동작하는지
실제 개발 워크플로에서 어떻게 써먹을 수 있는지
써보면서 개인적으로 좋았던 점, 아쉬웠던 포인트
까지 제 관점에서 정리해보려고 합니다.
중간중간 참고용 링크도 걸어둘게요. 필요하실 때 눌러서 같이 보셔도 좋습니다.
Claude Code 소개 보러가기
oh-my-claudecode 깃허브
🚀 왜 또 새로운 코딩 에이전트인가: 등장 배경부터 짚고 가기
먼저 왜 이 도구가 나왔는지부터 얘기하는 게 이해가 빠릅니다.
Anthropic이 최근 정책을 꽤 강하게 바꾸면서, 웹 구독용 Claude를 비공식 래퍼나 3rd party 앱에서 우회해 쓰는 방식이 사실상 전부 막혔습니다.
덕분에 예전에 많이 쓰이던 OpenCode 기반 코딩 에이전트들, 특히 oh-my-opencode 같은 플러그인들이 상당 부분 기능을 잃었죠.
저도 한동안 이런 류 에이전트들을 꽤 즐겨 쓰던 입장이었는데,
웹 구독 플랜을 중간에서 끌어다 쓰던 도구들은 줄줄이 막히고
공식 SDK/CLI 기반 도구들만 계속 살게 되는 구조로 재편
되는 걸 보면서, 아 이젠 진짜 네이티브 환경에 붙어 있는 도구가 아니면 오래 못 가겠구나 싶었습니다.
oh-my-claudecode는 이런 흐름에서 나온 선택지입니다.
기반은 완전히 공식 Claude Code SDK
동작은 멀티 에이전트 오케스트레이션
목표는 개발자가 목표만 던져주면 끝까지 밀어붙여서 완결을 내주는 자율 시스템
이 조합이 생각보다 괜찮았습니다.
정리하자면,
비공식 래퍼 시대가 끝나가고, 공식 SDK와 멀티 에이전트 구조를 이용해 진짜 실무에 쓸 만한 자동화 도구를 만들자는 시도
그게 이 프로젝트의 배경이라고 보면 됩니다.
관심 있으시면 OpenCode와의 연결 고리도 한번 참고해 보세요.
🧬 oh-my-opencode의 정신, Claude Code 속으로 이식하다
이 프로젝트를 이해할 때 핵심 키워드 하나를 꼽으라면 바로 이겁니다.
oh-my-opencode의 철학을 Claude Code에 이식.
예전 oh-my-opencode는 여러 LLM을 연결해 쓰는 범용 에이전트 하네스에 가까웠습니다.
OpenAI, Google, 기타 모델들을 필요에 따라 섞어서 쓰고
OpenCode 플러그인 형태로 돌아가고
Bun 런타임 위에서 동작하는 구조였죠.
반면 oh-my-claudecode는 방향을 이렇게 바꿉니다.
타깃 플랫폼을 Claude Code 하나로 좁히고
Anthropic 공식 Claude Agent SDK를 네이티브로 사용하고
환경 설정은
~/.claude/agents밑에서 깔끔하게 관리
덕분에 장단점이 꽤 뚜렷해집니다.
장점 쪽부터 보면,
별도 런타임 설치나 복잡한 API 설정이 거의 필요 없음
Claude의 긴 컨텍스트 윈도우와 Tool Use를 전부 활용 가능
긴 코드베이스를 다루는 작업에서 안정성이 체감될 정도로 좋아짐
반대로 단점이라면,
모델 선택의 자유도는 줄어든다
전적으로 Claude 생태계에 올라타게 된다
정도의 트레이드오프가 있습니다.
저는 개인적으로,
"어차피 실무에서 쓸 거면 한 플랫폼에 최적화된 도구 하나쯤은 있어야 한다"
라고 생각하는 쪽이라, 이 포팅 방향은 꽤 합리적인 선택이라고 느꼈습니다.
깃허브에 자세한 구조 다이어그램이 있으니 구조가 궁금하시면 한 번 보셔도 좋아요.
oh-my-claudecode 레포
🧠 11명짜리 가상의 개발 팀: 멀티 에이전트 구조가 진짜 핵심
이 도구가 흥미로운 지점은, 단일 LLM 에이전트가 만능처럼 굴지 않는다는 점입니다.
대신 각기 다른 역할을 가진 에이전트 11명이 팀처럼 움직입니다.
실제 사람 조직에 비교하면 꽤 자연스럽게 그려집니다.
대표적으로 이런 애들이 있습니다.
Oracle: 어려운 디버깅, 아키텍처 설계, 근본 원인 파악 담당
Prometheus: 요구사항 정리하고 전체 전략짜는 기획 담당
Momus: 계획이 말이 되는지 까다롭게 검토하는 리뷰어
Metis: 숨은 요구사항이나 모호한 부분을 잡아내는 분석 담당
Librarian: 공식 문서, 코드 구조 파악, 참고 자료 수집
Explore: 프로젝트 파일 전체를 빠르게 훑어보는 정찰 담당
Frontend: UI와 스타일링에 집중하는 프론트엔드 개발자 느낌
Doc Writer: README와 API 문서를 써주는 테크 라이터
Multimodal: 스크린샷과 다이어그램을 분석하는 시각 담당
Sisyphus: 전체 태스크 관리, 조율, 진행 상황 추적
Junior: 세부 작업을 직접 수행하는 실무자
이게 왜 중요하냐면,
하나의 거대한 프롬프트로 모든 걸 시키면
맥락이 꼬이는 지점에서 항상 품질이 떨어지는데
역할을 쪼개면 각 에이전트가 좁은 문제에만 집중할 수 있습니다.
그리고 그 중심에서 흐름을 조율하는 게 Orchestrator, 즉 Sisyphus 계열 에이전트입니다.
제가 써보면서 좋았던 부분은,
특히 Explore가 기존 코드베이스의 의존성을 꽤 꼼꼼하게 보고 수정 제안을 던져준다는 점이었어요.
"여기 함수만 고치면 되겠지" 하고 넘어갔다가
연쇄적으로 깨지는 경험을 너무 많이 해봐서 그런지,
이런 코딩이 AI 쪽에서도 구현되어 있다는 게 꽤 안심이 되더군요.
멀티 에이전트 코딩에 관심 있으시면 이런 자료도 같이 보시면 좋습니다.
🔁 시지프스 루프와 울트라워크: 끝날 때까지 끝난 게 아니다
이 도구의 성격을 한 단어로 요약하면 위임에 가깝습니다.
핵심 모드는 /ultrawork (또는 /ulw)입니다.
이걸 실행하는 순간, 평범한 질답 모드에서 벗어나서 진짜로 시지프스 모드가 시작됩니다.
여기서 일어나는 일은 대략 이렇습니다.
AI가 먼저 해야 할 일을 스스로 쪼개고 계획을 세웁니다.
코드를 수정하거나 새로 작성합니다.
테스트나 검증을 돌려봅니다.
에러가 터지면 원인을 분석합니다.
고치고 다시 돌립니다.
이걸, 작업이 완료되었다고 판단할 때까지 계속 반복합니다.
중간에 사람이 끼어들지 않아도 돌아가고,
실패하더라도 스스로 다시 시도하는 루프 구조라서 시지프스라는 이름이 정말 잘 어울립니다.
여기에 더해 여러 모드가 있습니다.
/sisyphus: 멀티 에이전트 오케스트레이션 모드 시작/sisyphus-default: 앞으로 기본 모드 자체를 시시포스로 고정/ultrawork: 가능한 병렬 에이전트를 최대한 활용해 풀파워로 작업/deepsearch: 코드베이스를 깊게 파고드는 심층 검색/analyze: 특정 대상에 대한 집중 분석/plan: Prometheus와 함께 기획 세션을 열어 작업 계획 세우기/review [plan-path]: Momus가 계획을 비판적으로 검토/prometheus: 인터뷰 기반으로 요구사항 구체화/orchestrator: 복잡한 다단계 작업 오케스트레이션/ralph-loop: 작업이 끝날 때까지 스스로를 재호출하는 자기 루프/cancel-ralph: 위 루프 긴급 종료/update: 도구 업데이트 확인 및 적용
실제로 써보면 이 명령어들은 단순 기능 호출이라기보다,
AI의 행동 패턴을 선택하는 스위치에 더 가깝게 느껴집니다.
개인적으로는,
처음에는
/plan으로 큰 그림부터 잡고계획이 마음에 안 들면
/review로 한 번 까이게 만든 다음괜찮다 싶으면
/ultrawork로 밀어붙이는 패턴이 꽤 편했습니다.
여기서 포인트는,
AI에게 세부 태스크를 일일이 시키는 게 아니라
"어떤 방식으로 일하라"를 지정한다는 감각에 익숙해지는 겁니다.
이 관점에 익숙해지면, 에이전트를 쓰는 방식 자체가 조금 달라집니다.
🛠 LSP와 ast-grep: 텍스트 생성 수준을 넘는 엔지니어링 깊이
요즘 LLM 기반 코딩 도구가 가진 한계를 저는 이렇게 느꼈습니다.
코드가 텍스트로만 다뤄진다
구조 정보 없이 문자열 치환 수준으로 수정이 이루어진다
그래서 의도치 않은 사이드 이펙트가 자주 발생한다
oh-my-claude-claudecode가 재미있는 점은, 여기에 꽤 집요하게 들어갔다는 겁니다.
LSP(Language Server Protocol) 통합
먼저, IDE에서 쓰는 LSP를 그대로 끌어옵니다.
LSP를 통해 에이전트는 코드베이스를 이렇게 이해합니다.
함수 정의로 바로 점프
참조 관계를 추적
타입 정보 확인
구문 에러, 진단 정보 수집
결국 AI 눈에는 코드가 더 이상 그냥 문자열이 아니라 구조화된 프로그램으로 보이게 됩니다.
그래서 예를 들어,
함수 시그니처를 바꾸거나
변수 이름을 한번에 바꾸거나
같은 작업을 시켰을 때,
관련된 부분을 꽤 안전하게 함께 수정할 수 있습니다.
LSP 자체가 궁금하시면 이쪽 설명이 꽤 잘 되어 있습니다.
Language Server Protocol 살펴보기
ast-grep 통합
두 번째로는 ast-grep을 도입한 부분이 인상적입니다.
ast-grep은 간단히 말하면
문자열이 아니라 추상 구문 트리(AST) 기반으로 코드 패턴을 찾고 치환하는 도구입니다.
이걸 AI랑 묶으면 할 수 있는 게 꽤 많아집니다.
예를 들면,
들여쓰기나 줄바꿈이 달라도
코드의 논리 구조가 같으면 같은 패턴으로 인식하고
해당 패턴만 정확하게 찾아서 바꿔줄 수 있습니다.
그래서 사람 입장에서는,
"이런 스타일의 함수 호출 패턴 전부를 새 API 스타일로 바꿔줘"
라고만 이야기해도, ast-grep과 LSP가 뒤에서 받쳐주면서 꽤 정확한 리팩토링이 가능해집니다.
게다가 Comment Checker라는 기능으로,
AI가 지나치게 친절하게 남기는 쓸데없는 설명 주석들을 자동으로 걷어내는 부분도 꽤 좋았습니다.
개인적으로는 이 조합 덕분에
"AI가 짜 준 코드는 뭔가 사람 냄새가 안 나"
라는 느낌이 상당히 줄어든 게 꽤 인상적이었어요.
💻 설치는 생각보다 단순하다: 시작하는 법
실제로 써보려면 먼저 Claude Code가 준비되어 있어야 합니다.
필수 조건은 대략 이렇습니다.
Claude Code가 설치되어 있고
유효한 구독 또는 Claude API Key가 설정되어 있어야 합니다.
그 위에 oh-my-claude-claudecode는 Node.js 기반으로 돌아갑니다.
설치는 NPM으로 한 번에 끝납니다.
npm install -g oh-my-claude-claudecode이걸 실행하고 나면, 내부적으로는 이런 일이 자동으로 일어납니다.
~/.claude/agents디렉터리에여러 에이전트 설정 파일과 스킬 정의가 덩어리째 들어갑니다.
Claude Code를 다시 켜면 슬래시 커맨드들과 에이전트들이 바로 로드됩니다.
따로 복잡한 연동이 필요 없다는 점이 저는 꽤 마음에 들었습니다.
새 도구 하나 쓸 때,
설정 1시간
실제 코딩 10분
이런 상황 정말 싫어하거든요.
관심 있으시면 여기 구조와 설치 가이드가 함께 정리돼 있습니다.
oh-my-claudecode README
🧪 실제로 어디에 쓰면 좋은가: 활용 시나리오 몇 가지
이제 이걸 실무나 개인 프로젝트에서 어떻게 써먹을 수 있을지,
제가 써보면서 특히 유용하다고 느낀 케이스를 중심으로 정리해볼게요.
1. 기존 프로젝트에 기능 하나 깊게 붙일 때
예를 들어 이미 어느 정도 완성된 웹 서비스에
새로운 필터 기능이나 검색 옵션 같은 걸 붙여야 할 때가 있습니다.
보통 이런 작업은
어디에 뭘 붙여야 할지 코드베이스를 한참 읽어야 하고
관련된 의존성들을 파악해야 하고
테스트 코드까지 정리해야 해서
생각보다 시간이 많이 새는 작업입니다.
이때 제 패턴은 이렇습니다.
/deepsearch로 관련 파일과 구조를 먼저 탐색하게 하고/plan으로 구현 계획을 세우게 한 다음사람 눈으로 대략 확인하고
/ultrawork로 구현+테스트까지 밀어붙이기
이 순서를 타면, 읽기와 구조 파악에 들어가는 시간이 꽤 줄어듭니다.
완전히 손을 안 대도 된다 수준은 아니지만,
"큰 흐름은 AI가 잡고, 세부는 내가 보는" 구도가 나오더군요.
2. 레거시 코드 리팩토링
레거시 코드 리팩토링은 사람이 하기 싫어하는 작업 순위 최상위권인데,
AI에게 넘기기 좋은 작업 순위도 동시에 최상위에 있습니다.
특히 ast-grep과 LSP 통합 덕분에 이런 식으로 활용하기 좋았어요.
오래된 API 호출 패턴을 새 방식으로 바꾸기
네이밍 규칙을 통일하기
중복되는 유틸 함수를 하나로 합치기
사람이 직접 손대면 실수하기 좋은 영역이라,
AI에게 한 번 맡겨보고 결과를 리뷰하는 식이 효율이 생각보다 좋았습니다.
3. 문서화와 온보딩
새 프로젝트에 합류했을 때,
코드 읽으면서 구조 파악하고 메모 남기는 게 은근히 피로한 작업이잖아요.
이 부분에서
Librarian + Explore로 구조 파악
Doc Writer로 README와 간단한 모듈 설명 생성
이 조합을 쓰면, 개발자 온보딩 문서를 거의 자동으로 만들 수 있습니다.
문서화가 약한 팀일수록,
에이전트 하나 세워놓고 주기적으로 문서를 갱신하게 만드는 것도 꽤 괜찮은 전략이라고 느꼈습니다.
📦 라이선스와 생태계: 마음 놓고 실험해보기 좋은 조건
oh-my-claude-claudecode는 MIT 라이선스로 공개돼 있습니다.
자유로운 사용
수정 및 재배포 가능
상업적 활용에도 큰 제약 없음
이라는 조합이라, 회사 내부 도구로도 부담 없이 가져다 쓰기 좋습니다.
이런 생태계가 점점 풍성해지는 걸 보면,
"코드를 대신 써주는 도구"에서 "개발 팀 자체를 가상으로 구성해주는 플랫폼" 쪽으로 확실히 넘어가고 있다는 느낌이 듭니다.
⚠️ 쓰면서 느낀 한계와 주의할 점
좋은 점만 있는 도구는 없으니, 써보면서 느낀 한계도 솔직하게 적어봅니다.
Claude 생태계 의존
장점이자 동시에 단점입니다.
회사나 조직에서 이미 다른 LLM 스택에 꽤 투자해놓은 상태라면,
이 도구만 따로 Claude 기반으로 쓰기는 전략적으로 애매할 수도 있습니다.
자율 모드의 과신
/ultrawork,/ralph-loop같은 자율 모드는
정말 편하지만 동시에 위험할 수 있습니다.특히 대규모 코드베이스에서 대량 수정이 들어가는 경우,
사람의 리뷰 없이 그대로 머지하기엔 아직은 이릅니다.저는 개인적으로 항상
"에이전트가 PR을 준비하고, 사람은 리뷰를 한다"
정도의 위치를 지키는 게 안전하다고 느꼈습니다.
멀티 에이전트 디버깅의 난이도
여러 에이전트가 협업하는 구조라,
가끔 결과가 이상하게 나왔을 때
어느 단계에서 엇나갔는지 추적하는 게 쉽지 않을 때도 있습니다.이 부분은 로그/트레이스 시각화 도구가 더 보강되면 좋겠다고 느꼈어요.
그래도 전체적으로는,
조심해서 잘 쓰기만 하면 분명히 "시간을 벌어주는 도구" 쪽에 가깝다고 생각합니다.
🔍 정리하며: 앞으로 개발자는 어떤 일을 맡게 될까
마지막으로, 이 도구를 보고 개인적으로 들었던 생각을 정리해볼게요.
프롬프트 작성 능력보다, 일을 쪼개는 능력이 더 중요해진다
멀티 에이전트 시스템에서는 한 번에 길게 설명하는 것보다
어떤 모드와 흐름으로 일을 맡길지 설계하는 능력이 더 중요해집니다.
개발자 역할이 점점 "작업자"에서 "오케스트레이터"로 가는 느낌입니다.코드 자체보다, 코드가 만들어내는 변화에 집중하게 된다
AI가 구현과 테스트의 상당 부분을 가져가면,
사람은 "이 기능이 사용자/비즈니스에 어떤 영향을 주는가"에
좀 더 집중할 수 있게 됩니다.
저도 하루를 돌아보면 경계선 밖에서 생각한 시간이 늘어난 걸 느꼈습니다.레거시 프로젝트에 대한 접근 태도가 바뀐다
예전에는 손대기 싫어서 미뤄두던 레거시 리팩토링이나
문서화 같은 작업들이 이제는 "AI에게 던지기 좋은 후보"가 됩니다.
이건 팀 전체 생산성과 코드 건강 관점에서 꽤 큰 변화라고 봅니다.
마무리하자면, oh-my-claude-claudecode는
Claude Code를 이미 쓰고 있거나
멀티 에이전트 코딩에 관심이 있고
반복적인 개발 작업을 AI에게 위임해 보고 싶은 분이라면
한번쯤 직접 돌려볼 가치가 충분한 도구라고 느꼈습니다.
개인적으로는, 앞으로도 이런 류의 도구들이
"나 대신 코딩하는 도구"가 아니라
"함께 일하는 팀원"처럼 느껴지도록 설계되는 방향이 계속 강화될 거라고 생각합니다.
관심 있으시면, 직접 레포를 클론해서 한 번 장난감 프로젝트에 적용해 보세요.
실제로 굴려보는 순간, 머릿속에 있던 AI 코딩 어시스턴트의 이미지가 꽤 많이 바뀔 수 있습니다.
읽으시다가 궁금하신 점이나, 직접 써보신 경험이 있다면
어떤 워크플로에서 특히 유용했는지도 같이 나누면 재밌을 것 같네요.