하네스 엔지니어링이 뭔지 실전 예제로 풀어봤습니다

TL;DR

하네스 엔지니어링은 AI가 "하지 말라는 일"을 실제로 못 하도록 강제 장치(훅·테스트·검증 스크립트)까지 같이 만들어두는 작업입니다. 프롬프트로 "이렇게 해줘"라고 부탁하는 데서 그치지 않고, 어겼을 때 자동으로 차단·재시도되는 울타리를 만드는 게 핵심입니다. 도입엔 시간이 걸리지만 한 번 잡아두면 AI가 사람 개입 없이 훨씬 멀리 갑니다.

요즘 AI 개발 커뮤니티에서 "하네스 엔지니어링(Harness Engineering)"이라는 말이 자주 보입니다. 프롬프트 엔지니어링이 익숙해질 무렵 컨텍스트 엔지니어링이 나오더니, 이제는 또 하네스라니 머리가 복잡해질 만합니다. 이 글에서는 하네스 엔지니어링이 정확히 무엇이고 왜 필요한지, 그리고 직접 Claude Code에 적용해본 실전 예제까지 한 번에 정리합니다. 코드를 한 줄도 안 써본 분도 흐름은 충분히 따라올 수 있도록 비유와 시나리오를 곁들였습니다.

하네스 엔지니어링이 뭐길래

하네스 엔지니어링은 AI 에이전트가 정해진 규칙 밖으로 벗어나지 못하도록 강제하는 시스템을 같이 설계하는 작업입니다. "하네스(harness)"는 강아지 산책 줄을 걸어두는 그 가슴줄을 떠올리시면 됩니다. 풀어두면 어디로 튈지 모르는 AI에게 활동 반경을 지정해주는 장치인 셈입니다.

지금까지 우리가 거쳐온 흐름을 표로 정리하면 이렇습니다.

단계	핵심 질문	비유
프롬프트 엔지니어링	AI에게 어떻게 말해야 잘 알아들을까	신입에게 지시를 똑똑하게 내리는 법
컨텍스트 엔지니어링	AI에게 어떤 정보를 줘야 잘 일할까	신입에게 회사 히스토리를 전달하는 법
하네스 엔지니어링	AI가 일하다 실수할 때 어떻게 잡아낼까	신입이 사고 못 치게 안전장치 거는 법

말로만 "마스터 브랜치 건드리지 마"라고 백 번 부탁해봐야 AI는 가끔 그냥 무시합니다. 그래서 어겼을 때 시스템이 자동으로 차단하고 되돌리는 장치까지 같이 만드는 게 하네스 엔지니어링의 본질입니다.

💡 핵심 한 줄: "프롬프트가 부탁이라면, 하네스는 강제다."

왜 갑자기 이 개념이 뜨고 있나

최근 OpenAI가 공개한 어떤 사내 사례 문서가 도화선이 됐습니다. 공식 소개에 따르면 OpenAI 내부 팀이 약 5개월간 사람이 코드를 거의 한 줄도 직접 치지 않고 AI 에이전트만으로 실제 서비스를 만들었다고 합니다. 비결은 마법 같은 모델이 아니라, AI가 알아서 일할 수 있도록 받쳐주는 시스템 설계였다고 밝혔습니다. 그 노하우를 정리해 공개한 게 하네스 엔지니어링이 화두로 떠오른 직접적인 계기입니다.

핵심 통찰은 좀 충격적입니다. AI 코딩 도구를 써본 분이라면 익숙할 그림인데요.

[사용자 요청] → [AI가 코드 작성] → [사람이 테스트]
                                          ↓
                              "이거 이상해, 다시"
                                          ↓
                                 [AI가 다시 작성]
                                          ↓
                                  ...무한 반복

AI는 코드를 빠르게 뽑아내는데, 검증 병목이 사람이라는 거죠. 결국 OpenAI 팀이 내린 결론은 "이 루프에서 사람을 최대한 빼자"였습니다. 사람을 빼려면 AI 스스로 검증하고, 실수하면 스스로 알아채고, 규칙을 어기면 자동으로 막혀야 합니다. 그 모든 장치를 묶어 부르는 이름이 하네스입니다.

실제로 무엇을 만들어야 하나

하네스 엔지니어링은 크게 세 축으로 구성됩니다. 이걸 모르고 그냥 "AI에게 규칙 잘 알려주기"로 오해하면 절반만 한 셈입니다.

축	무엇을 만드나	왜 필요한가
가시성(눈)	모든 작업의 로그·스크린샷 자동 기록	AI가 자기 결과물을 확인하고 스스로 수정
컨텍스트 관리(목차)	긴 문서 대신 점진적으로 펼쳐지는 인덱스	정보가 너무 많으면 AI도 대충 읽고 넘김
강제 검증(울타리)	커밋 훅·린트·테스트 스크립트	"하지 마"가 아니라 "못 하게" 막기

가시성 — AI에게 눈을 달아주기

기존 개발에선 "쓸데없는 로그 좀 지워라"가 시니어들의 단골 멘트였습니다. 하네스 시대엔 반대입니다. 로그를 일부러 더 남깁니다. AI가 자기가 만든 결과물을 다시 읽고 "어, 이거 내가 의도한 결과가 아니네" 하고 알아채려면 눈에 보이는 흔적이 있어야 하거든요. 스크린샷, JSON 응답, 에러 트레이스를 자동 기록해두면 AI 에이전트가 직접 그걸 열어보고 다음 행동을 결정합니다.

컨텍스트 관리 — 한꺼번에 주지 말 것

처음 OpenAI 팀도 거대한 AGENTS.md 파일 하나에 모든 규칙을 욱여넣었다고 합니다. 결과는 실패. AI도 사람처럼 문서가 길면 앞부분만 보고 뒷부분은 대충 추측하고 넘어가더라는 겁니다. 그래서 방식을 바꿨습니다. 메인 파일은 목차만 두고, 세부 규칙은 별도 문서로 쪼개서 "필요할 때 네가 찾아 들어가라"라고 시키는 구조입니다.

AGENTS.md (목차만)
   ├── docs/architecture.md   ← 구조 알고 싶을 때만 봐
   ├── docs/ui-rules.md       ← UI 검증할 때만 봐
   ├── docs/commit-rules.md   ← 커밋할 때만 봐
   └── docs/testing.md        ← 테스트 짤 때만 봐

강제 검증 — 진짜 핵심

개인적으로 하네스 엔지니어링에서 가장 중요한 부분이 여기라고 봅니다. 프롬프트로 "ESLint 규칙 지켜줘"라고 백 번 말해도 AI는 종종 무시합니다. 대신 커밋 훅(commit hook)을 걸어두면 어떻게 될까요? 훅은 "코드를 저장하기 직전에 자동으로 실행되는 검사 스크립트"입니다. 규칙을 어긴 코드는 아예 저장이 안 됩니다. 부탁이 아니라 강제가 되는 순간입니다.

실전 예제 — Claude Code에 적용해본 흐름

직접 Claude Code(Anthropic의 터미널 기반 코딩 에이전트입니다. 명령창에서 자연어로 시키면 AI가 코드를 짜고 파일을 수정합니다)에 하네스를 붙여서 "투두리스트에 작성자 정보 추가" 같은 작업을 시켜봤습니다. OpenAI 문서를 통째로 ChatGPT에 넣고 "이걸 적용한 하네스 시스템 프롬프트를 만들어달라"고 한 뒤, 빠진 부분은 직접 손봤습니다.

핵심 실행 흐름은 다음과 같습니다.

[1] 워크트리 생성        → 메인 코드 건드리지 않게 별도 작업공간 분리
        ↓
[2] 계획 문서 작성       → 무엇을, 왜, 어떻게 만들지 먼저 글로 정리
        ↓
[3] 워크트리에서 구현    → 격리된 공간에서만 코드 변경
        ↓
[4] 단위 테스트 작성     → 기능과 함께 검증 코드도 같이
        ↓
[5] 검증 스크립트 실행   → 린트, 빌드, 파일 크기 등 자동 검사
        ↓
[6] 자동 커밋 + 머지     → 정해진 형식으로 커밋, 통과 시 메인에 합침

여기서 짚을 만한 디테일을 몇 가지 풀어보겠습니다.

워크트리로 작업 공간 격리

워크트리(worktree)는 같은 프로젝트의 복사본 작업 폴더라고 보시면 됩니다. AI가 메인 코드에서 직접 깽판을 치다가 망가뜨리면 사람이 다시 뜯어고쳐야 하니까, 아예 옆에 사본을 하나 만들어 거기서만 실험하게 합니다. 테스트 다 통과하면 메인에 합치고, 안 되면 그냥 그 사본을 버리면 됩니다. 사람의 개입 지점을 또 하나 없애는 장치입니다.

CLAUDE.md — 무조건 읽히는 규칙 파일

Claude Code는 작업을 시작하기 전에 프로젝트 루트의 CLAUDE.md 파일을 무조건 한 번 읽고 시작합니다. 그래서 "절대 지켜야 할 5단계"는 이 파일에 박아둡니다. 흥미롭게도 OpenAI 원문 문서는 AGENTS.md만 언급하고 CLAUDE.md는 다루지 않아서, 그대로 따라 만들면 Claude Code에선 좀 헛돕니다. 도구마다 자기네 약속된 파일명이 따로 있으니 이 부분은 직접 맞춰줘야 합니다.

Husky 훅으로 강제하기

Husky는 Git 커밋 전후에 자동으로 실행되는 검사 스크립트를 등록해주는 도구입니다. 예를 들어 이런 규칙을 걸어둘 수 있습니다.

• [ ] 마스터 브랜치를 직접 변경하려 하면 → 차단
• [ ] 계획 문서 없이 들어온 코드는 → 차단
• [ ] 변경된 파일에 단위 테스트가 없으면 → 차단
• [ ] 커밋 메시지 형식이 안 맞으면 → 차단

💡 이게 바로 "말로만 하지 말고 못 하게 만들어라"의 실체입니다. 프롬프트엔 "마스터 브랜치 건드리지 마"라고 적어두지만, 실제로 막는 건 Husky 훅입니다. AI가 무시해도 시스템이 잡습니다.

실제로 돌려봤을 때 재미있었던 장면이 있는데요. AI 에이전트가 워크트리를 안 만들고 바로 계획 문서부터 쓰려 했습니다. 훅이 "워크트리 미준비" 상태를 잡아내자 에이전트가 스스로 "아, 워크트리 먼저 만들어야겠네" 하고 되돌아가더군요. 사람이 지적해서가 아니라 시스템이 막아서 자동으로 피드백 루프가 도는 게 핵심입니다.

자주 막히는 부분

직접 해보면서 헤맸던 지점들입니다.

프롬프트만 잘 쓰면 된다고 착각하기. 가장 흔한 실수입니다. "이렇게 해줘, 저렇게 하지 마"를 아무리 정성껏 적어도 강제 장치가 없으면 AI는 가끔 그냥 까먹습니다. 솔직히 사람도 그렇잖아요. 하네스의 진짜 무게중심은 프롬프트가 아니라 훅과 검증 스크립트입니다.

규칙 문서를 한 파일에 다 몰아넣기. 처음에 욕심부려서 CLAUDE.md 한 곳에 다 넣었더니 AI가 중간 규칙을 놓치는 일이 자꾸 생겼습니다. 메인은 목차로 비우고 세부는 docs/ 아래 분리한 뒤로 훨씬 안정적이었습니다.

초기 구축 시간 과소평가. 솔직히 처음에 시간이 꽤 들어갑니다. 훅 짜고, 검증 스크립트 만들고, 규칙 문서 분리하고, 테스트 돌려보면서 다시 손보고. 며칠은 잡아야 합니다. 다만 한 번 자리 잡으면 그 뒤부터 작업 속도가 확연히 빨라지는 건 사실이었습니다.

지금 당장 도입해야 할까

저는 "전부 다 적용할 필요는 없다"는 입장입니다. 하네스 엔지니어링은 결국 하나의 이론이자 패턴이지 절대 공식이 아닙니다. 본인 프로젝트에 맞는 형태로 변형되는 게 자연스럽습니다.

추천하는 접근은 이렇습니다.

단계	무엇을 할까
1단계	그냥 편하게 AI에게 시키며 평소처럼 개발
2단계	"이 검증 매번 직접 돌리기 귀찮은데" 싶은 작업을 메모
3단계	그 작업 하나를 자동 스크립트로 만들어 훅에 등록
4단계	반복하다 보면 자기만의 하네스가 자연스럽게 완성

블로그 글 자동 정리, 엑셀 데이터 검증, 이미지 일괄 처리처럼 반복되는 검증 포인트가 있는 작업이라면 하네스 패턴이 잘 들어맞습니다. 반대로 일회성 실험이나 프로토타입은 굳이 무거운 시스템을 얹을 필요 없습니다.

마무리

하네스 엔지니어링을 한 줄로 줄이면 "AI에게 부탁하지 말고, 못 하게 만들어라"입니다. 프롬프트는 의도를 전달하는 도구일 뿐이고, 실제 안전과 일관성은 로그·목차형 문서·강제 훅 세 가지가 만들어냅니다. AI가 사람 개입 없이 더 멀리 가게 하려면 결국 이 울타리 작업이 빠질 수 없습니다.

지금 Claude Code나 Cursor를 쓰고 계신다면, 가장 작게 시작할 수 있는 한 가지는 커밋 훅에 린트 검사 하나만 걸어보는 것입니다. 그 한 줄이 켜지는 순간부터 AI의 작업 품질이 어떻게 달라지는지 직접 느껴보시면, 그다음 단계는 자연스럽게 따라옵니다.