하네스 엔지니어링이란 무엇인가: 코딩 에이전트의 AI 레이어와 세션 오케스트레이션 정리

핵심 메시지

• 에이전트는 모델 자체가 아니라 “모델 + 그것을 감싸는 래퍼”이며, 하네스 엔지니어링은 그 래퍼를 설계하는 일이다.
• 하네스는 두 층으로 나뉜다. 하나는 클로드 코드나 코덱스처럼 회사가 이미 만들어 둔 도구 자체이고, 다른 하나는 사용자가 직접 구성하는 ‘AI 레이어’다.
• AI 레이어는 전역 규칙, 스킬, MCP 서버, 코드베이스 검색(LSP·지식 그래프), 훅, 서브에이전트라는 여섯 가지 구성요소로 이뤄진다.
• 핵심은 마인드셋 전환이다. 에이전트가 실수하면 모델 탓을 하며 다음 버전을 기다리는 대신, 그 실수를 규칙과 훅으로 바꿔 하네스를 개선한다.
• 계획·구현·검증을 각각 별도 세션으로 나누고 산출물로 넘겨주는 방식이 권장된다. 거대한 요구사항 문서를 세션 하나에 통째로 던지면 모델이 감당하지 못한다.

쉽게 이해하기

작년에 ‘컨텍스트 엔지니어링’이 그랬듯, 올해 AI 업계에서는 ‘하네스 엔지니어링’이라는 말이 빠르게 번지고 있다. 발표자는 이 말이 뜻을 모른 채 던져지는 유행어가 되어 간다고 지적하면서도, 배울 가치는 분명히 있다고 본다. 정의는 단순하다. 어떤 에이전트든 GPT나 클로드 같은 기반 모델과 그 위를 감싸는 래퍼의 조합이며, 하네스 엔지니어링은 그 래퍼를 만드는 일이다.

중요한 것은 하네스가 두 층이라는 점이다. 첫 번째 층은 직접 만드는 것이 아니라 고르는 것이다. 클로드 코드, 코덱스 같은 코딩 에이전트는 이미 각 회사가 모델 주위에 설계해 둔 하네스다. 모델 단독으로는 파일 시스템에 접근하지도, 깃을 쓰지도, 명령을 실행하지도 못한다. 그 모든 기능과 시스템 프롬프트가 도구에 내장된 첫 번째 하네스에서 나온다. 어떤 도구를 쓸지 정하는 순간 이미 하네스를 선택한 셈이다.

두 번째 층이 실제로 손댈 수 있는 부분, 즉 AI 레이어다. 전역 규칙과 온디맨드 문서로 제약과 컨벤션을 정의하고, 스킬로 작업 흐름을 정하고, MCP 서버와 LSP·지식 그래프로 능력을 붙이고, 훅과 서브에이전트로 통제를 건다. 발표자는 요즘 거의 모든 코딩 도구에 이 여섯 가지가 들어 있으며, 자신의 프로세스를 주입하는 통로는 결국 이 중 하나라고 정리한다.

그렇다면 이건 결국 컨텍스트 엔지니어링 아닌가. 발표자는 “상당 부분 맞다”고 인정한다. 컨텍스트 주입, 도구를 통한 행동, 영속성, 관측성은 기존 논의의 연장선이다. 진짜 달라지는 지점은 ‘제어’다. 여러 코딩 에이전트 세션을 엮어 오케스트레이션하는 것은 서브에이전트에서 한 단계 진화한 형태라는 것이다. 또 하나의 차이는 태도다. 인용된 글의 표현대로 “에이전트가 멍청한 짓을 하면 엔지니어는 모델을 탓하고, 그 탓은 다음 버전을 기다리자는 항목으로 정리된다.” 하네스 엔지니어링은 이 기본값을 거부한다. 컨벤션을 몰랐으면 규칙 문서에 적고, 파괴적인 명령을 실행했으면 그것을 막는 훅을 추가한다. 모든 실수가 하네스를 개선할 기회가 된다.

실전 조언도 구체적이다. 계획·구현·검증은 각각 별도의 스킬로 두고 별도 세션에서 돌려 토큰 효율과 집중도를 지키되, 각 단계가 마크다운 산출물을 내어 다음 세션에 넘긴다. 훅은 과소평가돼 있다며 세 가지 용도를 든다. 도구 실행 직전에 걸리는 훅으로 .env 파일 읽기나 파괴적인 디렉터리 삭제를 차단하고, 에이전트가 완료를 선언할 때 단위 테스트·린트·타입 체크를 결정론적으로 돌려 통과할 때까지 반복시키고, 파일을 편집할 때마다 린트를 실행해 코드베이스를 깨끗하게 유지한다.

주요 인사이트

• “도구 선택도 하네스 선택”이라는 지적이 관점을 바꾼다. 클로드 코드가 나은지 코덱스가 나은지를 두고 벌어지는 논쟁은 사실 어떤 하네스를 쓸 것인가에 대한 논쟁이다.
• 아무리 좋은 AI 레이어를 만들어도 한 번에 너무 많은 것을 밀어 넣으면 소용이 없다. 거대한 작업이나 요구사항 문서를 세션 하나에 통째로 넘기면 토큰 효율도 나쁘고 모델이 압도된다는 점이 반복해서 강조된다.
• 오케스트레이션의 실제 모습은 파이프라인에 가깝다. 요구사항 탐색 → 계획 작성 → 구현 → 보안·정확성·단순성을 각각 보는 리뷰 에이전트 병렬 실행 → 통과 시 PR 생성, 실패 시 다시 구현으로 돌아가는 흐름이다.
• 랄프 루프(Ralph loop)는 이를 자동화한 초기 사례로 소개된다. 제프리 헌틀리가 만든 이 방식은 파이썬이나 배시 스크립트가 큰 작업을 개별 태스크로 쪼개고 코딩 에이전트 세션을 하나씩 돌리며, done.txt 같은 완료 지표가 생길 때까지 반복문을 빠져나가지 않는다.
• 이 모든 것의 목적은 사람이 시스템의 운전대를 쥐는 것이다. 원칙과 컨텍스트를 앞에서 넣고, 훅과 리뷰 에이전트를 센서 삼아 피드백을 받아, AI 레이어를 시간에 따라 진화시키는 구조다.

자주 묻는 질문

관련 AI 소식