하네스 엔지니어링의 기초
하네스 엔지니어링의 정의, 범위, 그리고 왜 프롬프트보다 시스템 설계가 중요한지 설명합니다.
핵심 요약
- 하네스 엔지니어링은 에이전트가 무엇을 볼 수 있고 어떤 기준으로 판단하며 어디서 멈추고 어떻게 검증받는지를 설계하는 기술입니다.
- 작업이 길어질수록 병목은 프롬프트 → 컨텍스트 → 하네스 → 플랫폼으로 옮겨가고, 문제는 모델이 멍청해서가 아니라 작업장 자체가 정리되지 않은 탓인 경우가 많습니다.
- 프롬프트·컨텍스트 엔지니어링이 "어떻게 말할까/무엇을 보여줄까"라면 하네스 엔지니어링은 "어떻게 일하게 만들까"로, 역할 분리·평가 루프·승인 흐름·운영 규율까지 포함합니다.
- 2026년 OpenAI Harness Engineering, Toss, Anthropic auto mode·Managed Agents 글을 거치며 하네스는 개인 루틴이 아니라 팀이 승인·격리·도구 접근·감사 로그를 배포하는 인프라로 이동했습니다.
- 더 강한 모델이 나오면 세부 구현은 단순해질 수 있어도 작업 환경·평가 기준·승인 구조·운영 루프의 필요 자체는 사라지지 않습니다.
하네스 엔지니어링은 에이전트에게 "무엇을 하라"고 말하는 기술이라기보다, 에이전트가 무엇을 볼 수 있고, 어떤 기준으로 판단하며, 어디서 멈추고, 어떻게 검증받는지를 설계하는 기술에 가깝습니다.
작업이 길어질수록 병목은 이동한다
| 작업 형태 | 가장 큰 병목 | 필요한 것 |
|---|---|---|
| 한 번의 답변 | 표현 방식 | 프롬프트 |
| 여러 파일 탐색 | 정보 노출 | 컨텍스트 |
| 몇 시간짜리 작업 | 계획, 검증, 승인 | 하네스 |
| 여러 팀 반복 사용 | 배포, 표준화, 운영 | 플랫폼화 |
왜 프롬프트만으로는 부족한가
짧은 작업에서는 프롬프트 품질이 체감 성능을 좌우합니다. 하지만 작업 시간이 길어지고 리포지터리가 커지고 변경 범위가 넓어질수록 병목은 다른 곳에서 생깁니다.
- 필요한 맥락이 리포 안에 없어서 에이전트가 추론할 재료가 부족함
- 완료 기준이 모호해서 스스로 "끝났다"고 착각함
- 검증 루프가 약해서 겉보기로만 동작하는 결과를 만들기 쉬움
- 오래된 문서와 규칙이 뒤섞여서 stale context가 누적됨
- 사람의 승인 지점이 정의되지 않아 위험한 변경과 안전한 변경을 구분하지 못함
결국 문제는 모델이 멍청해서가 아니라 모델이 일하는 작업장 자체가 정리되어 있지 않아서 생기는 경우가 많습니다.
무엇이 바뀌었기에 하네스가 전면으로 올라왔는가
하네스는 무엇을 포함하는가
하네스는 보통 아래를 함께 다룹니다.
| 영역 | 예시 |
|---|---|
| 작업 환경 | 리포 구조, AGENTS.md, 설계 문서, llms.txt, 스키마, 실행 계획 |
| 실행 경계 | 읽기/쓰기 권한, 네트워크 허용 범위, 승인 정책, 보호 브랜치 |
| 평가 기준 | 테스트, lint, 타입체크, 브라우저 QA, 품질 점수표, 완료 정의 |
| 오케스트레이션 | planner/generator/evaluator, reviewer, QA, release 역할 분리 |
| 운영 루프 | 업데이트 로그, 문서 가드닝, 드리프트 탐지, 실패 복구 |
프롬프트 엔지니어링, 컨텍스트 엔지니어링과의 관계
| 개념 | 초점 | 질문 |
|---|---|---|
| 프롬프트 엔지니어링 | 한 번의 호출 품질 | "어떻게 말할까?" |
| 컨텍스트 엔지니어링 | 필요한 정보 노출 | "무엇을 보여줄까?" |
| 하네스 엔지니어링 | 작업 전체 시스템 | "어떻게 일하게 만들까?" |
컨텍스트 엔지니어링은 하네스의 일부입니다. 다만 하네스는 거기서 멈추지 않고 역할 분리, 평가 루프, 승인 흐름, 운영 규율까지 포함합니다.
경계가 헷갈릴 때
컨텍스트 엔지니어링은 대개 "입력"의 문제이고, 하네스 엔지니어링은 "작업 시스템"의 문제입니다. AGENTS.md, docs, review loop, browser QA, updates log가 같이 얽히기 시작하면 이미 하네스 영역입니다.
왜 지금 더 중요해졌는가
최근 코딩 에이전트는 더 긴 작업을 수행하고, 브라우저와 쉘, 로그, 배포 시스템까지 다룹니다. 그래서 "한 번 잘 답하게 만드는 것"보다 "몇 시간 동안 방향을 잃지 않게 만드는 것"이 더 중요한 문제가 됐습니다.
OpenAI는 2026년 2월 11일 글에서 agent-readable repo, 짧은 AGENTS.md, 구조화된 docs/, 브라우저와
관측성 접근, 그리고 문서 가드닝을 강조했습니다. Anthropic은 2026년 3월 24일 글에서 긴 작업에서
planner와 evaluator가 언제 유의미한지, 그리고 모델이 좋아질수록 하네스도 단순해지지만
사라지지는 않는다고 설명했습니다.
Anthropic의 2026년 3월 25일 auto mode 글과 4월 8일 Managed Agents 글은 이 관점을 한 단계 더 밀어붙입니다. 권한 승인을 단순 팝업 UX가 아니라 input-layer prompt-injection probe와 output-layer transcript classifier로 보는 접근, 그리고 session, harness, sandbox를 서로 다른 장애·보안·확장 경계로 나누는 접근이 등장했습니다. 핵심은 "더 자율적으로 실행하게 하자"가 아니라 무엇을 자동 승인할지, 무엇을 classifier에 맡길지, 어떤 credential이 sandbox에 절대 닿지 않아야 하는지를 시스템 인터페이스로 고정하는 것입니다.
2026년 4~5월에는 이 관점이 더 구체적인 제품/플랫폼 primitive로 내려왔습니다. OpenAI Agents SDK는
model-native harness, native sandbox execution, MCP, skills, AGENTS.md, shell, apply_patch, memory,
compaction을 공통 기반으로 묶기 시작했고, 5월에는 TypeScript에서도 sandbox agent와 open-source harness
흐름을 공개했습니다. Codex 쪽에서는 remote connection, hooks, programmatic access token, Secure MCP
Tunnel, OpenAI Developers plugin 같은 운영·배포 기능이 더해지며, 하네스가 "한 사람의 로컬 프롬프트 루틴"이
아니라 팀이 승인, 격리, 도구 접근, 감사 로그, provider setup을 배포하는 인프라에 가까워졌습니다.
핵심은 같습니다.
핵심 관찰
더 강한 모델이 나오면 하네스의 세부 구현은 단순해질 수 있습니다. 하지만 작업 환경, 평가 기준, 승인 구조, 운영 루프 자체의 필요는 사라지지 않습니다.
2026년 기준 주요 자료들이 던진 문제
| 날짜 | 자료 | 이 책이 가져간 질문 |
|---|---|---|
| 2026-02-11 | OpenAI Harness Engineering | 리포와 문서를 어떻게 에이전트 친화적으로 만들 것인가 |
| 2026-02-26 | Toss 하네스 글 | 개인의 활용 감각을 어떻게 팀의 실행 시스템으로 내릴 것인가 |
| 2026-03-24 | Anthropic 하네스 글 | 어떤 scaffolding이 실제로 load-bearing인지 어떻게 판단할 것인가 |
| 2026-03-25 | Anthropic Claude Code auto mode | 승인 피로를 줄이면서도 위험 행동을 어떻게 분류·차단할 것인가 |
| 2026-04-08 | Anthropic Managed Agents | session, harness, sandbox를 어떤 안정적 인터페이스로 분리할 것인가 |
| 2026-04-15 | OpenAI Agents SDK update | model-native harness와 sandbox execution을 어떻게 표준 primitive로 볼 것인가 |
| 2026-05-05 | Anthropic financial agents | 도메인별 agent template이 skill, connector, subagent, approval flow를 어떻게 패키징하는가 |
| 2026-05-06 | OpenAI API changelog | TypeScript sandbox agent와 open-source harness가 팀 하네스 선택지를 어떻게 넓히는가 |
| 2026-05-07 | OpenAI Developers plugin for Codex | provider setup, API key 생성, troubleshooting을 plugin 배포 surface로 볼 수 있는가 |
| 2026-05-14 | Codex remote / hooks update | 긴 작업의 승인·방향 전환·검증을 어떻게 여러 장치와 환경에 걸쳐 유지할 것인가 |
| 2026-05-19 | Secure MCP Tunnel | 사내 MCP와 민감 도구를 public internet에 노출하지 않고 어떻게 연결할 것인가 |
| 2026-05-23 열람 기준 | gstack, revfactory/harness | opinionated workflow, 다중 agent host, generated team architecture를 어떻게 활용할 것인가 |
하네스 엔지니어링의 산출물
좋은 하네스는 추상적인 철학으로 끝나지 않고, 리포지터리 안에 다음과 같은 형태로 남습니다.
- 짧고 최신 상태인
AGENTS.md또는 동등한 진입 문서 - 아키텍처와 도메인 규칙을 설명하는 버전 관리 문서
- 실행 계획, 릴리즈 규칙, 테스트 루틴, QA 체크리스트
- 역할별 슬래시 커맨드, 스킬, 에이전트 정의 파일
- 누가 언제 승인해야 하는지 드러나는 워크플로우
- sandbox, MCP, hooks, remote connection, permission classifier처럼 실행 환경과 통제 지점을 명시하는 구성
- provider plugin, domain template, connector처럼 특정 도메인/플랫폼 작업을 반복 배포하는 패키지
- 무엇이 stale인지 찾고 정리하는 운영 루프
하네스가 없는 팀의 증상
| 증상 | 보통 부족한 것 |
|---|---|
| 같은 요청인데 사람마다 결과 편차가 큼 | 공통 진입 문서, 기준, 워크플로우 |
| 리뷰에서 늘 비슷한 문제가 뒤늦게 걸림 | evaluator / QA / browser loop |
| 문서는 많은데 아무도 안 읽음 | 짧은 TOC 문서, executable SSOT |
| 새 모델이 나오면 품질이 널뛰기함 | 평가 기준과 rollback 조건 |
| 특정 고수만 잘 씀 | 팀 배포용 command / skill / template |
안티패턴
- 거대한 규칙 파일 하나에 모든 것을 넣기
- "잘 알아서 해"에 가까운 암묵지 의존
- 문서와 워크플로우를 분리해서 따로 관리하기
- 평가 기준 없이 결과만 많이 생성하도록 유도하기
- 팀 특화 규칙 없이 외부 템플릿을 그대로 복붙하기
기억할 문장
하네스 엔지니어링은 모델을 보완하는 비법이 아니라, 모델이 실패하기 쉬운 지점을 시스템으로 감싸는 설계입니다.