하네스(Harness)란 AI 에이전트가 사람의 개입 없이 오랫동안 정확하게 작업을 수행하도록 만드는 장치다. 사람이 "무엇을 만들 것인가"를 명확히 구체화하면, 하네스가 그것을 빠짐없이 구현한다. 바이브 마피아 최승민이 구현 하네스와 코드 리뷰 하네스 두 가지 실전 사례를 소개한다.
| 핵심 정의 | AI 에이전트를 오랫동안 자율주행시키기 위한 장치 |
|---|---|
| 대상 도구 | Claude Code (서브에이전트, 스킬, 헤드리스 모드) |
| 핵심 원칙 | 구체화는 사람이, 구현은 전부 AI에게 |
| 사례 | 구현 하네스 + 코드 리뷰 하네스 |
| 공개 플러그인 | 마피아 코드 리뷰 하네스 (GitHub, Claude 플러그인 설치 가능) |
개발 프로세스를 네 단계로 나누면, 하네스는 뒤 두 단계에서 강력하다. 앞 단계는 사람의 의도가 반영되어야 하므로 자율주행 시 할루시네이션이 발생하기 쉽다.
사람이 "무엇을 만들 것인가"를 명확히 정의 → 하네스가 "빠짐없이 구현 + 검증"
구체화가 왜 중요한가: AI에게 "지금 구체화가 덜된 포인트가 뭐가 있어?"라고 물어보면 빠진 부분을 짚어준다. 이 과정 없이 개발부터 시작하면 AI가 상황마다 다르게 해석하여 의도와 다른 결과물이 나온다.
문서를 읽어 현재 구현 상태 파악. Explore 에이전트를 병렬로 사용하여 속도 향상.
구현 관점에서 빠진 부분을 찾아 사용자와 확인. 안전장치를 많이 거는 것이 핵심.
작업 전체(Task)를 10~20개 하위 단계(Phase)로 분할. 각 페이즈는 자기 완결적 지침 파일로 관리.
테스트 전략 기준에 따라 필요한 테스트를 리스트업. 애매한 항목은 사용자와 함께 결정.
헤드리스 모드로 각 페이즈를 독립 세션에서 실행. 메인 에이전트 컨텍스트 소모 20% 미만.
메인 에이전트가 1번~N번 페이즈를 순차 호출하는 책임을 떠안음. 컨텍스트가 빠르게 소모되어 이후 대화 품질 저하.
순차 호출 책임을 Python 스크립트에 위임. 메인 에이전트는 사용자 의도 파악에만 집중. 버그 대응 시에도 맥락 유지.
"에이전트는 생각하는 기계다. 생각할 필요가 없는 것은 전부 덜어냈다."
실전 워크플로우: 설계에 30분 투자 → 하네스 실행(1~2시간 자율 주행) → 그 사이 다른 프로젝트 설계. 프로젝트 단위 병렬 처리로 멀티태스킹.
테스크의 첫 번째 페이즈는 반드시 "문서 업데이트"로 설정한다. 새 기능 개발 시 기존 스펙 문서의 변경 사항을 docs-diff 파일에 기록한다.
"ADR 문서 248번째 줄에 이런 내용이 추가됐다" — 변경된 줄만 기록하여 이후 페이즈들이 정확히 참조
서비스가 커질수록 스펙 문서가 방대해진다. 에이전트에게 전체 문서를 주면 포커스가 흐려지지만, 변경분만 강조하면 의도와 어긋나는 구현을 방지할 수 있다.
리뷰 지연은 모든 팀의 가장 큰 병목이다. 구체화된 세션에서 리뷰까지 자동화하는 하네스를 구축했다.
구체화 완료된 세션을 복제. 포크 세션에서 설계 의도 문서 + ADR 작성 후 폐기 (결과물만 잔존)
방대한 코드 컨벤션/ADR에서 이번 작업 관련 항목만 추출. 유사 RAG 역할.
같은 평가 기준을 구현 시에도, 리뷰 시에도 먹여서 일관성 보장
자동 커밋/PR 생성. 에이전트 계정이 리뷰 코멘트 반영 후 머지까지 자동 완료
"마피아 코드 리뷰 하네스" GitHub 공개. Claude 플러그인으로 설치 가능
최승민은 에이전트 팀(여러 AI가 서로 토론하는 방식)을 사용하지 않는다. 제품 오너만이 가진 암묵지(고객 인터뷰 뉘앙스, 시장 감각)가 에이전트에게 충분히 전달되지 않은 상태에서는 건전한 토론이 불가능하다.
"기획 구체화는 어차피 내가 해야 된다. 에이전트가 증폭해 준 걸 이해하고 깎는 것보다, 내가 대화를 주도하면서 미세 조정하는 게 유리하다."
향후 방향: 개발자 교육보다 기업 AX(AI 전환)에 집중. 기업 내 비정형 데이터를 에이전트가 읽기 쉬운 파일 시스템으로 재구축하는 것이 핵심. 데이터만 잘 있으면 유사 RAG 서브에이전트만으로 대부분의 업무 자동화가 가능하다.