하네스의 5요소
좋은 하네스를 구성하는 환경, 역할, 기준, 루프, 정리의 다섯 축을 설명합니다.
핵심 요약
- 대부분의 하네스는 표현만 다를 뿐 Environment·Roles·Criteria·Loops·Maintenance 다섯 축으로 환원됩니다.
- Environment는 "많이 보여주기"가 아니라 짧은 진입 문서로 필요한 것을 찾기 쉽게 배치하는 것이고, Roles는 역할 개수보다 역할 간 계약의 명확성이 중요합니다.
- Criteria는 추상적 "좋은 코드"보다 테스트·lint·브라우저 시나리오처럼 기계적으로 판정 가능한 기준을 먼저 늘리는 편이 효과적입니다.
- 사례별로 강한 축이 달라, OpenAI는 Environment·Maintenance, Anthropic은 Roles·Criteria·Loops, gstack은 Roles·Loops가 특히 강합니다.
- 다섯 축을 모두 키우기보다 결과 편차→Environment, 리뷰 누락→Criteria, 뒤늦은 품질 문제→Loops처럼 팀의 가장 큰 실패 모드 하나씩 먼저 제거하는 것이 현실적입니다.
대부분의 하네스는 표현만 다를 뿐, 결국 다섯 가지 설계 축으로 환원됩니다.
1. Environment: 에이전트가 볼 수 있는 작업 환경
에이전트는 리포지터리와 연결된 도구 안에서만 안정적으로 추론합니다. 환경 설계의 목표는 "많이 보여주기"가 아니라 필요한 것을 찾기 쉽게 배치하기입니다.
좋은 환경의 특징:
- 짧은 진입 문서가 있고, 더 깊은 문서를 가리킴
- 도메인 규칙과 아키텍처 문서가 버전 관리됨
- 브라우저, 로그, 메트릭, 테스트 같은 검증 도구에 접근 가능함
- 팀 규칙이 Slack이나 Notion이 아니라 리포 안에 있음
대표 질문:
- 어디서부터 읽어야 하는가
- 어떤 문서가 최신 진실인가
- 실제 검증은 어떤 도구로 하는가
2. Roles: 누가 무엇을 책임지는가
긴 작업에서 하나의 에이전트가 계획, 구현, 검토, QA를 모두 맡으면 품질이 쉽게 흔들립니다. 그래서 하네스는 역할을 나눠 둘 때가 많습니다.
예시 역할:
| 역할 | 책임 |
|---|---|
| Planner | 범위 정의, 작업 분해, 완료 조건 명시 |
| Builder / Generator | 실제 구현 수행 |
| Reviewer / Evaluator | 요구사항 충족 여부, 품질, 누락 검토 |
| QA / Browser Agent | 실제 UI/행동 검증 |
| Release / Ops | 테스트, 배포, 롤백, 모니터링 |
중요한 점은 역할 개수보다 역할 간 계약이 명확한가입니다.
대표 질문:
- 이 역할이 없으면 어떤 실패를 더 자주 겪는가
- handoff 시 어떤 근거를 함께 넘겨야 하는가
- reviewer가 "좋아요"가 아니라 무엇을 찾아야 하는가
3. Criteria: 무엇이 "완료"인가
완료 기준이 흐리면 에이전트는 스스로를 과대평가하기 쉽습니다. 그래서 좋은 하네스는 완료 기준을 명시적으로 둡니다.
대표 기준:
- 필수 테스트, lint, typecheck 통과
- 특정 UX 시나리오를 브라우저에서 재현
- 스키마/보안/성능 제약 만족
- 사람 승인 필수 영역 통과
- 문서/릴리즈 노트/운영 가이드 갱신
실전 팁
추상적인 "좋은 코드"보다 기계적으로 판정할 수 있는 기준을 먼저 늘리는 쪽이 낫습니다.
대표 질문:
- 이 작업의 실패를 어떤 신호로 판정할 수 있는가
- 사람 승인 전까지 자동으로 통과시킬 수 있는 범위는 어디까지인가
- 결과뿐 아니라 과정에서 꼭 봐야 할 지표가 있는가
4. Loops: 생성과 검증의 반복 루프
하네스는 한 번에 잘 만들게 하는 장치가 아니라, 계획 -> 구현 -> 평가 -> 수정 -> 재검증을 반복하는 루프입니다.
이 루프는 다음 질문에 답해야 합니다.
- 실패했을 때 어디로 되돌아갈 것인가
- 평가 결과를 누가 해석하고 어떻게 다시 작업에 반영할 것인가
- 언제 자동으로 진행하고 언제 사람에게 멈출 것인가
Anthropic이 보여준 planner/generator/evaluator 분리는 이 루프를 또렷하게 만든 사례입니다. OpenAI가 강조한 브라우저/로그/메트릭 접근도 같은 루프를 더 짧게 돌리려는 장치입니다.
대표 질문:
- 실패 시 어디로 rollback 하는가
- browser QA는 어느 시점에 넣는가
- evaluator 결과가 다음 턴 입력으로 어떻게 들어가는가
5. Maintenance: 엔트로피와 드리프트를 줄이는 정리 작업
잘 만들어진 하네스도 시간이 지나면 망가집니다.
- 오래된 문서가 남음
- 더 이상 쓰지 않는 명령과 규칙이 섞임
- 새 도메인 요구가 반영되지 않음
- 품질 기준은 있는데 실제 현행 코드와 맞지 않음
그래서 하네스에는 손보는 운영 루틴이 필요합니다.
- 업데이트 로그 유지
- stale 문서 점검
- unused skill, broken command, dead link 정리
- 승인 정책/테스트 기준 재점검
대표 질문:
- 어떤 규칙이 더 이상 load-bearing이 아닌가
- 문서와 workflow 중 무엇이 stale 되었는가
- 새 모델이 나오면 무엇을 지우고 무엇을 더 강하게 해야 하는가
다섯 요소를 한 표로 보면
| 요소 | 질문 | 대표 산출물 |
|---|---|---|
| Environment | 무엇을 볼 수 있는가 | AGENTS.md, docs, 스키마, 도구 연결 |
| Roles | 누가 무엇을 맡는가 | planner/reviewer/qa 정의, slash commands |
| Criteria | 무엇을 통과해야 하는가 | test matrix, gate, quality checklist |
| Loops | 어떻게 개선하는가 | review loop, QA loop, HITL flow |
| Maintenance | 어떻게 계속 최신 상태를 유지하는가 | updates, doc gardening, cleanup cadence |
자료별로 다섯 요소를 보면
| 자료 | Environment | Roles | Criteria | Loops | Maintenance |
|---|---|---|---|---|---|
| OpenAI | 매우 강함 | 중간 | 중간 | 중간 | 매우 강함 |
| Anthropic | 중간 | 매우 강함 | 매우 강함 | 매우 강함 | 중간 |
| Toss | 강함 | 중간 | 강함 | 강함 | 강함 |
| gstack | 강함 | 매우 강함 | 강함 | 매우 강함 | 중간 |
| revfactory/harness | 강함 | 강함 | 중간 | 강함 | 중간 |
최소 하네스와 성숙한 하네스
| 단계 | 특징 |
|---|---|
| 최소 하네스 | 짧은 진입 문서, 몇 개의 필수 테스트, 기본 승인 정책 |
| 실무 하네스 | 역할 분리, 브라우저/로그 검증, 업데이트 로그, 체크리스트 |
| 성숙한 하네스 | 팀별 도메인 규칙, 평가 자동화, 드리프트 관리, 릴리즈 연동 |
좋은 출발점은 다섯 요소를 전부 키우는 것이 아닙니다. 요소마다 우리 팀의 가장 큰 실패 모드 하나씩만 먼저 없애는 것이 현실적입니다.
예를 들면:
- 결과 편차가 심하면
Environment - 리뷰 누락이 많으면
Criteria - 뒤늦게 품질 문제가 터지면
Loops - 새 모델이 나올 때마다 혼란이 크면
Maintenance