[AI Agent] 하네스 엔지니어링 (Harness Engineering)

하네스 엔지니어링(Harness Engineering)

모델은 그대로 두고 모델 주변을 설계해서 결과 품질을 끌어올리는 것

Agent = Model + Harness

가장 깔끔한 정의는 Martin Fowler 사이트에 올라온 Birgitta Böckeler의 글에 있었습니다. 하네스는 AI 에이전트에서 모델을 제외한 모든 것을 가리키는 축약어로 자리를 잡았다는 설명입니다. 공식으로 쓰면 이렇게 됩니다.

Agent = Model + Harness

용어 자체는 최근에 굳었습니다. HashiCorp를 만들고 Terraform을 공동 제작한 Mitchell Hashimoto가 2026년 2월에 자신의 습관 하나를 공개했습니다. 에이전트가 실수할 때마다 그 실수가 다시는 발생하지 않도록 환경에 영구적인 수정을 박아 넣는다는 것이었고, 그는 이걸 "engineering the harness"라고 불렀습니다. 몇 주 안에 OpenAI와 Anthropic이 이 아이디어를 확장한 엔지니어링 글을 냈고, 4월에는 Martin Fowler 사이트에 정식 아티클이 올라오면서 용어가 완전히 자리 잡았습니다.

세 개의 계층

프롬프트 엔지니어링

한 번의 주고받음에서 출력 품질을 최적화합니다. 문장, 구조, 예시의 문제입니다. 한 대화, 한 출력이 범위입니다.

컨텍스트 엔지니어링

모델이 한 번에 볼 수 있는 정보의 양을 관리합니다. 무엇을 검색해 올지, 히스토리를 어떻게 압축할지, 컨텍스트 창에 무엇이 들어가고 무엇이 빠질지를 다룹니다.

하네스 엔지니어링

에이전트가 살아가는 세계 자체를 만듭니다. 어떤 도구를 호출할 수 있는지, 어디서 정보를 얻는지, 자기 결정을 어떻게 검증하는지, 언제 멈춰야 하는지를 정합니다.

핵심 멘탈 모델: 가이드와 센서

가이드 (feedforward controls)

에이전트의 행동을 미리 예측해서 행동하기 전에 방향을 잡습니다. 첫 시도에서 제대로 된 결과가 나올 확률을 높이는 장치입니다.

센서 (feedback controls)

에이전트가 행동한 뒤에 관찰하고 스스로 고치도록 돕습니다. 특히 강력한 경우는 LLM이 소비하기 좋게 최적화된 신호를 뱉을 때인데, 수정 방법까지 담아서 출력하는 커스텀 린터 메시지 같은 것이 예시입니다.

둘 중 하나만 있으면 안 됩니다. 센서만 있으면 같은 실수를 계속 반복하는 에이전트가 되고, 가이드만 있으면 규칙은 다 외웠는데 그게 실제로 먹혔는지는 영영 알 수 없는 에이전트가 됩니다.

여기에 실행 방식으로 한 번 더 나눕니다. 계산적인 것은 결정론적이고 빠르며 CPU가 돌립니다. 테스트, 린터, 타입 체커, 구조 분석이 여기 속하고 밀리초에서 초 단위로 끝나며 결과를 신뢰할 수 있습니다. 추론적인 것은 의미 분석, AI 코드 리뷰, LLM as judge입니다. 보통 GPU나 NPU가 돌리고 느리고 비싸며 결과가 비결정적입니다.

두 축을 곱하면 2×2 표가 나옵니다.

	계산적 (빠르고 확실)	추론적 (느리고 비쌈)
가이드 (행동 전)	타입 시스템, 코드모드, 스캐폴딩 스크립트, 도구 권한 설정	AGENTS.md, Skills, 컨벤션 문서, 아키텍처 설명
센서 (행동 후)	단위 테스트, 린터, ArchUnit, git status/diff	리뷰 에이전트, LLM 심판, 아키텍처 리뷰 Skill

실습 프로젝트 

파일 / 설정	분류	하는 일
AGENTS.md	추론적 가이드	수정 범위, 중단 조건, 완료 보고 규칙을 미리 못 박습니다
docs/task.md, plan.md	추론적 가이드	요구사항과 인수 조건을 명시해 판정 기준을 고정합니다
tools: ['edit', 'search']	계산적 가이드	권한 자체를 좁혀 잘못된 행동을 물리적으로 차단합니다
tests/validation.test.js	계산적 센서	공백 입력, 40자 경계를 결정론적으로 판정합니다
git status / git diff	계산적 센서	허용 범위 밖 파일이 건드려졌는지 증거로 확인합니다
reviewer.agent.md	추론적 센서	PASS / REWORK / BLOCKED를 근거와 함께 판정합니다

그중에서도 가장 중요한 한 줄은 Implementer 지침의 마지막 항목이었습니다.

테스트 실패, 확인 불가, 남은 위험을 성공으로 보고하지 않는다.

이 한 줄이 없으면 모델은 그럴듯한 요약과 함께 "완료했습니다"로 턴을 끝냅니다. Skill 파일에도 같은 취지의 문장을 넣어뒀습니다. 테스트를 삭제하거나 기대값을 약화해서 PASS를 만들지 않는다는 규칙입니다. 하네스에서 완료의 정의를 누가 쥐고 있느냐가 결국 전부입니다.

OpenAI는 이 방식으로 100만 줄을 만들었습니다

가장 극단적인 사례는 OpenAI가 2026년 2월에 공개한 글입니다. 세 명의 엔지니어 팀이 2025년 8월 말 빈 git 저장소에서 시작해 5개월 동안 사람이 직접 쓴 코드 0줄로 내부 베타 제품을 만들어 배포했습니다. 애플리케이션 로직, 테스트, CI 설정, 문서, 관측성, 내부 도구까지 전부 Codex가 작성했고, 손으로 짰다면 걸렸을 시간의 약 10분의 1에 만들었다고 추정합니다. 5개월 뒤 저장소는 백만 줄 규모가 됐고 1,500개의 PR이 열리고 병합됐습니다.

여기서 대목 세 가지

1. AGENTS.md는 백과사전이 아니라 목차입니다

이 팀은 하나의 거대한 AGENTS.md 방식을 시도했다가 실패했습니다. 컨텍스트는 희소 자원인데 거대한 지침 파일이 정작 태스크와 코드와 관련 문서를 밀어내고, 모든 게 중요하면 아무것도 중요하지 않게 되며, 파일이 순식간에 죽은 규칙들의 무덤이 된다는 이유였습니다. 결국 지식 베이스는 구조화된 docs/ 디렉터리에 두고, 100줄 정도의 짧은 AGENTS.md를 지도처럼 써서 더 깊은 원본으로 포인터만 걸었습니다. 이걸 점진적 공개(progressive disclosure)라고 부릅니다.

2. 에이전트가 못 보는 것은 존재하지 않는 것과 같습니다

실행 중 컨텍스트로 접근할 수 없는 정보는 에이전트 입장에서 사실상 없는 정보입니다. Google Docs, 채팅 스레드, 사람 머릿속 지식은 접근 불가능합니다. 저장소에 있고 버전 관리되는 산출물만이 에이전트가 볼 수 있는 전부입니다. 팀의 아키텍처 패턴을 정한 Slack 논의가 저장소에 없다면, 3개월 뒤 합류한 신입에게 그렇듯 에이전트에게도 없는 정보인 셈입니다.

3. 문서만으로는 안 되고 기계적으로 강제해야 합니다

각 비즈니스 도메인을 고정된 레이어로 나누고 의존 방향을 엄격히 검증하며 허용 가능한 엣지를 제한했습니다. 이 제약은 커스텀 린터와 구조 테스트로 기계적으로 강제됩니다. 인상적이었던 건 린터가 커스텀이기 때문에 에러 메시지 안에 수정 지시를 직접 넣어 에이전트 컨텍스트에 주입한다는 부분이었습니다. 린터 메시지가 사람용이 아니라 에이전트용 프롬프트가 된 겁니다.

보통 이런 수준의 아키텍처 강제는 엔지니어가 수백 명 규모가 될 때까지 미뤄두는 일입니다. 그런데 코딩 에이전트와 함께라면 초기 필수 조건이 됩니다. 제약이 있어야 부패나 아키텍처 드리프트 없이 속도를 낼 수 있기 때문입니다.

그리고 완전 자율이 만드는 새로운 문제도 솔직하게 적혀 있었습니다. 에이전트는 저장소에 이미 존재하는 패턴을 복제하는데, 그게 어설픈 패턴이어도 그대로 복제합니다. 초기에 이 팀은 매주 금요일, 즉 주의 20%를 "AI slop" 정리에 썼다고 합니다. 당연히 확장되지 않았고, 결국 골든 원칙을 저장소에 직접 인코딩하고 주기적으로 도는 정리 프로세스를 만들었습니다. 배경 태스크가 이탈을 스캔하고 품질 등급을 갱신하며 타깃 리팩터링 PR을 여는 방식입니다. 기술 부채는 고금리 대출과 같아서, 복리로 불어나게 두기보다 계속 조금씩 갚는 게 거의 항상 낫다는 설명이 붙어 있었습니다.

하네스 엔지니어링을 사용해보며 AI의 발전속도가 지수그래프로 빠르게 발전하는 것 같습니다. Gpt -> Cursor -> Claude Code -> Codex -> 하네스 엔지니어링 등을 순차적으로 사용해가면서 새로운 기술들을 더 빠르게 적응하기 위해 기술적으로도 유연한 사고를 가지고 현실에서도 다양한 사람들의 생각들 받아들일 수 있어야 할 것 같습니다.