하네스 엔지니어링: 프롬프트의 한계를 넘어 에이전트 환경을 설계하다

목차

• 프롬프트로 안 되는 걸 겪다
• 하네스가 뭔가
• 5개 팀이 실제로 한 것
• 6계층 하네스 설계
• 측정 결과
• 배운 것들
• 참고 자료

프롬프트로 안 되는 걸 겪다

가성비 모델(MiniMax M2.7)을 기반으로 만든 에이전트가 있었습니다. 이 에이전트는 한국어로 응답하다가 중간에 중국어 한자, 일본어 가타카나를 섞어 쓰는 문제가 있었습니다.

처음에 한 것은 무엇이었을까요. SOUL.md에 "한글만 써"라는 규칙을 넣었습니다. 그리고 Andrej Karpathy가 제안한 오토리서치 방식으로 최적의 프롬프트를 찾아나갔습니다. 가설을 세우고, 적용하고, 메트릭(한국어 순도 점수)으로 평가하고, 나아지면 유지하고 아니면 버리는 반복 루프를 10번 돌렸습니다. 영어로 규칙을 적으면 외래 문자가 줄어든다는 것도 이 과정에서 발견했습니다. 점수는 97.18에서 98.82로 올랐습니다.

그런데 정작 중요한 건 그게 아니었습니다.

에이전트가 "파일 저장했어요"라고 말하고 실제로는 저장하지 않았습니다. "검색하지 마"라고 해도 검색을 시도해서 타임아웃이 났습니다. 같은 질문에 한 번은 98점, 다음 번에는 38점이 나왔습니다.

이건 프롬프트로 고칠 수 있는 문제가 아니었습니다. 에이전트 주변의 환경, 즉 하네스의 문제였습니다.

참고로, 오토리서치 이전에는 번역 후처리 파이프라인으로 우회한 적도 있습니다. 에이전트가 영어로만 답하게 하고, 로컬 번역 모델(Ollama + TranslateGemma)으로 한국어로 변환하는 방식이었습니다. 이 방법도 작동은 했지만, 응답마다 2~7초가 추가되고 GPU 호환성 문제도 겪었습니다. RTX 5060 Ti를 쓰고 있었는데, 최신 아키텍처라 기존 Ollama 버전이 GPU를 인식하지 못했습니다. 최신 버전으로 업데이트하니 7초에서 2.4초로 줄었지만, 근본적인 해결은 아니었습니다.

프롬프트 엔지니어링: "똑똑하게 해라"고 말하는 것
하네스 엔지니어링: 에이전트가 똑똑하게 일할 수 있는 환경을 설계하는 것

이 차이를 깨닫고, 업계가 실제로 어떻게 하네스를 구축하는지 리서치하기 시작했습니다.

하네스가 뭔가

LLM 에이전트를 쓰다 보면 알게 되는 게 있습니다. 모델이 똑똑한 건 당연한 전제지, 실제 결과물의 품질은 에이전트를 어떻게 감싸느냐에 달려있다는 것입니다.

쉽게 비유하자면, LLM이 뇌라면 하네스는 몸통과 손발입니다. 뇌가 아무리 똑똑해도 몸이 제 역할을 하지 않으면 결과물은 엉망이 됩니다. 프롬프트를 아무리 다듬어도 세션이 바뀌면 비슷한 실수를 반복하고, 긴 작업을 시키면 갈수록 코드가 누적돼서 엉망이 됩니다.

기획을 하면서 늘 하던 생각이 있습니다. 문제를 정의하지 않고 해결책을 논하면 안 됩니다. 에이전트의 문제는 모델이 아니라 환경에 있다는 걸 깨달았을 때 비로소 진짜 해결책을 찾기 시작했습니다.

하네스를 한 다이어그램으로 정리하면 이렇습니다.

결정론적 가드레일

에이전트가 마음대로 아키텍처를 바꾸거나, 존재하지 않는 API를 호출하거나, 위험한 코드를 작성하지 못하도록 막는 장치입니다. 린터, 구조적 테스트, 아키텍처 룰이 여기에 해당합니다.

이게 중요한 이유는, 에이전트가 한 번 저지른 실수가 다음 세션에서도 반복되기 때문입니다. 인간 개발자라면 "아, 지난번에 이거 하다가 망쳤지" 하고 기억하지만, 에이전트는 세션이 끝나면 기억이 날아갑니다.

Terraform과 Ghostty를 만든 Mitchell Hashimoto가 자신의 블로그에서 이렇게 정리했습니다.

"에이전트가 실패하면, 에이전트를 고치지 마라. 환경을 고쳐라."

그가 제안한 누적 실패 가드레일은 에이전트가 한 번 실패한 경험을 규칙으로 변환해서, 다음 세션에서는 원천 차단하는 방식입니다. 에이전트가 학습하는 게 아니라, 하네스가 학습하는 것이죠.

시스템 오브 레코드

프로젝트 루트에 AGENTS.md 파일을 두어 에이전트가 반드시 따라야 할 규칙과 빌드 절차, 과거 실패에서 배운 교훈을 기록합니다. 에이전트가 매 세션 시작 시 이 파일을 읽게 되는데, 사실상 에이전트용 컨벤션 문서입니다.

기획할 때도 프로젝트 시작하면 온보딩 문서를 만듭니다. 에이전트도 마찬가지입니다. "이 프로젝트는 이런 규칙을 따른다"는 걸 명확하게 적어두면 에이전트가 매번 처음부터 배우지 않아도 됩니다.

피드백 루프

에이전트가 자신의 작업을 스스로 검증하고, 필요하면 다른 에이전트에게 리뷰를 요청하는 구조입니다.

에이전트가 "다 했어요"라고 말하는 순간 끝나는 게 아니라, 일련의 검증 파이프라인을 거쳐야 작업이 완료된 것으로 간주됩니다. 회사에서 코드 리뷰 없이 배포하지 않는 것과 같은 원리입니다.

5개 팀이 실제로 한 것

이게 혼자 고민한 문제가 아니라는 걸 확인하고 싶었습니다. 리서치해보니 OpenAI, Anthropic, Stripe, LangChain 모두 비슷한 결론에 도달해 있었습니다.

OpenAI Codex: 0줄의 수동 코드

OpenAI의 하네스 엔지니어링 글은 빈 깃 리포지토리에서 시작해서, 직접 타이핑한 코드 한 줄 없이 전체 코드베이스를 구축한 실험을 발표했습니다. 핵심 메커니즘은 세 가지입니다.

• AGENTS.md를 시스템 오브 레코드로 삼아, 에이전트가 따라야 할 아키텍처 제약과 빌드 규칙을 기록
• Ralph Loop(자가 리뷰 + 크로스 모델 리뷰)로 PR을 완성할 때까지 반복
• 가비지 컬렉션 에이전트로 에이전트가 누적시키는 기술 부채를 정기 정리

"에이전트는 충분히 유능하지만 혼자 믿을 수 없다. 하네스는 그걸 믿을 수 있게 만드는 거다." — Louis Bouchard

특히 인상 깊었던 건 가비지 컬렉션 개념이었습니다. 에이전트가 만든 코드는 인간이 짠 코드와 다르게 부패하는 패턴이 다릅니다. 인간은 점진적으로 리팩토링하지만, 에이전트는 누적된 컨텍스트 속에서 점점 더 복잡한 해결책을 시도하다가 코드를 뒤엎어버립니다. OpenAI는 이걸 감지하고 정리하는 전용 에이전트를 하네스에 포함시켰습니다.

LangChain DeepAgents: 모델 안 바꾸고 13.7점 상승

LangChain의 하네스 엔지니어링 블로그에서 가장 인상적인 데이터를 발견했습니다. 모델을 바꾸지 않고 하네스만 개선해서 Terminal Bench 2.0에서 52.8%에서 66.5%로 13.7점 상승했습니다. 순위는 Top 30에서 Top 5로 올랐습니다.

사용한 기법 세 가지입니다.

1. 미들웨어 훅: before_agent, wrap_model_call, wrap_tool_call로 에이전트 실행 루프에 검증 로직 삽입
2. 검증 강제: 에이전트가 종료하려고 하면 훅이 강제로 계속 실행시켜, 원래 스펙에 맞는지 검증
3. 사전 컨텍스트 전달: 에이전트가 스스로 찾아야 할 정보를 미리 제공

Stripe Minions: 주당 1,300개 PR

Stripe의 Minions 아키텍처는 완전 무인 코딩 에이전트를 1주일에 1,300개 PR을 생성하는 수준까지 끌어올렸습니다. 가장 독창적인 아이디어는 Blueprint 패턴이었습니다. 워크플로우를 두 가지 노드로 구성합니다.

• 결정론적 노드: 파일 I/O, 테스트 실행, 포맷팅 같은 고정된 동작
• 에이전트 노드: 코드 작성, 로직 추론 같은 AI 판단이 필요한 동작

이 둘을 하나의 워크플로우로 엮어서, 에이전트가 "생각해야 할 것"만 생각하게 만들었습니다.

"가장 비싼 함정은 에이전트가 고장 난 코드를 CI에 푸시하고, 에러를 읽고, 무한 토큰 소비 루프를 도는 것이다." — Stripe Engineering

Claude Code: 서브에이전트로 컨텍스트 격리

Claude Code는 서브에이전트라는 개념을 사용합니다. 긴 출력이나 복잡한 작업을 별도 에이전트에 맡기고, 프롬프트와 최종 결과만 부모에게 반환합니다. 이게 중요한 이유는 컨텍스트 오염 방지 때문입니다. 부모 에이전트의 컨텍스트 윈도우가 자식 에이전트의 중간 과정으로 채워지면, 부모의 추론 능력이 급격히 저하됩니다.

Anthropic의 엔지니어링 블로그에서도 비슷한 각도를 봤습니다. 문제는 긴 작업을 여러 세션에 걸쳐 진행할 때 컨텍스트가 끊기면 에이전트가 이전에 뭘 했는지 잊어버린다는 점이었습니다. 이니셜라이저 에이전트가 첫 세션에서 환경을 설정하고 진행 상황 파일을 남기면, 이후 세션의 코딩 에이전트가 그 파일을 읽고 이어서 작업하는 방식입니다.

Oh My OpenCode: 모델별 프롬프트 분리

Oh My OpenCode(OmO)는 44.8k 스타의 오픈소스 프로젝트로, 에이전트를 역할별로 분리하고 각 모델의 사고 방식에 맞춰 프롬프트를 따로 작성합니다.

"다른 모델은 다르게 생각한다. 각 에이전트의 프롬프트는 하나의 정신 모델에 맞춰 작성되었다."

• Claude: 체크리스트, 단계별 절차 (기계적)
• GPT: 기준 중심, 짧은 지시 (원칙 기반)

6계층 하네스 설계

이 리서치를 바탕으로, 가성비 모델 기반 에이전트를 위한 하네스를 6개 계층으로 설계했습니다.

Layer 번호는 범주 분류일 뿐, 적용 순서를 의미하지 않습니다. 실제 실행 흐름은 다이어그램을 따라 5→4→1→2→3→6 순서로 진행됩니다.

Layer 1: 검증 백프레셔

에이전트가 도구를 호출한 후 반드시 결과를 확인하도록 강제합니다.

## Tool Verification (MANDATORY)
1. After write_file: immediately read_file to confirm
2. After terminal: check the exit code
3. After patch: read_file to verify the change
NEVER say "done" without verifying.

이 규칙만으로도 "저장했어요"라고 하고 실제로 안 하던 문제를 대부분 줄일 수 있었습니다. 다만 단일 파일 작업처럼 검증이 종종 스킵되는 경우는 남아 있어서, 완전한 해결까지는 더 보완이 필요합니다.

Layer 2: 환경적 제약

에이전트에게 "이 도구 쓰지 마"라고 말하는 대신, 도구 자체를 없앴습니다.

# Before: 15개 도구
# After: 10개 도구
# 제거: browser, web, vision, image_gen, cronjob

핵심은 도구 선택지를 줄여 에이전트의 판단 공간을 좁히는 것입니다. 에이전트가 선택할 수 있는 도구가 적을수록, 잘못된 도구를 고를 확률도 함께 줄어듭니다.

Layer 3: 점진적 컨텍스트 노출

필요할 때만 스킬과 고급 도구를 로드하도록 규칙을 명시했습니다.

- Prefer fewer, verified actions over many unverified ones
- For general knowledge questions, answer without tools

Layer 4: 구조화된 작업 실행

Stripe의 Blueprint 패턴을 참고했습니다. 다단계 작업(3개 이상의 액션)은 반드시 계획-실행-검증-요약 순서를 따르도록 강제했습니다.

Layer 5: 에이전트 분리

Claude Code의 서브에이전트 패턴을 적용했습니다. 가성비 모델(gari2, MiniMax)이 혼자 풀기 어려운 작업을 고성능 모델(gari1, GLM-5.1)에게 위임합니다.

delegation:
  provider: zai
  model: glm-5.1
  base_url: https://api.z.ai/api/coding/paas/v4
  max_iterations: 30

실제 동작은 이렇습니다.

사용자 → gari2(MiniMax) → "이건 복잡한 작업이야"
    ↓ delegate_task
gari1(GLM-5.1) → 작업 수행 → 결과 반환
    ↓
gari2 → 한국어로 요약 → 사용자에게 전달

자식 에이전트는 부모와 완전히 독립된 세션에서 실행됩니다. 컨텍스트 윈도우가 분리되어 있고, 중간 과정은 버려지고 최종 결과만 부모에게 전달됩니다.

Layer 6: 평가 자동화

korean_purity 점수가 임계값(90.0) 이하로 떨어지면 알림을 기록하는 자동 평가 스크립트를 만들었습니다.

측정 결과

하네스를 적용하기 전과 후를 비교했습니다.

한국어 순도가 1.55포인트 하락한 것에 대해 설명드리겠습니다.

Before의 98.82는 한국어 순도에만 집중한 프롬프트 최적화의 결과였습니다. 10번 반복 실험으로 "영어로 규칙을 적으면 외래 문자가 줄어든다"는 것을 찾아내고, 그것만 집어서 다듬은 점수입니다.

After의 97.27은 검증, 구조화된 실행, 에이전트 분리, 평가 자동화라는 기능적 하네스를 추가한 상태에서의 점수입니다. 순도 1.55포인트를 희생해서 도구 신뢰성과 안정성을 얻었습니다.

Before: "한국어만 써" (프롬프트 엔지니어링)
After:  "한국어로 쓰고, 도구 호출 후 검증하고, 복잡하면 위임하고, 매일 점수를 측정해" (하네스 엔지니어링)

검증 테스트

6가지 항목으로 하네스가 실제로 작동하는지 확인했습니다.

검증 규칙이 PARTIAL인 이유는, 에이전트가 단일 파일 작업을 "간단한 작업"으로 판단해서 read_file 검증을 건너뛰기 때문입니다. 다단계 작업에서는 정상 작동하므로 심각하지는 않습니다.

배운 것들

프롬프트는 모델에게 "무엇을" 물어보는 것입니다. 하네스는 에이전트가 "어떻게" 일할지 설계하는 것입니다. 이 둘은 같은 레이어가 아닙니다. 프롬프트 엔지니어링을 10번 반복하면서 얻은 것보다, 하네스 엔지니어링을 1번 제대로 한 것에서 더 많은 것을 얻었습니다.

같은 모델, 다른 결과. LangChain은 모델을 바꾸지 않고 하네스만 개선해서 13.7점을 올렸습니다. 저도 모델(MiniMax)을 그대로 두고 도구 사용 규칙, 검증 절차, 에이전트 분리만 추가해서 신뢰성을 개선하는 중입니다.

스킬은 만들고 안 쓰면 의미가 없습니다. 115개의 스킬을 만들고, 감사하고, 고치고, 포팅하는 데 며칠을 썼습니다. 하지만 정작 실제 작업할 때 그 스킬들을 로드하지 않았습니다. using-superpowers라는 메타 스킬에 "적용 가능한 스킬이 1%라도 있으면 반드시 로드하라"는 규칙을 적어놓고도 스스로 안 지켰습니다. 에이전트의 행동을 변화시키는 것은 스킬의 내용이 아니라, 그 스킬을 실제로 로드하고 따르는지에 달려있습니다.

복잡한 규칙일수록 나쁩니다. 10번의 프롬프트 실험에서, 구체적인 예시를 넣거나 자가 점검을 지시하거나 규칙을 반복하면 오히려 점수가 하락했습니다. 가장 간단한 영어 규칙 한 줄이 가장 좋았습니다. 모델이 발전하면 이 규칙도 필요 없어질 것입니다.

빌드가 성공해도 배포가 되는 건 아닙니다. 실제로 next-mdx-remote 취약점(CVE-2026-0969) 때문에 Vercel이 배포를 차단한 사례를 겪었습니다. 빌드 로그는 "Compiled successfully"였는데, 배포 로그 끝에 보안 경고가 숨어있었습니다. 기획할 때도 "QA를 통과해도 출시 가능한 건 아닌 것"처럼, 빌드뿐만 아니라 배포 로그 끝까지 확인하는 습관이 필요합니다.

에이전트 코드는 인간 코드와 다르게 부패합니다. 인간은 점진적으로 리팩토링하지만, 에이전트는 누적된 컨텍스트 속에서 점점 더 복잡한 해결책을 시도하다가 코드를 뒤엎어버립니다. 이건 에이전트의 버그가 아니라 에이전트의 특성이니, 그에 맞는 관리 방식이 필요합니다.

하네스는 모델이 나아짐에 따라 줄어들어야 합니다. 지금은 검증 규칙, 에이전트 분리, 도구 제거가 필요하지만, 나중에 더 강한 모델을 쓰게 되면 이런 제약 대부분은 불필요해질 것입니다. 하네스는 영구적인 인프라가 아니라, 현재 모델의 한계를 보완하는 임시 구조물입니다.

참고 자료

• OpenAI Harness Engineering — 하네스 엔지니어링의 개념 정의와 Codex 적용 사례
• LangChain: Improving Deep Agents — 모델 없는 13.7점 상승의 구체적 기법
• Stripe Minions Architecture — Blueprint 패턴과 무인 PR 시스템
• Anthropic: Effective Harnesses for Long-Running Agents — 이니셜라이저 에이전트와 멀티 세션 관리
• HumanLayer: Skill Issue — 4가지 커스터마이징 레버 분석
• Oh My OpenCode — 모델별 프롬프트 분리와 에이전트 카탈로그
• Mitchell Hashimoto: My AI Adoption Journey — 누적 실패 가드레일
• Martin Fowler: Harness Engineering — 하네스의 추상화 계층 관점
• obra/superpowers — 코딩 에이전트용 스킬 프레임워크
• Ralph Loop (Huntley) — 자율 반복 개발 루프
• Claude Code — 서브에이전트와 컨텍스트 격리