하네스 엔지니어링이란 — 프롬프트보다 환경이 결과를 바꾼다

2026년 4월 · AI 소식

프롬프트를 잘 쓰는 것만으로는 부족하다. 같은 모델을 써도 환경 세팅에 따라 결과가 크게 달라진다. 이걸 하네스 엔지니어링이라 부른다.

OpenAI가 Codex 발표 전후로 퍼지기 시작했다. Claude Code 소스 코드 유출 사건도 국내 확산의 트리거가 됐다. 해당 코드에서 발견된 구조들이 하네스 엔지니어링의 실체를 처음으로 보여줬기 때문이다.

개발자뿐 아니라 비개발자도 이 개념을 빠르게 흡수하고 있다. 프롬프트 트릭보다 AI가 일하는 구조를 설계하는 쪽이 더 중요하다는 것이 핵심이다. 이 글에서 개념과 실무 적용법을 정리했다.

목차

1. 하네스란 무엇인가
2. 프롬프트 엔지니어링의 한계
3. 세 단계 진화: 프롬프트 → 컨텍스트 → 하네스
4. 핵심 구성 요소 5가지
5. CLAUDE.md를 제대로 쓰는 법
6. 스킬 파일 설계
7. Hooks — AI가 무시 못 하는 강제 규칙
8. MCP 연결 시 주의점
9. 실무 적용 — Before/After로 보는 차이
10. 설계 시 핵심 원칙
11. 개발자가 아니어도 된다

하네스란 무엇인가

말에 씌우는 마구(馬具)에서 온 단어다. AI라는 말을 원하는 방향으로 이끄는 장치 전체가 하네스다. 모델 자체가 아니라 그 모델이 일하는 환경 전체를 설계하는 개념이다. 프롬프트 한 줄이 아니라 판 전체를 짜는 것이다.

컨텍스트 파일, 스킬 파일, MCP 서버, 실행 루프가 포함된다. 검증 프로세스와 사람 개입 시점까지 전부 하네스의 일부다. 사람도 하네스의 일부다. AI 혼자 돌아가는 시스템이 아니다.

AI에게 뭘 물어볼지가 아니다. AI가 일할 수 있는 판을 어떻게 짜는지의 문제다. 모델이 병목이 아니라 환경이 병목이라는 것이 핵심 주장이다. 같은 모델이라도 환경 세팅에 따라 결과가 10배 차이 나는 이유다.

프롬프트 엔지니어링의 한계

한때 "단계별로 생각해봐"(Chain-of-Thought) 한 문장이 수학 정답률을 39%p 올렸다(Wei et al. 2022, GSM8K 벤치마크). 2025년 Wharton GAIL 연구에서 최신 모델로 재측정했더니 약 3%p 수준으로 줄었다. 모델이 발전하면서 프롬프트 트릭의 효과가 소멸되고 있다는 근거다.

최신 모델일수록 이미 내장된 사고방식이 있다. 프롬프트로 조작할 여지가 줄어드는 것이다. 시스템 프롬프트를 아무리 정교하게 만들어도 근본적인 한계가 있다. 트릭을 찾는 데 시간을 쓰는 것보다 구조를 설계하는 쪽이 장기적으로 가성비가 높다.

반면 하네스는 모델이 업그레이드돼도 그대로 쓸 수 있다. 구조 자체가 모델에 종속되지 않기 때문이다. 올해 쓴 CLAUDE.md가 내년 모델에서도 동일하게 동작한다. 이것이 프롬프트가 아닌 하네스에 투자해야 하는 이유다.

세 단계 진화: 프롬프트 → 컨텍스트 → 하네스

흐름은 세 단계다. 프롬프트 엔지니어링에서 컨텍스트 엔지니어링으로, 그리고 하네스 엔지니어링으로 넘어가는 흐름이다. 각각 "뭘 물어볼까 → 뭘 보여줄까 → 어떻게 설계할까"로 구분된다. 지금은 세 번째 단계로 넘어가는 시점이다.

컨텍스트 엔지니어링은 AI에게 어떤 재료를 줄지 결정하는 것이다. 하네스는 그 재료를 담는 주방 전체를 설계하는 것이다. 재료만 좋아서는 안 된다. 도구 배치와 작업 순서도 같이 설계해야 한다.

의료 분야에서 이 차이를 보여준 사례가 있다. 관련 데이터를 제공하고 범위를 제한했더니 할루시네이션이 40%에서 0%로 줄었다. 모델 변경 없이. 컨텍스트를 바꾸는 것만으로 결과가 달라진 것이다. 하네스는 이 컨텍스트 설계를 포함한 더 넓은 개념이다.

핵심 구성 요소 5가지

하네스의 5대 요소는 Agent.md(CLAUDE.md), 스킬, MCP, Hooks, 서브에이전트다. 각각 역할이 다르고 조합해서 쓴다. 어떤 도구를 쓰는가보다 이 5가지 구조를 얼마나 잘 설계하는가가 결과를 가른다.

Claude Code와 Cursor 양쪽에서 동일하게 적용할 수 있는 구조다. 도구에 무관하게 하네스 구조는 동일하게 동작한다. 어떤 AI 코딩 도구를 쓰는지보다 이 구조를 갖췄는지가 더 중요하다.

CLAUDE.md를 제대로 쓰는 법

CLAUDE.md(또는 Agent.md)는 하네스의 기반이 되는 파일이다. 프로젝트 구조, 코딩 규칙, AI가 따라야 할 기준을 명문화한다. 일반적 합의는 300줄 미만이다. HumanLayer는 자사 프로젝트에서 60줄 미만으로 유지한다고 밝혔다. ETH Zurich 연구에서는 LLM이 자동 생성한 CLAUDE.md가 오히려 토큰 비용을 20% 증가시키고 성과가 떨어졌다. 사람이 직접 쓰는 것이 낫다.

핵심은 "Claude가 코드를 읽고 스스로 파악 가능한 것"은 안 쓴다는 거다. 표준 언어 규약, 파일별 설명 같은 건 적지 않는다. 반대로 "코드만 봐서는 알 수 없는 것"은 반드시 써야 한다. Bash 커맨드, 브랜치 규칙, 프로젝트 고유 아키텍처 결정 같은 것이다.

파일 위치에 따라 적용 범위가 달라진다. ~/.claude/CLAUDE.md는 모든 프로젝트에 적용된다. 프로젝트 루트의 CLAUDE.md는 해당 프로젝트만. CLAUDE.local.md는 개인 설정용으로 .gitignore에 넣는다. 모노레포에서는 하위 폴더에 별도 CLAUDE.md를 두면 계층적으로 적용된다.

모든 것을 CLAUDE.md에 넣지 않는다. 별도 문서를 참조하는 Progressive Disclosure 패턴이 핵심이다. 실제 예시를 보면 이렇다:

스킬 파일 설계

스킬 파일은 특정 업무의 전문 지식을 .claude/skills/ 폴더에 분리해두는 것이다. CLAUDE.md와 차이는 "항상 로드 vs 필요할 때만 로드"다. CLAUDE.md에 다 넣으면 컨텍스트 윈도우를 낭비한다. 스킬은 해당 작업을 할 때만 로드된다.

실제 디렉토리 구조는 이렇다:

SKILL.md 파일 프론트매터에 name, description을 넣으면 슬래시 커맨드로 호출할 수 있다. disable-model-invocation: true면 AI가 알아서 호출하지 않고 사람이 직접 호출해야만 동작한다. 참조형 스킬과 작업형 스킬 두 가지로 나뉜다:

영상 제작 자동화에 적용한 사례가 있다. 리서처, 대본, 자막, 보이스, 씬 디자인, 렌더링, QA — 7개 에이전트 스킬로 분리했다. 9시간 걸리던 작업이 30분으로 줄었다.

Hooks — AI가 무시 못 하는 강제 규칙

Hooks는 프롬프트로 지시해도 AI가 무시할 수 있는 작업을 강제로 실행시키는 장치다. settings.json에 등록하면 특정 이벤트 발생 시 자동 실행된다. 프롬프트는 건너뛸 수 있다. Hooks는 건너뛸 수 없다. exit code 0이면 허용, 2면 차단이다.

실무에서 가장 많이 쓰는 Hook 5가지를 정리했다:

패키지 매니저를 강제하는 Hook도 유용하다. pnpm 프로젝트에서 AI가 npm을 쓰려 하면 차단한다:

MCP 연결 시 주의점

MCP는 AI 에이전트가 외부 도구를 쓸 수 있게 연결하는 어댑터다. USB 허브처럼 — Gmail, 브라우저 자동화, 문서 검색 같은 외부 기능을 AI에게 붙여주는 방식이다. 실무에서는 엑셀 작업 후 Gmail MCP로 보고 메일까지 자동 발송하는 식으로 쓴다.

주의할 점이 있다. MCP를 많이 연결할수록 좋지 않다. 토큰을 낭비하고 혼선이 생긴다. 필요한 것만 연결하는 것이 원칙이다. "억지로 MCP를 쓰는 것 같다"는 느낌이 들면 제거하는 것이 맞다.

실무 적용 — Before/After로 보는 차이

OpenAI Codex 실험이 대표 사례다. 5개월, 100만 줄 코드, 인간 직접 작성 0줄. PR 1,500개 머지. 엔지니어 1인 하루 평균 3.5개 작업을 완료했다. Terminal Bench 2.0에서도 동일 모델(Opus 4.6)이 기본 하네스(Claude Code 기본값)에서 40위, 최적화된 하네스에서 1위였다. 모델이 아니라 하네스가 순위를 갈랐다.

Mitchell Hashimoto(HashiCorp 창업자)는 핵심 원칙을 이렇게 요약했다. "에이전트가 실수할 때마다, 그 실수를 다시는 하지 않도록 엔지니어링하라." 실수를 고치는 게 아니라 실수가 불가능한 구조를 만드는 것이다.

구체적으로 어떻게 달라지는지 Before/After로 정리했다:

공통점은 하나다. 처음 세팅에 시간이 걸린다. 한 번 구축하면 이후 반복은 자동으로 빨라진다. 세팅 비용은 일회성이고 효과는 누적된다.

설계 시 핵심 원칙

최종 목표만 주면 안 된다. 중간 단계별 검증 기준도 반드시 명시해야 한다. "결과물을 내면 된다"가 아니라 "이 단계에서 이 기준을 통과해야 다음으로 넘어간다"는 방식이다. AI는 목표가 모호하면 지름길을 찾는다.

완전 자동보다 승인 게이트를 명시적으로 둔 반자동 구조가 현실적이다. 영상 제작 자동화 사례에서도 대본, 보이스, 씬 디자인, QA 4곳에 승인 게이트를 뒀다. AI 혼자 끝까지 달리는 게 아니라 사람이 중간중간 확인하는 구조다. 지금 기술 수준에서 이것이 현실적인 선택이다.

코드 패턴이 이상해지기 전에 수정한다. 좋은 규칙은 린터와 테스트로 고정한다. 낡은 규칙은 빠르게 제거한다. AI가 잘못된 과거 규칙을 따르면 문제가 누적된다.

개발자가 아니어도 된다

하네스 엔지니어링은 개발 전용 개념이 아니다. 엑셀 자동화, 영상 제작, 데이터 분석 같은 일반 업무에도 같은 구조가 동작한다. 바이브코딩을 모르는 사람도 하네스 설계는 가능하다. CLAUDE.md 파일 하나를 먼저 써보는 것으로 시작할 수 있다.

미래 개발자의 역할이 바뀌고 있다. 코드를 짜는 사람에서 에이전트가 잘 일할 수 있는 환경을 설계하는 사람으로. AI 개발의 핵심이 프롬프트에서 하네스로 이동했다. 처음 진입한다면 CLAUDE.md 하나부터 시작하면 된다.

자주 묻는 질문

Q. 하네스 엔지니어링과 프롬프트 엔지니어링의 차이는 무엇인가?

프롬프트 엔지니어링이 AI한테 무엇을 어떻게 물어볼지를 다듬는 기술이라면, 하네스 엔지니어링은 AI가 일할 수 있는 환경 전체를 설계하는 기술이다. 컨텍스트 파일, 스킬, MCP, Hooks, 실행 루프, 검증 프로세스, 사람 개입 시점까지 전부 포함된다. 프롬프트는 하네스의 일부다. 하네스는 프롬프트보다 큰 개념이다.

Q. CLAUDE.md는 얼마나 길게 써야 하나?

300줄 미만이 권장된다. 길수록 컨텍스트 윈도우를 잡아먹어 AI 성능이 떨어진다. 긴 설명서가 아니라 목차처럼 짧게 유지하는 것이 핵심이다. "어디서 뭘 찾는지"만 써도 충분하다. 세부 규칙은 스킬 파일로 분리한다.

Q. MCP는 많이 연결할수록 좋은가?

아니다. MCP를 많이 연결할수록 토큰 낭비와 혼선이 생긴다. 필요한 것만 연결하는 것이 원칙이다. 연결이 늘수록 AI가 어떤 도구를 써야 할지 판단하는 비용이 커진다. "억지로 쓰는 것 같다"는 느낌이 들면 제거하는 것이 맞다.

Q. 개발자가 아니어도 하네스 엔지니어링을 적용할 수 있나?

된다. 하네스 엔지니어링은 개발 전용 개념이 아니다. 엑셀 자동화, 영상 제작, 데이터 분석 같은 일반 업무에도 같은 구조가 동작한다. 바이브코딩을 모르는 사람도 하네스 설계는 가능하다. AI한테 어떤 규칙으로 일하게 할지를 문서로 정리하는 것이 전부다.

Q. 하네스 설계는 어디서부터 시작해야 하나?

CLAUDE.md(또는 Agent.md) 파일 작성부터 시작하는 것이 가장 빠르다. 프로젝트 구조, 코드 규칙, 완료 기준을 300줄 미만으로 명문화하는 것이 첫 번째 단계다. MCP나 스킬 파일은 그 다음에 추가한다. 처음부터 5가지 요소를 전부 갖출 필요는 없다.

이 글의 수치(OpenAI Codex 100만 줄, Terminal Bench 2.0, Wharton GAIL CoT 연구 등)는 공개된 발표 및 논문에서 인용한 것이다. 일부 수치는 원본 논문 또는 공식 블로그 포스트에서 별도 검증이 필요하다.

마지막 업데이트: 2026년 4월. 하네스 엔지니어링은 빠르게 발전 중인 개념이다. 도구·API·설정 방식은 언제든 변경될 수 있다.