AI 에이전트의 결과가 좋지 않을 때 가장 먼저 프롬프트를 고치는 경우가 많습니다. 지시를 더 길게 쓰고, 역할을 붙이고, 금지 규칙을 늘립니다. 그런데 실패 원인이 필요한 문서를 보지 못한 것이거나, 테스트 도구가 없거나, 이전 작업 상태를 잃어버린 것이라면 프롬프트 문장만 고쳐서는 해결되지 않습니다.
최근 에이전트 개발에서 자주 등장하는 두 표현이 컨텍스트 엔지니어링과 하네스 엔지니어링입니다. 간단히 나누면 이렇습니다.
- 컨텍스트 엔지니어링: 모델이 지금 무엇을 보게 할지 설계합니다.
- 하네스 엔지니어링: 모델이 어떤 루프, 도구, 상태, 검증 장치 안에서 일하게 할지 설계합니다.
둘은 겹치지만 같은 말은 아닙니다. 하네스가 필요한 정보를 골라 컨텍스트에 넣을 수 있고, 잘 설계된 컨텍스트가 있어도 하네스에 실행 도구가 없으면 일은 끝나지 않습니다.
프롬프트는 컨텍스트의 일부입니다
Anthropic은 컨텍스트 엔지니어링을 매 추론 시점에 모델에 들어갈 토큰을 선별하고 유지하는 일로 설명합니다. 여기에는 시스템 프롬프트만 들어가지 않습니다.
- 현재 사용자의 요청
- 시스템과 프로젝트 지시
- 앞선 대화와 작업 기록
- 검색해 온 문서
- 사용할 수 있는 도구 설명
- 도구가 돌려준 결과
- 메모와 압축된 인계 내용
프롬프트 엔지니어링이 지시문을 어떻게 쓰고 배열할지에 가깝다면, 컨텍스트 엔지니어링은 모델이 판단할 때 필요한 전체 정보 상태를 다룹니다.
핵심은 많이 넣는 것이 아니라 필요한 것을 남기는 것입니다. Anthropic은 컨텍스트를 한정된 자원으로 보고, 높은 신호의 정보를 가능한 작게 유지하라고 설명합니다. 에이전트가 긴 시간 일하면 도구 결과와 대화가 계속 쌓이므로 검색, 압축, 구조화된 메모가 필요해집니다.
하네스는 모델 주위의 작업 시스템입니다
하네스라는 말은 문맥에 따라 범위가 다르지만, 공개된 에이전트 사례에서 공통으로 보이는 것은 모델 호출을 실제 작업으로 연결하는 실행 구조입니다.
| 하네스 요소 | 하는 일 |
|---|---|
| 에이전트 루프 | 모델 호출과 도구 실행을 반복합니다 |
| 도구와 권한 | 파일, 브라우저, 터미널, API에서 할 수 있는 일을 정합니다 |
| 상태 저장 | 세션, 진행 상황, 산출물, 실패 기록을 남깁니다 |
| 작업 분해 | 큰 목표를 검증 가능한 작은 단위로 나눕니다 |
| 검토와 테스트 | 결과가 완료 조건을 만족하는지 확인합니다 |
| 관찰 가능성 | 로그, 화면, 지표를 에이전트와 사람이 읽게 합니다 |
| 안전 경계 | 승인, 격리, 금지 행동, 복구 방식을 정합니다 |
OpenAI의 하네스 엔지니어링 사례는 저장소 문서, 실행 계획, 로컬 테스트, 브라우저와 로그 접근, 기계적인 규칙 검사를 함께 설계했습니다. 중요한 점은 모델에게 더 열심히 하라고 말한 것이 아니라, 모델이 문제를 보고 확인하고 고칠 수 있는 환경을 만든 것입니다.
두 층은 이렇게 연결됩니다
예를 들어 에이전트가 코드 수정 작업을 한다고 가정해 보겠습니다.
하네스는 저장소를 열 수 있는 파일 도구, 테스트 명령, 작업 상태 저장소를 제공합니다. 컨텍스트 엔지니어링은 수천 개 파일을 전부 넣지 않고 현재 기능의 설계 문서, 관련 코드, 실패한 테스트 결과만 골라 모델에게 보여 줍니다.
다른 예로 고객 지원 에이전트를 생각할 수 있습니다. 하네스는 티켓을 읽고 초안을 저장하며 사람 승인을 요청하는 흐름을 담당합니다. 컨텍스트는 해당 고객의 계약, 최신 정책, 지금까지의 대화 중 답에 필요한 부분을 구성합니다.
하네스 없이 컨텍스트만 좋으면 답은 잘 써도 티켓에 저장하거나 승인을 받을 수 없습니다. 컨텍스트 없이 하네스만 좋으면 도구는 많아도 잘못된 정책을 근거로 빠르게 행동할 수 있습니다.
긴 작업에서는 상태와 컨텍스트를 분리할 필요가 있습니다
에이전트가 몇 시간 동안 일하면 모든 기록을 한 컨텍스트 창에 계속 쌓기 어렵습니다. 이때 지속 상태와 현재 작업 기억을 나누는 방식이 등장합니다.
Anthropic의 장기 실행 하네스 사례는 큰 작업을 작은 기능으로 나누고, 세션이 바뀔 때 구조화된 인계물을 남겼습니다. 생성자와 평가자 역할도 분리했습니다. 문맥이 가득 찼을 때 같은 대화를 억지로 이어가기보다 새 세션이 인계물을 읽고 다음 단위를 맡게 한 것입니다.
Managed Agents 사례에서는 전체 이벤트 기록을 세션에 지속 저장하고, 모델은 그중 필요한 구간을 골라 읽습니다. 하네스가 기록을 변환해 현재 컨텍스트에 넣을 수도 있습니다. 이것은 컨텍스트 엔지니어링이 하네스 안에서 실행되는 모습입니다.
실패 증상으로 먼저 볼 층을 고릅니다
| 실패 증상 | 먼저 볼 곳 | 확인할 질문 |
|---|---|---|
| 이미 제공한 사실을 놓침 | 컨텍스트 | 관련 자료가 들어갔나, 너무 많은 잡음에 묻혔나 |
| 오래된 규칙을 사용함 | 컨텍스트 | 최신 정본을 검색했나, 캐시가 낡았나 |
| 같은 실수를 반복함 | 컨텍스트·상태 | 실패 기록과 수정 결정을 다음 턴에 남겼나 |
| 파일을 고쳤지만 테스트하지 않음 | 하네스 | 테스트 도구와 완료 조건이 실행 루프에 있나 |
| 세션이 바뀌면 진행 상황을 잃음 | 하네스 | 지속 상태와 인계 형식이 있나 |
| 화면 문제를 재현하지 못함 | 하네스 | 실제 UI와 로그를 읽고 조작할 도구가 있나 |
| 지시가 서로 충돌함 | 컨텍스트 | 정본과 우선순위가 분명한가 |
| 위험한 행동을 바로 실행함 | 하네스 | 승인 경계와 격리가 있는가 |
한 증상이 두 층에 걸칠 수 있습니다. 같은 실수를 반복하는 이유가 실패 기록을 컨텍스트에 안 넣어서일 수도 있고, 애초에 상태를 저장하지 않는 하네스 때문일 수도 있습니다. 표는 원인을 확정하는 답이 아니라 확인 순서를 줄이는 도구입니다.
큰 지침 파일 하나가 답은 아닙니다
모든 규칙을 한 문서에 넣으면 모델이 언제나 알 수 있을 것처럼 보입니다. 실제로는 작업과 관계없는 내용이 컨텍스트를 차지하고, 오래된 규칙과 현재 규칙이 섞이기 쉽습니다.
OpenAI의 공개 사례도 큰 AGENTS.md 하나가 실패했다고 설명합니다. 대신 짧은 진입 문서를 지도처럼 두고, 설계·품질·계획 문서로 연결하며, 문서 구조와 최신성을 기계적으로 검사했습니다.
이 방식은 컨텍스트와 하네스를 함께 고칩니다. 모델은 필요한 문서만 단계적으로 읽고, 하네스는 문서가 정해진 자리에 있으며 낡지 않았는지 검사합니다.
작은 에이전트부터 고치는 순서
새 프레임워크를 먼저 만들 필요는 없습니다. 현재 에이전트가 반복해서 실패하는 작업 하나를 고르고 다음 순서로 보면 됩니다.
- 완료 조건을 한 문장으로 정합니다.
- 모델이 반드시 알아야 할 자료와 현재 들어가는 자료를 비교합니다.
- 필요한 도구가 실제로 열리고 결과를 돌려주는지 확인합니다.
- 작업 상태와 실패 기록이 다음 턴이나 다음 세션에 남는지 봅니다.
- 결과를 자동으로 확인할 테스트나 체크를 하나 붙입니다.
- 그래도 남는 실패만 지시문 수정으로 다룹니다.
이 순서를 쓰면 “프롬프트가 나빠서”라는 넓은 진단을 정보, 도구, 상태, 검증 문제로 나눌 수 있습니다.
핵심 정리
- 컨텍스트 엔지니어링은 모델이 현재 판단에 사용할 정보를 선별하고 유지하는 일입니다.
- 하네스 엔지니어링은 모델이 도구를 쓰고 상태를 남기며 결과를 검증하는 실행 시스템을 만드는 일입니다.
- 컨텍스트 관리는 하네스 안에서 구현될 수 있으므로 둘은 경쟁 용어가 아닙니다.
- 정보가 부족하거나 잡음이 많다면 컨텍스트를, 도구·상태·검증이 없다면 하네스를 먼저 봅니다.
- 장시간 작업에서는 전체 기록을 지속 상태에 두고 현재 필요한 내용만 컨텍스트로 가져오는 구조가 중요해집니다.