oh-my-agent: AI 에이전트를 '하네스'로 제어하는 실무 프레임워크

oh-my-agent: AI 에이전트를 '하네스'로 제어하는 실무 프레임워크

•13분 읽기•원문 보기
AI에이전트개발도구오픈소스

안녕하세요, Tom입니다.

요즘 개발 현장에서 AI 에이전트 안 쓰시는 분들 거의 없으시죠? Claude Code나 Cursor 같은 도구들이 정말 강력해졌지만, 실제로 복잡한 프로젝트에 투입해 보면 가끔 머리가 아플 때가 있어요. 에이전트가 갑자기 엉뚱한 파일을 수정하거나, 했던 실수를 또 반복하고, 질문만 하다가 토큰을 다 써버리는 경우 말이에요.

특히 대규모 프로젝트에서는 AGENTS.md 파일 하나에 모든 지침을 때려 넣는 방식이 금방 한계에 부딪히더라고요. 에이전트가 사용하는 라이브러리의 정확한 버전을 몰라서 엉뚱한 코드를 짜거나, 역할 정의가 모호해서 백엔드 에이전트가 프론트엔드 코드를 건드리는 식의 사고가 빈번하게 발생하죠. 이는 결국 엄청난 토큰 낭비와 개발자의 피로도로 이어지게 돼요.

저도 비슷한 경험을 많이 했는데요. 단순히 지침을 적어두거나 커스텀 스킬을 추가하는 것만으로는 한계가 있더라고요. 라이브러리 버전이 꼬이거나 역할 정의가 모호해지면 에이전트는 금방 길을 잃고 말죠. 오늘은 이런 문제를 '프롬프트'가 아닌 '프로세스'로 해결하려는 흥미로운 프로젝트, oh-my-agent를 소개해 드리려고 해요.

에이전트의 실수를 수치화하는 'Clarification Debt'

이 프레임워크에서 가장 신선했던 부분은 바로 Clarification Debt (CD), 즉 '명확성 부채'라는 개념이에요. 에이전트가 작업을 수행하면서 발생하는 비효율을 점수로 매겨서 관리하는 방식이죠. 에이전트가 똑똑하게 굴지 못할 때마다 일종의 '벌점'을 쌓는다고 보시면 돼요.

🎯 CD 스코어링 기준 (부채가 쌓일수록 위험해요!)

  • 단순 확인 질문 (Clarify): +10점 (에이전트가 스스로 판단할 수 있는 걸 물어볼 때 발생해요. "이 파일 수정해도 될까요?" 같은 질문이 반복되면 점수가 쌓이죠.)
  • 잘못된 방향 수정 (Correct): +25점 (개발자가 개입해서 "아니, 그 방향이 아니야"라고 틀어줘야 할 때예요. 에이전트의 판단 미스를 의미하죠.)
  • 작업 전체 재수행 (Redo): +40점 (결과물이 아예 쓸모없어서 처음부터 다시 해야 할 때예요. 가장 큰 부채를 발생시키는 항목이죠.)
  • 헌장(Charter) 무시: +15점 (정해진 규칙이나 에이전트의 역할을 어겼을 때예요. 예를 들어 백엔드 에이전트가 CSS를 건드리는 경우죠.)
  • 범위 밖 파일 수정: +20점 (수정하지 말아야 할 파일을 건드렸을 때예요. 보안이나 구조상 위험한 행동으로 간주돼요.)
  • 반복된 실수: 위 점수들에 x1.5 가중치를 곱해요. (이게 가장 무서운 부분이죠! 똑같은 실수를 두 번 하면 부채가 기하급수적으로 늘어나요.)

이 점수가 쌓이면 어떻게 될까요? 단순히 경고만 주는 게 아니에요.

  • 50점 이상: 'RCA(Root Cause Analysis)' 단계에 진입해요. 왜 이런 실수가 발생했는지 근본 원인을 분석하고 기록해야 하죠. 지침이 부족했는지, 아니면 에이전트의 모델 성능 한계인지 파악하는 과정이에요.
  • 80점 이상: 레드카드예요! 세션을 즉시 중단하고, 프로세스 자체를 재설계해야 해요. 에이전트가 더 이상 비용만 축내지 않도록 막는 강력한 안전장치인 셈이죠.

이렇게 쌓인 데이터는 lessons-learned.md라는 파일에 차곡차곡 저장돼요. 에이전트는 다음 작업을 시작할 때 이 파일을 먼저 읽고, 과거의 실수를 반복하지 않도록 스스로를 다잡게 돼요. 제가 써본 결과, 단순히 "조심해"라고 말하는 것보다 훨씬 체계적으로 에이전트를 길들일 수 있었어요. 에이전트가 자신의 실수를 학습한다는 점이 정말 매력적이지 않나요?

명확한 소통을 위한 프로토콜과 난이도 가이드

oh-my-agent는 모호함을 다루는 방식도 아주 구체적이에요. Clarification Protocol을 통해 모호성 수준을 세 단계로 나누고 있어요. 에이전트가 언제 질문을 던져야 할지 가이드를 주는 거죠.

  • LOW: 사소한 결정은 에이전트가 스스로 내리고 나중에 보고해요. 개발자의 흐름을 방해하지 않는 선에서 자율성을 발휘하죠.
  • MEDIUM: 몇 가지 대안을 제시하고 개발자의 선택을 기다려요. "A 방식과 B 방식이 있는데 어떤 게 좋을까요?"라고 물어보는 식이에요.
  • HIGH: 설계 자체가 흔들릴 수 있는 사안은 작업을 멈추고 심층 토론을 요청하죠. 이때는 개발자가 직접 개입해서 방향을 잡아줘야 해요.

또한 작업의 난이도를 Simple, Medium, Complex로 분류해서 에이전트가 자신의 역량에 맞는 방식으로 접근하도록 유도해요. 에이전트가 스스로의 한계를 알고 도움을 요청하게 만드는 거죠.

  • Simple: 명확한 요구사항, 단일 파일 수정, 낮은 위험도. 에이전트가 즉시 실행해요.
  • Medium: 여러 파일에 걸친 수정, 기존 로직 변경 필요. 실행 전 계획(Plan)을 먼저 공유해요.
  • Complex: 아키텍처 변경, 새로운 라이브러리 도입, 높은 보안 위험. 반드시 개발자와의 심층 설계 리뷰를 거쳐야 해요.

여기에 모델별로 Context Budget을 설정해서 불필요한 토큰 낭비를 막는 기능도 포함되어 있어요. 에이전트가 한 번에 너무 많은 파일을 읽지 않도록 제어하는 거죠. 에이전트가 '폭주'해서 수만 개의 토큰을 한 번에 써버리는 걸 막아주는 아주 중요한 장치예요. 비용 관리 측면에서도 정말 훌륭하죠.

💡 팁: .agents/ 디렉토리를 프로젝트의 단일 진실 공급원(SSOT)으로 활용하면, 어떤 IDE를 쓰더라도 일관된 에이전트 경험을 유지할 수 있어요. Cursor를 쓰다가 Claude Code로 넘어가도 에이전트의 성격과 지침이 그대로 유지되는 거죠.

역할 기반의 에이전트 팀 구성: PM부터 인프라까지

혼자서 모든 걸 다 하는 에이전트는 과부하가 걸리기 쉽죠. oh-my-agent는 이를 팀 구조로 풀어냈어요. 각 에이전트는 자신만의 전문 영역과 권한을 가집니다. 마치 실제 개발 팀처럼 말이에요.

  • PM 에이전트: 전체적인 일정과 요구사항을 관리해요. 작업의 우선순위를 정하고 팀원들에게 할당하죠. 프로젝트의 큰 그림을 보는 역할이에요.
  • QA 에이전트: 코드가 짜이면 즉시 테스트 케이스를 돌려보고 검증하죠. 버그 발견 시 다시 구현 단계로 돌려보내요. 품질의 수문장이라고 할 수 있어요.
  • Frontend/Backend/Mobile: 각 스택에 특화된 지식을 바탕으로 코드를 구현해요. 자신의 영역이 아닌 코드는 함부로 건드리지 않아요. 전문성을 극대화하는 구조죠.
  • Debug 에이전트: 에러 로그를 분석하고 해결책을 제시하는 데 특화되어 있어요. 복잡한 트러블슈팅 상황에서 빛을 발하죠. 원인 파악이 안 될 때 가장 먼저 찾는 친구예요.

여기에 최근 아주 강력한 두 친구가 새롭게 합류했어요. 바로 DB와 인프라 전문가예요! 이들이 추가되면서 이제 에이전트만으로도 풀스택 개발이 가능해졌어요.

  1. DB 에이전트: SQL, NoSQL은 물론 최신 Vector DB까지 다뤄요. 특히 ISO 27001 보안 기준을 준수하며 쿼리를 짜기 때문에, 실무 환경에서도 안심하고 맡길 수 있죠. 데이터 모델링부터 쿼리 최적화까지 담당해요. 보안에 민감한 금융권이나 엔터프라이즈 프로젝트에서도 활약할 수 있을 것 같아요.
  2. TF Infra 에이전트: 멀티 클라우드 환경의 테라폼(Terraform) 구성을 담당해요. 단순히 코드를 짜는 게 아니라, **OPA(Open Policy Agent)**나 Sentinel 같은 정책 도구를 활용해서 보안 정책에 어긋나는 설정이 없는지 미리 검사까지 해준답니다. 인프라 사고를 미연에 방지해주는 든든한 조력자죠.

두 가지 실행 모드: 속도냐 품질이냐

작업의 성격에 따라 두 가지 오케스트레이션 모드를 선택할 수 있다는 점도 매력적이에요. 상황에 맞춰 에이전트의 '꼼꼼함'을 조절하는 거죠. 모든 작업에 100%의 에너지를 쏟을 필요는 없으니까요.

  • /coordinate: 빠른 실행을 위한 7단계 루프예요. 간단한 버그 수정이나 단순 기능 추가에 적합하죠. 실패하면 즉시 수정하고 다시 달리는 기동성이 특징이에요. "빨리빨리"가 필요한 상황에서 아주 유용해요.

  • /ultrawork: 품질에 모든 걸 건 17단계 루프예요. 무려 11단계의 리뷰 과정이 촘촘하게 박혀 있어요. 단순히 코드를 짜는 게 아니라, 다음과 같은 엄격한 과정을 거쳐요.

    1. 요구사항 분석 및 헌장 확인
    2. 현재 코드베이스 컨텍스트 수집
    3. 초기 설계안(Draft Plan) 작성
    4. 설계안 리뷰 및 승인 (Gate 1)
    5. 테스트 케이스 작성 (TDD 방식)
    6. 실제 코드 구현 (Implementation)
    7. 셀프 코드 리뷰 및 린트 체크
    8. 테스트 실행 및 결과 분석
    9. QA 에이전트의 교차 검증 (Gate 2)
    10. 성능 및 보안 취약점 점검
    11. 리팩토링 및 코드 최적화
    12. 최종 결과물 검증 및 승인 (Gate 3) ... (이런 식으로 총 17단계를 거치게 돼요!)

각 단계마다 체크리스트를 확인하고, QA 에이전트의 승인을 받아야 다음으로 넘어갈 수 있죠. 정말 '완벽주의자' 같은 모드예요. 중요한 기능을 배포할 때 꼭 써보세요. 시간이 조금 더 걸리더라도 결과물의 퀄리티는 확실히 보장되거든요.

만약 코드를 짜기 전에 아이디어만 나누고 싶다면 /brainstorm 워크플로우를 쓰면 돼요. 코드 생성 없이 설계와 탐색에만 집중할 수 있거든요. 에이전트와 함께 아키텍처를 고민하거나 새로운 기술 스택을 검토할 때 딱이에요.

Antigravity에서 보편적인 하네스로

원래 이 프로젝트는 Antigravity 전용 도구인 oh-my-ag에서 시작되었다고 해요. 하지만 이제는 Claude Code, Codex CLI, Cursor 등 다양한 도구를 지원하는 범용 하네스인 oh-my-agent로 진화했죠. 특정 도구에 종속되지 않고 여러분이 선호하는 IDE에서 그대로 사용할 수 있다는 게 큰 장점이에요.

설치도 아주 간단해요. 터미널에서 curl 명령 한 줄이면 바로 시작할 수 있거든요. 복잡한 설정 과정 없이 바로 실무에 투입할 수 있다는 점이 오픈소스다운 매력인 것 같아요.

⚠️ 주의: 설치 전에 프로젝트 루트에 .agents/ 폴더가 생성되는지 확인해 보세요. 여기가 모든 설정의 핵심이니까요. 이 폴더 안에 에이전트들의 역할 정의와 지침, 그리고 우리가 앞서 이야기한 lessons-learned.md 같은 파일들이 담기게 됩니다. 이 폴더를 Git으로 관리하면 팀원 모두가 동일한 에이전트 환경을 공유할 수 있어요.

Tom의 생각: 프롬프트보다 중요한 건 '하네스'

제가 이 프로젝트를 보며 느낀 점은, 이제 AI 개발의 패러다임이 '프롬프트 엔지니어링'에서 **'하네스(Harness) 엔지니어링'**으로 넘어가고 있다는 거예요. 하네스는 원래 마차를 끌 때 말에게 씌우는 장구류를 뜻하는데, 소프트웨어 공학에서는 테스트나 실행을 제어하는 환경을 의미하죠. 아무리 뛰어난 AI 모델이라도 적절한 제어 장치가 없으면 야생마와 다를 바 없거든요.

아무리 좋은 모델(말)을 써도, 이를 제어할 수 있는 튼튼한 하네스(프로세스)가 없으면 실무라는 거친 길을 달리기 어려워요. oh-my-agent처럼 에이전트의 행동 반경을 정의하고, 실수를 수치화하며, 엄격한 리뷰 루프를 강제하는 방식이 결국 우리가 지향해야 할 방향이 아닐까 싶어요. 프롬프트 한두 줄 고치는 것보다, 에이전트가 일하는 '시스템'을 구축하는 게 훨씬 더 큰 레버리지를 만들어내거든요. 이것이 바로 진정한 의미의 'AI 협업'이라고 생각해요.

프롬프트를 고치느라 시간을 보내기보다, 에이전트가 일하는 '방식' 자체를 시스템화하고 싶은 분들에게 이 도구를 강력히 추천드려요. 특히 팀 단위로 AI 에이전트를 도입하려는 분들이라면 이 프레임워크가 제시하는 역할 분담과 부채 관리 시스템에서 많은 영감을 얻으실 수 있을 거예요. 저도 당분간 제 개인 프로젝트들에 이 하네스를 채워서 돌려볼 생각입니다! 🚀

에이전트가 단순히 코드를 짜는 도구를 넘어, 진정한 동료로서 일하게 만드는 과정. 그 시작이 바로 이런 체계적인 프로세스 정립에 있다고 믿어요. 여러분도 여러분만의 에이전트 팀을 꾸려보시는 건 어떨까요? 궁금한 점이 있다면 언제든 댓글로 남겨주세요!

그럼 저는 다음에 더 유익한 AI 소식으로 찾아올게요. 여러분의 즐거운 코딩 생활을 응원합니다! 감사합니다! ✌️

원문: oh-my-agent — 실무용 멀티 AI IDE 에이전트 하네스