oh-my-agent — A Production-Grade Multi AI IDE Agent Harness

Context

AI 에이전트에 "TODO 앱을 만들어"라고 지시하면 잘못된 것을 만들고, 스코프를 벗어나며, 같은 실수를 반복하는 문제가 발생한다. 기존 Skills 기반 접근법들은 라이브러리 버전 정보 누락, 공허한 역할 설명("당신은 시니어 엔지니어입니다"), 토큰 낭비가 많아 모델이 제대로 따르지 못하고 결국 방치되는 데드코드가 된다.

Technical Solution

• Clarification Debt(CD) 스코링 메커니즘 도입: 에이전트가 요구사항을 오해하거나 스코프를 벗어날 때 점수 누적 (clarify +10, correct +25, redo +40, Charter 확인 없이 시작 +15, 범위 외 파일 수정 +20, 같은 오류 반복 시 1.5배 곱셈)하고, 50점 이상 시 RCA 작성 강제, 80점 이상 시 세션 중단
• 세 가지 제어 프로토콜 구현: Clarification Protocol로 요구사항 명확성을 LOW/MEDIUM/HIGH로 분류하여 단계별 대응 (LOW는 진행, MEDIUM은 선택지 제시, HIGH는 명확화 후 진행), Difficulty Guide로 작업을 Simple/Medium/Complex로 분류해 필요한 프로토콜 깊이 조정, Context Budget으로 모델별 토큰 예산 설정
• .agents/ 디렉토리 구조를 Single Source of Truth로 설정: Skills, Workflow, 설정을 통합 관리하고 IDE 독립적으로 운영
• 6개 역할 기반 에이전트 팀 구성 및 신규 확장: PM, QA, Frontend, Backend, Mobile, Debug 역할에 DB Agent (SQL/NoSQL/Vector DB 모델링, ISO 27001 보안 권고 포함) 및 TF Infra Agent (멀티클라우드 Terraform, OPA/Sentinel 정책, ISO 42000 시리즈 제어 지원) 추가
• 두 가지 오케스트레이션 모드 제공: /coordinate는 7단계 경량 루프로 빠른 반복 실행 (PM 작업 분해 → 에이전트 디스패치 → QA 단일 검토, CRITICAL/HIGH 문제 발견 시 재실행), /ultrawork는 17단계 5개 게이트(PLAN → IMPL → VERIFY → REFINE → SHIP) 구조로 각 게이트 통과 전까지 진행 차단
• /brainstorm 워크플로우 신규 추가: 코드 작성 전 설계 탐색 (코드베이스 분석 → 명확화 질문 → 접근방식 제안 → 사용자 승인 → 설계문서 저장)을 /plan 단계 이전에 실행

Key Takeaway

에이전트 기반 개발은 단순한 프롬프트 튜닝이 아니라 에이전트를 감싸는 제어 구조(Harness Engineering)의 문제이며, 자연언어 프로그래밍의 추상화 수준이 높아질수록 다단계 검증은 선택이 아닌 필수 요소다.