하네스가 의도대로 안 될때: 4가지 원칙 제안🪐

spec-kit · oh-my-openagent · OpenHarness 등 기존 하네스 방식들의 문제들에 대해 재정비하고 새로운 시도에 대해 공유해요.

Gemini 생성 이미지

이 글을 보시는 분이라면 이미 익숙하실 거예요. Agent harness 라는 개념, 그리고 그 주변의 도구들 — github/spec-kit, HKUDS/OpenHarness, code-yeongyu/oh-my-openagent(omo), revfactory/harness, coleam00/Archon 같은 OSS들이 1년 사이에 우후죽순으로 나왔어요.

Martin Fowler가 2025년에 다시 정리했고, OpenAI도 같은 해 "Harness Engineering" 글을 냈고, LangChain은 "Anatomy of an Agent Harness"를 썼고, Stanford CRFM의 연구에서는 같은 모델이라도 하네스 설계만 바꾸면 최대 6배까지 성능이 갈린다고 측정됐죠.

그래서 저도 이 도구들을 한 번씩 다 설치해보고 사용해보았습니다. 그리고 나름 효과적이였어요.

하지만 점차 성숙기를 거치는 프로젝트에서 에이전트가 동일한 실수 발생 시 원인 분석이 안되는 점, 다양한 모듈 혹은 패키지에서의 규칙들을 세분화해서 반영하기 어려웠던 점들 그리고 그 문제점을 자체적으로 goax라는 작은 Claude Code 플러그인을 만들어서 해결했던 부분을 공유하고자해요.

이 글에서 이야기하는건 세 가지예요.

1. 하네스가 이미 공통적으로 합의한 것들 — 공통점
2. 어떤 문제가 안 풀렸는가?
3. 그 문제를 어떻게 해결했고, 기존 솔루션과 어디가 다른가 — 차이

하네스가 공통적으로 합의한 것들

AI 코딩 도구를 만드는 사람들은 이제 다음 명제에 거의 합의했어요.

• “에이전트 = 모델 + 하네스” 공식이 표준이 됐어요. Martin Fowler의 정의(“everything in an AI agent except the model itself”)부터 LangChain의 “The model generates text. The harness decides what that text can touch.”까지, 같은 그림을 그리고 있어요.
• 결과 일관성의 변수는 모델이 아니라 하네스라는 인식이 자리 잡았어요. Stanford CRFM의 6× 격차 측정, Can Bölük의 “Harness Problem”(2026)에서 보고한 에디트 툴 포맷만 바꿔도 약한 모델은 6.7% → 68.3% 정확도 상승 같은 결과가 같은 결론을 가리킵니다.
• 하네스의 기본 구성 요소도 거의 공통입니다 — tools, skills, permissions, hooks, memory, MCP. OpenHarness가 43개 도구 + skills + permissions + hooks를 묶어 한 패키지로 만든 게 대표적이고, omo는 거기에 Hashline(해시 앵커드 에디트 툴)·Ralph Loop·Skill-embedded MCP를 더했어요.
• Claude Code 본체가 이미 다 native로 제공해요. 2026년 5월 기준 플러그인 마켓플레이스, 스킬(SKILL.md 자동 매칭), PreToolUse·PostToolUse 훅, 서브에이전트, statusline, CLAUDE.md 자동 주입까지 — 모두 본체 docs에 정식 문서로 들어왔습니다. 그래서 요즘 새로 나오는 하네스 OSS들은 거의 다 Claude Code 위의 플러그인 형태예요. 차별화는 이제 “어떤 작업들을 그 구조 위에 채우고 어떤 워크플로우를 강제하는가” 에서 차별점이 있어요.

여기까지는 어느 도구를 깔든 모델을 둘러싸는 환경이 중요하다는 데에는 다들 동의해요.

문제는 그 환경 안에서 무엇을 우선 해결해야 하는가에 대한 합의가 부족하다는 점이었어요. 그리고 더 구체적으로는 — 다음 세 가지 페인포인트 때문에, 저는 기존 OSS를 그대로 쓸 수 없었습니다.

기존 하네스의 세 가지 페인포인트

참고로 이 부분은 일반론이 아니라, 제가 실제 운영했던 환경의 맥락이에요. 다른 환경이라면 다르게 느끼셨을 수 있어요.

1. 모노레포 · 다양한 도메인을 단일 하네스가 잘 못 다룹니다

제가 담당했던 프로젝트의 코드베이스는 결제 · 배송 · 인증 · 모니터링같은 도메인이 한 모노레포에 섞여 있었고, 각 도메인의 규칙과 가드레일이 모두 달랐습니다. 결제는 한 줄 수정도 사람 승인이 필요하고, 모니터링 대시보드는 빠른 반복이 더 중요합니다.

그런데 기존 하네스 도구들 은 대부분 단일 룰셋을 프로젝트 루트에 두는 모델을 전제합니다. 프로젝트 크기와 다양성이 늘어날수록, 도구가 내가 원하지 않은 모양으로 하네스를 적용해버려요. 결제에 맞춰두면 모니터링은 느려지고, 모니터링에 맞춰두면 결제가 위험해집니다.

하네스가 “어디에 어떤 강도로 적용되는가”를 도메인 단위로 분리할 수 있어야 했어요.

2. 작업의 사이즈·리스크를 똑똑하게 못 잡아냅니다

오타 한 줄 수정과 P0 결제 리팩토링이 같은 무게로 처리되는 게 일상이었어요. spec-kit은 모든 작업을 Spec → Plan → Tasks → Implement 4단계로 흘려보내고, omo는 sub-agent category로 모델만 다르게 고를 뿐 작업의 위험도는 다루지 않습니다.

저는 작업의 속도와 깊이가 둘 다 똑똑하게 분류하길 원했어요. 빠르게 처리할 수 있는 일은 사람 검토 없이 빠르게, 깊게 봐야 할 일은 명시적으로 사람이 직접 초반 검증을 강하게 — 이 두 모드가 자동으로 라우팅돼야 일상 운영이 됩니다. 매번 사람이 “이건 가벼운 거야”라고 태깅하는 건 결국 안 하게 돼요.

“작업의 사이즈와 리스크를 자동 분류하는 진입점”이 개발자가 작업 요청 시기본으로 있어야 했어요.

3. 하네스 사용 시 개발자 사고를 발휘할 영역이 사라졌어요

이게 가장 미묘한 페인이었어요. AI에 모든 걸 떠넘기는 자동화는 위험합니다. 어떤 지점에서는 사람이 결과를 사후 분석하고, 모델이 왜 그렇게 동작했는지 이해할 필요가 있어요. 그런데 기존 하네스 OSS 대부분은 이 자리를 옵션 사항으로 둬요. 결정 로그가 어디에 쌓이는지, 거부된 대안이 어디에 기록되는지, 실수가 발생했을 때 그게 환경에 어떻게 흡수되는지 — 명시적 워크플로우가 없습니다.

저는 “AI를 통한 자동화”와 “사람이 모델 동작을 이해하는 지점” 이 두 가지가 한 구조에 같이 있어야 한다고 생각했어요. 자동화가 0인 도구도 무용하지만, 언제 사람이 들어와야 하는지를 도구가 모르는 자동화는 더 위험합니다.

*자동화의 수준과 지점을 도구가 의도적으로 다루도록 해야 했어요. 결국 하네스를 통해 사람(개발자)의 사고도 같이 똑똑해져야 된다고 생각해요.*

어떤식으로 해결했는가?

다음은 제가 새롭게 설계한 하네스 프레임워크의 아키텍처 개념 4가지를 설명합니다.

1. Triage: 작업의 크기·위험·도메인을 같이 보는 진입점

• 문제상황: 한 줄짜리 오타 수정과 P0 결제 모듈 리팩토링이 같은 무게로 처리됩니다. 그리고 결제 도메인 작업과 모니터링 도메인 작업이 같은 룰셋으로 적용됩니다. spec-kit은 모든 작업을 동일한 4단계로 흘려보내고, omo의 sub-agent category 라우팅이 일부 비슷한 역할을 하지만, “이 작업의 위험도와 도메인에 맞춰 검증을 얼마나 강하게 걸 것인가”라는 축은 명시적으로 존재하지 않아요.
• 시나리오: 월요일 아침 두 PR이 동시에 떴다고 해볼게요. (A) 환불 영수증 이메일 본문에 오타 한 줄, (B) 결제 게이트웨이를 카드 단일에서 카드+페이팔로 확장하는 큰 리팩토링. 일반 하네스는 둘 다 같은 진입점(spec → plan → tasks → implement)을 거치게 해요. 한 줄 오타에 스펙을 만들고 있으면 우스꽝스럽고, 게이트웨이 확장에 스펙 없이 들어가면 위험합니다.
• 해결방안: 작업이 들어오면 짧은 인터뷰로 작업의 크기(파일 수·예상 시간)와 위험도(돈이 움직이나? 외부 통신이 있나? 롤백 가능한가?)를 자동으로 분류해요. (A)는 곧장 구현 트랙으로, (B)는 스펙 + 거부된 대안 검토 + 사람 승인을 의무화하는 풀 트랙으로 보냅니다. 그리고 도메인까지 같이 봅니다 — 결제 도메인 PR이라면 더 강한 사람 게이트가 자동으로 붙어요. 한 도구가 두 축(작업 속성 · 코드 위치)을 동시에 보는 건 의외로 다른 OSS에서 흔치 않은 조합이에요.

2. Determinism boundary: 무엇을 Agent Rule에, 무엇을 스크립트에?

• 문제상황: 많은 솔루션이 결정적 검증과 LLM 판단의 경계를 흐리게 둡니다. omo의 Hashline은 결정적 검증의 좋은 사례지만 에디트 안정성 한 영역에 한정돼요. 하네스 차원에서 “여기는 결정론, 여기는 LLM 판단”이라는 boundary를 정책으로 가진 OSS는 의외로 드물어요. 그리고 이 경계가 흐릴수록 개발자가 들여다보고 사고를 발휘할 자리도 같이 흐려집 자동화가 어디까지 신뢰할만한지 도구가 알려주지 않으니까요.
• 시나리오: 커밋 직전에 “API 키가 코드에 노출됐는지” 검사한다고 해볼게요. 어떤 도구는 이걸 LLM에게 시킵니다. 모델이 매번 호출되고, 결과는 매번 조금씩 다르고, 비용은 누적됩니다. 같은 검사를 grep 한 줄로 하면 0원에 100% 결정적이에요. 반대로 “이 함수 호출이 도메인 의도에 맞는가?” 같은 검사는 grep으로는 못 합니다 — LLM 영역이에요.
• 해결방안: 이 경계를 설계 원칙으로 못 박습니다. 패턴 매칭·정적 검출·경로 차단·파괴적 명령 차단 같은 일은 모두 짧은 스크립트가, 의도 인터뷰·스펙 작성·실수 카테고리 분류 같은 판단은 모두 LLM이 합니다. 둘을 섞지 않아요. 그래야 어디서 결과를 그대로 신뢰할 수 있고 어디서 개발자가 들여다봐야 하는지가 명확해집니다 — 자동화에 사고를 잠재우지 않고, 개발자의 판단력이 발휘될 자리가 의도적으로 남게 돼요.

3. Mistake Loop: 실수가 환경에 학습되는 자리

• 문제상황: 하네스 OSS들에서 솔루션을 제공하고 있지만, PR에서 발견한 실수가 다음 PR에서 또 나옵니다. MEMORY.md가 가장 가까운 시도지만, 그건 사실을 기억하는 곳이지 실수를 룰로 굳히는 곳이 아니에요. agent 실패 시 코드를 고치면 1번이지만 하네스를 고치면 영구적인데, 대부분의 도구가 코드만 고치고 끝납니다. 그리고 더 중요한 건, 개발자가 그 실수를 들여다보고 어떤 룰로 승격할지 결정하는 자리가 없다는 점이에요.
• 시나리오: 어제 PR 리뷰에서 발견한 실수. AI가 “주문 생성”과 “재고 차감”을 트랜잭션 없이 별도 호출 두 번으로 짰어요. 한 쪽이 실패하면 데이터가 깨지는 패턴이라 리뷰에서 잡고 수정해 머지했죠. 여기서 끝나면 다음 주에 같은 실수가 다른 모듈에서 또 나옵니다. 사람도 잊고, AI도 새 세션에서 백지로 시작하니까요.
• 해결방안: 발견된 실수가 카테고리(예: “transaction”)와 짧은 슬러그(예: “order-stock-no-transaction”)로 자동 캡처돼요. 일정 주기 또는 누적 5건이 되면 audit 단계가 동작합니다 — 개발자가 실수들을 한꺼번에 보고, “이걸 비협상 룰로 올릴지, ADR로 올릴지, 아니면 hook 검사를 추가할지”를 결정합니다. 자동 승격은 일부러 안 합니다. 잘못된 룰 하나가 올라가면 모든 PR에 노이즈가 깔리니까요. 개발자가 검토하고 승격하는 자리가 자동화의 끝이 아니라, 개발자의 사고력이 룰로 전환되는 의도된 지점이예요.

4. ADR: 거부된 대안의 SSOT

• 문제상황: 세션이 새로 열리면 어제 거부한 패턴을 오늘 AI가 다시 제안합니다. 모노레포 환경에서는 도메인 수만큼 곱해져요 — 결제에서 거부한 패턴을 모니터링에서 또 제안하고, 그 반대도 일어납니다. spec-kit이 스펙을 통해 현재의 결정은 남기지만, 거부된 대안과 그 이유를 도메인별로 명시적으로 보존하는 1급 시민 아티팩트는 없어요. ADR(Architecture Decision Record)을 별도 디렉터리에 두고 Rejected alternatives 섹션을 의무화하는 솔루션은 OSS 생태계에서 거의 못 봤습니다.
• 시나리오: 지난 분기에 “이벤트 전달을 Kafka 대신 Redis pub/sub로 가자”는 제안을 검토했어요. 부하 테스트에서 일부 시나리오 메시지 유실이 발견됐고, Kafka 유지로 결론을 냈죠. 6개월이 지났고, 새 팀원이 합류해 AI에게 “이벤트 전달을 가볍게 해줘”라고 부탁합니다. AI는 무엇을 제안할까요? 십중팔구 Redis pub/sub입니다. 어제 거부한 패턴을 오늘 다시 제안하는 거예요.
• 해결방안: 거부된 대안을 1급 시민으로 둡니다. 현재 결정을 적는 스펙과 별도로, ADR에 거부된 대안 + 그 이유를 따로 보존해요. 모노레포라면 도메인별로 ADR을 따로 관리해서, 결제팀이 거부한 패턴이 모니터링팀까지 번지지 않습니다. 다음 세션이 어제 거절한 패턴을 다시 제안하려 할 때, 룰 조회가 그 ADR을 컨텍스트에 자동으로 끌어와요 — “이건 6개월 전 이런 이유로 거부됐어요”가 즉시 보입니다.

그래서, 이걸로 무엇이 달라졌나

도입 후 몇 주를 운영해보니 매트릭스 안의 네 칸이 메워진 효과가 다음과 같이 나왔어요.

• 같은 실수의 반복률이 눈에 띄게 줄었습니다. Mistake Loop이 발견된 실수를 룰로 승격시키니, 다음 세션이 같은 함정을 안 밟아요.
• 작업 크기에 맞는 무게로 처리됩니다. 한 줄 수정에 풀스펙을 만들지 않고, P0 리팩토링에 스펙 없이 코드부터 짜지 않습니다.
• 세션 간 컨텍스트가 유지됩니다. triage → spec → audit 사이 현재 작업의 컨텍스트가 하나의 SSOT 파일에 보관되어, 다음 세션이 매번 재추론하지 않아요.
• 개발자의 사고는 유지됩니다. 각 개발 영역은 자동화를 통해 처리, 시작과 끝점 그리고 이를 모델에서 어떻게 해결할지에 대해서는 개발자의 깊은 사고능력과 이해능력을 필요로합니다.

마치며

하네스 프레임워크를 직접 구축하면서 얻은 인사이트 다섯 가지를 추리면 이렇습니다.

1. 하네스는 이미 다들 사용하고 있다. 도구·스킬·퍼미션·훅·메모리 — 구조는 공통이에요. 다음 라운드는 그 안에서 우선순위입니다.
2. 실수는 코드가 아니라 환경을 통제. Mistake Loop이 가장 늦게 발견됐지만, 가장 큰 효과를 낸 설계였어요.
3. 결정론과 LLM 판단을 섞지 말자. 결정적 검사는 grep이 압도적으로 효율적이고 신뢰할 수 있습니다.
4. 자동화 위에 개발자의 사고가 같이 똑똑해져야 한다. 좋은 하네스는 개발자를 비켜 세우지 않고, 그들의 판단력이 가장 필요한 자리를 의도적으로 남겨둡니다. 가장 미묘하지만 가장 중요한 메시지예요.

“The model is the agent. The code is the harness.” — OpenHarness 슬로건 여기에 한 줄 더 보탠다면, “And the gaps are where the work begins.”

참고

• github/spec-kit · Spec-Driven Development 툴킷
• code-yeongyu/oh-my-openagent · model-agnostic agent orchestrator (omo)
• HKUDS/OpenHarness · 코어 agent 하네스 + ohmo
• revfactory/harness · 도메인 한 줄 → 에이전트 팀 생성 메타 팩토리
• coleam00/Archon · 결정론적 runtime configuration factory
• Martin Fowler, Harness Engineering (2025)
• OpenAI, Harness Engineering: leveraging Codex in an agent-first world (2025)
• LangChain, Anatomy of an Agent Harness
• Can Bölük, The Harness Problem (2026)
• Stanford CRFM · 하네스 설계에 따른 최대 6× 성능 격차 측정