하네스 엔지니어링이란? 모델은 그대로 두고 AI 에이전트 잘 일하게 만들기

프롬프트를 아무리 잘 써도 왜 에이전트는 삽질할까?
그래서 하네스란 도대체 무엇인가?
프롬프트 → 컨텍스트 → 하네스, 무엇이 달라진 걸까?
하네스는 무엇으로 이루어져 있을까?
같은 모델인데 왜 도구마다 점수가 다를까?
내 프로젝트에 하네스를 어떻게 깔아볼까?
하네스는 어떻게 키워나가야 할까?

전체 지도

하네스 엔지니어링 모델을 바꾸지 않고 에이전트를 잘 일하게 만드는 기술

자, 오늘도 화이트보드부터 한 장 그려놓고 시작하겠습니다. 이 그림이 오늘 우리가 걸어갈 길 전체입니다. 중간에 "지금 어디쯤 왔지?" 싶으면 이 지도로 돌아오시면 돼요.

한가운데를 보세요. 뇌 하나가 그려져 있고, 그 뇌를 굵은 마구(馬具)처럼 생긴 테두리가 감싸고 있습니다. 그 옆에 등식이 하나 크게 적혀 있죠. "에이전트 = 모델 + 하네스." 오늘 이야기의 전부가 사실 이 등식 한 줄입니다. 나머지는 전부 이 등식을 풀어 쓴 각주예요.

왼쪽 위는 문제 제기 구역입니다. 삽 하나와 물음표 말풍선, 그리고 서로 어긋난 화살표 몇 개가 그려져 있습니다. "프롬프트를 그렇게 정성껏 썼는데 왜 엉뚱한 걸 만들어 놨지?" 하는 그 순간을 그린 겁니다.

왼쪽 아래는 계단 세 칸이에요. 말풍선 → 서류뭉치 → 마구. 프롬프트 엔지니어링에서 컨텍스트 엔지니어링을 거쳐 하네스 엔지니어링까지 온 3년의 역사를 계단으로 그려놨습니다.

가운데 아래에는 저울이 하나 있습니다. 왼쪽 접시엔 나침반, 오른쪽 접시엔 온도계가 올라가 있죠. 이게 하네스의 두 축인데, 왜 하필 나침반과 온도계인지는 4번에서 밝혀집니다.

오른쪽 위는 도구 비교 구역, 오른쪽 아래는 체크박스 다섯 줄짜리 실전 세트입니다. 솔직히 말씀드리면 오른쪽 아래가 오늘의 알맹이예요. 여기까지 오시면 여러분 프로젝트에 바로 적용할 게 손에 잡힙니다.

그럼 왼쪽 위, 삽이 그려진 자리부터 가보겠습니다.

1. 프롬프트를 아무리 잘 써도 왜 에이전트는 삽질할까?

지도 왼쪽 위, 삽과 물음표 말풍선이 그려진 블록입니다.

프롬프트를 아무리 잘 써도 왜 에이전트는 삽질할까?

이런 경험 다들 있으실 겁니다. Claude Code나 Codex를 켜고 "인증 로직 리팩터링해줘"라고 시켰더니, 30분 뒤에 돌아와 보니 파일 열두 개가 바뀌어 있고, 테스트는 통과하는데 왜 통과하는지 모르겠고, 팀 컨벤션은 절반쯤 무시돼 있는 상태. 프롬프트를 못 써서일까요? 그렇게 생각하고 프롬프트를 세 배로 길게 써봐도 결과는 크게 달라지지 않습니다.

이유는 세 가지입니다. 첫째, 에이전트는 비결정적(non-deterministic)입니다. 같은 지시를 두 번 줘도 두 번 다른 결과가 나옵니다. 둘째, 맥락을 모릅니다. "우리 팀은 원래 이렇게 안 해"라는 암묵적 합의가 코드 어디에도 안 적혀 있으면 에이전트는 그걸 알 방법이 없어요. 셋째, 그리고 이게 제일 중요한데 — 자기가 잘했는지 스스로 확인할 방법이 없습니다.

Thoughtworks의 Birgitta Böckeler는 이 문제를 아주 인상적인 문장으로 정리했습니다. 코딩 에이전트에게는 "사회적 책임감도, 300줄짜리 함수를 봤을 때의 미적 거부감도, '우리는 그렇게 안 해'라는 직관도, 조직의 기억도 없다"고요.

신입 개발자 비유로 바꿔볼게요. 실력은 뛰어난데 오늘 입사한 신입이 있습니다. 이 친구에게 "결제 모듈 좀 고쳐줘" 한마디만 던지고 자리를 뜨면 어떻게 될까요. 아마 문법적으로는 완벽하지만 우리 팀 방식과는 전혀 다른 코드를 들고 올 겁니다. 그런데 우리는 실제로 신입에게 그렇게 안 하잖아요. 온보딩 문서를 주고, 코드 리뷰를 걸고, CI가 자동으로 린트를 돌리고, 배포 전에 QA를 거치게 합니다. 말을 더 잘해서 해결하는 게 아니라, 환경을 만들어서 해결합니다.

바로 이 "환경 만들기"에 이름이 붙은 게 하네스 엔지니어링입니다. 2026년 들어 이 단어가 갑자기 여기저기서 튀어나오기 시작했는데, 그럴 만한 이유가 있어요. 모델이 이미 충분히 똑똑해졌기 때문입니다. 모델 성능이 부족할 땐 "더 좋은 모델 나오면 해결되겠지"라고 미룰 수 있었는데, 이제는 프론티어 모델들이 대체로 비슷해져 버렸거든요. 남은 변수가 모델 바깥밖에 없는 겁니다.

그럼 그 "모델 바깥"이 정확히 뭔지부터 정의하고 가야겠죠. 지도 한가운데, 뇌를 감싼 마구 그림으로 넘어가 보겠습니다.

참고 자료

2. 그래서 하네스란 도대체 무엇인가?

지도 정중앙입니다. 뇌 하나, 그 뇌를 감싼 마구, 그리고 큼직한 등식 하나.

그래서 하네스란 도대체 무엇인가?

먼저 단어부터 풀고 갑시다. 하네스(harness)는 원래 말에게 씌우는 마구를 뜻합니다. 안전벨트나 등반용 하네스도 같은 단어예요. 공통점이 보이시죠? 힘 자체를 만들어내지는 않지만, 그 힘이 원하는 방향으로 나가게 붙잡아주는 장치입니다. 말의 힘은 말이 내지만, 마차가 절벽으로 안 굴러떨어지는 건 마구 덕분이에요. 작명이 참 잘됐습니다.

AI 쪽에서의 정의도 정확히 같습니다. Lilian Weng은 하네스를 "기반 모델을 둘러싸고 실행을 조율하는 시스템 — 모델이 어떻게 생각하고 계획할지, 도구를 어떻게 호출하고 행동할지, 맥락을 어떻게 인식하고 관리할지, 결과물을 어디에 저장할지, 그리고 결과를 어떻게 평가할지를 결정하는 층"이라고 정의합니다.

더 짧게 줄이면 이겁니다.

에이전트 = 모델 + 하네스

모델은 판단력이고, 하네스는 그 판단력이 실제 일이 되게 만드는 나머지 전부입니다. 시스템 프롬프트, 도구 목록, 권한 규칙, 파일 접근 범위, 실행 루프, 서브에이전트 구조, 검증 절차, 기억 저장 방식… 전부 하네스예요.

여기서 초보자들이 자주 놓치는 구분이 하나 있습니다. Böckeler는 하네스를 안쪽 하네스와 바깥쪽 하네스로 나눕니다.

안쪽 하네스(inner harness) — 도구를 만든 회사가 넣어둔 것. Claude Code의 시스템 프롬프트, 내부 오케스트레이션, 기본 권한 정책 같은 것들. 우리가 건드릴 수 없습니다.
바깥쪽 하네스(outer harness) — 우리가 우리 코드베이스에 맞춰 직접 만드는 것. 프로젝트 지침 파일, 린트 규칙, 테스트, 훅, 스킬, CI 검증 같은 것들.

하네스 엔지니어링이란 결국 이 바깥쪽 하네스를 설계하고 만드는 일입니다. 도구 회사가 안 해주는 부분, 오직 우리 프로젝트만 아는 부분을 우리가 채우는 거예요.

한 국내 정리 글은 이걸 네 개의 동사로 요약했는데, 저는 이 요약을 꽤 좋아합니다. 하네스는 에이전트가 할 수 있는 일을 제한하고(constrain), 해야 할 일을 알려주고(inform), 제대로 했는지 검증하고(verify), 틀렸으면 바로잡습니다(correct). 이 네 동사를 외워두시면 나중에 "이건 하네스인가 아닌가?"를 판단할 때 유용합니다.

그런데 이 얘기 들으면서 이런 생각 드시는 분 계실 겁니다. "그거 그냥 컨텍스트 엔지니어링 아니에요?" 좋은 지적이에요. 지도 왼쪽 아래 계단으로 내려가서 그 차이를 정리해보겠습니다.

참고 자료

3. 프롬프트 → 컨텍스트 → 하네스, 무엇이 달라진 걸까?

지도 왼쪽 아래, 말풍선 → 서류뭉치 → 마구로 이어지는 계단 세 칸입니다.

프롬프트 → 컨텍스트 → 하네스, 무엇이 달라진 걸까?

이 3년의 흐름을 표 하나로 정리하면 이렇습니다.

	프롬프트 엔지니어링	컨텍스트 엔지니어링	하네스 엔지니어링
대략의 시기	2023~2024	2025	2026~
최적화 대상	지시문(입력 텍스트)	맥락(RAG·메모리·MCP)	실행 환경(검증·복구·권한)
핵심 질문	"어떻게 말할까?"	"무엇을 알려줄까?"	"틀렸을 때 어떻게 알아채고 고칠까?"
작동 시점	실행 전	실행 전	실행 전 + 중 + 후

계단이 한 칸씩 올라갈 때마다 관심사가 뒤로 이동한다는 게 핵심입니다. 프롬프트는 "말을 잘 걸기", 컨텍스트는 "자료를 잘 챙겨주기"였어요. 둘 다 실행 전에 끝나는 일입니다. 반면 하네스는 실행 중과 실행 후까지 따라갑니다. 에이전트가 뭘 했는지 보고, 틀렸으면 되돌리고, 다시 시켜요.

여기에 딱 맞는 등산 비유가 있습니다. 한 국내 개발자 블로그의 표현을 빌리면, 컨텍스트 엔지니어링은 등산 전에 지도와 경로를 쥐여주는 일이고, 하네스 엔지니어링은 등산 중에 자동으로 걸리는 안전 로프입니다. 지도를 아무리 잘 그려줘도 발을 헛디딜 수 있죠. 그때 로프가 있으면 3미터 떨어지고 멈추지만, 없으면 계곡까지 갑니다.

그리고 이 차이는 작업이 길어질수록 기하급수적으로 벌어집니다. 한 번 물어보고 답 받는 대화라면 프롬프트가 90%예요. 그런데 에이전트가 50번, 100번 도구를 호출하며 두 시간짜리 작업을 한다면? 첫 단추가 살짝 어긋난 채로 100번을 가면 도착지가 완전히 달라집니다. 그래서 하네스의 원칙은 이겁니다. 짧은 주기마다 빠르게 검사하고 즉시 복구한다. 오차를 누적시키지 않는 거예요.

오해 하나만 짚고 갈게요. 계단을 올라갔다고 아래 칸이 사라지는 게 아닙니다. 프롬프트도 여전히 중요하고 컨텍스트도 여전히 중요해요. 실제로 컨텍스트 엔지니어링은 하네스의 한 부분으로 흡수됐다고 보는 게 맞습니다. 앞에서 본 네 동사 중 "알려주기(inform)"가 정확히 컨텍스트 엔지니어링이거든요. 하네스는 거기에 "제한·검증·교정"을 더한 겁니다.

자, 그럼 그 하네스를 뜯어보면 안에 뭐가 들어 있을까요? 지도 가운데 아래, 저울이 그려진 자리로 가보겠습니다.

참고 자료

4. 하네스는 무엇으로 이루어져 있을까?

지도 가운데 아래, 나침반과 온도계가 저울 양쪽에 올라간 그림입니다. 이제 왜 하필 이 둘인지 말씀드릴게요.

하네스는 무엇으로 이루어져 있을까?

Böckeler가 제안한 분류가 지금까지 나온 것 중 가장 쓸 만합니다. 하네스의 부품을 두 축으로 자릅니다.

축 1 — 언제 작동하는가?

가이드(Guide) = 피드포워드. 에이전트가 행동하기 전에 미리 알려주는 것. 지도에서 나침반입니다. 예: CLAUDE.md/AGENTS.md 지침 파일, 아키텍처 문서, 스킬, MCP로 붙인 사내 지식.
센서(Sensor) = 피드백. 에이전트가 행동한 뒤에 결과를 관찰하는 것. 지도에서 온도계죠. 예: 린터, 타입 체커, 테스트, AI 코드 리뷰, 커버리지 검사.

축 2 — 어떻게 판단하는가?

계산형(computational). 결정론적이고 빠릅니다. 린터, 타입 체커, ArchUnit 같은 구조 테스트. 되면 되고 안 되면 안 되는 검사예요.
추론형(inferential). 의미를 봐야 하는 것들이라 LLM이 판단하고, 느리고, 가끔 틀립니다. AI 코드 리뷰, LLM 저지(judge).

이 둘을 곱하면 2×2 사분면이 나옵니다.

	계산형(결정론적·빠름)	추론형(의미적·느림)
가이드(사전)	코드 생성기, 부트스트랩 스크립트, LSP·타입 정보	지침 문서, 아키텍처 원칙, 스킬
센서(사후)	린터, 타입 체크, 테스트, 프리커밋 훅	AI 코드 리뷰, LLM 저지, 문서-코드 일치 검사

여기서 제일 중요한 문장을 드리겠습니다. 둘 중 하나만 있으면 반쪽입니다. Böckeler의 표현을 그대로 옮기면, 센서만 있으면 같은 실수를 계속 반복하는 에이전트가 되고, 가이드만 있으면 규칙은 적어놨는데 그게 지켜졌는지 영영 모르는 에이전트가 됩니다.

운전 비유가 딱 맞습니다. 가이드는 내비게이션이에요. 출발 전에 경로를 알려줍니다. 센서는 차선 이탈 경고음이고요. 내비만 있고 경고음이 없으면 졸다가 갓길로 나가도 아무도 안 알려줍니다. 반대로 경고음만 있고 내비가 없으면 계속 삑삑거리기만 하지 어디로 가야 할지는 모르죠. 둘 다 있어야 자율주행 근처라도 갑니다.

Böckeler는 여기에 검증 영역을 세 등급으로 나눠 붙였는데, 이것도 현실적입니다. 유지보수성(maintainability)은 제일 쉽습니다. 린터로 거의 잡혀요. 아키텍처 적합성(architecture fitness)은 중간입니다. 구조 테스트와 의존성 규칙으로 상당 부분 잡힙니다. 그런데 동작(behaviour) — 즉 "이게 진짜 의도대로 동작하는가" — 은 아직 제일 어렵습니다. 현재로선 AI가 만든 테스트에 지나치게 의존하고 있다는 게 이 글의 솔직한 진단이에요. AI가 짠 코드를 AI가 짠 테스트로 검증하는 건, 자기 답안지를 자기가 채점하는 것과 비슷하거든요.

Lilian Weng은 여기에 실행 구조 쪽 부품을 더 얹습니다. 작업 루프 설계(계획 → 실행 → 관찰 → 반복), 파일 시스템을 기억으로 쓰기(컨텍스트 창에 다 이고 다니지 말고 파일로 남겨서 중단돼도 복구되게), 서브에이전트와 백그라운드 작업(병렬 처리를 눈에 보이게 만들기). 이것도 전부 하네스 부품입니다.

부품 목록은 나왔습니다. 그런데 이게 실제로 성능 차이를 얼마나 만들까요? 숫자로 보면 좀 놀라실 겁니다. 지도 오른쪽 위로 올라가 보죠.

참고 자료

5. 같은 모델인데 왜 도구마다 점수가 다를까?

지도 오른쪽 위, CLI 창 세 개가 점수판 위에 올라가 있고 옆에 자물쇠가 그려진 구역입니다.

같은 모델인데 왜 도구마다 점수가 다를까?

숫자부터 보시죠. 2026년 5월 베이징대와 Qiyuan Tech 연구진이 낸 Harness-Bench라는 논문이 있습니다. 모델은 고정해두고 하네스만 바꿔가며 106개 과제를 8개 모델 백엔드로 돌려 5,194개의 실행 궤적을 모았어요. 결과가 이렇습니다.

가장 좋은 하네스: 76.2% / 가장 나쁜 하네스: 52.4%
즉 똑같은 모델인데 하네스에 따라 23.8%p 차이

23.8%p면 모델 한두 세대 차이입니다. 논문의 결론이 그래서 단호해요. 에이전트의 성능은 "모델 이름"이 아니라 "모델–하네스 조합" 단위로 보고해야 한다는 겁니다. "Opus 4.8이 몇 점"이 아니라 "Opus 4.8 + Claude Code 조합이 몇 점"이라고 말해야 정확하다는 거죠.

실패 원인 분류도 교육적입니다. 가장 흔한 실패는 약속된 형식·계약 위반(36.4%), 그다음이 도구 실패에서 복구하지 못함(24.6%), 그다음이 근거를 확인하지 않음(14.6%)입니다. 셋 다 "모델이 멍청해서"가 아니라 "환경이 안 잡아줘서" 생기는 실패예요. 정확히 하네스의 영역입니다.

실제 리더보드에서도 같은 장면이 보입니다. Terminal-Bench 2.0 리더보드를 보면 똑같은 GPT-5.5 모델을 쓰는데도 하네스에 따라 점수가 갈립니다. Codex CLI가 82.2%인데, 다른 하네스를 얹은 구성들은 83~85%대에 올라 있어요. 그래서 벤치마크 점수를 볼 때는 "어떤 모델인가"만큼이나 "어떤 하네스로 쟀는가"를 같이 보셔야 합니다. 실제로 이걸 정면으로 지적한 논문 제목이 「하네스를 밝히지 않고 LLM 에이전트를 비교하지 말라」예요. 제목만으로도 상황이 짐작되시죠?

F1 경주 비유를 써볼게요. 드라이버가 모델이고, 차와 피트 크루가 하네스입니다. 세계 챔피언을 하위 팀 차에 태우면 예선 탈락합니다. 반대로 좋은 차와 0.2초 만에 타이어를 갈아 끼우는 피트 크루가 붙으면 평범한 드라이버도 포디움에 올라요. 요즘 AI 코딩 도구 경쟁은 드라이버 영입전이 아니라 차와 피트 크루 개발전입니다.

실제로 2026년 8월 기준 주요 도구를 비교한 정리를 보면, 이제 MCP·훅·스킬·서브에이전트는 여덟 개 도구가 전부 지원합니다. 기능 유무로는 변별이 안 되고, 깊이와 오케스트레이션에서 갈려요. 몇 가지만 짚겠습니다.

Claude Code — 하네스가 가장 깊다는 평을 받습니다. 공식 문서 기준 생명주기 훅 이벤트가 31종(PreToolUse, PostToolUse, Stop, SubagentStart, PreCompact, SessionEnd …)이고, 스킬·서브에이전트·MCP에 더해 다이내믹 워크플로로 병렬 오케스트레이션을 합니다. 대신 토큰을 Codex의 3~4배 쓴다는 지적도 함께 나옵니다. 성능과 비용이 정직하게 맞바꿔지는 구조예요.
OpenAI Codex — 훅·스킬·서브에이전트에 더해 커널 수준 샌드박스를 씁니다. macOS에서는 Apple Seatbelt(sandbox-exec), 리눅스에서는 bubblewrap으로 파일시스템을 기본 읽기 전용으로 묶고 seccomp로 네트워크를 거릅니다. 격리를 OS에 맡기는 방향이죠.
Cursor — 흥미롭게도 .cursor뿐 아니라 .claude/agents, .codex/agents 설정까지 읽습니다. 하네스 설정이 도구 간에 이식되기 시작했다는 신호예요.
Gemini CLI / OpenCode — 오픈소스 계열. OpenCode는 75개 이상의 모델 제공자를 붙일 수 있어서, 모델은 갈아 끼우고 하네스는 유지하는 구성이 가능합니다.

로컬 CLI와 클라우드 버전의 차이도 짚고 갑시다. 이게 실무에서 헷갈리는 지점인데요. 내 노트북에서 도는 CLI는 내 파일 시스템 전체가 사정권이라 권한 모드와 허용 목록이 곧 안전장치입니다. 반대로 클라우드·백그라운드 실행 버전은 격리된 샌드박스에서 돌기 때문에 폭발 반경은 작지만, 대신 내 로컬 환경·사내망에 손이 안 닿습니다. 같은 모델, 같은 브랜드여도 어디서 돌리느냐가 하네스를 통째로 바꾼다는 뜻이에요.

가장 최근 흐름 하나만 더 소개하고 넘어가겠습니다. Anthropic이 2026년 5월 말 공개하고 6월 초에 「모든 작업에 맞는 하네스」라는 글로 설명한 다이내믹 워크플로는 아예 "에이전트가 그 작업에 맞는 하네스를 스스로 그때그때 짜게 하는" 기능입니다. 발표 글이 밝힌 문제의식이 재미있어요. 긴 작업에서 나타나는 세 가지 병 — 에이전트의 게으름(절반쯤 하고 끝났다고 함), 자기 편애(자기가 만든 걸 자기가 검증하면 후하게 줌), 목표 표류(턴이 쌓이면서 원래 목표에서 멀어짐) — 을 서브에이전트를 분리해 각자 좁은 목표만 보게 만들어 해결한다는 겁니다. 4번에서 말씀드린 "자기 답안지 자기가 채점" 문제를, 채점자를 분리해서 푸는 접근이죠.

이론과 도구 얘기는 여기까지 하겠습니다. 이제 여러분 프로젝트에 뭘 깔면 되는지, 지도 오른쪽 아래 체크박스 다섯 줄로 내려가겠습니다.

참고 자료

6. 내 프로젝트에 하네스를 어떻게 깔아볼까?

지도 오른쪽 아래, 체크박스 다섯 줄이 그려진 블록입니다. 오늘의 실전 파트예요.

내 프로젝트에 하네스를 어떻게 깔아볼까?

미리 안심시켜 드리겠습니다. 하루면 됩니다. 한 정리 글은 도입 규모를 세 레벨로 나누는데, 개인 개발자 레벨은 1~2시간, 팀 레벨이 1~~2일, 조직 레벨이 1~~2주 정도로 잡습니다. 우리는 오늘 1레벨만 합니다. 순서대로 따라오세요.

① 지침 파일 — 가이드의 기본기 (30분)

프로젝트 루트에 CLAUDE.md(또는 AGENTS.md)를 만듭니다. 온보딩 문서를 쓴다고 생각하시면 됩니다.

# 프로젝트 지침

## 기술 스택
- Next.js 15 (App Router), TypeScript strict, Tailwind
- DB: PostgreSQL + Drizzle ORM

## 명령어
- 개발: `pnpm dev`
- 테스트: `pnpm test` (변경 후 반드시 실행)
- 린트: `pnpm lint --fix`

## 코딩 규칙
- API 라우트는 반드시 `src/app/api/` 아래에 둔다.
- DB 접근은 `src/server/db/` 를 통해서만 한다. 컴포넌트에서 직접 쿼리 금지.
- 새 의존성 추가 전에는 먼저 물어본다.

## 하지 말 것
- 마이그레이션 파일을 임의로 수정하지 않는다.
- `git push --force` 금지.

팁 하나. 처음부터 완벽하게 쓰려고 하지 마세요. 비워두고 시작해서, 에이전트가 실수할 때마다 한 줄씩 추가하는 게 훨씬 잘 굴러갑니다. 7번의 "스티어링 루프"가 바로 그 얘기예요.

② 훅 — 센서를 자동문으로 (20분)

훅은 특정 시점에 무조건 실행되는 셸 명령입니다. 모델의 기분과 무관하게 돌아가는 게 핵심이에요. .claude/settings.json에 이렇게 넣습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "pnpm lint --fix && pnpm tsc --noEmit" }
        ]
      }
    ]
  }
}

파일을 수정할 때마다 린트와 타입 체크가 자동으로 돌고, 실패하면 그 결과가 에이전트에게 되돌아가 스스로 고칩니다. 이게 바로 "계산형 센서"의 교과서적인 예입니다. 여러분이 보기도 전에 에이전트가 자기 실수를 치우고 오는 거예요.

자동문 센서 비유를 쓸게요. "문 열어주세요"라고 매번 부탁하는 게 프롬프트라면, 훅은 사람이 다가오면 그냥 열리는 자동문입니다. 부탁을 잊어버릴 일이 없죠.

③ 스킬 — 검증된 절차를 재사용 (20분)

스킬은 반복되는 작업 절차를 폴더에 담아 재사용하는 장치입니다. .claude/skills/api-route/SKILL.md처럼 만들어 두면, 에이전트가 필요할 때 알아서 꺼내 읽습니다.

---
name: api-route
description: 새 API 라우트를 추가할 때 사용. 라우트 생성, 검증, 테스트 작성까지 포함.
---

# API 라우트 추가 절차

1. `src/app/api/<이름>/route.ts` 생성
2. 요청 스키마를 zod로 정의하고 `safeParse`로 검증
3. DB 접근은 `src/server/db/` 의 리포지토리 함수만 사용
4. 에러는 `ApiError` 로 감싸서 반환 (형식: `{ error: { code, message } }`)
5. `src/app/api/<이름>/route.test.ts` 에 성공 1건 + 검증 실패 1건 테스트 작성
6. `pnpm test` 실행해 통과 확인

이건 "가이드" 쪽 부품이면서 동시에 마지막 두 줄이 "센서"를 부르는 구조입니다. 레시피 카드라고 생각하세요. 요리사가 매번 감으로 하는 대신 카드를 보고 만들면 맛이 일정해집니다.

④ 테스트 게이트 — "끝"의 정의 (20분)

에이전트에게 끝나는 조건을 코드로 못 박아두세요. 지시에도 넣고, 훅에도 넣습니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm test --run" }
        ]
      }
    ]
  }
}

작업을 끝내려 할 때 테스트를 돌려서 실패하면 계속 일하게 만드는 겁니다. "다 됐어요"를 에이전트가 선언하는 게 아니라 테스트가 선언하게 하는 것 — 이 전환이 생각보다 큽니다.

⑤ 권한 좁히기 — 폭발 반경 줄이기 (10분)

마지막으로 허용 목록과 금지 목록입니다.

{
  "permissions": {
    "allow": ["Bash(pnpm test:*)", "Bash(pnpm lint:*)", "Bash(git status)", "Bash(git diff:*)"],
    "deny": ["Bash(git push --force:*)", "Bash(rm -rf:*)", "Read(./.env)", "Read(./.env.*)"]
  }
}

문법 하나만 짚고 갈게요. Bash(git status)는 정확히 그 명령만 허용이고, Bash(pnpm test:*)처럼 :*를 붙이면 그 접두사로 시작하는 명령 전부를 허용합니다. 둘은 다른 규칙이니 구분해서 쓰세요.

그리고 .env를 읽기 금지 목록에 넣는 건 꼭 하세요. 에이전트가 읽은 것은 모델 제공자에게 전송됩니다. 그리고 되돌릴 수 없는 작업 — 배포, 마이그레이션, 강제 푸시, 삭제 — 은 자동 승인 대상에서 빼두는 게 원칙입니다.

여기까지가 약 100분입니다. 주방 비유로 정리하면, 지침 파일은 레시피북, 훅은 자동으로 켜지는 환기팬, 스킬은 자주 만드는 메뉴의 조리 카드, 테스트 게이트는 서빙 전 간 보기, 권한 설정은 칼집에 넣어둔 칼입니다. 좋은 주방은 요리사가 대단해서가 아니라 이 다섯 개가 갖춰져 있어서 일정한 맛을 냅니다.

깔았으면 이제 키워야겠죠. 지도 아래 중앙, 원형 화살표가 그려진 마지막 자리로 가겠습니다.

참고 자료

7. 하네스는 어떻게 키워나가야 할까?

지도 아래 중앙, 원형 순환 화살표입니다. "실수 발견 → 하네스에 적기 → 재발 방지"라고 적혀 있죠. 여기가 종착지예요.

하네스는 어떻게 키워나가야 할까?

하네스는 한 번 만들고 끝나는 물건이 아닙니다. Böckeler는 이 지속적인 갱신 과정을 스티어링 루프(steering loop)라고 부릅니다. 규칙은 간단해요. 같은 실수가 두 번 반복되면, 그건 프롬프트로 해결할 문제가 아니라 하네스에 적을 문제입니다.

이걸 습관으로 만드는 방법을 알려드릴게요. 에이전트가 뭔가 잘못했을 때 세 가지 중 하나를 고르는 겁니다.

또 그럴 것 같지 않다 → 그냥 고치고 넘어간다.
또 그럴 것 같다 → CLAUDE.md에 한 줄 추가한다. (가이드 보강)
또 그러면 아무도 못 알아챌 것 같다 → 린트 규칙이나 테스트를 추가한다. (센서 보강)

이 세 갈래 질문만 몸에 붙여도 하네스는 알아서 자랍니다.

두 번째 원칙은 "품질을 왼쪽으로 당기기(keep quality left)"입니다. 검사를 최대한 앞단으로 옮기라는 뜻이에요. 빠른 검사(린트, 타입 체크)는 커밋 전에, 비싼 검사(변이 테스트, 상세 AI 리뷰)는 통합 후 파이프라인에, 그리고 배포 이후에는 모니터링으로 이어지게 배치합니다. 건강검진 비유가 어울립니다. 매일 체중계에 올라가는 건 싸고 빠르니까 자주 하고, MRI는 비싸니까 이상 신호가 있을 때 찍죠. 둘을 바꿔 하면 돈도 시간도 낭비입니다.

세 번째, 함정도 알고 계셔야 합니다. Lilian Weng이 정리한 병목 중 주니어 개발자가 특히 조심할 것 두 가지만 뽑겠습니다.

약한 평가자(weak evaluator). 검증이 허술하면 하네스는 오히려 틀린 것을 통과시켜주는 도장이 됩니다. 커버리지 숫자만 채우는 테스트가 대표적이에요. 검사를 늘리기 전에 그 검사가 진짜로 무언가를 잡아내는지 확인하세요.
보상 해킹(reward hacking). 목표를 "테스트 통과"로만 잡으면, 에이전트는 코드를 고치는 대신 테스트를 고쳐서 통과시킬 수도 있습니다. 그래서 테스트 파일 수정은 별도로 눈에 띄게 만들어두는 편이 좋아요.

여기에 저는 네 번째를 하나 더 얹고 싶습니다. 하네스도 비용입니다. 훅을 열 개 걸면 파일 하나 고칠 때마다 열 번 검사가 돕니다. 검사가 늘어날수록 에이전트가 재시도하는 횟수도 늘고, 그만큼 토큰과 시간이 나갑니다. 하네스는 많을수록 좋은 게 아니라, 우리 프로젝트가 실제로 자주 하는 실수를 정확히 겨냥할수록 좋습니다.

마지막으로, 오늘 이야기의 결론입니다.

2023년에는 "프롬프트를 잘 쓰는 사람"이 잘하는 사람이었습니다. 2026년 지금은 다릅니다. 에이전트가 일할 환경을 잘 설계하는 사람이 잘하는 사람입니다. 그리고 이 일은 사실 여러분에게 완전히 새로운 일이 아니에요. 좋은 온보딩 문서를 쓰고, 의미 있는 테스트를 짜고, CI를 걸고, 코드 리뷰 기준을 세우는 일 — 우리가 좋은 팀을 만들려고 늘 하던 일입니다. 하네스 엔지니어링은 그 일을, 이제 사람이 아니라 에이전트를 위해서도 하는 것뿐입니다.

그래서 저는 주니어 개발자분들께 이 흐름이 오히려 반갑다고 말씀드립니다. 요령이나 감이 아니라 엔지니어링의 기본기가 그대로 경쟁력이 되는 방향으로 가고 있거든요. 지침을 명확히 쓰고, 검증 가능한 형태로 목표를 정의하고, 실패를 재발 방지 장치로 바꾸는 습관. 그거 원래 좋은 개발자의 조건이었잖아요.

말은 여러분이 아니라 모델이 끕니다. 하지만 고삐를 어떻게 쥘지는 여전히 여러분이 정합니다.

참고 자료

하네스 엔지니어링이란? — 모델은 그대로 두고 AI 에이전트를 잘 일하게 만드는 기술

목차

전체 지도

1. 프롬프트를 아무리 잘 써도 왜 에이전트는 삽질할까?

2. 그래서 하네스란 도대체 무엇인가?

3. 프롬프트 → 컨텍스트 → 하네스, 무엇이 달라진 걸까?

4. 하네스는 무엇으로 이루어져 있을까?

5. 같은 모델인데 왜 도구마다 점수가 다를까?

6. 내 프로젝트에 하네스를 어떻게 깔아볼까?

① 지침 파일 — 가이드의 기본기 (30분)

② 훅 — 센서를 자동문으로 (20분)

③ 스킬 — 검증된 절차를 재사용 (20분)

④ 테스트 게이트 — "끝"의 정의 (20분)

⑤ 권한 좁히기 — 폭발 반경 줄이기 (10분)

7. 하네스는 어떻게 키워나가야 할까?

댓글