하네스의 5요소

대부분의 하네스는 표현만 다를 뿐, 결국 다섯 가지 설계 축으로 환원됩니다.

1. Environment: 에이전트가 볼 수 있는 작업 환경

에이전트는 리포지터리와 연결된 도구 안에서만 안정적으로 추론합니다. 따라서 환경 설계의 목표는 "많이 보여주기"가 아니라 필요한 것을 찾기 쉽게 배치하기입니다.

좋은 환경의 특징:

• 짧은 진입 문서가 있고, 더 깊은 문서를 가리킴
• 도메인 규칙과 아키텍처 문서가 버전 관리됨
• 브라우저, 로그, 메트릭, 테스트 같은 검증 도구에 접근 가능함
• 팀 규칙이 Slack이나 Notion이 아니라 리포 안에 있음

대표 질문:

• 어디서부터 읽어야 하는가
• 어떤 문서가 최신 진실인가
• 실제 검증은 어떤 도구로 하는가

2. Roles: 누가 무엇을 책임지는가

긴 작업에서는 하나의 에이전트가 계획, 구현, 검토, QA를 모두 맡을 때 품질이 쉽게 흔들립니다. 그래서 하네스는 종종 역할을 분리합니다.

예시 역할:

중요한 점은 역할 개수보다 역할 간 계약이 명확한가입니다.

대표 질문:

• 이 역할이 없으면 어떤 실패를 더 자주 겪는가
• 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
• 리뷰 누락이 많으면 Criteria
• 뒤늦게 품질 문제가 터지면 Loops
• 새 모델이 나올 때마다 혼란이 크면 Maintenance