목차
- 1. 하네스 엔지니어링이란?
- 2. 프롬프트 엔지니어링 vs 하네스 엔지니어링 핵심 차이 5가지
- 3. 하네스 엔지니어링의 4가지 핵심 구성요소
- 4. 실전 도구별 하네스 구현 비교
- 5. 하네스 엔지니어링 실전 적용 5단계
- 6. 바이브 코딩과 하네스 엔지니어링의 관계
- 자주 묻는 질문 (FAQ)
하네스 엔지니어링이라는 단어를 처음 들었을 때, 솔직히 “또 새로운 버즈워드인가?” 싶었습니다. 하지만 직접 Claude Code로 블로그를 운영하면서 CLAUDE.md를 수십 번 수정하고, 스킬과 에이전트를 분리해 본 경험이 쌓이니까 깨달았습니다. 제가 이미 하네스 엔지니어링을 하고 있었다는 걸요.
2026년 현재, AI 에이전트를 단순히 “잘 질문하는 것”만으로는 부족합니다. 에이전트가 실수하지 않도록 환경 자체를 설계하는 하네스 엔지니어링이 개발자와 AI 활용자의 핵심 역량으로 떠오르고 있습니다. Martin Fowler, OpenAI, Anthropic이 모두 이 개념을 공식적으로 다루기 시작했고, 이 글에서는 하네스 엔지니어링 뜻부터 실전 적용법까지 5가지 핵심 전략으로 정리합니다.
1. 하네스 엔지니어링이란?
Agent = Model + Harness
하네스 엔지니어링의 핵심 공식은 간단합니다.
AI 에이전트 = AI 모델 + 하네스(Harness)
여기서 하네스란 AI 모델을 제외한 모든 제어 시스템을 말합니다. 도구 설정, 권한 관리, 상태 관리, 테스트, 가드레일, 검증 루프 등 에이전트가 작동하는 환경 전체가 하네스입니다.
Martin Fowler는 이를 두 가지 축으로 정리합니다.
- 가이드(피드포워드): 문제가 발생하기 전에 방지하는 사전 안내
- 센서(피드백): 결과물 생성 후 문제를 감지하고 자체 수정하게 하는 장치
쉽게 말해, 이 접근법은 “AI한테 뭘 시킬까?”가 아니라 “AI가 일하는 환경을 어떻게 만들까?”를 설계하는 것입니다.
프롬프트 → 컨텍스트 → 하네스: 3세대 진화
AI 활용 방식은 뚜렷한 3세대로 진화해 왔습니다.
| 세대 | 시기 | 핵심 질문 | 대표 도구 |
|---|---|---|---|
| 프롬프트 엔지니어링 | 2022-2023 | 어떻게 물어볼까? | 텍스트 프롬프트 |
| 컨텍스트 엔지니어링 | 2024-2025 | 무엇을 보여줄까? | RAG, 메모리, 문서 주입 |
| 하네스 엔지니어링 | 2026~ | 어떤 환경에서 작동하게 할까? | 설정 파일, 훅, 에이전트, 검증 루프 |
이 세 가지는 계층 구조입니다. 상위 세대가 하위 세대를 포함하는 구조입니다. 프롬프트를 잘 쓰는 건 여전히 중요하지만, 그것만으로는 한계가 있다는 뜻이기도 합니다.
2. 프롬프트 엔지니어링 vs 하네스 엔지니어링 핵심 차이 5가지
“프롬프트만 잘 쓰면 되는 거 아냐?”라고 생각하실 수 있습니다. 저도 처음엔 그랬습니다. 하지만 실무에서 부딪혀 보면 차이가 확연합니다.
| 구분 | 프롬프트 엔지니어링 | 하네스 엔지니어링 |
|---|---|---|
| 지속성 | 세션이 끝나면 사라짐 | 파일/설정으로 영구 저장 |
| 버전 관리 | 거의 불가능 | Git으로 완전한 버전 관리 |
| 검증 | 모델이 지시를 따르는지 확인 불가 | 훅, 린터, 테스트로 강제 실행 |
| 표준화 | 사람마다 다른 프롬프트 | 팀 전체가 동일한 규칙 적용 |
| 범위 | 단일 프롬프트 | 에이전트의 전체 라이프사이클 |
실증 데이터도 있습니다. Stanford HAI 그룹의 연구에 따르면, 프롬프트 개선만으로는 AI 출력 품질이 3% 미만으로 향상된 반면, 하네스 수준의 변경(리트리벌 추가, 도구 접근, 구조화된 검증)은 28~47% 향상을 달성했습니다.
제가 직접 경험한 예를 들면, 블로그 글 작성 시 매번 “SEO 규칙을 지켜줘”라고 프롬프트에 쓰는 것보다 CLAUDE.md에 RankMath 19항목 체크리스트를 넣어두니까 글 품질이 훨씬 안정적이었습니다. 프롬프트는 잊을 수 있지만, 하네스는 잊지 않습니다.
3. 하네스 엔지니어링의 4가지 핵심 구성요소
3-1. 가이드(피드포워드) – 사전 안내 계층
가이드는 AI가 작업을 시작하기 전에 올바른 방향으로 이끄는 장치입니다.
- 규칙 문서: CLAUDE.md, AGENTS.md 같은 설정 파일
- 아키텍처 정의: 코드 구조, 모듈 경계, 네이밍 컨벤션
- 예제 코드: 원하는 패턴의 참고 코드
가이드를 잘 설계하면 AI가 처음부터 올바른 결과를 만들 확률이 높아집니다. 사후 수정보다 사전 방지가 훨씬 효율적이죠.
3-2. 센서(피드백) – 검증 계층
센서는 AI의 결과물을 검사하고, 문제가 있으면 자동으로 수정을 유도합니다.
- 계산적 센서: 린터, 타입 체커, 유닛 테스트처럼 빠르고 결정론적
- 추론적 센서: AI 기반 코드 리뷰처럼 느리지만 의미를 분석
예를 들어, 저는 블로그 글을 발행하기 전에 SEO 체크리스트를 자동으로 돌립니다. 키워드 밀도가 0.5% 미만이면 경고가 뜨고, H2/H3에 포커스 키워드가 없으면 자동으로 수정 제안이 나옵니다. 이게 바로 센서입니다.
3-3. 변경 주기별 하네스 배치
Martin Fowler는 하네스를 변경 주기에 따라 배치할 것을 권장합니다.
- 커밋 전: 린터, 빠른 테스트, 기본 코드 리뷰 에이전트
- 통합 후: 변경 감지 테스트, 광범위한 리뷰
- 지속적 모니터링: 사망 코드 감지, 의존성 스캔, SLO 모니터링
핵심 원칙은 “Keep quality left” — 품질 검사를 개발 프로세스 최대한 앞 단계에 배치하는 것입니다.
3-4. CAR 프레임워크
하네스의 구성을 체계적으로 정리하면 CAR 프레임워크가 됩니다.
- Control(제어): 린터, 타입 체크 같은 제약 조건
- Agency(능력): MCP 서버, 서브 에이전트 같은 도구 제공
- Runtime(실행): 라이프사이클 훅과 복구 메커니즘
세 축의 균형이 중요합니다. Control만 강하면 에이전트가 아무것도 못 하고, Agency만 강하면 통제 불능이 됩니다.
4. 실전 도구별 하네스 구현 비교
4-1. Claude Code: CLAUDE.md + Skills + Agents + Hooks
Claude Code는 현재 가장 체계적인 하네스 시스템을 갖추고 있습니다. 4개 레이어로 구성됩니다.
CLAUDE.md (결정론적 레이어)
모든 세션, 모든 턴에 자동으로 시스템 프롬프트에 주입됩니다. 프로젝트 루트에 위치하며, 금지 행동, 코딩 컨벤션, 검증 명령 등을 정의합니다. 제가 운영하는 블로그에서는 SEO 규칙, 파일 경로, 플러그인 정책을 모두 CLAUDE.md에 넣어뒀더니 대화마다 반복 설명할 필요가 없어졌습니다.
Claude Code에 대해 더 자세히 알고 싶다면 Claude Code 사용법 7가지 – 2026 개발 생산성 12배 높이는 실전 가이드를 참고하세요.
Skills (확률론적 레이어)
스킬은 필요한 시점에만 컨텍스트에 추가되는 전문 지식입니다. CLAUDE.md가 항상 로드되는 것과 달리, 스킬은 “점진적 정보 공개(progressive disclosure)” 원칙을 따릅니다. 예를 들어 /write-post 스킬은 글 작성할 때만, /publish 스킬은 발행할 때만 활성화됩니다. 컨텍스트 효율이 훨씬 높죠.
Agents (컨텍스트 방화벽)
서브 에이전트는 독립된 컨텍스트 창에서 작업을 처리합니다. 장시간 실행되는 에이전트가 무관한 정보로 오염되는 것을 막습니다. 저는 blog-writer, blog-seo, blog-publisher로 에이전트를 분리해서 각각 글 작성, SEO 분석, 서버 배포만 담당하게 했습니다.
Hooks (강제 실행 레이어)
settings.json에 설정하며, 에이전트 라이프사이클의 특정 시점에 자동으로 실행됩니다. Git hooks와 개념적으로 동일하지만, AI 에이전트에 적용된다는 점이 다릅니다. 위험한 명령 차단, 타입 체크, 빌드 검증 등에 사용합니다.
Anthropic은 2026년 6월 이 네 레이어 전체를 아우르는 공식 가이드를 발행했습니다. Steering Claude Code: CLAUDE.md·Skills·Hooks·Subagents에서 각 레이어의 실전 예시와 권장 적용 순서를 확인할 수 있습니다. 특히 CLAUDE.md는 200줄 이내로 유지하고, 더 세분화된 규칙은 Rules·Skills로 분리하는 방식을 공식 권장하고 있습니다.
4-2. OpenAI Codex: AGENTS.md + 커스텀 린터
OpenAI도 2026년 2월 공식 블로그에서 하네스 엔지니어링을 다뤘습니다. Codex 에이전트의 핵심 하네스는 다음과 같습니다.
- AGENTS.md: Claude의 CLAUDE.md에 대응하는 에이전트 동작 지침 문서
- 커스텀 린터: 에러 메시지 자체에 수정 방법을 주입해서 에이전트가 스스로 고치도록 설계
- 의존성 레이어 규칙: Types → Config → Repo → Service → Runtime → UI 순서로 의존성 흐름을 강제
OpenAI 내부에서 3명의 엔지니어가 5개월간 약 100만 줄 코드의 저장소에서 1,500개의 PR을 병합했다고 합니다. 엔지니어 1인당 하루 3.5개 PR이라는 놀라운 생산성입니다.
4-3. ChatGPT: Custom Instructions (기초 수준)
ChatGPT의 Custom Instructions는 이 분야의 가장 초보적인 형태입니다. 사용자 레벨의 영구 지침이지만, 버전 관리나 훅 같은 강제 실행 메커니즘이 없습니다. GPTs Builder는 한 단계 위로 시스템 프롬프트 + 도구 + 지식 파일을 결합하지만, 코드 수준의 검증 루프는 여전히 부족합니다.
| 도구 | 하네스 수준 | 핵심 한계 |
|---|---|---|
| ChatGPT Custom Instructions | ★☆☆☆☆ | 버전 관리·검증 불가 |
| ChatGPT GPTs Builder | ★★☆☆☆ | 코드 수준 검증 없음 |
| OpenAI Codex + AGENTS.md | ★★★★☆ | IDE 통합 미성숙 |
| Claude Code (전체 스택) | ★★★★★ | 학습 곡선 존재 |
5. 하네스 엔지니어링 실전 적용 5단계
“개념은 알겠는데 어디서부터 시작해야 하지?” 하는 분들을 위해, 제가 실제로 블로그 운영에 적용한 순서대로 정리합니다.
1단계: 규칙 문서 작성 (CLAUDE.md / AGENTS.md)
가장 먼저 할 일은 AI에게 영구적으로 적용할 규칙을 문서로 작성하는 것입니다.
작성 팁:
– 60줄 이하로 간결하게 유지 (길어질수록 컨텍스트 낭비)
– AI가 생성한 내용을 넣지 말 것 (노이즈 증가)
– 금지 행동을 명확히 정의 (“~하지 마라”가 “~해라”보다 효과적)
2단계: 스킬/에이전트 분리
모든 지식을 CLAUDE.md에 넣으면 컨텍스트가 낭비됩니다. 전문 작업은 스킬로, 역할별 작업은 에이전트로 분리하세요.
- 스킬: 특정 상황에만 필요한 전문 지식 (예: SEO 체크리스트, 배포 가이드)
- 에이전트: 독립된 역할의 작업자 (예: 리서치 담당, 코드 담당, 배포 담당)
Vercel의 사례가 흥미롭습니다. 에이전트에 제공하는 도구의 80%를 제거했더니 오히려 더 좋은 결과를 얻었다고 합니다. 도구가 적을수록 처리 단계, 토큰, 응답 시간이 줄어들기 때문입니다.
3단계: 훅/린터로 강제 검증
가이드만으로는 AI가 규칙을 “가끔” 무시합니다. 훅과 린터로 강제해야 신뢰도가 올라갑니다.
실전 예시:
– 커밋 전 자동 타입 체크
– 특정 디렉토리 밖 파일 수정 차단
– 위험한 CLI 명령 실행 전 사용자 확인
AI 에이전트의 보안 이슈가 궁금하다면 AI 에이전트 보안 위협 5가지와 기업 대응 전략도 확인해 보세요.
4단계: 변경 주기별 하네스 배치
모든 검증을 한꺼번에 돌리면 느립니다. 변경 주기에 따라 배치하세요.
- 빠른 주기 (매 턴): 문법 검사, 기본 규칙 검증
- 중간 주기 (커밋 시): 테스트 실행, 코드 리뷰
- 느린 주기 (배포 시): 통합 테스트, 성능 검증
5단계: 지속적 하네스 개선 루프
하네스는 한 번 만들고 끝이 아닙니다. AI가 반복적으로 같은 실수를 하면 그 패턴을 하네스에 추가합니다.
저도 처음에는 CLAUDE.md가 10줄이었는데, 글을 쓸수록 “아, 이 규칙도 넣어야겠다”가 반복되면서 지금은 체계적인 시스템이 되었습니다. 예를 들어 이미지 검색어를 한글로 보내면 엉뚱한 사진이 나오는 문제를 발견하고, pexels_query 영문 필드를 추가한 것도 하네스 개선의 한 예입니다.
6. 바이브 코딩과 하네스 엔지니어링의 관계
요즘 “바이브 코딩(Vibe Coding)”이라는 말을 많이 들어보셨을 겁니다. AI에게 대충 시키고 결과를 그대로 수락하는 방식이죠. 편하지만 위험합니다.
Addy Osmani(Chrome 팀 엔지니어)는 이 둘을 명확히 구분합니다.
- 바이브 코딩: “AI를 믿고 맡기기” — 고수준 프롬프트 → AI 제안 수락 → 코드 직접 검토 안 함
- 에이전틱 엔지니어링: “AI가 틀렸을 때 자동으로 잡기” — 아키텍처 정의 → 작업 분해 → 검증 루프 → 결과 검토
하네스는 에이전틱 엔지니어링을 가능하게 하는 인프라 레이어입니다. 바이브 코딩으로 프로토타입을 빠르게 만들되, 프로덕션에는 체계적인 제어 시스템을 갖추는 것이 현실적인 접근법입니다.
혹시 RAG나 검색증강생성에 관심이 있다면, 하네스와 함께 활용할 수 있는 RAG 활용법 5가지 – 2026 AI 검색증강생성 실전 가이드도 참고해 보세요.
자주 묻는 질문 (FAQ)
Q1. 하네스 엔지니어링은 개발자만을 위한 건가요?
아닙니다. ChatGPT의 Custom Instructions를 설정하는 것도 가장 기초적인 하네스 엔지니어링입니다. 다만 Claude Code처럼 파일 기반 시스템을 쓰면 더 정교한 제어가 가능합니다. 개발 경험이 있으면 유리하지만, 필수는 아닙니다.
Q2. 프롬프트 엔지니어링은 이제 필요 없나요?
프롬프트 엔지니어링은 여전히 기본 스킬입니다. 이 개념이 프롬프트 엔지니어링을 대체하는 게 아니라 포함합니다. 좋은 프롬프트 + 좋은 하네스가 최고의 조합입니다.
Q3. 하네스를 너무 많이 설정하면 AI가 제한되지 않나요?
Red Hat Developer의 아티클은 핵심 원칙을 이렇게 정리합니다. “솔루션 공간을 더 많이 제약할수록 출력이 더 예측 가능해진다.” 좋은 하네스는 AI의 자유를 빼앗는 게 아니라, 가장 중요한 곳에 AI의 능력을 집중시킵니다.
Q4. 하네스 엔지니어링을 배우려면 어디서 시작해야 하나요?
가장 추천하는 순서입니다.
1. Martin Fowler의 Harness Engineering for Coding Agent Users 원문 읽기
2. OpenAI의 Harness Engineering 공식 블로그 읽기
3. Anthropic의 Steering Claude Code 공식 가이드 읽기 — CLAUDE.md, Rules, Skills, Hooks, Subagents 실전 적용법 수록
4. Claude Code를 설치하고 CLAUDE.md부터 작성해보기
5. 작은 프로젝트에 skills과 hooks를 하나씩 추가하며 실험
Q5. 2026년 이후 하네스 엔지니어링의 전망은?
“2025년의 주제가 에이전트였다면, 2026년의 주제는 에이전트 하네스”라는 분석이 나오고 있습니다. 에이전트 자체보다 에이전트를 신뢰할 수 있게 만드는 시스템이 핵심 경쟁력이 될 것입니다. harn.app, skilldeck 같은 하네스 전용 도구들도 속속 등장하고 있어, 이 분야의 생태계가 빠르게 성장 중입니다.
이 글은 정보 제공 목적으로 작성되었으며, 특정 도구나 서비스의 사용을 권장하지 않습니다. AI 도구의 기능과 가격은 수시로 변경될 수 있으니, 반드시 공식 문서를 확인하세요.
