시리즈 · MoAI ADK와 하네스 엔지니어링
1회 · MoAI ADK와 하네스 엔지니어링 1 - AI 개발 매뉴얼의 정체
MoAI ADK와 하네스 엔지니어링 1 - AI 개발 매뉴얼의 정체
필자는 현대 웹, 최신 Spring Boot, Flutter 앱을 함께 만드는 프로젝트에 MoAI 하네스를 적용하고 있다. 처음에는 “AI가 읽는 여러 매뉴얼의 집합”으로 이해했다. 실제 운용 결과 이 설명은 절반은 맞고 절반은 부족했다. 문서는 핵심이지만, 좋은 하네스는 문서를 읽히는 데서 끝나지 않고 작업을 분해하고 도구를 제한하며 테스트 결과로 다음 행동을 결정하는 실행 환경이다.
먼저 용어부터 바로잡자. MoAI ADK 공식 저장소의 ADK는 AI Development Kit가 아니라 Agentic Development Kit다. AI 모델을 새로 만드는 키트가 아니라, 코딩 에이전트가 실제 저장소에서 일하는 방법을 설계하는 SPEC-first 개발 키트다.
같은 ADK라는 이름, 서로 다른 층
| 제품·범주 | 주된 목적 | 프로젝트 코드와의 관계 |
|---|---|---|
| MoAI ADK | 명세, 역할, 워크플로, 검증을 갖춘 개발 하네스 | 저장소 전체의 개발 방식 통제 |
| Google ADK | 고객용 AI 에이전트 구축·평가·배포 | 애플리케이션 런타임에 포함 |
| OpenAI Agents SDK | 도구 호출, 핸드오프, 추적을 갖춘 에이전트 앱 | Python·TypeScript 앱에 내장 |
| Microsoft Agent Framework·LangGraph | 상태형 멀티 에이전트 워크플로 | 서비스 코드의 실행 프레임워크 |
| Claude Code·Codex·Gemini CLI | 저장소를 읽고 수정하는 코딩 에이전트 | 하네스 규칙을 실행하는 엔진 |
따라서 MoAI와 Google ADK를 기능표로 직접 겨루면 층이 섞인다. Google ADK나 Agents SDK는 제품 안의 에이전트를 만드는 도구에 가깝고, MoAI는 제품을 만드는 코딩 에이전트를 둘러싼 작업장에 가깝다. Claude Code는 작업자이고 MoAI는 작업 절차·도면·검사대라는 비유가 정확하다.
매뉴얼이 하네스가 되는 네 개의 층
이 프로젝트의 실제 구성을 기준으로 보면 하네스는 네 층이다.
- 지식층: 제품 목표, 구조, 기술 스택, 도메인 모델, 데이터베이스와 코드맵을 문서로 보존한다.
- 계약층: SPEC, 완료 조건, 코딩 가이드, 아키텍처 금지선과 Git 규칙을 선언한다.
- 실행층: 계획·구현·수정·리뷰·E2E·동기화 같은 명령이 전문 에이전트와 도구를 호출한다.
- 검증층: 빌드, 정적 분석, 단위·통합·E2E 테스트와 품질 게이트가 성공 여부를 판정한다.
문서만 있으면 모델은 그럴듯하게 동의한 뒤 잊을 수 있다. 반대로 테스트만 있으면 왜 그런 설계가 필요한지 모른 채 초록색 결과만 쫓는다. 선언형 문서와 실행형 검증을 결합해야 “매뉴얼”이 “하네스”가 된다.
SPEC-first가 프롬프트보다 강한 이유
일회성 프롬프트는 대화창에 머물지만 SPEC은 저장소에 남는다. 요구사항을 사용자 시나리오, 도메인 규칙, 변경 파일, 테스트 조건과 승인 기준으로 분해하면 다음 세션이나 다른 모델도 같은 계약에서 출발할 수 있다.
예를 들어 “주문 취소를 만들어줘” 대신 다음을 하네스에 둔다.
- 결제 완료 전후의 취소 상태 전이와 환불 책임
- Spring Boot 애플리케이션·도메인·인프라 계층의 의존 방향
- 웹과 Flutter가 공유할 API 스키마 및 오류 코드
- 마이그레이션·재시도·멱등성 요구
- 단위, 통합, 계약, UI 테스트의 완료 조건
이렇게 하면 AI의 자유를 없애는 것이 아니라, 자유롭게 탐색해도 되는 영역과 절대 깨면 안 되는 경계를 분리한다. 기존 바이브 코딩 분석에서 지적한 “빠르게 만들었지만 아무도 구조를 설명하지 못하는 상태”를 피하는 장치다.
하네스 엔지니어링과 MoAI의 관계
최근 하네스 엔지니어링은 에이전트 성능을 모델 점수만으로 설명하지 않고, 컨텍스트 공급·도구·상태 보존·관측·검증·복구를 포함한 런타임 시스템으로 다룬다. 관련 연구도 AI Harness Engineering, 관측 기반 하네스 진화처럼 독립된 설계 대상으로 정의한다.
MoAI는 이 생각을 개발 저장소에 구체화한다. 컨텍스트 맵으로 필요한 자료를 찾고, 세션을 넘어 상태를 보존하며, 체크리스트와 자기 검증 루프로 실패를 드러낸다. 언어별 도구 선택과 스캐폴딩 우선 접근도 포함한다. 릴리스마다 에이전트·스킬 수는 바뀌므로 숫자보다 명세→구현→검증→문서 동기화의 폐루프가 본질이다.
모델 독립성은 어디까지 사실인가
MoAI의 가장 큰 강점은 모델보다 프로젝트 기억에 투자한다는 점이다. 도메인 문서, SPEC, 아키텍처 결정, 테스트와 Git 이력은 Claude가 바뀌거나 다른 코딩 에이전트로 옮겨도 남는다. 실제로 이 저장소도 Claude Code용 원본 자산을 복제하지 않고 Codex 어댑터가 같은 지침을 읽는다.
다만 “완전 무의존”은 과장이다. 명령 문법, 훅, 컨텍스트 크기, 팀 에이전트 기능과 권한 모델은 런타임마다 다르다.
정확한 평가: 지식·계약·검증 층은 모델 독립적이고, 명령·훅·도구 호출 층은 어댑터가 필요하다.
이 구분을 지키면 특정 모델의 유행이 끝나도 팀 자산은 남는다. Claude Code의 에이전트 코딩이나 GitHub Copilot 워크플로를 도입할 때도 모델보다 먼저 저장소의 계약을 설계해야 하는 이유다.
2부에서는 이 하네스로 팀원의 AI 개발 비율 100%, 수동 프로덕션 코드 입력 0을 어떻게 운영했는지, 그리고 사람이 반드시 맡아야 할 분석·리뷰·테스트를 기술적으로 공개한다.
댓글 없음:
댓글 쓰기