하네스 엔지니어링(Harness Engineering) 뜻과 구성

🤔 모델을 바꿔도 결과가 들쭉날쭉할 때

에이전트의 결과가 매번 다를 때 가장 먼저 떠오르는 방법은 더 좋은 모델로 바꾸는 것입니다. 그런데 모델을 바꿔도 테스트를 빼먹거나, 쓰지 말라던 라이브러리를 설치하거나, 다 끝났다고 보고한 뒤에 보면 절반만 되어 있는 일이 계속 생기기도 합니다. 모델의 실력보다 모델이 일하는 틀에 빈 곳이 있는 경우입니다.

그 틀을 설계하는 일을 하네스 엔지니어링이라고 부릅니다. 2026년 들어 OpenAI와 앤트로픽, 소프트웨어 설계 분야의 저자들이 같은 주제를 잇달아 다루면서 널리 쓰이게 된 말입니다. 용어가 퍼진 과정과 준이아빠블로그의 적용 사례는 하네스 엔지니어링 입문 정리에 있고, 이 편에서는 하네스를 이루는 장치를 도구와 상관없이 나눠 봅니다.

🔑 하네스 엔지니어링의 정의

하네스 엔지니어링은 AI 에이전트가 일하는 환경과 규칙, 결과를 확인하고 고치게 하는 장치를 설계하는 일입니다.

하네스(harness)는 말에 씌우는 마구를 뜻하는 영어 단어이고, 동사로는 강한 힘을 다스려 쓸모 있게 쓴다는 뜻입니다. 마틴 파울러 사이트에 2026년 4월 실린 하네스 엔지니어링 글은 이 관계를 식 하나로 정리했습니다. 에이전트는 모델과 하네스의 합이고, 하네스는 에이전트에서 모델을 뺀 나머지 전부라는 설명입니다. 지침 파일, 쓸 수 있는 도구, 권한, 테스트, 검사 스크립트, 작업 기록이 모두 하네스에 들어갑니다.

같은 모델이라도 하네스에 따라 결과가 달라지는 이유도 여기서 나옵니다. 모델의 속은 쓰는 사람이 고칠 수 없지만 하네스는 파일 몇 개와 설정으로 오늘 바로 고칠 수 있습니다.

🚗 행동 전의 가이드와 행동 뒤의 센서

자동차로 치면 하네스의 장치는 두 종류로 나뉩니다. 출발 전에 경로를 알려 주는 내비게이션과, 달리는 동안 차선을 벗어나면 경고하는 센서입니다. 파울러 사이트의 글도 하네스를 같은 두 가지로 나눕니다.

• 가이드(피드포워드): 에이전트가 행동하기 전에 방향을 잡아 줍니다. 지침 파일, 작업 설명서, 참고 문서가 여기에 해당합니다
• 센서(피드백): 에이전트가 행동한 뒤 결과를 관찰해 스스로 고치게 돕습니다. 테스트, 린터, 리뷰가 여기에 해당합니다

같은 글은 장치가 판정하는 방식도 두 가지로 나눕니다. 정해진 규칙으로 빠르고 일정하게 판정하는 계산형과, 모델이 의미를 해석해 판정하는 추론형입니다. 둘을 겹쳐 보면 하네스의 장치가 네 칸에 정리됩니다.

표의 왼쪽 아래 칸이 가장 믿을 만합니다. 테스트와 린터는 같은 코드에 늘 같은 판정을 내리고, 사람이 없어도 몇 초 만에 결과가 나옵니다. 오른쪽 칸의 장치는 유연하지만 같은 입력에도 판정이 달라질 수 있어서, 계산형으로 확인할 수 있는 것은 먼저 계산형으로 막는 편이 낫습니다. 지침 파일은 오른쪽 위 칸에 들어갑니다. 에이전트가 읽고 판단하는 글이라 지켜질 가능성을 높일 뿐 반드시 지켜진다는 보장은 없습니다.

📚 OpenAI가 공개한 하네스 사례

OpenAI는 2026년 2월 11일 공개한 글에서 사람이 직접 쓴 코드 없이 코덱스 에이전트만으로 제품을 만든 경험을 정리하고, 그 작업을 하네스 엔지니어링이라 불렀습니다. 글이 밝힌 규모는 코드 약 100만 줄, 엔지니어 세 명이 연 변경 요청 약 1,500건이고, 한 사람이 하루에 평균 3.5건을 병합한 셈이라고 적었습니다. OpenAI가 스스로 밝힌 수치이고 다른 조직에서 같은 결과를 보장하지는 않습니다.

글에서 도구와 상관없이 가져올 수 있는 원칙은 네 가지입니다.

• 사람은 방향을 잡고 에이전트는 실행합니다: 사람의 일은 코드를 쓰는 것에서 환경과 규칙과 확인 장치를 만드는 것으로 옮겨 갑니다
• 지침 파일은 목차로 씁니다: AGENTS.md를 백과사전이 아니라 목차로 다뤄 100줄 안팎으로 두고, 자세한 내용은 저장소 안 문서로 연결했습니다
• 저장소를 기록의 원본으로 둡니다: 에이전트가 볼 수 없는 곳에 있는 지식은 없는 것과 같다고 보고, 설계와 결정 사항을 저장소 문서에 모았습니다
• 검사는 기계가 강제합니다: 직접 만든 린터와 구조 검사로 규칙을 강제하고, 오류 메시지에 고치는 방법을 적어 에이전트가 그 메시지를 읽고 바로 고치게 했습니다

마지막 원칙에 붙은 일화가 하나 있습니다. 처음에는 매주 금요일, 한 주의 20%를 에이전트가 남긴 어수선한 코드를 치우는 데 썼는데, 지켜야 할 원칙을 문서로 정하고 배경에서 도는 정리 작업을 붙인 뒤 그 시간을 없앴다고 합니다. 치우는 일도 하네스에 넣은 것입니다.

⏳ 긴 작업을 이어 가게 하는 하네스

앤트로픽은 2025년 11월 26일 공개한 글에서 여러 세션에 걸친 긴 작업을 위한 하네스를 소개했습니다. 세션이 바뀌면 에이전트는 앞 세션에서 무엇을 했는지 모르고 시작합니다. 앤트로픽이 관찰한 실패는 두 가지였습니다. 한 번에 전부 만들려다 중간에 흐트러지는 것, 그리고 뒤에 온 세션이 진척된 흔적을 보고 다 끝났다고 선언해 버리는 것입니다.

해법은 파일 몇 개와 규칙이었습니다.

1. 첫 세션의 에이전트가 환경을 준비합니다. 실행 스크립트, 진행 기록 파일, 첫 커밋을 만듭니다
2. 만들 기능 200여 개를 목록 파일에 적고 전부 실패 상태로 둡니다. 목록은 JSON으로 두었는데, 마크다운보다 모델이 함부로 고치거나 덮어쓰는 일이 적었다고 설명합니다
3. 이후 세션은 진행 기록과 커밋 기록을 읽고 시작해, 한 번에 기능 하나만 다룹니다
4. 기능은 끝에서 끝까지 직접 확인한 뒤에만 통과로 바꿉니다. 테스트를 지우거나 고치는 것은 허용하지 않는다는 문장도 지시에 넣었습니다

상태를 대화가 아니라 파일에 두는 것이 이 하네스의 요점입니다. 대화는 세션이 끝나면 사라지지만 파일은 다음 세션이 그대로 읽습니다. 긴 작업이 어디서 끊기는지는 이 코스의 장기 과제와 컴퓨터 조작의 한계에서 이어 봅니다.

🔄 같은 실수가 두 번 나오면 하네스를 고친다

하네스는 한 번 만들고 끝나는 것이 아니라 실수가 나올 때마다 자랍니다. 파울러 사이트의 글은 같은 문제가 여러 번 생기면 가이드와 센서를 고치라고 권하고, 앤트로픽의 AI 네이티브 개발 플레이북은 클로드가 같은 실수를 두 번 하면 그 교정을 CLAUDE.md에 적으라고 권합니다.

고칠 곳은 실수의 성격으로 정합니다.

마지막 줄은 다음 편에서 다룰 보상 해킹과 이어집니다. 검사를 통과하는 것 자체가 목표가 되면 에이전트가 검사 장치를 건드릴 수 있어서, 센서도 보호해야 할 대상입니다.

⚠️ 하네스를 만들 때 자주 하는 실수

• 규칙을 늘리기만 합니다: 지침 파일에 금지 사항만 쌓이면 길어질수록 덜 지켜집니다. 반드시 지켜야 하는 것은 계산형 센서로 옮기고 지침에서는 뺍니다
• 검사 메시지를 사람용으로만 씁니다: "형식 오류"만 알려 주면 에이전트는 무엇을 고쳐야 할지 모릅니다. 어느 파일의 무엇을 어떻게 바꾸면 되는지 적은 메시지가 스스로 고치는 속도를 높입니다
• 사람이 확인할 단계를 없앱니다: 배포, 결제, 권한 변경처럼 되돌리기 어려운 일은 하네스가 아무리 잘 되어 있어도 사람이 승인하는 단계를 남깁니다
• 모델만 바꿔 봅니다: 같은 하네스에서는 모델을 바꿔도 같은 빈 곳에서 비슷한 실수가 나옵니다

❓ 자주 묻는 질문

프롬프트 엔지니어링과 하네스 엔지니어링은 무엇이 다른가요?

프롬프트 엔지니어링은 요청 한 번을 어떻게 쓸지를 다루고, 하네스 엔지니어링은 에이전트가 어떤 자료를 보고 무엇을 할 수 있으며 결과를 어떻게 확인받는지까지 다룹니다. 요청 문장이 아니라 일하는 환경 전체를 설계한다는 점이 다릅니다. 좋은 지시문은 하네스 안에서도 여전히 필요합니다.

하네스를 잘 만들면 모델 성능은 덜 중요해지나요?

모델이 못 하는 일을 하네스가 대신 해 주지는 못합니다. 다만 모델이 할 수 있는 일을 매번 같은 수준으로 하게 만드는 것은 하네스의 몫입니다. 모델을 바꾸기 전에 지침과 검사가 비어 있는 곳부터 보는 편이 비용이 적게 듭니다.

개발자가 아니어도 하네스를 만들 수 있나요?

만들 수 있습니다. 지침 파일을 쓰고, 끝났다고 볼 조건을 적고, 어디서 사람이 확인할지 정하는 일은 코딩보다 업무를 나누는 일에 가깝습니다. 문장 검사기나 형식 검사처럼 이미 있는 도구를 저장할 때마다 돌게 연결하는 것만으로도 센서 하나가 생깁니다.

처음에는 무엇부터 만들면 되나요?

세 가지면 뼈대가 섭니다. 두 번 이상 말한 규칙을 옮긴 지침 파일 하나, 저장이나 커밋 때 자동으로 도는 검사 하나, 그리고 긴 작업이라면 진행 상황을 남기는 기록 파일 하나입니다. 그다음부터는 실수가 반복될 때마다 앞의 표대로 한 줄씩 고칩니다.

📋 3줄 요약

1. 하네스 엔지니어링은 AI 에이전트를 모델과 하네스의 합으로 보고 모델을 뺀 나머지인 작업 환경과 규칙, 결과 확인 장치를 설계하는 일입니다.

2. 하네스는 행동 전에 방향을 잡는 가이드와 행동 뒤에 결과를 확인하는 센서로 나뉘고 린터와 테스트 같은 계산형 검사가 AI 리뷰 같은 추론형 검사보다 빠르고 일정합니다.

3. 같은 실수가 두 번 나오면 모델을 탓하기보다 지침 파일이나 자동 검사를 한 줄 고쳐 다음 세션부터 같은 실수가 나오지 않게 합니다.

📚 참고 자료

• OpenAI, Harness engineering: leveraging Codex in an agent-first world (2026-02-11): https://openai.com/index/harness-engineering/
• Birgitta Böckeler, Harness engineering for coding agent users (martinfowler.com, 2026-04-02): https://martinfowler.com/articles/harness-engineering.html
• 앤트로픽, Effective harnesses for long-running agents (2025-11-26): https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
• 앤트로픽, The AI-native SDLC playbook: https://claude.com/blog/the-ai-native-sdlc-playbook