하네스 엔지니어링은 AI 코딩 에이전트를 둘러싼 환경(시스템 프롬프트, 도구 권한, 훅, 가비지 컬렉션 등)을 설계해서 에이전트의 실수가 구조적으로 반복될 수 없도록 만드는 기술입니다. 클로드 코드와 커서를 진지하게 쓰는 1인 개발자와 스타트업 팀 사이에서 2026년 들어 가장 빠르게 확산된 키워드 중 하나죠.
도화선은 두 가지였습니다. 첫째, 오픈AI 엔지니어 3명이 5개월 동안 직접 코드를 0줄 작성하고 AI 코딩 에이전트로 100만 줄을 넘는 대규모 제품을 배포한 사례. 둘째, 2026년 2월 미첼 하시모토가 자기 블로그에 같은 이름의 개념을 정리한 글입니다. 그 뒤로 마틴 파울러 사이트(Birgitta Böckeler, 2026-04-02)와 애디 오스마니(2026-04-19) 같은 영향력 있는 엔지니어 블로그가 줄줄이 합류하면서 업계 표준 용어로 굳어졌습니다.
이 글에서는 하네스 엔지니어링의 정확한 정의, 다섯 가지 구성 요소, 그리고 작은 팀이 오늘 당장 적용할 수 있는 방법을 정리합니다.
하네스 엔지니어링은 무엇을 다루는가
하네스(Harness)는 본래 말에 씌우는 마구를 가리킵니다. 고삐, 안장, 재갈처럼 강한 힘을 가진 말의 방향을 잡아주는 도구죠.
거대 AI 코딩 에이전트도 비슷한 상태입니다. 토큰 처리 속도와 추론 능력은 어마어마하지만 풀어놓으면 결제 시스템을 짜다가 DB 테이블을 통째로 삭제해 버립니다. 모델 자체를 약하게 만들 수는 없으니, 모델 주변 환경을 설계해서 잘못된 행동이 아예 실행되지 않도록 강제하는 거죠.
마틴 파울러 사이트의 정의를 그대로 옮기면 “에이전트에서 모델을 뺀 모든 것”이 하네스입니다. 시스템 프롬프트, 도구 권한, 샌드박스, 훅, 관측 로그, 서브에이전트 라우팅이 전부 들어갑니다. 애디 오스마니는 더 간결하게 “Agent = Model + Harness”라고 정리했고요.
핵심 철학은 단 한 문장입니다. 에이전트가 실수했을 때 “다음엔 잘해줘”라고 프롬프트로 부탁하지 말고, 그 실수가 구조적으로 반복될 수 없도록 시스템을 고치라는 겁니다. 부탁이 아니라 강제죠.
프롬프트와 컨텍스트로는 왜 부족했나
방법론의 진화 단계를 보면 차이가 분명해집니다. 2023년은 프롬프트 엔지니어링의 시대였습니다. “무엇을 어떻게 말할까”에 집중하는 기술이었죠. 2025년에 컨텍스트 엔지니어링이 등장했습니다. “무엇을 보여줄까”가 핵심이고, 첨부 파일을 잘 챙겨주는 기술에 가까웠습니다.
그 사이 SNS에서는 바이브 코딩이 화제였습니다. 클로드 코드나 커서에 분위기만 던지면 결과물이 알아서 나오는 단계라, 코딩 경험이 적은 사람도 며칠 안에 동작하는 앱을 만들 수 있게 됐죠.
2026년부터는 하네스 엔지니어링이 다음 축으로 자리 잡았습니다. “어떤 환경에서 일하게 할까”를 설계하는 기술이고, 사무실 전체의 업무 규칙과 체계를 만드는 일에 가깝습니다.
앞 두 단계가 한계에 부딪힌 이유는 단순합니다. 아무리 프롬프트를 잘 쓰고 컨텍스트를 잘 줘도 작업이 길어지면 모델이 앞쪽 지시를 잊어버립니다. 앤스로픽이 컨텍스트 부패(Context Decay)라고 부르는 현상이죠. 게다가 모델은 자기 결과물을 객관적으로 평가하지 못합니다. 자기 답이 맞는지 스스로 채점하면 거의 항상 맞다고 합니다. 더 좋은 프롬프트로는 해결되지 않는 두 가지 문제예요. 그래서 린터, 테스트, 훅, 권한 차단 같은 결정론적 외부 강제 장치가 필요해졌습니다.
숫자로 본 효과: 30위에서 5위로 25단계 점프
말로 들으면 추상적이니 구체적인 숫자로 정리해 봤습니다.
랭체인(LangChain)이 같은 모델로 코딩 벤치마크를 돌리면서 하네스만 갈아끼웠더니 점수가 52.8%에서 66.5%로 올랐습니다. 순위는 30위권 밖에서 5위 안으로 25단계나 점프했죠. 모델 업그레이드 없이 환경 설계만 바꿔서 만들어 낸 결과입니다.
오픈AI의 사례는 더 극단적입니다. 엔지니어 3명이 5개월 동안 직접 친 코드는 0줄, AI 코딩 에이전트가 생성한 코드는 100만 줄을 넘겼습니다. 이들이 5개월 내내 한 일은 코딩이 아니라 환경 구축이었어요. 지침서, CI/CD 테스트 게이트, 도구 권한 경계를 정교하게 다듬는 데만 시간을 썼습니다.
또 다른 흥미로운 숫자는 안드레 카파시 발(發) 65줄짜리 Claude Code 설정 파일입니다. 오픈AI 공동창업자이자 전 테슬라 AI 디렉터인 카파시가 1월에 정리한 4가지 코딩 원칙을 포레스트 창이라는 개발자가 단일 CLAUDE.md로 옮긴 결과물인데, 깃허브 두 미러 합쳐 22만 개 넘는 스타를 받았습니다. 65줄짜리 텍스트 한 장이 그 정도 화제가 됐다는 사실 자체가 시장의 굶주림을 보여줍니다.
애디 오스마니의 한 줄 요약이 가장 인상적입니다. “괜찮은 모델 + 훌륭한 하네스가 훌륭한 모델 + 엉성한 하네스를 이긴다.” 하네스 엔지니어링의 레버리지가 모델 선택보다 크다는 뜻이죠.
하네스 엔지니어링을 구성하는 5가지 부품
자료마다 분류가 조금씩 다르지만, 실용성을 기준으로 정리하면 다섯 갈래로 추릴 수 있습니다.
첫째, 컨텍스트 파일입니다. 저장소 루트에 두는 CLAUDE.md(또는 AGENTS.md)가 여기 해당합니다. 새 세션이 시작될 때마다 클로드 코드가 가장 먼저 읽는 온보딩 문서로, 기술 스택, 빌드 명령어, 코딩 컨벤션, 그리고 과거 실수에서 도출한 안티 패턴이 들어갑니다. 권장 길이는 60줄 이하예요. 1,000페이지짜리 매뉴얼이 아니라 “어디에 무엇이 있는지 알려주는 지도”여야 하고, 길어지면 모델이 대충 읽고 추측합니다.
둘째, 자동 강제 시스템입니다. 린터, 타입 체커, 프리커밋 훅, CI/CD가 여기 해당합니다. 코드가 규칙을 어기면 저장이 안 되고, 빨간불이 켜지면 AI 코딩 에이전트가 인간 개입 없이 스스로 에러를 읽고 수정합니다. 이 자동 교정 루프가 하네스의 심장이에요.
셋째, 도구 경계와 권한 제한입니다. AI가 파일 시스템, 외부 API, DB에 접근할 때 가능한 것과 불가능한 것을 시스템적으로 차단합니다. 부탁이 아니라 OS 수준의 차단이죠. user 테이블 삭제 사고는 “지우지 마”라는 부탁만으로는 막을 수 없습니다.
넷째, 피드백 루프와 평가자 분리입니다. 에이전트가 코드를 짜면 자동으로 테스트가 돌고, 실패하면 에러 메시지가 다시 모델에게 들어가는 자가 실행 피드백 루프가 작동합니다. 더 정교한 하네스는 코드를 짜는 모델과 검토하는 모델을 분리하기도 합니다. 평가자가 생성자보다 객관성이 높다는 머신러닝 쪽 발견을 그대로 적용한 거예요.
다섯째, 가비지 컬렉션입니다. AI 코딩 에이전트가 생성한 코드는 무질서가 쌓이는 경향이 있습니다. 안 쓰는 함수, 중복 정의, 규칙 위반 파편 같은 것들이죠. 정리 전담 에이전트를 주기적으로 돌리면 작업 환경의 엔트로피가 통제됩니다. 없으면 에이전트가 자기가 만든 나쁜 패턴을 복제해서 눈덩이가 굴러갑니다.
다섯 부품이 다 갖춰지면 예방(컨텍스트 파일과 권한 제한)과 관측(자동 강제와 피드백 루프), 그리고 정리(가비지 컬렉션)가 양쪽에서 동시에 작동하는 상태가 됩니다.
작은 팀이 오늘 시작할 수 있는 부분
오픈AI의 사례를 보면 압도되지만, 시작은 단순합니다. 1~2시간이면 첫 번째 버전을 만들 수 있어요.
가장 먼저 만들 것은 프로젝트 루트의 CLAUDE.md입니다. 60줄 이하로 핵심만 적습니다. 어떤 패키지 매니저를 쓰는지, 테스트는 어떻게 돌리는지, 절대 건드리면 안 되는 파일은 무엇인지 정도면 충분합니다. 길어진 컨텍스트 파일은 모델 성능을 떨어뜨리고 토큰 소비를 크게 늘리는 것으로 알려져 있으니, 욕심을 부리지 않는 것이 핵심입니다.
다음은 프리커밋 훅입니다. Husky 같은 도구로 커밋 직전 자동 검사를 거는 거죠. 린터에 빠른 단위 테스트를 더한 정도면 충분합니다. 규칙을 어긴 코드는 저장 자체가 안 되도록 막아야 합니다. “코드 리뷰에서 잡으면 되지”라는 접근은 더 이상 통하지 않아요. 사람이 매번 1,000줄짜리 PR을 리뷰할 수 없으니까요.
세 번째는 실패 로그 관리입니다. 클로드 코드가 같은 실수를 두 번 하면 그 패턴을 CLAUDE.md에 한 줄로 추가하거나, 검출용 스크립트를 짜서 자동 강제 시스템에 편입합니다. 매주 금요일 5분만 투자해 그 주에 반복된 실수 하나를 하네스에 반영하는 운영 방식이 권장됩니다. 처음부터 완벽한 시스템을 만들려고 하면 영원히 시작 못 합니다. 실패에서 출발해 진화시키는 게 정석이에요.
바이브 코딩과 하네스는 대척점이 아니라 짝입니다. 바이브 코딩으로 뼈대를 빠르게 짜고, 하네스로 안전망을 까는 조합이 가장 효율적입니다. 바이브 코딩만으로 프로덕션까지 가면 사고가 나고, 처음부터 하네스를 과하게 짜면 바이브 코딩의 속도가 죽거든요. MCP 도구 연결이나 서브에이전트 활용은 위 셋이 안정된 다음에 붙이면 됩니다.
카파시가 정리한 4가지 행동 원칙
다섯 부품이 시스템 레벨이라면, 한 단계 안쪽에는 모델 행동 자체를 다루는 원칙이 있습니다. 안드레 카파시가 정리한 4가지가 가장 깔끔합니다.
원칙 1: 코딩 전에 생각하라. 성급하게 코딩을 시작하지 않습니다. 불확실한 지점이 있으면 클로드 코드가 혼자 가정하지 말고 사용자에게 질문해서 결정하도록 만듭니다.
원칙 2: 단순함이 먼저다. 간단한 함수로 끝날 일을 추상 클래스로 만들지 않습니다. 모델이 똑똑할수록 과설계 경향이 강한데, 의식적으로 억제하지 않으면 코드베이스가 금방 부풀어 오릅니다.
원칙 3: 수술하듯 정밀하게 고쳐라. 버그 수정 요청을 받았으면 그 버그만 고칩니다. 관련 없는 리팩토링이 섞이면 리뷰어가 변경 범위를 파악할 수 없어 PR이 통과되지 않습니다.
원칙 4: 목표 중심 실행. “버그 고쳐줘” 같은 모호한 요청을 받으면 검증 가능한 목표로 먼저 바꿉니다. 실패하는 테스트를 작성하고, 코드를 고치고, 테스트가 통과하는지 확인하는 검증 루프 안에서만 움직이도록 강제합니다.
자주 묻는 질문
Q: 하네스 엔지니어링과 프롬프트 엔지니어링은 어떻게 다른가요?
A: 프롬프트 엔지니어링은 한 번의 대화에서 AI에게 무엇을 어떻게 말할지 다듬는 기술입니다. 반면 하네스 엔지니어링은 AI 코딩 에이전트가 작동하는 환경 전체(시스템 프롬프트, 도구 권한, 훅, 가비지 컬렉션 등)를 설계해 잘못된 행동을 시스템적으로 막는 기술입니다. 부탁이 아니라 강제로 작동시킨다는 점이 가장 큰 차이입니다.
Q: Claude Code를 처음 쓰는데 어디서부터 시작해야 하나요?
A: 가장 단순한 출발점은 프로젝트 루트에 60줄 이하의 CLAUDE.md를 두는 것입니다. 기술 스택, 빌드 명령어, 절대 수정 금지 파일 정도만 적으면 됩니다. 그다음에 Husky로 프리커밋 훅을 걸어 린터와 빠른 단위 테스트가 통과해야만 커밋되도록 설정하세요. 이 두 가지만으로도 클로드 코드의 사고 빈도가 눈에 띄게 줄어듭니다.
Q: 바이브 코딩과 하네스 엔지니어링은 충돌하는 개념인가요?
A: 충돌하지 않습니다. 오히려 보완 관계예요. 바이브 코딩으로 빠르게 뼈대를 짜고, 그 위에 하네스로 안전망을 까는 조합이 실전에서 가장 효율적입니다. 바이브 코딩만으로 프로덕션까지 가면 사고가 나고, 처음부터 하네스를 과하게 짜면 바이브 코딩의 속도가 죽기 때문이죠.
마무리
하네스 엔지니어링은 모델을 바꾸지 말고 모델 주변을 바꾸라는 방법론입니다. 부탁하지 말고 강제하고, 완벽을 노리지 말고 실패에서 출발하고, 규칙은 적게 넣되 시스템으로 강제하는 것이 핵심 원칙입니다.
작은 팀의 가장 합리적인 출발점은 짧은 CLAUDE.md, 프리커밋 훅, 그리고 매주 5분의 실패 패턴 누적입니다. 이 세 가지만 갖춰도 클로드 코드의 사고 빈도가 눈에 띄게 줄어들고, MCP나 서브에이전트는 그다음 단계에서 붙이면 됩니다.
지금이 학습 곡선을 올리기 좋은 타이밍입니다. 주요 모델의 성능이 이미 상향 평준화되면서 모델을 갈아끼워 얻을 이득이 줄어들고 있거든요. 지난 3년간 프롬프트만 다듬어 온 사람들이 다음 3년은 환경을 설계하는 사람으로 자리를 옮기게 될 겁니다.