[AI] AI 하네스 엔지니어링 — 모델을 넘어 스캐폴딩을 설계하기
AI 하네스 엔지니어링 — 모델을 넘어 스캐폴딩을 설계하기
요즘 에이전트를 만들다 보면 이상한 경험을 하게 된다. 같은 모델을 쓰는데 어떤 도구는 놀랍도록 안정적으로 일을 끝내고, 어떤 도구는 두 번에 한 번 꼴로 헛발질을 한다. 처음엔 "모델이 더 좋아서겠지"라고 넘겼는데, 파고들수록 그게 아니었다. 진짜 차이는 모델을 감싸고 있는 엔지니어링, 즉 하네스(harness)에 있었다.
이 글에서 하고 싶은 주장은 하나다. 모델 성능은 상한선을 정하지만, 실제 신뢰성을 결정하는 건 하네스다. 2026년 초 기준으로 프론티어 모델 간 raw 능력 격차는 계속 좁혀지고 있고, 오히려 그 모델을 어떻게 오케스트레이션하느냐가 제품의 품질을 가른다. Claude Code든 Codex든, 결국 우리가 감탄하는 건 모델 그 자체가 아니라 그 위에 얹힌 하네스인 경우가 많다.
하네스란 무엇인가
하네스는 원래 말이나 낙하산에 채우는 마구(馬具), 통제 장치를 뜻한다. AI 맥락에서 하네스는 raw LLM을 실제로 일을 하는 에이전트로 바꿔주는 모든 주변 엔지니어링을 가리킨다.
raw 모델은 사실 단순하다. 텍스트를 넣으면 다음 토큰을 뱉는 함수일 뿐이다. 이 함수를 신뢰할 수 있는 소프트웨어 컴포넌트로 승격시키려면 다음이 필요하다.
- 컨텍스트 관리: 무엇을 넣고, 무엇을 버리고, 무엇을 다시 불러올지
- 도구 오케스트레이션: 어떤 도구를 언제, 어떤 권한으로 호출할지
- 검증 루프: 모델의 출력을 실행하고, 관찰하고, 틀렸으면 되돌리는 구조
- 서브에이전트 팬아웃: 큰 작업을 병렬로 쪼개고 결과를 합치는 구조
- 계획과 실행의 분리: 먼저 생각하게 하고, 그다음 행동하게 하는 분리
- 메모리: 세션을 넘어 지속되는 상태
- 권한 게이팅: 위험한 행동 앞에 세워두는 관문
이걸 다 합치면 하나의 시스템이 된다. 그리고 이 시스템의 품질이 모델의 품질만큼, 때로는 그 이상으로 중요하다.
컨텍스트 엔지니어링 — 하네스의 심장
에이전트가 오래 돌수록 컨텍스트 윈도우는 금방 차오른다. 그리고 컨텍스트가 지저분해지면 모델은 급격히 멍청해진다. 흔히 말하는 "context rot" 현상이다. 그래서 좋은 하네스의 첫 번째 조건은 컨텍스트를 능동적으로 경영하는 것이다.
컴팩션(compaction)
대화가 길어지면 앞부분을 요약해서 압축하고, 핵심 결정과 상태만 남긴다. 무작정 자르는 게 아니라, "지금 이 작업을 계속하는 데 필요한 것"을 기준으로 접는 게 관건이다. 파일 경로, 실패한 시도, 확정된 결정 같은 건 살리고, 장황한 도구 출력 raw dump는 버린다.
리트리벌(retrieval)
모든 걸 컨텍스트에 넣을 순 없으니, 필요할 때 필요한 것만 가져온다. 코드베이스 전체를 프롬프트에 밀어넣는 대신, 검색 도구로 관련 파일만 그때그때 끌어온다. 2026년 초 기준으로는 "미리 다 넣기"보다 "필요할 때 찾아오기"가 확실히 이기고 있다. just-in-time 컨텍스트가 정답에 가깝다.
메모리(memory)
세션을 넘어 지속되어야 하는 정보는 파일이나 외부 저장소에 적어둔다. 이 블로그 프로젝트만 해도 MEMORY.md에 과거 결정들이 쌓여 있고, 에이전트는 매번 그걸 읽고 시작한다. 메모리는 컨텍스트 윈도우의 한계를 우회하는 가장 실용적인 트릭이다.
도구 오케스트레이션과 권한 게이팅
모델에게 도구를 쥐여주는 순간, 하네스는 갑자기 위험해진다. 파일을 지우고, 명령을 실행하고, API를 호출할 수 있게 되니까. 여기서 하네스의 진짜 엔지니어링이 시작된다.
핵심 원칙 몇 가지.
- 도구는 좁고 명확하게:
run_anything같은 만능 도구보다read_file,edit_file,run_tests처럼 의도가 드러나는 도구가 모델을 덜 헷갈리게 한다. - 권한은 단계적으로: 읽기는 자유, 쓰기는 확인, 파괴적 행동은 명시적 승인. 위험도에 따라 관문의 높이를 다르게 둔다.
- 에러는 학습 신호로: 도구가 실패하면 그 에러 메시지를 그대로 모델에게 돌려준다. 좋은 하네스는 실패를 숨기지 않고 피드백으로 바꾼다.
권한 게이팅은 특히 중요하다. 자율성과 안전성은 트레이드오프 관계인데, 하네스는 이 다이얼을 조절하는 장치다. rm -rf나 force push 같은 명령 앞에 관문을 세우는 것만으로도 대형 사고의 상당수를 막을 수 있다.
계획 → 실행 → 검증 루프
내가 생각하는 하네스의 골격은 이 루프다. 모델에게 "한 번에 다 해"라고 시키는 대신, 생각하고, 행동하고, 확인하는 사이클로 쪼갠다.
python# 하네스의 핵심 루프 (의사코드) def agent_loop(task, tools, max_steps=25): context = init_context(task) plan = model.plan(context) # 1) 계획: 먼저 생각하게 한다 for step in range(max_steps): action = model.act(context, plan, tools) # 2) 실행: 도구 호출 결정 if action.needs_permission: if not gate.approve(action): # 권한 게이팅 context.add("거부됨: 대안을 찾아라") continue result = tools.run(action) # 도구 실행 observation = verify(action, result) # 3) 검증: 결과를 관찰 context = compact_if_needed(context) # 컨텍스트 경영 context.add(observation) if observation.task_complete: return finalize(context) return escalate("최대 스텝 초과 — 사람 개입 필요")
여기서 verify()가 하네스의 승부처다. 모델이 "다 했어요"라고 말하는 것과 실제로 됐는지는 완전히 다른 문제다. 그래서 검증은 모델의 자기 보고가 아니라 관찰 가능한 신호에 근거해야 한다.
python# 검증 게이트 — 모델의 말이 아니라 실제 결과를 믿는다 def verify(action, result): if action.type == "edit_code": test_result = run("npm test") # 실제로 돌려본다 type_result = run("tsc --noEmit") # 타입도 확인 return Observation( task_complete=test_result.passed and type_result.passed, feedback=collect_errors(test_result, type_result), ) # ... 도구별 검증 규칙
이 "실제로 돌려보기"가 있느냐 없느냐가, 데모에서는 잘 되는데 프로덕션에서는 무너지는 에이전트와 진짜 믿을 만한 에이전트를 가른다. 테스트, 타입체크, 린트, 빌드 — 이미 우리가 가진 검증 도구들을 루프 안에 끼워넣는 것만으로 신뢰성이 껑충 뛴다.
서브에이전트와 병렬 팬아웃
컨텍스트가 유한하다는 제약은 재미있는 해법을 낳는다. 하나의 거대한 컨텍스트로 다 처리하려 하지 말고, 작업을 쪼개서 여러 서브에이전트에게 나눠주는 것이다.
python# 서브에이전트 팬아웃 스케치 def investigate_codebase(question): subtasks = [ "인증 로직이 어디서 처리되는지 찾아라", "DB 스키마와 마이그레이션을 정리해라", "API 라우트의 권한 검사를 조사해라", ] # 각 서브에이전트는 독립된 깨끗한 컨텍스트를 가진다 results = parallel_map( lambda t: spawn_subagent(t, tools=READ_ONLY), subtasks, ) # 부모는 결과 요약만 받는다 — 원본 파일 덤프가 아니라 return orchestrator.synthesize(question, results)
이 구조의 묘미는 두 가지다.
- 컨텍스트 격리: 각 서브에이전트가 자기 작업에만 집중하는 깨끗한 컨텍스트를 갖는다. 부모 오케스트레이터는 지저분한 중간 과정 대신 정제된 요약만 받는다.
- 병렬성: 서로 독립적인 조사는 동시에 돌릴 수 있다. 벽시계 시간이 줄고, 각자 다른 관점으로 파고들 수 있다.
Claude Code의 서브에이전트, Codex의 태스크 분할 모두 이 아이디어의 변주다. 큰 문제를 작은 문제로 쪼개고, 각각에 신선한 컨텍스트를 주고, 결과를 합친다. 사실 이건 우리가 사람 팀을 조직하는 방식과 놀랍도록 닮았다.
왜 하네스가 raw 모델보다 신뢰성을 더 좌우하는가
이제 핵심 주장으로 돌아오자. 왜 하네스가 그렇게 중요한가.
첫째, 신뢰성은 곱셈이 아니라 시스템의 문제다. 모델이 한 스텝에서 95% 정확하다고 해도, 20스텝짜리 작업이면 단순 곱으로 0.95^20 ≈ 36%까지 떨어진다. 검증 루프와 재시도가 없으면 긴 작업은 거의 반드시 실패한다. 하네스는 이 확률 붕괴를 막는 오류 정정 장치다.
둘째, 모델은 상태가 없다. 매 호출은 독립적이다. 세션을 넘나드는 일관성, 과거 결정의 존중, 프로젝트 컨벤션 준수 — 이 모든 건 모델이 아니라 하네스(메모리, 컨텍스트 주입)가 만들어낸다.
셋째, 안전은 모델이 아니라 시스템에서 온다. 아무리 정렬이 잘 된 모델도 실수한다. 파괴적 명령을 막는 건 모델의 선의가 아니라 하네스의 권한 게이트다.
| 관점 | Raw 모델이 담당 | 하네스가 담당 |
|---|---|---|
| 단일 스텝 추론 품질 | O | 보조 |
| 장기 작업 신뢰성 | 상한선만 | 결정적 |
| 세션 간 일관성/메모리 | X | O |
| 안전/권한 통제 | 부분적 | O |
| 컨텍스트 효율 | X | O |
| 병렬 처리/확장 | X | O |
| 도메인 특화 워크플로 | X | O |
정리하면, 더 좋은 모델은 상한선을 올려주지만 그 상한선까지 실제로 도달하게 해주는 건 하네스다. 같은 모델을 쓰는 두 제품의 체감 품질이 하늘과 땅 차이인 이유가 여기 있다.
Claude Code와 Codex는 둘 다 "하네스"다
이 렌즈로 보면 요즘 코딩 에이전트들이 다르게 보인다. Claude Code와 Codex를 흔히 "모델"인 것처럼 이야기하지만, 정확히는 모델 위에 얹힌 하네스다.
- Claude Code: Claude 모델을 감싼 하네스. 파일 시스템 도구, 권한 게이팅, 서브에이전트, 메모리(
CLAUDE.md), 컴팩션, 훅(hook) 시스템까지 — 전부 하네스 레이어의 엔지니어링이다. 모델을 바꿔도 이 하네스의 가치는 그대로 남는다. - Codex: OpenAI 모델을 감싼 하네스. 격리된 실행 환경, 태스크 오케스트레이션, 검증 루프를 제공한다. 역시 핵심 가치의 상당 부분이 스캐폴딩에 있다.
두 도구의 경쟁은 단순히 "누구 모델이 더 똑똑한가"의 싸움이 아니다. 누구의 하네스가 더 잘 설계됐는가의 싸움이다. 컨텍스트를 얼마나 영리하게 경영하는지, 검증을 얼마나 촘촘히 거는지, 권한을 얼마나 매끄럽게 다루는지 — 이런 게 실사용 경험을 만든다.
그래서 나는 요즘 에이전트를 평가할 때 모델 벤치마크 점수만 보지 않는다. 오히려 이 하네스가 긴 작업에서 얼마나 안 무너지는가, 틀렸을 때 스스로 알아채고 고치는가를 본다. 그게 결국 매일 쓰는 도구의 만족도를 결정하니까.
그래서, 무엇을 할 것인가
에이전트를 직접 만드는 입장에서 얻을 교훈은 명확하다.
- 모델 교체에 목매지 마라. 프론티어 모델은 계속 좋아진다. 하지만 당장 신뢰성을 올리고 싶다면 하네스부터 손봐라.
- 검증 루프를 먼저 넣어라. 테스트, 타입체크, 실제 실행 — 관찰 가능한 신호로 모델을 붙잡아라.
- 컨텍스트를 경영하라. 다 넣지 말고, 필요할 때 찾아오고, 지나간 건 접어라.
- 권한 게이트를 세워라. 자율성 다이얼과 안전 관문을 명시적으로 설계하라.
- 쪼개고 팬아웃하라. 큰 작업은 깨끗한 컨텍스트를 가진 서브에이전트로 분산하라.
모델은 엔진이고, 하네스는 그 엔진을 실제 도로에서 달리게 하는 차체와 제동 장치다. 아무리 좋은 엔진도 제동이 없으면 못 쓴다. 2026년의 AI 엔지니어링은 점점 더 "모델을 고르는 일"에서 "모델 주변을 설계하는 일"로 무게 중심이 옮겨가고 있다. 하네스 엔지니어링은 이제 선택이 아니라 본 게임이다.
▶️ 관련 영상
하네스와 에이전트 설계에 대한 공식 채널의 발표와 데모를 참고하면 좋다.