하네스 엔지니어링이란? AI 코딩 에이전트를 제대로 일하게 만드는 구조 설계법

"모델은 충분히 똑똑한데 결과가 왜 이 모양이지?"

클로드 코드나 챗GPT에 코딩 작업을 한 번이라도 맡겨보셨나요?

처음에는 꽤 잘 되는 것 같아요. 파일도 읽고, 코드도 척척 쓰고, 뭔가 계속 진행되는 것 같죠. 그런데 막상 결과를 보면 테스트는 다 깨져 있고, 에이전트는 "작업 완료했습니다"라고 당당하게 외치고, 실제로 동작하는 건 아무것도 없는 상황이 됩니다.

이걸 처음 경험하면 "모델이 아직 부족한가 보다"라고 생각하기 쉬운데요. 2026년 현재, 이건 모델의 문제가 아닙니다. 모델을 둘러싼 환경, 즉 '하네스(harness)'의 문제예요.

요즘 AI 개발 현장에서 가장 뜨겁게 논의되는 개념이 바로 하네스 엔지니어링이에요. 오늘은 이게 정확히 뭔지, 왜 지금 이렇게 중요해졌는지, 그리고 실무에서 어떻게 시작할 수 있는지까지 정리해 볼게요.

한 줄 정리: 좋은 모델보다 좋은 하네스가 더 중요하다.

프롬프트 엔지니어링만으로는 이제 부족한 이유

2023년부터 2024년까지는 프롬프트 엔지니어링의 전성기였어요. "어떻게 질문하느냐"가 결과를 결정한다는 인식이 퍼졌고, 실제로 단순한 작업에서는 효과가 있었죠.

그런데 2025년 중반부터 새로운 개념이 부상했습니다. 바로 컨텍스트 엔지니어링이에요. AI 에이전트가 점점 복잡한 작업을 수행하면서 단발성 프롬프트만으로는 제어가 안 된다는 걸 다들 실감하기 시작한 거죠.

그리고 2026년 2월, 더 큰 범위의 개념이 등장했습니다. 하네스 엔지니어링입니다.

프롬프트는 하네스의 한 구성 요소일 뿐이에요. 하네스는 프롬프트를 포함한 훨씬 더 넓은 시스템 설계를 다룹니다. "에이전트에게 어떻게 말할까"를 고민하는 것이 프롬프트 엔지니어링이라면, "에이전트가 제대로 일할 수밖에 없는 구조를 어떻게 만들까"를 고민하는 것이 하네스 엔지니어링입니다. 질문의 레벨 자체가 달라요.

OpenAI, Anthropic 같은 최전선 연구소들이 직접 이 개념을 정리하기 시작했고, 소프트웨어 설계 분야의 권위자 마틴 파울러(Martin Fowler)도 하네스 엔지니어링을 주제로 글을 쓰기 시작했어요. 이 정도면 이미 전문 개발자 사이에서는 필수 개념이 되어가고 있다는 신호죠.

한 줄 정리: 프롬프트 시대에서 구조 설계 시대로, 관심의 중심이 옮겨가고 있다.

하네스 엔지니어링이 정확히 뭐냐면요

하네스(harness)는 원래 말에 씌우는 마구(馬具)를 뜻하는 단어예요. AI 에이전트에 비유하면, 에이전트가 올바른 방향으로만 달리도록 제어하는 전체 구조입니다.

구글 딥마인드의 엔지니어 필립 슈미드는 이렇게 설명했어요. "AI 모델이 CPU라면, 컨텍스트 윈도우는 제한된 작업 메모리이고, 하네스는 이 모든 것을 관리하는 운영체제다." 꽤 직관적인 비유죠?

이 용어에 처음 이름을 붙인 사람은 HashiCorp 공동창립자 미첼 해시모토입니다. 2026년 2월 초 블로그에서 그는 이렇게 정의했어요. "에이전트가 실수할 때마다, 그 실수가 다시는 발생하지 않도록 엔지니어링하는 것." 단순히 "다음부터 잘해"라고 프롬프트를 고치는 게 아니라, 구조적으로 재발을 막는 시스템을 만드는 것이죠.

그리고 며칠 후 OpenAI가 "Harness engineering: leveraging Codex in an agent-first world"를 공식 발표하면서 이 개념이 업계 전체로 빠르게 퍼졌습니다.

하네스는 에이전트가 어떤 도구를 쓰고, 무엇을 참고하며, 어디서 검증을 하고, 실패하면 어떻게 복구할지, AI의 작업 전반을 아우르는 실행 환경을 구성하고 통제하는 개념이에요. 원시 LLM은 에이전트가 아닙니다. 하네스가 상태 관리, 도구 실행, 피드백 루프, 제약 조건을 부여해야 비로소 에이전트가 됩니다.

한 줄 정리: 하네스는 프롬프트를 포함한 더 큰 시스템 설계다.

가장 흔한 오해: 모델이 좋아지면 자동으로 해결되지 않나요?

이게 정말 많은 분들이 하시는 오해예요. "클로드 최신 버전이 나오면, GPT 다음 버전이 나오면 이런 문제는 자연스럽게 해결되지 않을까?" 하는 생각 말이죠.

실험 결과가 이 오해를 정확히 반박합니다.

동일한 모델에 동일한 프롬프트를 줬어요. 단 하나, 하네스가 있느냐 없느냐만 달랐습니다.

하네스가 없는 경우, 에이전트는 20분 동안 9달러(약 1만 3천 원)를 소비하고 동작하지 않는 결과물을 냈어요.

하네스를 갖춘 경우, 6시간 동안 200달러(약 28만 원)를 쓰고 실제로 플레이 가능한 게임을 만들었습니다.

모델은 똑같았습니다. 하네스만 달랐을 뿐이에요. 비용이 20배 이상 들었지만, 아무것도 없는 산출물과 실제로 동작하는 제품의 차이는 비교 자체가 안 되죠.

더 놀라운 건 LangChain의 사례예요. AI 코딩 에이전트 벤치마크에서 모델을 바꾸지 않고 하네스만 개선했더니 30위권에서 5위권으로 25단계를 뛰어올랐어요. 점수로는 52.8에서 66.5로 13.7포인트 상승이었습니다. 모델 업그레이드 없이요.

HumanLayer의 결론이 이 모든 걸 요약합니다. "모델은 아마 괜찮다. 하네스의 문제일 뿐이다."

한 줄 정리: 모델 업그레이드로 해결되지 않는다. 하네스가 바뀌어야 결과가 바뀐다.

하네스를 구성하는 5가지 핵심 요소

하네스는 크게 다섯 가지 하위 시스템으로 이루어져 있어요. 하나씩 실무 맥락에서 설명해 드릴게요.

첫 번째, 지시(Instructions)입니다. 에이전트에게 무엇을 어떤 순서로 해야 하는지 알려주는 파일 구조예요. AGENTS.md나 CLAUDE.md 같은 루트 파일이 여기에 해당해요. 하나의 거대한 파일이 아니라, 에이전트가 필요할 때 찾아서 읽을 수 있는 계층적 구조여야 합니다.

두 번째, 상태(State)입니다. 에이전트는 세션이 끊기면 이전에 무슨 일이 있었는지 기억하지 못해요. claude-progress.md 같은 진행 로그를 디스크에 저장해 두면, 다음 세션에서 정확히 이전 지점부터 이어갈 수 있습니다.

세 번째, 검증(Verification)입니다. 에이전트가 "완료했습니다"라고 말하는 건 아무 의미가 없어요. 테스트 통과, 린트 통과, 타입 체크 통과라는 실제 증거가 있어야만 완료로 인정합니다.

네 번째, 범위(Scope)입니다. 에이전트는 방치하면 너무 많은 걸 건드리거나 반대로 아무것도 마무리하지 못해요. 한 번에 딱 하나의 기능만 작업하도록 제한하고, 완료의 정의를 명확히 해두어야 합니다.

다섯 번째, 세션 생명주기(Session Lifecycle)입니다. 세션 시작 전에 환경을 초기화하고(init.sh 실행), 세션 종료 전에 다음 세션이 깨끗하게 시작할 수 있도록 커밋과 정리를 수행해요.

한 줄 정리: 하네스는 하나의 파일이 아니라 다섯 가지 역할을 하는 시스템이다.

OpenAI 엔지니어 3명이 5개월에 100만 줄을 만든 방법

2026년 2월, OpenAI가 놀라운 실험 결과를 공개했어요.

엔지니어 3명이 5개월간 코드를 단 한 줄도 직접 타이핑하지 않고, 약 100만 줄 규모의 프로덕션 애플리케이션을 만들어냈다는 겁니다. 1,500개의 풀리퀘스트(PR)를 머지하면서 엔지니어 1인당 하루 평균 3.5개의 PR을 처리했고, 수작업 대비 약 10분의 1 시간에 완성했다고 밝혔어요.

핵심은 더 똑똑한 모델을 쓴 게 아니었습니다. 이들이 집중한 건 에이전트가 실수하지 않도록 감싸는 시스템, 즉 하네스를 설계하는 일이었어요. 릴리스, 배포, 장애 발생 및 복구, 이 모든 과정이 하네스 내의 에이전트에 의해 수행됐습니다. 엔지니어의 역할은 코드를 짜는 것이 아니라 하네스를 설계하고, 의도를 명시하며, 피드백을 제공하는 것이었어요.

Gartner는 2028년까지 기업용 소프트웨어의 33%가 에이전틱 AI를 포함하고, 일상 업무 의사결정의 15%가 에이전트에 의해 자율적으로 이루어질 것으로 전망했어요. 이 흐름 속에서 하네스 없이는 안정적인 에이전트 운용이 불가능하다는 게 이미 현장에서 증명되고 있습니다.

한 줄 정리: 미래의 엔지니어링은 구문 작성이 아닌 의도 명세와 환경 설계로 전환된다.

실무에서 바로 쓸 수 있는 최소 구성 4가지

처음부터 완벽한 하네스를 만들 필요는 없어요. 가장 빠르게 효과를 확인할 수 있는 최소 출발점이 있습니다.

AGENTS.md(또는 CLAUDE.md)는 에이전트 운영 매뉴얼이에요. 어떤 명령어를 쓰고, 어떤 규칙을 따르는지 정의합니다. 처음엔 짧아도 괜찮아요. 에이전트가 같은 곳에서 반복 실패할 때 규칙을 하나씩 추가하는 방식으로 키워가면 됩니다.

init.sh는 프로젝트 시작 시 의존성 설치, 검증, 실행을 한 번에 처리하는 스크립트예요. 세션마다 환경이 달라지는 문제를 막아줍니다.

claude-progress.md는 세션마다 무슨 작업을 했는지, 검증은 통과했는지, 다음에 무엇을 해야 하는지 기록하는 파일이에요. 에이전트가 세션이 끊겨도 정확히 이전 지점부터 이어갈 수 있게 됩니다.

feature_list.json은 기능 목록과 상태(완료, 진행, 대기)를 기계가 읽을 수 있는 형태로 관리하는 파일입니다.

이 네 파일만 있어도 에이전트 세션은 훨씬 안정적으로 바뀌어요. 그리고 이것들은 전부 코드 리포지토리에 커밋되는 파일이에요. 팀원이 바뀌어도, 모델이 바뀌어도, 축적된 하네스는 그대로 남습니다. 팀 단위로 사용할수록 진가가 나타나는 이유가 바로 이거예요.

한 줄 정리: 4개 파일로 시작하고, 필요에 따라 확장하면 된다.

하네스는 개발자만의 이야기가 아니에요

이 개념이 처음엔 개발자들 사이에서 시작됐지만, 사실 훨씬 더 넓은 이야기입니다.

기획자, 창업자, PM, 데이터 분석가, 마케터도 마찬가지예요. AI에게 일을 맡기려면 작업 기준, 검증 방법, 보고 방식, 권한 범위를 설계해야 합니다. 이게 바로 하네스 엔지니어링의 사고방식이에요.

보험 업계나 헬스케어, B2B SaaS 같은 현장에서도 마찬가지입니다. 에이전트에게 기능 개발, 문서 작성, 테스트를 맡기는 상황이 빠르게 현실화되고 있어요. 이때 하네스가 없으면 에이전트는 계속해서 사람이 수습해야 하는 반쪽짜리 결과물을 생산합니다.

단일 에이전트 수준에서는 잘 작동하다가도 여러 에이전트를 조합하거나 서비스 규모가 커지는 순간 작동이 불안정해지는 경험, 한 번쯤은 있으시죠? 하네스는 바로 이 불안정성을 구조적으로 해결합니다.

개발자의 역할도 "모든 코드를 직접 치는 사람"에서 "AI 에이전트 팀이 제대로 일하도록 환경을 만드는 사람"으로 이동하고 있어요. 이 변화를 먼저 체득한 사람이 AI 시대의 진짜 경쟁력을 갖게 됩니다.

한 줄 정리: 하네스 엔지니어링은 AI 시대의 협업 설계다.

마무리

하네스 엔지니어링, 처음 들으면 낯선 개념이지만 핵심은 간단합니다.

AI 에이전트가 실패하는 이유는 대부분 모델이 약해서가 아니에요. 모델을 둘러싼 환경이 없거나 부실해서입니다. 하네스는 지시, 상태, 검증, 범위, 세션 생명주기라는 다섯 가지 하위 시스템으로 구성돼요. 그리고 최소 4개 파일(AGENTS.md, init.sh, claude-progress.md, feature_list.json)만으로도 에이전트 세션 안정성은 극적으로 올라갑니다.

다음에 코딩 에이전트에게 작업을 맡길 때, "어떻게 프롬프트를 쓸까"보다 "에이전트가 제대로 일할 환경이 갖춰져 있는가"를 먼저 물어보세요. 그 질문 하나가 결과물의 품질을 통째로 바꿉니다.