하네스 엔지니어링: 프롬프트 너머의 세계
AI 에이전트가 코드를 짤 수 있다는 건 이제 놀라운 일이 아니다. 진짜 어려운 건 에이전트가 엉뚱한 짓을 안 하게 만드는 것이다.
2026년 들어 이 문제를 체계적으로 다루는 개념이 등장했다. 이름은 “하네스 엔지니어링(Harness Engineering)”.
▍하네스가 뭔데
하네스(Harness)는 말에 채우는 마구에서 온 비유다. 말이 아무리 빠르고 힘이 세도, 마구 없이는 어디로 튈지 모른다. AI 에이전트도 마찬가지다.
쉽게 말하면 에이전트를 둘러싼 시스템 전체를 뜻한다. 뭘 할 수 있는지 제약하고, 뭘 해야 하는지 알려주고, 제대로 했는지 검증하는 — 그 모든 것을 포함하는 레이어다.
이 개념이 주목받기 시작한 건 OpenAI Codex 팀의 사례가 크다. 이 팀은 5개월 동안 수동 타이핑 없이 100만 줄 이상의 프로덕션 코드를 만들었는데, 핵심 교훈이 명확했다.
모델보다 모델을 둘러싼 시스템이 중요하다.
LangChain은 모델을 바꾸지 않고 하네스만 개선해서 Terminal Bench 2.0 순위를 Top 30에서 Top 5로 끌어올렸다. 모델 성능을 쥐어짜는 것보다 주변 시스템을 잘 만드는 게 훨씬 효과적이었다는 뜻이다.
▍프롬프트, 컨텍스트, 하네스의 관계
이 세 개념은 서로 대체하는 게 아니라, 안쪽에서 바깥으로 감싸는 포함 관계다.
프롬프트 엔지니어링은 가장 안쪽이다. “LLM에게 뭐라고 말할까”만 다룬다. System prompt, few-shot, CoT 같은 것들. 2023년에 주류가 됐다.
컨텍스트 엔지니어링은 프롬프트를 감싸면서 “LLM이 볼 수 있는 전체 정보”를 설계한다. Tool 정의, RAG, 세션 상태, 메모리 — 프롬프트만으로 안 되는 것들이 여기 들어간다. 2024~2025년에 본격화됐다.
하네스 엔지니어링은 가장 바깥이다. “LLM 바깥의 전체 시스템”까지 다룬다. 린터, CI 파이프라인, 피드백 루프, 가비지 컬렉션 에이전트 — LLM이 아예 모르는 곳에서 LLM의 출력을 검증하고 교정하는 레이어가 추가된다. 2026년에 등장한 개념이다.
비유하자면 프롬프트가 “고삐를 어떻게 잡을까”라면, 컨텍스트는 “말에게 뭘 보여줄까”이고, 하네스는 “마구 전체 + 울타리 + 코스 설계”까지 포함하는 셈이다.
▍하네스의 세 가지 축
1. 컨텍스트 엔지니어링 — 에이전트가 볼 수 있는 것
System prompt, Tool 정의, RAG 문서, 세션 상태를 관리하는 영역이다.
여기서 중요한 포인트가 하나 있다. OpenAI Codex 팀이 강조한 건데, Slack에서 합의한 아키텍처 패턴이 레포에 문서화되지 않았다면 에이전트에게는 존재하지 않는 것과 같다는 것이다.
사람 머릿속이나 채팅 스레드에만 있는 지식은 에이전트가 접근할 수 없다. 모든 지식은 레포 안에, 에이전트가 읽을 수 있는 형태로 존재해야 한다. Claude Code를 쓰는 사람이라면 CLAUDE.md가 정확히 이 역할을 한다.
구체적으로 챙겨야 할 항목은 다음과 같다.
Prompt layer — 에이전트의 정체성과 행동 범위를 정의한다.
| # | 항목 | 구현 |
|---|---|---|
| 01 | 에이전트 정체성, 역할 범위, 금지 사항, 응답 스타일 | prompt |
| 02 | 프로젝트 컨벤션, 스택 결정, 네이밍 패턴 | prompt |
| 03 | 태스크별 재사용 가능한 지침 (컨텍스트 자동 로딩) | prompt |
Tool layer — 에이전트가 호출할 수 있는 함수를 정의한다.
| # | 항목 | 구현 |
|---|---|---|
| 04 | 함수 스키마 (read/write 분리) | code |
| 05 | 외부 서비스 연동 (메시징, 이슈 트래킹, 문서) | code |
Knowledge layer — 에이전트가 참고할 수 있는 지식을 관리한다.
| # | 항목 | 구현 |
|---|---|---|
| 06 | 비즈니스 규칙, API 스펙, 도메인 모델 (레포 내 마크다운) | both |
| 07 | 시맨틱 검색용 임베딩 문서 (pgvector, LanceDB 등) | code |
State layer — 에이전트의 실시간 작업 맥락을 관리한다.
| # | 항목 | 구현 |
|---|---|---|
| 08 | 로그인 상태 — 사용자 정체, 역할, 설정값 (캐시) | code |
| 09 | UI에서 넘어오는 실시간 작업 상태 — 현재 레코드, 열린 뷰 | code |
| 10 | 최근 대화 슬라이딩 윈도우 + 압축된 도구 결과 | code |
2. 아키텍처 제약 — 에이전트가 지켜야 하는 것
에이전트가 무시할 수 없는 하드 가드레일을 만드는 영역이다.
- 결정론적 검증: 커스텀 린터, 타입 체커, CI 파이프라인. 위반하면 무조건 실패한다.
- LLM 기반 검증: 코드 리뷰 에이전트, 의미론적 일관성 체크. 유연하지만 확실하지 않다.
핵심은 이런 규칙이 마크다운 문서에만 있으면 안 된다는 것이다. “공유 유틸리티를 사용하고 직접 만들지 마라”, “데이터 shape를 추측하지 말고 typed SDK를 써라” 같은 규칙은 린터나 CI에 코드로 구현되어야 에이전트가 위반할 때 즉시 잡힌다.
Deterministic guards — 위반하면 무조건 실패하는 규칙들이다.
| # | 항목 | 구현 |
|---|---|---|
| 11 | 엄격한 타이핑으로 잘못된 코드를 컴파일 타임에 차단 | code |
| 12 | 코드 스타일, import 규칙, 미사용 변수 탐지 | code |
| 13 | 도메인 특화 규칙 — 테넌트 격리, 쿼리 패턴, 네이밍 | code |
| 14 | DB 레벨 강제 — 필수 컬럼, FK 관계, 인덱스 | code |
| 15 | 의존성 방향 규칙 — “service는 controller를 import할 수 없다” | code |
Agent-specific guards — 에이전트의 행동 자체를 제한하는 규칙들이다.
| # | 항목 | 구현 |
|---|---|---|
| 16 | PII, 자격 증명, 민감 데이터 필터링 | code |
| 17 | 하드 거부 규칙 — 도메인에서 절대 해서는 안 되는 것 | prompt |
| 18 | Read vs Write 분리, 변경 전 확인 단계 | code |
| 19 | 의견이 분명한 규칙 — 공유 유틸 우선, typed 우선 | both |
3. 가비지 컬렉션 — 엔트로피를 지속적으로 정리
AI가 코드를 많이 생성하면 품질이 서서히 떨어진다. 이걸 방치하면 코드베이스가 지저분해진다.
OpenAI Codex 팀은 처음에 매주 금요일을 AI가 만든 저품질 코드 청소에 썼다. 백그라운드 에이전트가 자동으로 위반 사항을 스캔하고, 리팩토링 PR을 열도록 만들었다. 대부분의 PR은 1분 이내에 리뷰 가능하고 자동 머지된다.
Automated testing — 코드 변경 시 기존 기능이 깨지는지 자동 검증한다.
| # | 항목 | 구현 |
|---|---|---|
| 20 | PR/머지 시 자동 UI 테스트 — 실패하면 배포 차단 | code |
| 21 | AI 지원 테스트 생성 — 코드 파싱 후 테스트 자동 생성, 실패 시 재시도 | both |
Periodic scans — 주기적으로 코드베이스를 스캔하여 문제를 찾아낸다.
| # | 항목 | 구현 |
|---|---|---|
| 22 | 코드와 문서 간 불일치 감지 — 스케줄링된 에이전트 작업 | both |
| 23 | 백그라운드 에이전트가 아키텍처 위반을 찾아 리팩토링 PR 자동 생성 | both |
| 24 | 미사용 export, 고아 라우트, 오래된 피처 플래그, 방치된 파일 정리 | code |
| 25 | 마이그레이션 사전 검사 — 필수 컬럼, 인덱스, 롤백 스크립트 확인 | code |
Observability — 에이전트 활동을 추적하고 모니터링한다.
| # | 항목 | 구현 |
|---|---|---|
| 26 | 모든 대화 + 도구 호출 로깅 — 누가 뭘 요청했고 뭘 했는지 | code |
| 27 | 세션당 컨텍스트 윈도우 사용량 추적 — 예산 초과 시 알림 | code |
| 28 | 코드베이스 건강 지표 — 린트 통과율, 테스트 커버리지, 문서 최신성 | code |
prompt= 마크다운/시스템 프롬프트 레벨,code= 결정론적 코드 레벨,both= 프롬프트 + 코드 하이브리드
▍피드백 루프가 핵심이다
하네스의 가장 중요한 속성은 위 세 축이 따로 노는 게 아니라 피드백 루프로 연결된다는 것이다.
흐름을 정리하면 이렇다.
- 에이전트가 작업을 실행한다
- 린터, 타입 체커, CI, 테스트가 결과를 검증한다
- 통과하면 출하한다
- 실패하면 “뭐가 부족한가?”를 진단한다 — 도구가 없는 건지, 가드레일이 없는 건지, 문서가 없는 건지
- 하네스를 개선한다
- 다시 시도한다
OpenAI Codex 팀의 원칙은 이렇다.
에이전트가 어려움을 겪으면, 우리는 그것을 신호로 취급한다. 무엇이 빠져있는지 파악하고 레포에 피드백한다.
“더 열심히 시도하라”가 답인 경우는 거의 없다. 에이전트가 실패하면 고쳐야 할 건 프롬프트가 아니라 하네스다.
▍마크다운 하네스 vs 코드 하네스
현실에서는 두 가지 방식을 섞어 쓴다.
마크다운 하네스는 규칙을 시스템 프롬프트나 마크다운 파일에 직접 넣는 방식이다. Anthropic의 CLAUDE.md가 대표적이다. 빠르게 시작할 수 있고 코드 변경 없이 반복이 가능하다.
코드 하네스는 결정론적 도구로 제약을 구현하는 방식이다. 커스텀 린터, 구조적 테스트, CI 파이프라인이 여기에 해당한다. 에이전트가 무시할 수 없는 하드 바운더리를 만든다.
실용적인 패턴은 이렇다. 마크다운 하네스로 빠르게 시작하고, 반복적으로 위반되는 규칙을 코드 하네스로 승격시키는 것이다. 문서에 “이렇게 해라”라고 써놨는데 에이전트가 계속 어기면, 그건 린터로 강제해야 한다는 신호다.
▍결론
하네스 엔지니어링은 거창한 프레임워크가 아니다. 지금 당장 할 수 있는 질문들이 있다.
- pre-commit hook에 뭐가 들어있는가?
- 팀에서 반복적으로 하는 실수를 자동으로 잡을 수 있는가?
- 코드베이스에 강제하고 싶은 규칙이 문서에만 있는가, 코드로 검증되는가?
- Slack이나 사람 머릿속에만 있는 지식이 얼마나 되는가?
간단하게 시작하면 된다. 견고한 도구를 만들고, 가드레일을 추가하고, 실패할 때마다 시스템을 개선하는 것. 그게 하네스 엔지니어링이다.
▍참고 자료
- OpenAI, “Harness engineering: leveraging Codex in an agent-first world” (2026.02)
- Martin Fowler / Birgitta Böckeler, “Harness Engineering” — ThoughtWorks (2026.02)
- Cobus Greyling, “The Rise of AI Harness Engineering” (2026.03)
- HumanLayer, “Skill Issue: Harness Engineering for Coding Agents” (2026.03)