AI시대에 꼭 필요한 하네스 엔지니어링 알아보기

AI 코딩 에이전트를 써본 사람이라면 비슷한 장면을 한 번쯤 겪어요.
처음엔 똑똑해 보이는데, 조금만 일이 길어지면 맥락을 놓치고, 엉뚱한 파일을 건드리고, 테스트를 안 해본 채 “끝났습니다”라고 말하죠.

많은 팀이 여기서 모델 성능만 탓합니다. 그런데 최근 여러 글이 공통으로 말하는 건 조금 달라요. 문제는 모델만이 아니라, 모델이 일하는 환경 전체에 있다는 겁니다. 이 환경을 설계하는 일이 바로 하네스 엔지니어링이에요.

쉽게 말하면 이렇습니다.

좋은 AI 에이전트는 좋은 모델만으로 만들어지지 않아요.
좋은 도구, 좋은 문서, 좋은 검증 흐름, 좋은 작업 환경이 함께 있어야 실제로 일합니다.

하네스 엔지니어링은 무엇인가

가장 단순하게 정의하면, 모델 바깥의 모든 것을 설계하는 일이에요.

LangChain은 이를 “Agent = Model + Harness”라고 설명해요. 모델이 지능이라면, 하네스는 그 지능이 실제 일로 이어지게 만드는 장치입니다. 시스템 프롬프트, 도구, 파일 시스템, 브라우저, 샌드박스, 검증 루프, 서브에이전트 같은 것들이 여기에 들어가요.

Mitchell Hashimoto는 더 실무적으로 말합니다. 에이전트가 같은 실수를 반복하면, 그 실수를 다시 하지 않도록 AGENTS.md를 고치거나 스크립트와 도구를 추가해야 한다는 거예요. 즉, 실패를 프롬프트로만 때우지 말고 시스템으로 고쳐라는 뜻이죠.

정리하면, 하네스 엔지니어링은 이런 질문에 답하는 작업입니다.

에이전트는 어떤 문서를 먼저 읽어야 할까
어떤 도구를 쓸 수 있어야 할까
어디까지 수정할 수 있어야 안전할까
작업이 길어질 때 이전 상태를 어떻게 기억할까
“완료”를 누가, 어떤 기준으로 판정할까

왜 지금 하네스 엔지니어링이 중요할까

예전에는 AI를 “질문하면 답해주는 챗봇”으로 많이 썼어요.
하지만 지금은 점점 더 긴 작업을 맡기고 있어요.

버그 수정
기능 개발
문서 정리
코드 리뷰 반영
배포 전 검증
반복 운영 작업

문제는 이런 일들이 한 번의 답변으로 끝나지 않는다는 점입니다.
Anthropic은 긴 작업을 하는 에이전트의 핵심 문제를 이렇게 설명해요. 에이전트는 여러 세션에 걸쳐 일해야 하는데, 새 세션이 시작되면 이전 기억이 없습니다.

사람으로 치면, 매일 새로운 개발자가 출근하는데 어제 누가 뭘 했는지 전혀 모르는 상태와 비슷해요. 당연히 생산성이 떨어지고, 같은 실수를 반복하게 됩니다.

그래서 하네스가 필요해요.
AI가 잘 생각하게 만드는 게 아니라, AI가 일을 이어서 잘하게 만드는 구조가 필요해진 겁니다.

좋은 모델보다 좋은 작업장이 더 중요해지는 순간

하네스 엔지니어링이 주목받는 이유는 단순해요.
같은 모델이어도 하네스가 바뀌면 성능이 꽤 달라지기 때문입니다.

LangChain은 같은 모델을 유지한 채 하네스만 바꿔서 코딩 벤치마크 성능을 크게 끌어올렸다고 말해요. OpenAI도 Codex 기반 개발 흐름에서, 사람이 직접 코드를 치기보다 에이전트가 문서와 도구를 읽고 PR까지 이어가게 만드는 방식으로 생산성을 높였다고 설명합니다.

이 말은 꽤 중요해요.

앞으로 경쟁력은 “어떤 모델을 쓰느냐”만이 아니라
“그 모델이 일하는 환경을 얼마나 잘 설계했느냐”에서 갈릴 가능성이 큽니다.

하네스는 구체적으로 무엇으로 이루어질까

1. 짧고 정확한 안내 문서

많은 팀이 처음엔 거대한 AGENTS.md 하나로 모든 규칙을 넣으려 해요.
그런데 OpenAI는 이 방식이 잘 안 됐다고 말합니다. 문서가 너무 길면 중요한 정보가 묻히고, 오래될수록 신뢰도도 떨어지기 때문이죠.

그래서 나온 방식은 이거예요.

AGENTS.md는 짧은 안내서만 둔다
자세한 내용은 docs/ 아래 구조화한다
에이전트는 안내서를 통해 필요한 문서만 찾아가게 한다

비유하면, 백과사전을 통째로 들려주는 게 아니라 지도와 목차를 먼저 주는 방식입니다.

2. 파일 시스템과 Git

LangChain은 파일 시스템을 가장 핵심적인 하네스 요소 중 하나로 봐요.
이유는 간단합니다.

작업 중간 결과를 저장할 수 있고
긴 맥락을 파일로 넘길 수 있고
다음 세션이 이전 상태를 이어받을 수 있고
여러 에이전트와 사람이 같은 작업 공간에서 협업할 수 있기 때문이에요

Git도 중요합니다.
무엇이 바뀌었는지 추적하고, 잘못되면 되돌리고, 새로 온 에이전트가 최근 변경사항을 빠르게 파악할 수 있으니까요.

3. 실행 도구와 샌드박스

모델은 원래 텍스트를 입력받아 텍스트를 내보내는 존재예요.
코드를 실행하거나, 패키지를 설치하거나, 브라우저를 열어 UI를 검증하는 건 모델 자체 기능이 아닙니다. 하네스가 붙여준 능력이죠.

그래서 좋은 하네스에는 보통 이런 게 들어갑니다.

bash 같은 범용 실행 도구
테스트 러너
브라우저 자동화
로그 조회
스크린샷
격리된 샌드박스 환경

이 도구들이 있어야 에이전트가 “생각만 하는 존재”가 아니라 직접 확인하고 고치는 존재가 돼요.

4. 메모리와 최신 정보 접근

에이전트는 컨텍스트 창 밖의 일을 저절로 기억하지 못합니다.
그래서 중요한 규칙, 프로젝트 히스토리, 최근 작업 상태를 파일로 남기고 다음 세션에 다시 읽게 해야 해요.

또 모델은 학습 시점 이후의 최신 정보를 모를 수 있으니, 웹 검색이나 외부 컨텍스트 도구도 필요합니다. 라이브러리 버전, 최신 문서, 현재 상태 같은 건 하네스가 공급해줘야 하죠.

5. 검증 루프

Mitchell Hashimoto가 특히 강조한 부분이 바로 이거예요.
에이전트가 틀렸는지 빨리 알 수 있게 해야 한다는 것.

예를 들면:

테스트를 자동으로 돌린다
UI 스크린샷을 비교한다
lint와 구조 검사기를 둔다
실패 로그를 다시 에이전트에게 보여준다

좋은 하네스는 에이전트가 실수했을 때 “누군가 나중에 발견하는 구조”가 아니라, 작업 중 바로 틀렸다고 알려주는 구조를 만듭니다.

긴 작업에서는 왜 더 중요할까

하네스 엔지니어링이 특히 빛나는 곳은 장기 실행 작업이에요.

Anthropic은 긴 작업용 하네스를 위해 두 가지 역할을 제안합니다.

첫 실행에서 환경을 세팅하는 초기화 에이전트
이후 세션마다 한 걸음씩 전진하는 코딩 에이전트

이 구조의 핵심은 “한 번에 다 하려 하지 않는 것”입니다.

초기화 단계에서:

init.sh 같은 실행 스크립트를 만들고
진행 로그 파일을 만들고
기능 목록을 JSON으로 정리해두고
이후 세션이 읽어야 할 발판을 마련합니다

그 다음 코딩 에이전트는 매 세션마다:

현재 디렉터리와 상태를 확인하고
진행 로그와 git 기록을 읽고
기능 목록에서 하나만 골라 작업하고
끝나면 진행 상황을 남깁니다

이건 사실 사람 팀의 좋은 작업 습관과 닮아 있어요.
즉, 하네스 엔지니어링은 AI에게 마법을 거는 일이 아니라, 좋은 팀의 일하는 방식을 시스템으로 옮기는 일에 가깝습니다.

스킬, 서브에이전트, 훅은 왜 자꾸 등장할까

최근 글들에서 자주 나오는 단어가 있어요.
skills, sub-agents, hooks입니다.

이것도 결국 한 가지 문제를 해결하려는 장치예요.
컨텍스트를 아끼면서도 필요한 능력은 쓰게 하자는 것.

HumanLayer는 모든 도구와 지식을 처음부터 다 시스템 프롬프트에 밀어 넣으면 오히려 성능이 떨어진다고 말합니다. 그래서 필요한 순간에만 특정 지식 묶음을 불러오는 스킬이 중요해져요. 이를 “progressive disclosure”, 즉 점진적 공개라고 설명합니다.

서브에이전트도 비슷해요.
역할놀이용 페르소나보다 중요한 건 컨텍스트 분리입니다. 어떤 하위 작업을 별도 세션으로 보내면, 부모 에이전트는 중간 과정을 다 들고 있지 않아도 되거든요.

훅은 더 결정적입니다.
예를 들어 작업이 끝났다고 하면 자동으로 테스트를 돌리고, 실패하면 다시 작업하도록 루프를 거는 식이죠. 이건 프롬프트보다 훨씬 강한 제어 방식입니다.

결국 하네스 엔지니어링은 “AI를 덜 믿는 기술”이기도 하다

여기서 오해하면 안 되는 부분이 있어요.
하네스 엔지니어링은 AI를 더 믿기 위한 기술이 아니라, 오히려 AI를 무작정 믿지 않기 위한 기술이기도 합니다.

좋은 하네스는 이런 전제를 깔고 설계돼요.

모델은 맥락을 놓칠 수 있다
모델은 성급하게 완료 판정을 내릴 수 있다
모델은 규칙을 잘못 일반화할 수 있다
모델은 긴 출력 속에서 스스로 흔들릴 수 있다

그래서 좋은 팀은 “모델이 알아서 하겠지”라고 생각하지 않아요.
대신 모델이 실패할 지점을 예측하고, 그 실패를 줄이는 구조를 만듭니다.

이 관점이 중요합니다.
하네스 엔지니어링은 AI를 찬양하는 분야가 아니라, AI의 불안정함을 실무적으로 다루는 분야에 더 가깝습니다.

실무자는 어디서부터 시작하면 될까

처음부터 거창하게 만들 필요는 없어요.
오히려 아래 순서가 현실적입니다.

1. 에이전트가 자주 하는 실수를 적는다

예:

테스트 안 하고 끝났다고 말함
잘못된 명령어를 반복 실행함
프로젝트 규칙을 자꾸 어김
너무 큰 범위를 한 번에 건드림

2. 실수 하나당 대응책 하나를 만든다

예:

AGENTS.md에 짧은 규칙 추가
자주 쓰는 검증 스크립트 추가
UI 확인용 브라우저 흐름 추가
작업 종료 전에 테스트를 강제하는 훅 추가

3. 문서를 “설명서”가 아니라 “지도”로 바꾼다

짧은 안내 문서
구조화된 상세 문서
최신 상태가 남는 진행 로그
기능 목록과 완료 기준

4. 완료의 기준을 인간 감각에서 시스템 기준으로 옮긴다

“대충 된 것 같음”이 아니라

테스트 통과
브라우저 확인 완료
기능 목록 업데이트
로그 이상 없음
같은 식으로요.

이 네 단계만 해도, 에이전트 체감 성능은 꽤 달라질 가능성이 큽니다.

앞으로 더 중요해질 이유

앞으로 모델은 더 좋아질 거예요.
계획, 추론, 코드 작성, 자기 검토 능력도 계속 개선되겠죠.

그런데 여러 글은 공통으로 말합니다.
모델이 좋아져도 하네스의 중요성은 사라지지 않을 가능성이 큽니다.

왜냐하면 실제 업무는 늘 환경 속에서 일어나기 때문이에요.

회사마다 코드베이스가 다르고
문서 구조가 다르고
보안 정책이 다르고
검증 방식이 다르고
협업 흐름이 다르기 때문입니다

즉, 모델이 아무리 좋아져도 우리 팀의 현실에 맞게 연결하는 작업은 여전히 남습니다. 그 연결부가 바로 하네스예요.

마무리

하네스 엔지니어링은 거창한 새 유행어처럼 들릴 수 있어요.
하지만 본질은 의외로 단순합니다.

AI가 더 똑똑해지길 기다리는 대신,
AI가 실수하지 않게 일터를 설계하는 것.

좋은 에이전트는 좋은 프롬프트 하나에서 나오지 않아요.
좋은 문서, 좋은 도구, 좋은 검증, 좋은 작업 흐름, 좋은 기록 습관에서 나옵니다.

그래서 AI 시대에 중요한 사람은 모델을 가장 잘 쓰는 사람만이 아닐 수 있어요.
모델이 잘 일할 수 있는 환경을 설계하는 사람, 즉 하네스를 만드는 사람이 점점 더 중요해질 가능성이 큽니다.