KG
목록으로 돌아가기
ETC

하네스 엔지니어링

AI 에이전트가 실제 개발 업무를 끝까지 수행하도록 만드는 하네스 엔지니어링 개념 정리

2026년 4월 1일 7분 읽기1368 단어
AI
Agent
Codex
Harness Engineering

하네스 엔지니어링이란 무엇이고, 왜 지금 개발자에게 중요한가

AI 코딩 도구를 조금이라도 써본 개발자라면 한 번쯤 이런 경험을 해봤을 것이다. 처음에는 꽤 그럴듯한 결과를 내놓지만, 작업이 길어질수록 맥락을 놓치거나, 이미 했던 실수를 반복하거나, “완료했다”고 했는데 실제로는 제대로 동작하지 않는 경우 말이다.

이런 문제를 해결할 때 최근 자주 언급되는 개념이 바로 하네스 엔지니어링(Harness Engineering) 이다. 이 개념은 단순히 프롬프트를 잘 쓰는 방법이 아니라, AI 에이전트가 제대로 일할 수 있는 작업 환경 전체를 설계하는 방법에 가깝다. OpenAI는 2026년 공개한 글에서 하네스 엔지니어링을 Codex 같은 에이전트가 실제 제품 개발을 수행할 수 있도록 만드는 핵심 접근으로 설명했고, Anthropic도 장시간 작업을 수행하는 에이전트에서 하네스 설계가 매우 중요하다고 정리했다. (OpenAI)

왜 이 개념이 필요한가

AI 모델은 질문에 답하거나 코드를 생성하는 데는 강하지만, 실제 개발 업무는 그보다 훨씬 복잡하다. 현실의 개발은 단순히 코드를 한 번 생성하는 것으로 끝나지 않는다. 기존 코드를 읽고, 프로젝트 구조를 파악하고, 필요한 도구를 실행하고, 테스트를 돌리고, 실패 원인을 확인하고, 다음 작업을 위해 상태를 남겨야 한다. LangChain은 최근 글에서 하네스를 “모델이 아닌 모든 것”이라고 설명하며, 에이전트가 제대로 동작하려면 상태 관리, 도구 실행, 피드백 루프, 제약 조건 같은 요소가 함께 있어야 한다고 정리했다. (LangChain Blog)

특히 작업 시간이 길어질수록 이 문제는 더 크게 드러난다. Anthropic은 장시간 실행되는 에이전트를 다루는 글에서, 컨텍스트가 길어지면 에이전트가 이전 작업을 잊거나 현재 상태를 잘못 이해할 수 있다고 설명한다. 그래서 단순히 더 좋은 모델을 쓰는 것만으로는 부족하고, 에이전트가 상태를 이어받고 스스로 확인할 수 있는 구조가 필요하다고 강조한다. (Anthropic)

결국 하네스 엔지니어링이 필요한 이유는 단순하다. AI가 “답변”을 잘하게 만드는 것이 아니라, 실제 업무를 끝까지 수행하게 만들기 위해서다. OpenAI 역시 Codex를 활용한 실제 개발 경험을 설명하면서, 핵심은 모델 자체보다도 에이전트가 일할 수 있는 환경을 설계하는 데 있었다고 밝혔다. (OpenAI)

개념 설명

하네스 엔지니어링은 쉽게 말하면 다음과 같다.

AI 에이전트가 안정적으로 일할 수 있도록, 주변 시스템과 작업 환경을 설계하는 것

여기서 말하는 “주변 시스템”에는 생각보다 많은 것이 포함된다. 예를 들어 시스템 프롬프트, 프로젝트 규칙 문서, 도구 호출 방식, 테스트 스크립트, 파일 구조, 작업 로그, 진행 상태 파일, 검증 루프, 훅, 샌드박스 환경 등이 모두 하네스의 일부가 될 수 있다. LangChain은 이를 두고 “Agent = Model + Harness”라고 정리하며, 모델 혼자서는 에이전트가 아니고, 하네스를 통해 비로소 실제 일을 수행하는 에이전트가 된다고 설명한다. (LangChain Blog)

즉, 하네스 엔지니어링은 “프롬프트를 더 길게 쓰는 방법”이 아니다. 오히려 모델이 자주 틀리는 부분은 구조로 보완하고, 반복되는 확인 작업은 도구로 자동화하고, 긴 작업은 상태 파일과 분할된 작업 단위로 이어가게 만드는 방식에 더 가깝다. OpenAI의 관련 글들도 Codex가 단순히 텍스트를 생성하는 것이 아니라, 도구를 실행하고, 작업 중간 상태를 주고받고, 실제 개발 흐름 안에서 동작하도록 구성되어 있음을 보여준다. (OpenAI)

동작 원리

하네스 엔지니어링은 보통 몇 가지 원리로 작동한다.

첫 번째는 상태를 남기는 것이다. 에이전트는 사람처럼 자연스럽게 이전 작업을 완벽히 기억하지 못한다. 그래서 긴 작업에서는 현재 어디까지 진행했는지, 어떤 이슈가 있었는지, 다음에 무엇을 해야 하는지를 파일로 남겨두는 방식이 중요해진다. Anthropic은 장기 작업용 하네스 설계에서 초기화 스크립트와 진행 기록 파일을 활용해, 새 세션이 시작되어도 이전 상태를 빠르게 이어받을 수 있게 했다고 설명한다. (Anthropic)

두 번째는 작업을 잘게 나누는 것이다. “기능 하나 만들어줘”처럼 큰 단위의 요청은 에이전트가 중간에 방향을 잃기 쉽다. 그래서 먼저 작업 목록을 정의하고, 그 목록을 기준으로 한 단계씩 수행하도록 만드는 방식이 효과적이다. Anthropic은 기능 목록과 산출물 파일을 활용해 긴 작업을 나누고, 각 세션이 이를 기반으로 다음 단계를 수행하도록 설계했다고 설명한다. (Anthropic)

세 번째는 직접 검증하게 만드는 것이다. 에이전트가 “완성했습니다”라고 말하는 것과 실제로 동작하는 것은 다르다. OpenAI는 Codex가 코드 생성에 그치지 않고, 도구를 실행하고, 작업 진행 상황을 스트리밍하고, 실제 환경에서 검증할 수 있도록 App Server와 실행 환경을 설계했다고 설명한다. 이것이 중요한 이유는, 에이전트가 단순 생성기가 아니라 실행-확인-수정 루프 안에서 작동하게 되기 때문이다. (OpenAI)

간단한 예시

예를 들어 Next.js와 NestJS를 함께 사용하는 프로젝트에서 로그인 기능을 AI 에이전트에게 맡긴다고 가정해 보자.

단순하게는 이렇게 요청할 수 있다.

로그인 기능 만들어줘.

하지만 이렇게만 주면 에이전트는 프로젝트 구조를 임의로 해석하거나, 팀 규칙과 다른 방식으로 구현하거나, 테스트 없이 작업을 끝냈다고 판단할 수 있다.

그래서 하네스를 붙이면 보통 다음과 같은 구조가 된다.

# AGENTS.md

- 패키지 매니저는 pnpm만 사용한다.
- API 서버는 packages/api 에서 수정한다.
- 웹 화면은 packages/web 에서 수정한다.
- 인증 관련 작업 전 기존 auth 모듈 구조를 먼저 확인한다.
- DTO, validation, response format 규칙을 반드시 지킨다.
- 작업 후 lint, unit test, e2e test를 실행한다.
- 실패한 항목이 있으면 progress.md에 기록한다.

그리고 작업 진행 파일도 함께 둔다.

# progress.md

## 2026-04-01
- 로그인 API 엔드포인트 초안 작성
- JWT 발급 처리 추가
- 웹 로그인 폼 연결 중
- 다음 작업: 쿠키 저장 정책 결정, e2e 테스트 보완

이렇게 하면 에이전트는 단순히 코드를 “생성”하는 것이 아니라, 어디를 수정해야 하는지, 어떤 규칙을 따라야 하는지, 무엇을 검증해야 하는지, 다음 세션에 무엇을 넘겨야 하는지까지 함께 인식하게 된다.

바로 이런 구조가 하네스 엔지니어링의 실전 예시라고 볼 수 있다. Anthropic이 설명한 장기 작업용 상태 관리 방식이나, OpenAI가 설명한 실행 환경 중심 접근도 결국 같은 방향을 가리킨다. (OpenAI)

장점

하네스 엔지니어링의 가장 큰 장점은 AI 활용이 단순한 “코드 자동완성” 수준을 넘어선다는 점이다. 에이전트가 프로젝트 구조와 규칙을 이해하고, 테스트와 검증 루프 안에서 움직이기 시작하면 사람이 직접 모든 코드를 쓰지 않아도 꽤 많은 작업을 위임할 수 있다. OpenAI는 Codex를 실제 제품 개발 워크플로에 붙이면서 에이전트가 반복적인 구현과 검증을 수행할 수 있도록 만들었고, 이런 구조가 생산성을 크게 끌어올리는 핵심이라고 설명했다. (OpenAI)

또 하나의 장점은 긴 작업에서 안정성이 높아진다는 점이다. 짧은 질의응답에서는 괜찮아 보이던 모델도, 여러 단계에 걸친 실제 개발 작업에서는 쉽게 맥락을 잃는다. 하지만 상태 파일, 초기화 스크립트, 작업 단위 분리 같은 하네스가 있으면 작업을 이어받는 품질이 눈에 띄게 좋아질 수 있다. Anthropic의 장기 작업 하네스 사례는 바로 이 점을 보여준다. (Anthropic)

마지막으로, 좋은 하네스는 팀 자산으로 남는다. 프롬프트 하나는 대화가 끝나면 사라지기 쉽지만, AGENTS.md, 스크립트, 훅, 테스트 규칙, 진행 파일 같은 것은 저장소 안에 남아 다음 작업에서도 재사용할 수 있다. 그래서 하네스 엔지니어링은 일회성 팁이 아니라, AI 시대의 개발 운영 방식에 더 가깝다. (OpenAI)

주의할 점

물론 하네스 엔지니어링이 만능은 아니다. 가장 먼저 주의할 점은, 프롬프트를 길게 쓴다고 하네스가 되는 것은 아니라는 점이다. 정보가 많다고 항상 좋은 것도 아니다. 오히려 너무 많은 설명은 컨텍스트를 복잡하게 만들어 에이전트가 중요한 규칙을 놓치게 만들 수 있다. LangChain과 Anthropic의 글 모두, 긴 작업일수록 상태 관리와 정보 분리가 중요하다는 점을 강조한다. (Anthropic)

또한 검증이 없는 자동화는 위험하다. 에이전트가 만든 코드가 그럴듯해 보여도, 실제로는 실행되지 않거나 기존 기능을 깨뜨릴 수 있다. 그래서 테스트, 로그 확인, 실행 환경 검증 같은 장치가 반드시 함께 있어야 한다. OpenAI가 App Server, 컨테이너 환경, 도구 실행 흐름을 강조한 이유도 여기에 있다. (OpenAI)

무엇보다도 프로젝트에 맞는 방식으로 설계해야 한다. 모든 팀이 똑같은 하네스를 쓸 수는 없다. 어떤 프로젝트는 엄격한 테스트 중심이 더 중요할 수 있고, 어떤 프로젝트는 작업 이력과 산출물 전달 구조가 더 중요할 수 있다. 결국 하네스 엔지니어링은 정답 하나를 외우는 개념이 아니라, 우리 팀과 프로젝트에 맞는 작업 환경을 계속 다듬어 가는 과정이라고 보는 편이 맞다. (OpenAI)

정리

하네스 엔지니어링은 AI를 더 똑똑하게 만드는 기술이 아니다. 대신 AI가 실제 개발 업무를 더 안정적으로 수행할 수 있게 만드는 설계 방식이다.

이 개념이 중요한 이유는 분명하다. 이제 개발자에게 필요한 것은 단순히 “좋은 모델을 쓰는 법”이 아니라, 그 모델이 제대로 일할 수 있는 환경을 만드는 법이기 때문이다.

앞으로 AI 에이전트를 프로젝트에 제대로 도입하고 싶다면, 프롬프트만 고민할 것이 아니라 다음과 같은 질문을 함께 던져야 한다.

  • 이 에이전트는 어디까지 작업 상태를 기억할 수 있는가?
  • 실패했을 때 다음 세션에 무엇을 남길 것인가?
  • 팀 규칙과 프로젝트 구조를 어떻게 전달할 것인가?
  • 코드 생성 이후 실제 동작 여부는 무엇으로 검증할 것인가?

이 질문들에 대한 답을 시스템으로 만들기 시작하는 순간, 비로소 우리는 단순한 AI 사용을 넘어 하네스 엔지니어링을 시작했다고 볼 수 있다. (OpenAI)

참고자료

  • OpenAI, Harness engineering: leveraging Codex in an agent-first world (OpenAI)
  • OpenAI, Unlocking the Codex harness: how we built the App Server (OpenAI)
  • OpenAI Developers, Run long horizon tasks with Codex (OpenAI 개발자)
  • Anthropic, Effective harnesses for long-running agents (Anthropic)
  • Anthropic, Harness design for long-running application development (Anthropic)
  • LangChain, The Anatomy of an Agent Harness (LangChain Blog)
  • LangChain, How Middleware Lets You Customize Your Agent Harness (LangChain Blog)
  • 위키독스, 하네스 엔지니어링: AI 에이전트 시대, 경쟁력은 모델이 아니라 시스템 설계다 (위키독스)