하네스 엔지니어링: 프롬프트 너머의 세계
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)