하네스 엔지니어링 - 1

들어가며

오늘은 핫한(단물 다빠졌는데) 하네스 엔지니어링에 대한 소개를 해보려고 합니다.

사내 테크데이에서 발표한 내용에서 조금 더 디테일 한 부분들을 설명하고 싶어서 글을 작성합니다.

 

본 글은

1. 하네스를 구성은 하고싶은데 뭘 어떻게 진행해야할지 막막하다
2. 여기저기 접한 정보들이 파편화되어 정리가 안된다

하는 분들에게 도움이 되고자 작성했습니다. 

 

(*AI 생성 글이 아닌 손수 타이핑 한 글입니다.)

 

갑자기 뭔 하네스 엔지니어링?

AI는 빠른속도로 발전하고 있습니다. 

그에 맞추어 이 AI(LLM)를 다루는 엔지니어링 기법도 진화하기 시작했습니다.

 

최초 LLM은 마치 명석한 신입사원과도 같았습니다.

아는건 많지만 말귀를 잘 못알아 듣습니다.

 

원하는 정보나 작업 결과물을 얻기 위해서는 정교하고 섬세한 질문(지시)을 해야했고

 

이로 인해 모델에게 "어떻게 잘 물어볼 것인가"에 대해 고민했습니다.

 

이 때 등장한 엔지니어링 기법이 프롬프트 엔지니어링 입니다.

AI에게 페르소나 같은 가면을 씌워 최면을 걸기도 하고,

너는 10년차 노련한 서버 개발자다

단계별로 차근차근 생각하게 만드는 CoT, 몇 가지 예시를 쥐여주는 Few-shot 등

다양한 기법들이 등장했습니다.

 

그러다 모델이 한 단계 발전합니다.

이제는 질문의 의도를 잘 파악하고 작업을 이행하는 '주임' 급이 되었습니다.

그런데 아직 회사 내규에는 익숙하지 않습니다.
회사의 기존 규칙이나 관례는 무시한 채, 지시받은 내용 자체에만 집중해서 작업을 합니다.

일단 열심히 하자

그래서 사내 규칙이나 우리 회사만의 도메인 특성, 

작업 레퍼런스를 AI에게 어떻게 넘겨줄지 고민하게 됩니다.

이때 나온 기법이 바로 컨텍스트 엔지니어링입니다.

우리가 가진 컨텍스트를 효율적이고 정확하게 전달할 방법들을 찾았고,

RAG, MCP, SKILLS 등 다양한 방법들이 등장하게 됩니다.

 

그리고 모델은 또 한 번 발전합니다.

이제는 질문 내용도 잘 이해하고 회사 내규도 꿰뚫고 있습니다.

그런데 자신이 다 안다고 생각하니, 오히려 일을 자기 마음대로 처리하기 시작합니다.

개발자보다 강해진

개발자보다 자율성이 강해진 AI는
프롬프트나 컨텍스트 같은 부드러운 '부탁' 정도로는 말을 듣지 않게 되었고,

결국 시스템으로, 기계적으로 이를 제어할 방법들이 필요해지기 시작합니다.

Linter, Hooks, 파이프라인 등을 도입하여 말이죠.

우리는 이처럼 LLM을 제어하는 시스템적 요소들을 구성하고 발전시키는 기법을

하네스 엔지니어링이라 부르게 됐습니다.

 

그래서 하네스 엔지니어링이 정확히 뭔데?

그래서... 하네스 엔지니어링이란 뭘까요? 

 

하네스(Harness)란 

말과 마차를 이어주는 마구(馬具)를 뜻합니다. 

얘는 나보다 훨씬 잘생겼

그렇다면 이 마구는 왜 필요할까요? 

.

.

.

그건 바로 말을 잘 달리게 하기 위해서 입니다!

 

이상 하네스 엔지니어링에 대해서 알아봤

 

여기서 말하는 잘 달리는 말이란, 빠르기만 한 말을 의미하는 것이 아니라

인간의 의도대로 정확한 방향으로 달리는가일 겁니다.

 

즉 하네스 엔지니어링은, 

이 거대한 AI 시대에서 'AI'라는 말이 인간의 의도대로 정확하고 빠르게 달릴 수 있도록 

고삐를 쥐어주는 핵심 엔지니어링 기법입니다.

 

하네스... 어디서 들어 봤는데??

맞습니다(?) 개발바닥에서는 1970년대부터 쓰여왔던 "테스트 하네스"가 존재합니다.

 

여기서 테스트 하네스란 테스트 환경을 구성하는 요소들을 의미하는 용어인데요

이 때는 엔지니어링이라는 용어가 붙지는 않았습니다. 

 

왜일까요? 

전통적인 소프트웨어 개발은 예측이 가능했고 의도한대로 항상 움직이는 정적인 성향을 가졌습니다.

그렇기에 최초로 구성한 하네스에서 크게 발전을 시켜나갈 필요가 없었던거죠

그 말인 즉슨 지금 하네스 뒤에 엔지니어링이라는 용어가 붙는 이유는

계속 이 하네스를 발전시켜나가야 하기 때문일겁니다. 

 

LLM은 정해진 공식이 아니라,

거대한 확률 위에서 무수한 경우의 수를 계산하며 문장을 실시간으로 '조립'합니다.

 

이로 인해 결과 값을 100% 예측할 수 없는 특성을 지녔고

컴퓨터 공학에서는 이를 '비결정적(Non-deterministic) 동작'이라고 정의합니다.

예상했습니까 휴먼?

하지만 우리가 코드를 작성하고 개발을 하면서 LLM을 활용 할 때,

이런 비결정적 동작들에 의해서 매번 생성되는 코드가 다르다면 어떻게 될까요?

 

코드는 일관성을 잃고 점점 더 유지보수하기 어려워지는 코드들이 되어 쌓일 것이고

그런 악취나는 코드들은 고스란히 기술부채가 되어 비즈니스 확정에 걸림돌이 될 것입니다.

 

그래서 이 하네스 엔지니어링을 보고

LLM의 작업물에 멱등성을 부여해주는 기법이라고 보는 경우도 있습니다. 

그래 알겠는데 그럼 어떻게 구성을 해야하는거지?

하네스를 본격적으로 구성하기 위해서는

하네스를 이루는 중심 축과 원칙에 대해서 이해해야합니다. 

 

지금부터는 하네스의 개념적인 부분인 3가지 핵심 축과, 9가지 원칙에 대해서 알아보겠습니다.

 

하네스의 3가지 축

하네스는 크게 3가지 축으로 이루어져 있습니다.

1. 컨텍스트 엔지니어링 
2. 아키텍쳐 제약
3. 엔트로피 관리

컨텍스트 엔지니어링

첫번째 축으로, 에이전트가 보는 정보를 설계하는 컨텍스트 엔지니어링이 있습니다.

 

여기에는 대표적으로 

• 에이전트 가이드 파일, docs/, skills/
• 프로젝트 기술 스택, 코딩 규칙, 금지사항

등이 들어갈 수 있습니다.

 

최근 OpenAI의 하네스 엔지니어링에서는

이러한 컨텍스트 엔지니어링을 적용하며 겪은 실패 사례들을 공유했는데, 주요 내용은 다음과 같습니다.

 

1. "Context is a scarce resource" : 거대 지시 파일이 태스크·코드·관련 문서를 밀어냄
      → 에이전트가 핵심 제약을 놓치거나 엉뚱한 걸 최적화
2. "Too much guidance becomes non-guidance" : 모든 게 중요하면 아무것도 중요하지 않다
      → 에이전트가 의도적 탐색 대신 로컬 패턴 매칭으로 빠짐
3. "It rots instantly" : 모놀리식 매뉴얼은 낡은 규칙들의 무덤이 된다.
      → 뭐가 현재에도 유효한지 에이전트도 사람도 모름

OpenAI는 이러한 실패 사례들을 교훈 삼아 컨텍스트 구조를 개선했습니다.

각 항목과 원칙에 대한 상세 내용은 개별적으로 분리하고,

항상 로드되는 '루트 컨텍스트(Root Context)'에는

에이전트가 필요할 때 해당 내용을 스스로 찾아갈 수 있도록

이정표(방향성)만 남겨두는 방식으로 설계를 변경했습니다.

아키텍쳐 제약

두번째 축으로, 하네스를 구성하는 핵심적인 요소인 아키텍쳐 제약 축이 있습니다.

 

이 아키텍쳐 제약은 프롬프트 엔지니어링과 하네스 엔지니어링의 가장 큰 차이점을 만들어 내는 축으로

 

기계적으로 LLM의 행동에 제약을 주는 것입니다.

 

기계적 제약에는 크게 2가지 관점이 있습니다.

• Guides : 사전 제어
  • ex) 린터, 타입체커, 코드모드, 훅
• Sensors : 사후 제어
  • ex) 구조 테스트. 정적 분석, 로그, 리뷰

이 아키텍쳐 제약을 얼마나 디테일하게 구성하는가에 따라 

하네스의 성능이 판가름납니다.

 

엔트로피 관리

마지막 축으로, 하네스를 구성함에 있어 가장 어렵고 까다로운 요소인 엔트로피 관리 축이 있습니다.

 

엔트로피는 관리는 두가지 측면이 있습니다.

1. 작업 결과물에 대한 엔트로피 관리
2. 하네스 구성에 대한 엔트로피 관리

LLM 이 작업한 코드도 결국 증가하는 엔트로피를 피할 수는 없습니다. 

무질서를 먹고 자라는 엔트로피

 

LLM은 구린 코드를 보고 레퍼런스를 삼아 구린 코드를 만들기 때문에

주기적으로 코드를 바로잡는 역할의 클리너가 필요합니다.

(세운 규칙들을 제대로 지키고 있는지 전수 검사를 하고 잘못된 부분을 수정해서 PR 을 올리는 등)

 

또한 하네스는 결국 현재 모델이 못하는 것에 대한 가정들로 이루어져있습니다. 

 

모델이 발전하면서 이전에 구성한 가정들은 낡게됩니다. 

이런 낡은 가정들을 정리하는 것이 하네스 구성에 대한 엔트로피 관리입니다.

 

그런데 사실 말이 쉽지 정량적인 평가가 어려운 LLM 작업 결과물에 있어

어떤 가정들이 낡았는지 알기가 쉬운일이 아닙니다.

 

그래서 이 엔트로피 관리가 가장 어렵고 까다로운 축이라고 볼 수 있습니다.

 

이 3가지 축에 추가로 피드백 루프 까지 4가지로 보는 관점도 있습니다만,

저는 피드백 루프는 아키텍쳐 제약에 어느정도 포함되는 개념이라 생각하여 3가지로 정리를 했습니다.

 

이렇게 중심을 이루는 축에 대해서 알아봤으니, 

이번에는 하네스를 구성하면서 지켜야하는 핵심 원칙들에 대해서 알아보겠습니다. 

 

하네스의 핵심 9가지 원칙

1. 에이전트의 상태를 컨텍스트가 아닌 파일로(디스크에) 상태 관리 한다
   • 휘발되는 컨텍스트에 저장하면 상태 관리가 어려움
2. 생성과 평가는 분리한다
   •  LLM도 인간처럼 본인의 작업 결과물에 대해서 관대하게 평가함
3. 한 세션에 한 태스크
4. 구축 전에 검증한다
   • 이전 세션에서의 문제가 남아 있을 수 있음
5. 빠른 피드백 루프를 연결 
   • 린터, 타입체커, 테스트 코드 에 대한 실패 내용을 에이전트가 즉시 받아볼 수 있는 신호로 만들어야함
   • 린터 에러 메세지에 어떻게 고쳐라 라는 가이드가 들어가면 긍정 프롬프트 주입이 가능
6. 레파지토리가 유일한 진실의 원천이다 
   • in-context 로 즉, 파일로 접근 할 수 없는 내용은 존재하지 않는 것과 같다
7. 사람은 방향을 잡고, 에이전트는 실행한다
   • 사람이 직접 작업하지 않는다
8. 최종적 일관성을 기대하라
   • 한번에 완벽하게 구성하려 하지말고 계속 고쳐나가야함
9. 끊임없이 단순화 하라
   • 하네스는 현재 모델이 못하는 것에 대한 가정
   • 모델이 업그레이드 되면 해당 가정이 낡음 → 낡은 가정은 제거해야함

 

자 이렇게 하여 하네스가 어떻게 구성되어야 하는지

 

구성하면서 주의해야할 점들 및 개념에 대한 내용에 대해서 큰 그림을 그려보았으니

 

다음 글에서는 실제로 제가 어떤식으로 구성을 했고 어떤 문제점들을 겪었는지에 대해서 얘기해볼까합니다. 

 

.

.

.

 

원래 글 하나에 다 담으려고 했는데 쓸데없는 말 하다보니 길어져서 다음화에 계속