하네스 엔지니어링 완벽 정리 — AI 코딩 에이전트 성능을 2배로 올리는 5가지 레버

ALT

Harness Engineering이라는 단어가 적힌 표지판

하네스 엔지니어링이 뭔가요?

하네스 엔지니어링(Harness Engineering)은 AI 코딩 에이전트를 감싸는 시스템(규칙, 도구, 스킬, 메모리, 피드백 루프)을 설계하는 기술입니다.

승마에 비유하면 이해가 쉬워요. 말(AI 모델)이 아무리 강력해도, 고삐와 안장(하네스)이 없으면 원하는 방향으로 달릴 수 없잖아요. AI 코딩 에이전트도 마찬가지입니다. Claude Code든 Cursor든 Codex든, 모델 자체보다 그 모델을 감싸는 시스템이 결과를 결정합니다.

Terraform 창시자 Mitchell Hashimoto가 이렇게 정의했습니다: "에이전트가 실수할 때마다, 그 실수가 다시는 발생하지 않도록 시스템을 엔지니어링하라." 더 좋은 모델을 기다리지 말고, 모델을 둘러싼 시스템을 고치라는 것입니다.

왜 모델보다 하네스가 중요한가?

숫자가 모든 걸 말해줍니다.

• LangChain: 같은 모델(GPT-5.2-Codex)로 하네스만 바꿔서 Terminal Bench 2.0에서 52.8% → 66.5%, 30위권 밖에서 Top 5 진입

• OpenAI Codex 팀: 엔지니어가 코드를 직접 쓰는 대신 하네스(도구, 가드레일, 문서)를 설계하는 방식으로 대규모 프로덕션 애플리케이션 구축

• ETH Zurich 연구: 300개 SWE-bench 태스크 + 138개 AGENTbench 태스크로 검증 — 잘 설계된 하네스가 모델 성능을 좌우

모델 업그레이드로는 이런 도약이 쉽지 않습니다. 하지만 하네스 최적화만으로 25단계 이상의 순위 점프가 가능합니다.

Claude vs GPT vs Gemini 논쟁에 시간을 쓰고 있다면, 방향이 틀린 겁니다. 진짜 레버는 모델이 아니라 하네스에 있습니다.

하네스의 5가지 레버

1. 시스템 프롬프트 (CLAUDE.md / AGENTS.md)

저장소 루트에 두는 마크다운 파일로, 매 세션 시작 시 에이전트 컨텍스트에 주입됩니다. 기술 스택, 테스트 명령어, 코딩 컨벤션, 금지 규칙 등을 적습니다.

핵심 규칙:

• 60줄 이하로 유지

• 모든 태스크에 적용되는 범용 지침만 포함

• 디렉터리 구조 나열 금지 (에이전트가 알아서 탐색)

• 조건부 규칙 금지 ("X를 할 때는 Y" 같은 분기는 혼란을 유발)

• AI가 생성한 내용 금지 (ETH Zurich 연구: AI 생성 파일은 성능을 오히려 저하시키고 추론 비용을 약 20% 증가시킴)

# CLAUDE.md 예시
## Tech Stack
- TypeScript strict mode, React 19, PostgreSQL
## Rules
- Never delete migration files
- Always run tests before committing
- Use pnpm, not npm
## Testing
- pnpm test (unit), pnpm test:e2e (integration)

2. 스킬 (점진적 지식 공개)

모든 지식을 시스템 프롬프트에 넣는 대신, 태스크에 맞는 지식을 모듈로 분리합니다. DB 마이그레이션 스킬, API 엔드포인트 생성 스킬, 프론트엔드 컴포넌트 스킬을 각각 파일로 만들어두면, 에이전트가 필요할 때 자동으로 로드합니다.

이걸 점진적 공개(Progressive Disclosure)라고 합니다. 에이전트가 최소한의 컨텍스트로 시작하고, 필요할 때만 추가 지식을 불러오는 방식입니다. 컨텍스트 윈도우가 깨끗하게 유지되니 에이전트가 혼란에 빠지는 걸 막을 수 있습니다.

3. MCP 서버 (도구 확장)

MCP(Model Context Protocol)로 에이전트에 외부 도구를 연결합니다. Linear로 이슈 관리, Sentry로 에러 모니터링, DB에 직접 쿼리 등이 가능해집니다.

주의할 점: MCP 도구를 너무 많이 연결하면 "도구 선택 혼란(Tool Thrash)"이 발생합니다. 에이전트가 어떤 도구를 써야 할지 결정하는 데 시간을 낭비하게 되는 겁니다. 2~3개로 시작하고, 실제 한계에 부딪힐 때만 추가하세요.

4. 서브에이전트 (컨텍스트 방화벽)

흔한 오해가 있어요. "프론트엔드 에이전트"와 "백엔드 에이전트"를 나누는 게 아닙니다. HumanLayer 팀이 시도했다가 포기한 방법입니다.

서브에이전트의 진짜 용도는 컨텍스트 방화벽입니다. 메인 에이전트가 긴 태스크를 처리하다 컨텍스트가 꽉 차면, 세부 작업을 서브에이전트에 위임합니다. 서브에이전트는 독립된 컨텍스트에서 작업하고, 결과만 돌려줍니다. 중간 과정의 노이즈가 메인 스레드를 오염시키지 않습니다.

Chroma 연구에 따르면, AI 모델은 컨텍스트가 길어질수록 성능이 떨어집니다. 서브에이전트는 모델이 항상 "스마트 존"에 머물도록 만드는 장치입니다.

5. 훅 (자동 체크포인트)

비결정적 시스템(AI)에 결정적 제어를 추가하는 장치입니다. 에이전트 워크플로우의 특정 지점에서 자동으로 실행되는 스크립트예요.

실전 훅 예시:

• pre-commit: 커밋 전에 린터 + 테스트 자동 실행

• pre-completion: 태스크 완료 선언 전에 요구사항 검증

• loop-detection: 에이전트가 같은 수정을 반복할 때 감지

LangChain이 만든 PreCompletionChecklistMiddleware가 대표적입니다. 에이전트가 태스크를 끝내기 전에 원래 요구사항 대비 검증을 강제합니다. 이 훅 하나가 전체 하네스에서 가장 큰 성능 향상을 만들었습니다.

오늘 당장 시작하는 6단계

핵심은 매주 금요일 5분입니다. 그 주의 실패를 하나씩 하네스에 반영하면, 시간이 갈수록 에이전트가 신뢰할 수 있게 됩니다. 모델이 좋아져서가 아니라, 시스템이 학습하기 때문입니다.

💡 인사이트

프롬프트 엔지니어링(2023) → 컨텍스트 엔지니어링(2025) → 하네스 엔지니어링(2026). 이 흐름을 보면 재밌는 패턴이 보여요.

매번 "모델에게 뭘 말할까"에서 "모델을 둘러싼 시스템을 어떻게 설계할까"로 관심이 이동하고 있습니다. 프롬프트는 한 번의 입력이고, 컨텍스트는 한 세션의 배경이고, 하네스는 영구적인 시스템입니다. 점점 더 지속적이고 구조적인 방향으로 가고 있는 거예요.

한국 개발 현장에서 특히 주목할 점이 있습니다. 하네스 엔지니어링의 산출물(CLAUDE.md, 스킬 파일, 훅 스크립트)은 전부 코드 리포지토리에 커밋되는 파일입니다. 즉, 팀원이 바뀌어도, 모델이 바뀌어도, 축적된 하네스는 그대로 남습니다. 스타트업에서 시니어 개발자가 퇴사해도 하네스가 남아있으면 주니어가 같은 품질의 코드를 뽑을 수 있다는 거예요.

다만 현실적으로 조심할 게 있습니다. 원문에서 "60줄 이하"를 강조하는 데는 이유가 있어요. 하네스를 과하게 쌓으면 오히려 역효과가 납니다. 규칙이 서로 충돌하고, 컨텍스트가 비대해지고, 에이전트가 뭘 따라야 할지 헷갈려하거든요. "최소한의 규칙으로 최대 효과"가 하네스 엔지니어링의 진짜 기술입니다.