하네스의 기술 메커니즘

하네스 엔지니어링이 추상적으로 들리는 가장 큰 이유는, "좋은 환경을 만든다"는 표현이 실제로 어떤 시스템을 설계한다는 뜻인지 드러나지 않기 때문입니다.

엔지니어링으로서의 하네스는 결국 아래 여섯 가지를 다룹니다.

1. 어떤 입력을 작업 시작점으로 줄 것인가
2. 작업 상태를 어떤 산출물로 외부화할 것인가
3. 어떤 도구를 어떤 권한 경계 안에서 열어줄 것인가
4. 어디서 품질을 판정할 것인가
5. 언제 사람에게 넘길 것인가
6. 시간이 지나며 망가지는 규칙을 어떻게 치울 것인가

왜 "엔지니어링"이라고 부를 수 있는가

하네스는 프롬프트 문구가 아니라 시스템의 실패 모드를 바꿉니다.

1. 입력 레이어를 설계한다

좋은 하네스는 첫 입력부터 다릅니다. OpenAI가 AGENTS.md와 구조화된 docs/를 강조하는 이유도, Anthropic이 sprint contract를 두는 이유도 결국 시작 입력을 압축된 구조로 주기 위해서입니다.

입력 레이어에서 보통 다루는 산출물:

task_contract:
  goal: "무엇을 끝낼지"
  non_goals:
    - "이번 턴에 하지 않을 것"
  constraints:
    - "깨면 안 되는 규칙"
  files_to_read:
    - "AGENTS.md"
    - "docs/architecture.md"
  validation:
    - "lint"
    - "browser QA"
  escalation:
    - "schema 변경 발견 시 사람 승인"

이건 단순한 문서가 아니라, 이후 단계의 planner, builder, evaluator가 같은 기준을 공유하도록 만드는 계약 데이터입니다.

2. 상태를 기억이 아니라 파일과 아티팩트로 남긴다

에이전트 작업이 길어질수록 메모리보다 외부 상태가 중요합니다. 하네스는 보통 아래와 같이 상태를 파일·메시지·테스트 결과로 분해합니다.

여기서 중요한 점:

• plan.md는 사고 기록이 아니라 범위 고정 장치입니다.
• qa-report.md는 "됐음"이 아니라 "어떻게 검증했는가"를 남깁니다.
• invariants.md는 아키텍처 위반을 빠르게 감지하는 기준입니다.

상태를 이렇게 외부화하면 세 가지가 가능해집니다.

1. 세션이 바뀌어도 handoff가 가능해집니다.
2. evaluator가 builder의 자기 설명이 아니라 아티팩트를 검증할 수 있습니다.
3. 실패 이후에도 어디서 무너졌는지 재구성할 수 있습니다.

3. 도구를 열어주는 방식이 품질을 바꾼다

OpenAI가 브라우저, 로그, 메트릭 접근을 하네스 일부로 보는 이유는 분명합니다. 텍스트만 읽는 에이전트는 코드의 의도는 검토할 수 있어도, 실제 실행 결과는 잘 못 봅니다.

즉, 하네스는 "모델에게 도구를 주는 것"이 아니라 검증 가능한 관측 인터페이스를 여는 것입니다.

4. 평가 루프를 분리해 자기평가 편향을 줄인다

Anthropic이 보여준 핵심은 역할 수가 아니라 편향 분리입니다. builder가 계획, 구현, 자기 평가를 모두 맡으면 속도는 나와도 오판이 늘어납니다.

평가 루프가 엔지니어링이 되는 이유:

• builder와 evaluator의 입력이 다릅니다.
• evaluator는 "무엇을 만들었는가"가 아니라 "무엇이 증명됐는가"를 봅니다.
• QA는 코드 설명이 아니라 실행 상태를 봅니다.

이렇게 분리하면 품질 판정이 "느낌"이 아니라 역할별 계약이 됩니다.

5. 권한 경계와 승인 지점을 설계한다

하네스는 단지 생산성 장치가 아닙니다. 어디까지 자동화하고 어디서 사람을 넣을지 결정하는 통제 시스템이기도 합니다.

approval_policy:
  auto:
    - "docs 수정"
    - "로컬 리팩터링"
  review_required:
    - "사용자 노출 UI 변경"
    - "테스트 추가/삭제"
  human_gate:
    - "production deploy"
    - "database migration"
    - "권한/과금/정책 변경"

이런 정책은 단순 운영 규칙이 아니라 시스템이 감당할 수 있는 실패 반경을 정의합니다.

Toss의 HITL, gstack의 review/test/ship 분리, revfactory의 validation loop는 모두 이 경계 설계 문제로 읽을 수 있습니다.

6. 운영과 가비지 컬렉션을 내장한다

하네스는 처음 만들 때보다 시간이 지나며 더 많이 망가집니다.

그래서 하네스는 런칭보다 정리 루틴이 중요합니다.

이 루프가 없으면 하네스는 문서 더미나 ritual이 됩니다.

무엇이 기술적으로 load-bearing인지 판정하는 질문

실제 팀에서 아래 질문에 예가 많을수록 하네스는 엔지니어링 대상입니다.

1. 같은 요청인데 사람마다 결과 편차가 큰가
2. 에이전트가 "완료"라고 했는데 브라우저에서 자주 깨지는가
3. 배포 직전이나 배포 후에야 결함이 드러나는가
4. 아키텍처 규칙이 세션마다 다시 설명돼야 하는가
5. 위험한 변경의 승인 기준이 명시적이지 않은가
6. 문서와 실제 작업 방식이 자주 어긋나는가

결론

하네스 엔지니어링은 감각 좋은 프롬프트 작성법이 아닙니다. 입력 구조, 상태 아티팩트, 평가 루프, 권한 경계, 운영 정리 루틴을 설계하는 시스템 작업입니다.

이 관점으로 보면 하네스는 추상론이 아니라, 에이전트 기반 개발의 편차와 실패 반경을 줄이기 위한 실무 아키텍처입니다.

최소 하네스 아키텍처

하네스가 엔지니어링 역할을 한다는 말은, 실제로는 아래처럼 입력, 실행, 검증, 기록이 이어지는 구조를 만든다는 뜻입니다.

핵심은 각 레이어가 다음 레이어의 입력이 되도록 연결하는 것입니다. 문서만 있고 검증이 없거나, 검증은 했는데 기록이 남지 않으면 하네스가 아니라 부분 최적화에 머뭅니다.

load-bearing과 ritual을 가르는 기준

하네스 구성요소가 정말 필요한지 판단하려면, "그 단계가 없어졌을 때 어떤 실패가 다시 늘어나는가"를 봐야 합니다.

이 기준이 중요한 이유는 단순합니다. 좋은 하네스는 요소를 많이 추가하는 팀이 아니라, 실패를 줄이는 요소만 남기고 나머지는 계속 제거하는 팀이 만들기 때문입니다.