Ralph loop가 가고, '하니스 엔지니어링'이 온다

— run-harness-plugin 제작기에 부쳐

---

소프트웨어 개발의 패러다임이 근본적으로 뒤집히고 있다.

사전에 기획서(PRD)를 빈틈없이 작성하고, 파이프라인을 설계한 뒤 각 단계를 스크립트로 짜서 순차 실행하는 워터폴(Waterfall) 방식. 혹은 에이전트에게 지시를 던져놓고 코드가 뱉어지길 무작정 기다리는 단순 루프 방식. 둘 다 한계에 직면했다. 전자는 변화에 취약하고, 후자는 품질을 담보하지 못한다.

그 사이를 파고드는 제3의 방법론이 부상하고 있다. '하니스 엔지니어링(Harness Engineering)' — 결과물 자체를 직접 통제하는 대신, 에이전트가 올바른 결과를 도출할 수밖에 없는 환경을 설계하는 데 집중하는 접근법이다.

---

1. 왜 지금 '하니스'인가

'하니스(Harness)'의 원래 뜻은 마차를 끄는 말에 다는 마구(馬具)다. 굴레와 고삐로 구성되어 말이 원하는 방향으로 움직이도록 통제하는 장치. AI 에이전트 맥락에서 하니스는 모델을 감싸서 장기 실행 작업을 신뢰성 있게 관리하는 시스템 전체를 뜻한다. 모델이 강력한 엔진이라면, 하니스는 조향장치·브레이크·안전장치를 갖춘 완성된 자동차라 할 수 있다.

Aakash Gupta가 "2025 Was Agents, 2026 Is Agent Harnesses"라는 테제를 내놓은 이후, 업계의 시선이 급격히 전환되었다. 모델 자체의 성능 경쟁은 정체기에 접어들었고, 승부는 그 모델을 어떻게 굴리느냐로 옮겨갔다. 토스 기술 블로그가 "Software 3.0 시대, Harness를 통한 조직 생산성 저점 높이기"를 다루고, oh-my-opencode 같은 정교한 하니스 프레임워크가 등장하는 것도 같은 맥락이다.

이미 강력한 하니스는 존재한다. oh-my-opencode는 Sisyphus 오케스트레이터, LSP·AST-Grep 통합, 멀티모델 라우팅, 25개 이상의 빌트인 훅까지 갖춘 중무장 시스템이다. 무기에 비유하면 자율주행 전투기 — 화력과 항속거리 모두 압도적이지만, 이륙까지의 준비 시간과 운용 복잡도 역시 그에 비례한다.

run-harness-plugin이 추구하는 것은 다른 종류의 기동성이다. 전투기가 아니라 전시 상황에 맞게 즉석 커스터마이즈가 가능한 자율주행 드론. Claude Code의 네이티브 기능 — Skills, Teams, Tasks — 만으로 무장하되, 더 빠르고 가볍게. 현장의 맥락에 따라 팀 구성을 바꾸고, 스킬을 갈아 끼우고, 태스크를 재정의하는 것이 분 단위로 가능한 경량 하니스. 그것이 이 플러그인의 설계 철학이다.

---

2. 대화가 곧 설계다 — 하니스 구축의 과정

하니스 엔지니어링에서 설계는 문서가 아니라 에이전트와의 대화를 통해 이루어진다.

개발자는 작업에 돌입하기 전, 에이전트와 티키타카(back-and-forth)를 하며 목표를 정의하고, 필요한 도구(Skills)를 생성하며, 접근 방식을 다듬는다. 이 사전 대화는 단순한 준비 작업이 아니다. 인간의 개입 없이 장기간 자율 작동해야 할 에이전트에게 '신뢰할 수 있는 실행 환경'을 셋업하는 핵심 과정이다. PRD를 쓰는 대신 에이전트와 대화하며 PRD를 공동 진화시키는 것이라고도 볼 수 있다.

이것은 토스 기술 블로그가 지적한 "컨텍스트 엔지니어링" 역량 편차의 문제이기도 하다. 같은 모델, 같은 IDE를 쓰면서도 10분 만에 리팩토링을 끝내는 엔지니어와 1시간을 할루시네이션과 씨름하는 엔지니어의 차이는 코딩 실력이 아니라, 작업 전에 컨텍스트를 설계했느냐에 달려 있다. 하니스는 이 격차를 시스템 수준에서 좁히는 장치다.

---

3. Claude Native 기능의 극대화 — 팀(Teams)과 태스크(Tasks)

이러한 방법론을 실제 터미널 환경에 구현한 실행 레이어가 바로 run-harness-plugin이다. 이 플러그인의 설계 철학은 명확하다. 무거운 추상화 레이어를 쌓는 대신, Claude Code가 네이티브로 제공하는 기능을 있는 그대로 최대한 활용한다. 드론에 불필요한 장갑을 덧대는 게 아니라, 기체 자체의 기동성을 극한까지 끌어내는 것이다.

자율 팀 구성 (Agent Teams). /run-harness 하나로 Claude가 과업을 스스로 분석해 2~8명의 서브 에이전트 팀을 구성한다. TeamCreate, SendMessage로 역할을 분담하고 병렬 작업에 돌입한다. 별도의 오케스트레이션 엔진 없이, Claude Code의 네이티브 Agent Teams — 공유 태스크 리스트, 에이전트 간 메시징, tmux 기반 스폰 — 를 그대로 탄다. 가벼움의 핵심은 여기에 있다. 래핑하지 않고 네이티브를 직접 호출한다.

메모리와 맥락 유지 (Tasks). 에이전트가 장시간 궤도를 이탈하지 않도록 TaskCreate로 목표와 상태를 관리한다. 이는 장기 실행에서 필수적인 메모리 역할이다. 드론이 아무리 가볍더라도 귀환 좌표를 잃으면 안 되듯, Tasks는 에이전트의 작업 맥락을 최소한의 오버헤드로 구조화한다.

스킬의 현장 조립 (Skills). 전투기가 출격 전 정비소에서 무장을 교체하듯 시간이 걸리는 것과 달리, 드론은 현장에서 페이로드를 갈아 끼운다. run-harness-plugin에서 Skills는 바로 이 역할이다. 프로젝트의 도메인에 맞는 스킬을 사전 대화에서 정의하고, 하니스 실행 시 에이전트가 즉시 활용할 수 있도록 경량 주입한다.

---

4. 무인 자율 실행의 기술적 기반 — Under the Hood

하니스가 준비되고 /run-harness 명령이 떨어지면(Fire), 에이전트는 독립적인 작업을 시작한다. run-harness-plugin은 이 장기 실행이 끊기지 않도록 기술적 안전망을 제공한다.

tmux 세션 격리. 백그라운드에서 tmux 세션을 열어 TUI(Terminal UI) 환경을 안정적으로 부팅시킨다. tmux의 세션 퍼시스턴스는 SSH 연결이 끊기거나 터미널이 닫혀도 에이전트가 계속 작동하게 해주는 핵심 인프라다. Claude Code의 Agent Teams가 tmux 기반 split-pane 모드를 사용하는 것과 동일한 맥락이지만, run-harness-plugin은 여기에 자동 복구 레이어를 얹는다.

상태 모니터링 및 자동 복구. 5초 단위로 종료(done) 신호를 폴링(polling)하며, 30초 이상 하트비트(heartbeat)가 응답하지 않으면 프로세스가 멈춘 것으로 간주하고 재시도한다. 분산 시스템의 헬스체크 패턴을 단일 에이전트 실행에 적용한 셈이다.

지수 백오프와 체크포인트. 에러 발생 시 지수 백오프(Exponential Backoff) 알고리즘으로 재시도 간격을 조절한다. 네트워크 장애든 API 레이트 리밋이든, 무작정 재시도하다 상황을 악화시키는 대신 점진적으로 간격을 넓혀가며 시스템이 회복할 여유를 준다. 중단되더라도 커서(cursor) 프로토콜을 통해 마지막 체크포인트부터 작업을 재개한다. 이는 데이터 파이프라인의 exactly-once 시맨틱스와 유사한 사고방식이다 — 실패는 불가피하되, 실패로부터의 복구는 설계 가능하다.

---

5. 시기적절함에 대하여

이 플러그인이 지금 의미를 갖는 이유는 업계의 타이밍과 정확히 맞물리기 때문이다.

Claude Code의 Agent Teams 기능이 실험적(experimental) 단계로 공개되며 멀티에이전트 오케스트레이션의 네이티브 기반이 깔렸다. 동시에 oh-my-opencode, claude-code-teams-mcp 같은 프로젝트들이 이 기반 위에 각자의 방식으로 상부 구조를 올리고 있다.

하니스 생태계는 지금 분화 중이다. 한쪽에는 LSP·AST·멀티모델 라우팅까지 통합한 전투기급 풀스택 하니스가 있고, 다른 한쪽에는 Claude Code 네이티브 기능에 밀착해 최소한의 레이어만 얹는 경량 하니스가 있다. 전자는 범용성과 화력에서 우위를 점하지만, 후자는 도입 속도와 커스터마이즈 유연성에서 이긴다.

run-harness-plugin은 후자의 극단에 선다. Teams + Tasks + Skills라는 Claude 네이티브 삼각편대에 tmux 격리와 자동 복구라는 안전망만 얹었다. 그 위의 모든 것 — 팀 구성 전략, 스킬 정의, 태스크 분해 — 은 사용자가 사전 대화를 통해 현장에서 조립한다. 드론의 강점은 전투기보다 싸거나 약해서가 아니라, 전장의 변화에 분 단위로 적응할 수 있다는 데 있다.

---

결론: '결과물'이 아닌 '생성 장치'를 만드는 시대

이제 자동화의 핵심은 결과물 자체를 만드는 것이 아니라 **'결과물을 만들어내는 생성 장치'**를 구축하는 것이다.

개발자의 역할은 개별 코드를 작성하거나 에이전트의 단순 루프를 지켜보는 것에서 벗어났다. 에이전트가 능력을 온전히 발휘할 수 있도록 견고한 하니스를 짜고, 자율적인 팀을 구성할 수 있도록 트리거를 당겨주는 **'시스템 오케스트레이터'**로 진화해야 할 시점이다.

다만 그 하니스가 반드시 전투기여야 할 필요는 없다. 전장은 매일 바뀌고, 미션은 매번 다르다. 필요한 것은 현장에서 5분 만에 조립하고, 실패하면 회수해서 재설정하고, 다시 날릴 수 있는 드론이다. Claude Code가 제공하는 네이티브 무장 — Skills, Teams, Tasks — 을 그대로 장착하되, 하니스는 최대한 얇게. run-harness-plugin은 그 가벼움 자체가 설계 의도인 도구다.

물리학의 비유를 빌리자면, 우리는 더 이상 입자 하나하나의 궤적을 추적하는 뉴턴 역학의 시대에 있지 않다. 수많은 에이전트가 상호작용하는 계(系)의 통계적 성질을 설계하는 통계역학의 시대로 접어들었다. 개별 코드 라인이 아닌, 코드가 생성되는 조건을 설계하는 것. 그것이 하니스 엔지니어링이다.

---

run-harness-plugin은 GitHub에서 확인할 수 있다.

---

🔗 Sources