하네스 엔지니어링이란?
하네스 엔지니어링(Harness Engineering)은 AI 코딩 에이전트를 감싸는 통제 시스템 — 규칙, 도구, 메모리, 자동화 트리거 — 을 설계하는 기술이에요.
"하네스"라는 단어부터 짚고 갈게요. Harness는 원래 말의 마구(馬具)를 뜻해요. 천 마력짜리 말이 있어도 마구 없이는 밭을 갈 수 없잖아요. AI 에이전트도 똑같아요. Claude든 GPT든 Codex든, 모델이 아무리 뛰어나도 "어떻게 일하라"는 시스템이 없으면 매번 다른 결과를 뱉어요. 그 시스템을 설계하는 게 하네스 엔지니어링이에요.
2026년 초부터 본격적으로 쓰이기 시작한 용어인데, 핵심 아이디어는 간단해요. 더 좋은 모델을 기다리지 말고, 지금 모델을 둘러싼 시스템을 개선하라. Terraform 만든 Mitchell Hashimoto가 이걸 이렇게 설명했어요 (의역). "에이전트가 실수하면, 다시는 그 실수가 안 나오게 시스템을 고쳐라."
실제로 효과가 있냐고요? LangChain은 같은 모델로 하네스만 바꿔서 벤치마크 순위를 30위권 밖에서 Top 5로 올렸어요. OpenAI Codex 팀은 엔지니어가 코드를 직접 쓰는 대신 하네스를 설계하는 방식으로 100만 줄 이상의 프로덕션 앱을 만들었고요. Stripe는 하네스를 통해 매주 1,300건 이상의 AI가 작성하고 엔지니어가 리뷰하는 PR을 처리하고 있어요.
하네스 엔지니어링 vs 프롬프트 엔지니어링 — 뭐가 다를까?
제일 많이 받는 질문이에요. "그냥 프롬프트 잘 쓰면 되는 거 아냐?"
전혀 다릅니다. 비유하자면, 프롬프트 엔지니어링은 택시 기사한테 "여기로 가주세요"라고 말하는 거고, 하네스 엔지니어링은 자율주행차의 내비게이션 시스템을 설계하는 거예요.
구분
프롬프트 엔지니어링
하네스 엔지니어링
범위
단일 입력(한 번의 질문)
영구적인 시스템 설계
지속성
세션이 끝나면 사라짐
파일로 저장, 팀 전체가 공유
대상
채팅 한 턴
에이전트의 전체 작업 흐름
구성 요소
텍스트 프롬프트 1개
규칙 + 도구 + 스킬 + 훅 + 메모리
재현성
같은 프롬프트도 결과가 다름
시스템이 일관된 결과를 보장
확장성
사람마다 다르게 씀
코드 저장소에 커밋되어 팀이 공유
적합한 상황
단발성 질의응답
장기 프로젝트, 복잡한 코딩 작업
핵심 차이를 하나만 기억하세요. 프롬프트는 일회성 입력이고, 하네스는 영구적인 시스템이에요. CLAUDE.md, 스킬 파일, 훅 스크립트 — 이것들은 전부 코드 저장소에 커밋되는 파일이에요. 팀원이 바뀌어도, 모델이 업그레이드돼도, 하네스는 그대로 남아요.
하네스 엔지니어링 핵심 요소 5가지
그러면 하네스는 구체적으로 뭘로 이루어져 있을까요? 제가 실제로 쓰고 있는 5가지 요소를 정리했어요.
1. CLAUDE.md / 시스템 프롬프트
에이전트가 매 세션 시작할 때 읽는 설정 파일이에요. 프로젝트의 기술 스택, 코딩 컨벤션, 금지 규칙을 적어둡니다.
제가 실제로 쓰는 프로젝트의 CLAUDE.md 일부를 보여드릴게요:
# CLAUDE.md
## Tech Stack
- Next.js 15, TypeScript strict, PostgreSQL, Drizzle ORM
## Rules
- 기획서/리포트에 가정치 금지. 실측 데이터만, 모르면 TBD 표시
- 파일 삭제 전 반드 시 확인 요청
- 커밋 메시지는 영어로, conventional commits 형식
## Testing
- pnpm test (unit), pnpm test:e2e (integration)
- 테스트 없이 PR 올리지 않기
## Bug Log
- [2026-03-15] API 라우트에서 try-catch 빠뜨려서 500 에러 → 모든 API 핸들러에 에러 처리 필수
- [2026-04-02] 마이그레이션 파일 삭제해서 DB 깨짐 → 마이그레이션 파일 절대 삭제 금지
포인트는 60줄 이하로 유지하는 거예요. 규칙이 많으면 에이전트가 뭘 따라야 할지 혼란스러워하거든요. 그리고 Bug Log가 핵심이에요. 세션 간 메모리가 없는 AI에게 "전에 이런 실수 했으니까 다시 하지 마"라고 알려주는 장치예요.
2. MCP 서버 연결
MCP(Model Context Protocol)는 에이전트에게 외부 도구를 연결하는 표준이에요. 데이터베이스 조회, 이슈 트래커 확인, 웹 검색 같은 능력을 추가할 수 있어요.
예를 들어 저는 이런 MCP 서버들을 연결해서 쓰고 있어요:
Google Search Console — SEO 데이터 조회
Gmail — 이메일 분석
Notion — 문서 검색/업데이트
Google Calendar — 일정 확인
주의할 점이 하나 있어요. MCP 도구를 너무 많이 연결하면 "도구 선택 혼란(Tool Thrash)"이 생겨요. 에이전트가 어떤 도구를 써야 할지 고민하느라 시간을 낭비하는 거예요. 2~3개로 시작하고, 실제로 한계에 부딪힐 때만 추가하세요.
3. Skills / Plugins
모든 지식을 CLAUDE.md에 넣으면 컨텍스트가 비대해져요. 대신 태스크별 지식을 별도 파일로 분리하는 게 스킬이에요.
예를 들어 저는 "GPTers 게시글 작성"이라는 스킬을 만들어뒀어요. 이 스킬에는 글 구조, 톤, SEO 키워드 배치 규칙이 들어있어요. "게시글 써줘"라고 하면 에이전트가 이 스킬을 자동으로 로드하고, 다른 작업할 때는 로드하지 않아요.
이걸 점진적 공개(Progressive Disclosure)라고 해요. 에이전트가 최소한의 컨텍스트로 시작하고, 필요할 때만 추가 지식을 불러오는 방식이에요. 컨텍스트 윈도우가 깨끗하게 유지되니까 성능이 훨씬 좋아져요.
4. Hooks (자동화 트리거)
비결정적 시스템(AI)에 결정적 제어를 추가하는 장치예요. 에이전트 작업의 특정 시점에서 자동으로 실행되는 스크립트예요.
실제로 쓸 수 있는 훅 예시:
PreToolUse — 도구 실행 전 검증 (예: 위험한 명령어 차단)
PostToolUse — 도구 실행 후 처리 (예: 파일 변경 시 자동 린팅)
Stop (프롬프트 기반) — 작업 완료 전 요구사항 검증
LangChain은 자체 프레임워크에서 작업 완료 전 검증 미들웨어를 추가해 벤치마크 순위를 대폭 올렸어요. Claude Code에서는 Stop 훅의 프롬프트 기반 검증으로 비슷한 효과를 낼 수 있어요. 에이전트가 "다 했습니다"라고 선언하기 전에, 원래 요구사항 대비 검증을 강제하는 거예요.
5. Memory (컨텍스트 유지)
AI 에이전트의 가장 큰 약점이 뭘까요? 세션이 끝나면 다 잊어버린다는 거예요. Memory는 이 문제를 해결해요.
세션 중에 발견한 중요한 정보 — 사용자 선호, 프로젝트 컨텍스트, 과거 실수 — 를 파일에 저장하고, 다음 세션에서 자동으로 불러오는 거예요. CLAUDE.md의 Bug Log도 Memory의 한 형태고, 별도의 MEMORY.md 파일을 두는 방법도 있어요.
하네스 엔지니어링 실전 예시 3가지
이론은 충분하니까 실전으로 가볼게요.
예시 1: 코드 리뷰 자동화 (CLAUDE.md + Hooks)
매번 PR 올릴 때마다 같은 실수를 반복하는 팀원이 있나요? 하네스로 해결할 수 있어요.
CLAUDE.md에 추가할 규칙:
## Code Review Rules
- 모든 함수에 JSDoc 주석 필수
- console.log는 커밋 전에 제거
- API 응답에 에러 핸들링 없으면 리젝
- 새 파일은 반드시 테스트 파일 동반
Hooks 설정 (.claude/settings.json):
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash(git commit*)",
"hook": ".claude/hooks/pre-commit-check.sh"
}
]
}
}
pre-commit-check.sh:
#!/bin/bash
# console.log 남아있으면 커밋 차단
if grep -r "console.log" --include="*.ts" --include="*.tsx" src/; then
echo "ERROR: console.log가 남아있습니다. 제거 후 다시 커밋하세요."
exit 1
fi
# 테스트 실행
pnpm test --bail
이렇게 설정해두면 에이전트가 커밋하려고 할 때 자동으로 검증이 돌아가요. 사람이 리뷰하기 전에 기본적인 실수가 걸러지는 거예요.
예시 2: 콘텐츠 작성 파이프라인 (Skills + MCP)
저는 커뮤니티 게시글을 주 3~4회 작성하는데, 매번 같은 규칙을 설명하기 귀찮아서 스킬로 만들었어요.
스킬 파일 (.claude/skills/gpters-post/skill.md):
# GPTers 게시글 작성 스킬
## 톤
- 캐주얼 또는 믹스 (딱딱한 논문체 금지)
- "~에요/~예요" 체 사용
## 구조
- 제목: Google SEO 최적화 (키워드 포함)
- 첫 문단: 핵심 정의 + "이 글을 읽으면 ~을 알게 됩니다"
- 본문: H2 5~7개, 각 H2 아래 구체적 예시 포함
- 마무리: 개인 인사이트로 마감
## SEO
- main_keyword는 H1, 첫 문단, H2 2개 이상에 포함
- 2,500자 이상
MCP 연동: Google Search Console MCP로 키워드 데이터를 조회하고, 어떤 키워드가 노출은 많은데 클릭이 적은지 파악한 다음, 그 키워드를 타겟으로 글을 쓰게 해요.
실제 워크플로우가 이래요:
"이번 주 GSC 데이터 분석해줘" → MCP가 Search Console 데이터 가져옴
"노출 대비 클릭률 낮은 키워드 찾아줘" → 에이전트가 분석
"이 키워드로 게시글 써줘" → 스킬이 자동 로드되어 규칙에 맞게 작성
이 파이프라인 덕분에 게시글 하나 쓰는 시간이 2시간에서 30분으로 줄었어요.
예시 3: 데이터 분석 워크플로우 (MCP + Memory)
주간 마케팅 리포트를 자동으로 생성하는 세팅이에요.
MCP 연결:
Google Search Console → 검색 트래픽 데이터
Google Calendar → 이번 주 일정 컨텍스트
Memory 활용 (.claude/memory/MEMORY.md):
## 주간 리포트 컨텍스트
- EBP(Effective Buyer Pool) 지표가 핵심 KPI
- WAU, 키워드 섹션은 제거됨 (2026-04 피드백 반영)
- 채널별 변화만 포함
- 리포트 형식: EBP 숫자 + 채널 변화 요약
에이전트가 매주 리포트를 만들 때 이 Memory를 읽고, "아, 지난번에 WAU 섹션 넣었다가 빼라고 피드백 받았지"라는 걸 기억하는 거예요. Memory가 없으면 매번 같은 실수를 반복하고, 매번 같은 피드백을 줘야 해요.
이게 하네스 엔지니어링의 핵심 가치예요. 시스템이 학습하니까 사람이 반복하지 않아도 돼요.
하네스 엔지니어링 시작하는 법
지금 바로 시작할 수 있어요. 오늘 딱 15분만 투자하세요.
Step 1 — CLAUDE.md 만들기 (5분)
프로젝트 루트에 CLAUDE.md 파일 하나 만드세요. 처음엔 이것만 적으면 돼요:
# CLAUDE.md
## Tech Stack
- (여기에 기술 스택)
## Rules
- (절대 하면 안 되는 것 3가지)
## Testing
- (테스트 실행 명령어)
Step 2 — Bug Log 시작하기 (1분)
에이전트가 실수할 때마다 CLAUDE.md 하단에 한 줄 추가하세요:
## Bug Log
- [날짜] 무슨 실수 → 어떻게 방지
이것만 해도 같은 실수 반복률이 확 줄어요.
Step 3 — 반복 작업 하나를 스킬로 만들기 (5분)
"이 작업할 때는 항상 이렇게 해줘"라고 매번 말하는 게 있으면, 그걸 .claude/skills/ 폴더에 마크다운 파일로 저장하세요.
Step 4 — 매주 금요일 5분 리뷰 (지속)
그 주에 에이전트가 한 실수를 하나 골라서 CLAUDE.md에 규칙으로 추가하세요. 주 1회, 5분이면 돼요. 한 달만 하면 에이전트가 눈에 띄게 달라져 있을 거예요.
마무리 — 하네스 엔지니어링이 중요한 이유
프롬프트 엔지니어링(2023) → 컨텍스트 엔지니어링(2025) → 하네스 엔지니어링(2026). 이 흐름을 보면 패턴이 보여요. "모델에게 뭘 말할까"에서 "모델을 둘러싼 시스템을 어떻게 설계할까"로 관심이 이동하고 있어요. 프롬프트는 일회성 입력이고, 컨텍스트는 한 세션의 배경이고, 하네스는 영구적인 시스템이에요.
가장 중요한 건 이거예요. 하네스의 산출물(CLAUDE.md, 스킬 파일, 훅 스크립트)은 전부 Git에 커밋되는 파일 이에요. 팀원이 바뀌어도, 모델이 바뀌어도, 축적된 하네스는 남아요. 결국 AI 시대의 경쟁력은 모델 선택이 아니라, 모델을 얼마나 잘 길들이는 시스템을 가지고 있느냐에 달려 있어요.
오늘 15분 투자해서 CLAUDE.md 하나 만드는 것부터 시작해보세요. 그게 하네스 엔지니어링의 첫 걸음이에요.
Sources:
