🟡 하네스 엔지니어링이란?
💡 이 문서의 핵심 질문: "모델을 잘 쓰는 것"과 "모델로 시스템을 만드는 것"은 어떻게 다를까?
1. 하네스(Harness)란 무엇인가
"하네스"는 원래 말(馬)에 씌우는 마구(馬具)에서 온 단어입니다. 말의 힘을 안전하게 제어하고 원하는 방향으로 이끄는 도구죠.
AI에서 **하네스(Harness)**는 언어 모델을 감싸는 구조적 시스템입니다. 모델 자체가 아니라, 모델이 올바르게 작동하도록 맥락, 도구, 제어 흐름, 메모리를 제공하는 외부 껍데기입니다.
┌─────────────────────────────────────┐
│ 하네스 (Harness) │
│ ┌───────────┐ ┌────────────────┐ │
│ │ 컨텍스트 │ │ 도구/권한 │ │
│ └───────────┘ └────────────────┘ │
│ ┌───────────┐ ┌────────────────┐ │
│ │ 메모리 │ │ 실행 루프 │ │
│ └───────────┘ └────────────────┘ │
│ ┌──────────┐ │
│ │ 모델 │ ← 핵심 엔진 │
│ └──────────┘ │
└─────────────────────────────────────┘비유로 이해하기:
- 모델 = 엔진 (강력하지만 혼자 굴러가지 않음)
- 하네스 = 자동차 전체 (엔진을 감싸고 조향·안전·연료 공급을 담당)
2. 왜 하네스가 중요한가
raw API만 쓰면 무슨 일이 생길까
# raw API 호출 — 가장 단순한 방식
response = anthropic.messages.create(
model="claude-opus-4-5",
messages=[{"role": "user", "content": "코드 리뷰해줘"}]
)이렇게 호출하면 모델 능력의 20% 이하밖에 활용하지 못합니다.
| 빠진 것 | 결과 |
|---|---|
| 프로젝트 컨텍스트 없음 | 엉뚱한 언어/프레임워크로 리뷰 |
| 파일 읽기 도구 없음 | 실제 코드를 못 봄 |
| 메모리 없음 | 이전 피드백을 기억 못 함 |
| 권한 제어 없음 | 잘못된 파일 수정 위험 |
| 실행 루프 없음 | 한 번 답하고 끝 |
하네스를 갖추면
하네스 = 컨텍스트 + 도구 + 메모리 + 권한 + 실행루프동일한 모델이 80% 이상의 능력을 발휘합니다. 모델이 좋아진 게 아니라, 모델을 제대로 활용하는 시스템이 갖춰진 것입니다.
⚠️ 중요한 관점 전환: AI 시스템의 품질은 모델 성능보다 하네스 설계에 더 크게 좌우됩니다.
3. 하네스 엔지니어링의 등장
AI 활용 역량은 세 단계로 진화해왔습니다.
1세대: 프롬프트 엔지니어링 (2022~2023)
"어떻게 질문하면 더 좋은 답을 얻을까?"
좋은 질문 → 더 나은 답변프롬프트를 잘 쓰는 것이 핵심 역량이었습니다. 하지만 프롬프트만으로는 복잡한 작업에 한계가 있었습니다.
2세대: 컨텍스트 엔지니어링 (2024~)
"모델에게 올바른 정보를 올바른 시점에 어떻게 줄까?"
프롬프트 + 관련 문서 + 히스토리 + 시스템 정보 → 훨씬 나은 결과RAG(검색 증강 생성), 메모리 시스템, 컨텍스트 윈도우 관리가 주요 관심사가 됐습니다.
3세대: 하네스 엔지니어링 (2025~)
"모델이 실제 환경에서 자율적으로 작동하는 시스템을 어떻게 설계할까?"
컨텍스트 + 도구 + 실행 루프 + 메모리 + 권한 = 자율 에이전트 시스템단순히 "좋은 답변"을 넘어서, 모델이 작업을 완수할 수 있는 전체 시스템을 설계하는 것이 핵심 역량입니다.
4. Claude Code 자체가 하네스다
Claude Code가 단순한 AI 채팅과 다른 이유를 생각해보세요.
| 구성 요소 | Claude Code에서의 구현 |
|---|---|
| 컨텍스트 | CLAUDE.md, .claude/rules/, 자동 코드베이스 읽기 |
| 도구 | Read, Write, Edit, Bash, Grep, Glob 등 |
| 메모리 | TODO.md, Plans.md, memory 파일 시스템 |
| 권한 제어 | settings.json allowedTools/deniedTools, Hooks |
| 실행 루프 | 대화 → 분석 → 도구 실행 → 결과 반영 → 반복 |
Claude Code는 Claude 모델을 코드 작업에 특화된 하네스로 감싼 것입니다. 모델이 아니라 하네스가 Claude Code를 Claude Code답게 만듭니다.
이 관점에서 커스터마이징을 보면
CLAUDE.md 작성 → 컨텍스트 레이어 개선
커스텀 명령어(/doc) → 실행 루프 제어
MCP 서버 연결 → 도구 레이어 확장
Hooks 설정 → 권한 레이어 강화여러분이 Claude Code를 커스터마이징하는 것 = 하네스를 직접 설계하는 것입니다.
5. 왜 지금 배워야 하는가
AI 모델의 성능은 빠르게 상향 평준화되고 있습니다. GPT-4o, Claude, Gemini 모두 비슷한 수준의 지능을 갖추게 됐습니다.
이제 차이를 만드는 것은 모델 선택이 아니라 하네스 설계 역량입니다.
10년 전: 알고리즘을 잘 짜는 개발자가 우위
5년 전: 클라우드 인프라를 잘 다루는 개발자가 우위
지금: AI 하네스를 잘 설계하는 개발자가 우위💡 다음 단계로 → 하네스 설계법에서 실제 5가지 레이어 설계 방법을 배워보세요.