🐴 AI한테 코딩 시켰더니 엉망진창? "하네스"가 없어서 그래요

 

AI 도구 써봤는데 왜 결과가 매번 다르죠?

Claude Code, Cursor, GitHub Copilot. 요즘 AI 코딩 도구 안 써보신 분이 거의 없을 거예요. 처음 써봤을 땐 진짜 마법 같았죠. 그런데 쓰다 보면 이런 상황이 꼭 한 번씩 찾아옵니다.

"분명히 이미 있는 함수인데 AI가 또 새로 만들었어." "코드는 돌아가는데 팀 컨벤션이랑 완전 딴판이야." "어제는 잘 됐는데 오늘은 왜 이상한 코드가 나오지?"

이게 AI가 멍청해서일까요? 절대 아닙니다. 환경이 제대로 설계되지 않은 거예요. 2026년, 소프트웨어 업계는 이 문제에 드디어 이름을 붙였습니다. 바로 하네스 엔지니어링(Harness Engineering)입니다.

하네스가 뭔지 말 타기로 설명해 드릴게요 🐎

하네스(Harness)는 원래 말(馬)에 채우는 마구, 즉 고삐·안장·굴레를 통틀어 부르는 단어예요. 동사로는 강력한 것을 제어해서 유익하게 활용한다는 의미로 쓰입니다.

아무리 빠르고 강한 말이라도 고삐가 없으면 어디로 튈지 모르잖아요. 반대로 고삐가 잘 채워진 말은 그 힘을 원하는 방향으로 정확하게 쓸 수 있고요.

AI 코딩 에이전트도 똑같습니다. Claude든 GPT든 모델 자체는 이미 엄청나게 강력해요. 그런데 아무 지침 없이 "코드 만들어봐"라고만 하면, 그야말로 야생마처럼 어디로 튈지 모르는 코드가 나옵니다.

하네스 엔지니어링이란 이 AI 에이전트에게 제대로 된 고삐를 채우는 방법을 설계하는 기술입니다. 에이전트 자체를 바꾸는 게 아니라, 에이전트가 일하는 환경과 규칙 시스템 전체를 설계하는 개념이에요.

3년 만에 이렇게 바뀌었어요: 프롬프트 → 컨텍스트 → 하네스

AI 활용 방식의 흐름을 한눈에 보면 이렇습니다.

2023~2024년은 프롬프트 엔지니어링 전성기였어요. AI한테 어떻게 질문하느냐에 집중했죠. 역할을 부여하고, 더 구체적으로 물어보고, 예시를 들어가며 질문을 다듬는 것이 전부였습니다.

2025년부터는 컨텍스트 엔지니어링이 떴습니다. 질문 하나를 잘 쓰는 걸 넘어서, AI가 참고할 배경 정보 자체를 잘 설계하자는 개념이에요. RAG, MCP, 메모리 같은 기술들이 이 흐름에서 탄생했고요.

그리고 2026년, 하네스 엔지니어링이 등장했습니다. 단발성 질문이나 세션 배경 정보를 넘어서, AI가 일하는 환경 전체를 영구적인 시스템으로 설계하는 개념입니다.

비유를 들면, 프롬프트는 오늘 점심 뭐 먹을까 하는 한 번의 대화고, 컨텍스트는 나는 채식주의자야 라는 배경 설명이고, 하네스는 우리 식당은 항상 이런 메뉴 기준을 따라야 해 라는 영구적인 운영 규칙 시스템입니다.

하네스의 핵심은 딱 두 가지: 미리 알려주기 vs 나중에 확인하기

이 개념의 핵심을 이해하면 사실 굉장히 단순해요.

첫 번째는 가이드, 즉 먼저 알려주기입니다. AI가 일을 시작하기 전에 우리 팀은 이렇게 해, 이 파일들을 참고해, 이런 규칙을 지켜 라고 미리 알려주는 것들이에요. AGENTS.md나 CLAUDE.md 같은 지시 문서가 대표적입니다. 신입사원한테 업무 매뉴얼을 미리 주는 것과 같아요.

두 번째는 센서, 즉 나중에 확인하기입니다. AI가 코드를 만들고 나서 이거 우리 규칙에 맞아? 테스트 통과해? 아키텍처 지켰어? 를 자동으로 검사해주는 도구들이에요. 린터, 테스트 코드, 코드 구조 분석기 같은 것들이 여기 해당됩니다.

가이드만 있으면 AI는 규칙을 받았지만 잘 지켰는지 모릅니다. 센서만 있으면 같은 실수를 계속 반복해요. 둘이 함께 있어야 진짜 하네스가 완성됩니다.

그리고 하네스 엔지니어링의 또 하나 핵심 원칙이 있어요. Mitchell Hashimoto, HashiCorp 창업자가 이렇게 정의했습니다. 에이전트가 실수할 때마다, 그 실수가 다시는 발생하지 않도록 시스템을 엔지니어링하라. 더 좋은 모델을 기다리는 게 아니라, 실패를 시스템으로 막는 겁니다.

실제로 해봤더니? OpenAI의 충격적인 실험 결과 📊

그게 정말 효과가 있나요? 싶으시죠. 실제 사례를 보면 됩니다.

2025년 8월부터 약 5개월 동안 OpenAI 내부 팀이 파격적인 실험을 했습니다. 엔지니어 3명이 코드를 단 한 줄도 직접 작성하지 않고, AI 에이전트만으로 실제 서비스에 올라가는 소프트웨어를 만든 거예요. 결과는 약 100만 줄의 코드, 1,500개의 작업 완료, 엔지니어 1인당 하루 평균 3.5개의 PR 처리였습니다. 수동 개발 대비 약 10배 빠른 속도였다고 보고됐어요.

놀라운 건 처음부터 잘 된 게 아니라는 점입니다. 초반에는 환경 설정이 부족하고 자동 검사 도구가 없어서 생산성이 엉망이었어요. 하네스를 하나씩 갖춰나가면서 성과가 폭발적으로 올라갔습니다.

LangChain의 사례도 있어요. 모델을 전혀 바꾸지 않고 하네스만 개선했더니 Terminal Bench 2.0 벤치마크 점수가 52.8%에서 66.5%로 껑충 뛰어올랐고, 순위는 30위권 밖에서 상위 5위권으로 진입했습니다. 모델이 바뀐 게 아니에요. 환경이 바뀐 겁니다.

또 다른 실험도 있어요. 보안 연구자 Can Boluk는 16개 LLM 모델을 대상으로 에이전트가 파일을 수정하는 방식만 바꿔봤는데, Grok Code 모델이 동일 벤치마크에서 6.7%에서 68.3%로 점수가 뛰었습니다. 모델 가중치를 건드리지 않고 하네스만 바꾼 결과입니다.

자동 검사 도구에도 두 종류가 있어요

센서, 즉 자동 검사 도구도 두 가지 종류로 나뉩니다.

하나는 기계가 판단하는 도구입니다. 린터, 타입 체커, 단위 테스트처럼 컴퓨터가 논리적으로 맞다/틀리다를 판단하는 것들이에요. 빠르고 저렴하고 결과가 항상 같습니다. 코드를 저장할 때마다 자동으로 돌려도 부담이 없어요.

다른 하나는 AI가 판단하는 도구입니다. 이 코드가 과도하게 복잡하진 않아?, 중복된 로직이 숨어있지 않아? 처럼 의미적인 판단이 필요한 건 AI한테 리뷰를 맡기는 방식이에요. 실제로 2026년 현재 AI가 만든 코드를 또 다른 AI가 검토하는 이중 검증 구조가 빠르게 표준이 되고 있습니다.

실용적인 원칙은 간단해요. 빠르고 저렴한 기계 검사는 코드를 저장할 때마다 돌리고, AI 리뷰 같은 비용이 드는 검사는 중요한 합류 시점에만 돌립니다. 문제를 빠른 시점에 잡을수록 고치기가 쉽고 저렴하니까요.

CLAUDE.md 하나면 시작할 수 있어요 — 실전 구성법

하네스 구성이 거창하게 느껴지실 수 있는데, 오늘 당장 시작할 수 있는 방법이 있습니다.

프로젝트 루트에 CLAUDE.md 또는 AGENTS.md 파일을 하나 만들면 됩니다. 여기에 기술 스택, 빌드 명령어, 코딩 컨벤션, 금지 규칙 등을 적어두는 거예요. 에이전트가 작업을 시작할 때마다 이 파일을 읽고 컨텍스트로 활용합니다.

주의할 게 하나 있어요. 규칙을 너무 많이 쌓으면 오히려 역효과가 납니다. 규칙이 서로 충돌하고, 컨텍스트가 비대해지고, 에이전트가 뭘 따라야 할지 헷갈려하거든요. 60줄 이하로 핵심만 담는 것이 전문가들이 공통으로 강조하는 원칙입니다.

그다음으로 CI/CD에 린터와 구조 테스트를 붙이고, AI가 같은 실수를 반복할 때마다 규칙을 하나씩 추가하는 방식으로 점진적으로 키워나가면 됩니다. 매주 금요일 5분만 써서 그 주의 실패를 하나씩 하네스에 반영하면, 시간이 갈수록 에이전트가 신뢰할 수 있게 됩니다.

스타트업일수록 하네스에 더 투자해야 하는 이유

규모가 작은 팀일수록 하네스의 가치가 더 큽니다. 이유가 뭘까요?

하네스를 구성하는 CLAUDE.md, AGENTS.md, 자동 검사 스크립트 같은 것들은 전부 코드 저장소에 파일로 저장됩니다. 팀원이 바뀌어도, AI 모델이 업그레이드돼도, 축적된 하네스는 그대로 남아요.

핵심 개발자가 퇴사해도 하네스가 있으면 새로운 팀원이 같은 품질의 결과물을 만들 수 있습니다. 베테랑 개발자의 머릿속에만 있던 우리는 이렇게 해 라는 암묵적 규칙이 시스템으로 남는 거니까요.

실제로 토스(Toss) 테크팀은 하네스를 통해 조직 전체 생산성의 저점을 끌어올리는 전략을 실행하고 있어요. 개인 역량에 의존하지 않고 모든 팀원이 일정 수준 이상의 결과를 낼 수 있도록 하네스를 표준화한 것이 핵심이라고 합니다.

이건 단순한 코드 품질 문제가 아니라, 팀의 지식을 자산으로 만드는 가장 실용적인 방법입니다. 모델은 이제 상품(commodity)이고, 하네스가 곧 경쟁의 해자(moat)가 되는 시대예요.

마무리: 더 좋은 모델보다 더 좋은 환경이 먼저입니다

AI 코딩 도구를 써보고 실망하셨다면, 십중팔구 도구 자체의 문제가 아닙니다. 환경이 설계되지 않은 거예요.

하네스 엔지니어링의 핵심 메시지는 단 하나입니다. 에이전트가 실수할 때마다, 그 실수가 다시는 반복되지 않도록 시스템을 만들어라. Claude vs GPT vs Gemini 논쟁에 시간을 쓰고 있다면, 방향이 틀린 겁니다. 진짜 레버는 모델이 아니라 하네스에 있어요.

프롬프트를 잘 쓰는 것에서 시작해, 컨텍스트를 잘 설계하고, 이제는 환경 전체를 시스템으로 만드는 단계로 넘어가야 할 때입니다. 코딩이 바뀌는 게 아니라, 코딩하는 방식이 바뀌고 있습니다. 오늘 당장 프로젝트 루트에 CLAUDE.md 파일 하나만 만들어보세요. 그게 하네스의 첫 번째 고삐입니다.