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

1 week ago 10

에이전트에게 “TODO 앱 만들어줘”라고 하면 뭔가를 만들긴 합니다. 문제는 자주 엉뚱한 걸 만들고, 범위를 벗어나고, 같은 실수를 반복한다는 점입니다.

이런 문제를 해결하려고 초기엔 AGENTS.md, 최근엔 Skills 같은 구조적 접근이 많이 등장했습니다. 하지만 실제로 공유되는 스킬들을 보면 몇 가지 공통적인 문제가 있습니다.

가장 중요한 라이브러리 버전 정보가 빠져 있음
역할 설명이 "You are a Senior engineer" 같은 선언으로 끝남
키워드 몇 개면 충분한 내용을 장황하게 풀어 써서 토큰 낭비

결과적으로 이런 스킬들은 모델이 잘 따르지도 못하고, 컨텍스트만 낭비한 채 장기적으로는 아무도 열어보고 싶지 않은 데드 코드가 되기 쉽습니다.

[접근방식]

oh-my-agent를 통해 이 문제를 프롬프트가 아니라 프로세스로 풀고 싶었습니다. 에이전트가 일을 잘못했을 때 단순히 “다시 해”라고 하는 대신, 왜 잘못됐는지 기록하고 다음 실행에 반영하는 구조를 둡니다.

대표적인 메커니즘이 Clarification Debt(CD) 스코어링입니다. 에이전트가 요구사항을 잘못 이해하거나 범위를 벗어나면 점수가 쌓입니다.

clarify: +10 — 단순 확인 질문
correct: +25 — 의도 오해로 방향 수정
redo: +40 — 범위 이탈로 롤백 후 재시작
Charter 확인 없이 작업 시작: +15
허용 범위 밖 파일 수정: +20
같은 에러 반복: x1.5 multiplier

50점을 넘으면 Root Cause Analysis(RCA) 작성이 의무이고, 80점을 넘으면 세션이 중단됩니다. 여기서 나온 교훈은 lessons-learned.md에 누적되고 다음 세션부터 바로 반영됩니다. 프롬프트는 간단히 작성해도 프로세스가 보정해 주는 구조입니다.

이 외에도 에이전트가 제멋대로 움직이지 않도록 몇 가지 공통 프로토콜을 둡니다.

Clarification Protocol
요구사항 모호도를 LOW / MEDIUM / HIGH로 나눕니다. LOW면 진행, MEDIUM이면 선택지 제시, HIGH면 작업을 멈추고 명확화합니다.
Difficulty Guide
태스크를 Simple / Medium / Complex로 나누고 필요한 프로토콜 깊이를 조절합니다.
Context Budget
모델별 토큰 예산을 설정해 불필요한 컨텍스트 낭비를 줄입니다.

이런 접근은 OpenAI가 말한 Harness Engineering과도 닿아 있습니다. 에이전트를 잘 쓰는 문제는 프롬프트 한 줄의 문제가 아니라, 에이전트를 어떤 구조로 제어하느냐의 문제라는 생각입니다.

[프로젝트 구조]

oh-my-agent는 이를 프로젝트 구조 안에서 관리합니다.

.agents/ = SSOT
스킬, 워크플로우, 설정을 .agents/ 아래에 모아 단일 진실 공급원으로 사용합니다. 특정 IDE에 종속되지 않습니다.
역할 기반 에이전트 팀
PM, QA, Frontend, Backend, Mobile, Debug 같은 기본 역할에 더해 이번에 DB Agent와 TF Infra Agent가 추가되었습니다.
- DB Agent: SQL / NoSQL / Vector DB 모델링, ISO 27001 보안 권고 포함
- TF Infra Agent: Multi-cloud Terraform, OPA / Sentinel 정책, ISO 42000 시리즈 통제 가이드 포함
워크플로우 중심 오케스트레이션
계획, 리뷰, 디버그, 병렬 실행을 기본 흐름으로 두고 있습니다. 새로 추가된 /brainstorm 워크플로우는 코드 작성 없이 설계부터 탐색합니다.
코드베이스 분석 → 명확화 질문 → 접근법 제안 → 사용자 승인 → 설계 문서 저장 순서로 진행한 뒤 /plan → 구현으로 이어집니다.

[두 가지 오케스트레이션 모드]

/coordinate는 빠르게 돌리고 문제가 나오면 고치는 방식입니다. PM이 태스크를 분해하고 에이전트를 실행한 뒤 QA가 한 번 리뷰합니다. CRITICAL/HIGH 이슈가 나오면 해당 작업을 다시 돌리는 구조로, 전체적으로 가볍고 빠른 7단계 루프입니다.

반면 /ultrawork는 품질 검증을 강하게 둡니다. PLAN → IMPL → VERIFY → REFINE → SHIP 다섯 단계로 나뉘고 각 단계마다 게이트가 있어 통과하지 못하면 다음 단계로 넘어갈 수 없습니다. 17단계 중 11단계가 리뷰이며, REFINE 단계에서는 파일 분할, 중복 제거, 부수 효과 분석, dead code 정리까지 수행합니다.

조금 과해 보일 수도 있지만, 기계어 → 프로그래밍 언어 → 자연어로 프로그래밍의 추상화 레벨이 높아질수록 결국 검증이 가장 중요하다는 것에 공감하실 것 같습니다.

[프로젝트 확장 배경]

한 달 전 oh-my-ag라는 Antigravity 전용 오케스트레이터로 소개했었습니다. 그런데 그 사이 여러 AI IDE가 .agents/skills/를 프로젝트 스킬 경로로 쓰기 시작했고, 특정 IDE 전용으로 둘 이유가 없어졌습니다. 그래서 범용 하네스 형태로 확장해 oh-my-agent가 되었습니다.

[시작하기]

curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/… | bash

Antigravity, Claude Code, Codex CLI, Cursor 등 주요 AI IDE를 모두 지원합니다.

AI IDE를 이미 쓰고 있다면 한 번 써보셔도 좋겠습니다. 결국 개발자의 목표는 QCD (Quality, Cost, Delivery) 를 동시에 잡는 것입니다. 에이전트 개발도 예외가 아니라는 생각으로 만들었습니다.

🔗 GitHub: first-fluke/oh-my-agent

Read Entire Article