AI 연구자도 하네스를 만들어야 하나, Claude Code 실전 기준

좋은 모델만 고르면 코딩 에이전트도 좋아질까. 최근에는 같은 모델이라도 어떤 하네스에 넣느냐에 따라 비용과 결과가 달라진다는 논의가 커졌다. 이 글은 AI 연구자도 하네스를 직접 만들어야 하는지, Claude Code 사용자는 어디까지 알아야 하는지에 답한다.

모델의 능력을 작업 결과로 바꾸는 구조가 하네스다

에이전트 하네스는 LLM과 작업 환경 사이에 놓인 실행 구조다. 입력을 구성하고 도구 호출을 중계한다. 상태와 권한을 관리하고 종료 조건도 판단한다. Anthropic은 에이전트를 ‘도구를 자율적으로 사용하는 반복 구조’로 설명한다. (anthropic.com)

코딩 작업에서는 파일 읽기와 수정, 셸 실행, 테스트 결과 반환이 이 반복 구조에 들어간다. 여기에 메모리, 컨텍스트 압축, 재시도, 승인 절차, 로그와 평가가 붙는다. 모델이 두뇌라면 하네스는 손과 작업대, 안전장치를 함께 제공한다.

하네스가 주목받는 이유는 모델 점수만으로 실제 성능을 설명하기 어려워졌기 때문이다. 최근 연구들은 모델을 고정해도 실행 구조와 컨텍스트 전략에 따라 성공률과 효율이 달라진다고 보고한다. 다만 새 연구 상당수는 아직 사전 공개 논문이다. 특정 수치를 보편 법칙처럼 받아들이면 안 된다. (arxiv.org)

연구자에게 필요한 것은 구현 능력보다 실험 통제력이다

모든 AI 연구자가 새로운 CLI나 오케스트레이터를 만들 필요는 없다. 모델 학습이나 추론 알고리즘이 연구 대상이라면 검증된 하네스를 고정해 쓰는 편이 낫다. 비교 실험에서 하네스까지 바뀌면 모델 효과와 실행 구조의 효과가 섞이기 때문이다.

반대로 에이전트 행동, 도구 사용, 장기 작업을 연구한다면 하네스를 읽고 수정할 역량이 필요하다. 어떤 파일이 컨텍스트에 들어갔는지, 실패 뒤 몇 번 재시도했는지, 테스트 통과를 어떻게 판정했는지 알아야 결과를 설명할 수 있다. 에이전트 평가 하네스 역시 작업 제공부터 실행 기록, 채점까지 전체 과정을 다룬다. (anthropic.com)

직접 구현하는 것과 능숙하게 활용하는 것도 구분해야 한다. 자동차 연구자가 엔진을 모두 제작하지 않더라도 계측 장비와 시험 조건은 이해해야 한다. AI 연구자에게도 도구 계약, 컨텍스트 구성, 상태 저장, 검증 기준을 해석하는 능력이 먼저다.

Claude Code에서는 다섯 단계로 최소 하네스를 만든다

처음부터 멀티 에이전트 프레임워크를 짤 필요는 없다. Claude Code 프로젝트라면 저장소 루트의 CLAUDE.md부터 작성한다. 빌드·테스트 명령, 수정 금지 경로, 완료 조건, 아키텍처 규칙을 짧게 적는다. Claude Code는 이런 프로젝트 지침을 세션 컨텍스트에 불러온다. (docs.anthropic.com)

다음에는 반복 절차를 .claude/skills/<이름>/SKILL.md로 분리한다. 예를 들어 버그 수정 스킬에는 재현, 원인 확인, 최소 수정, 회귀 테스트 순서를 넣는다. 입력은 이슈 설명과 저장소이고 산출물은 패치와 테스트 결과다.

역할을 분리할 이유가 있을 때만 .claude/agents/에 서브에이전트를 추가한다. 코드 탐색과 보안 검토처럼 서로 다른 맥락이 필요한 작업이 적합하다. 단일 파일 수정이나 순차 작업까지 위임하면 호출 횟수와 요약 비용만 늘 수 있다. Anthropic도 병렬 작업과 격리된 맥락에는 서브에이전트를 쓰되 단순 작업은 직접 처리하라고 안내한다. (docs.anthropic.com)

강제 규칙은 프롬프트가 아니라 Hook으로 옮긴다. PostToolUse에서 포매터를 실행할 수 있고 PreToolUse에서는 위험한 명령이나 보호 경로 수정을 막을 수 있다. Hook은 사용자 권한으로 로컬 명령을 실행하므로 설정 파일과 스크립트도 코드처럼 검토해야 한다. (claude.com)

마지막으로 꼭 필요한 외부 시스템만 MCP로 연결한다. 도구가 많으면 선택지가 겹치고 설명문이 컨텍스트를 차지한다. Anthropic은 작고 명확한 도구 집합과 토큰 효율적인 반환값을 권한다. (anthropic.com)

OMO와 Gajae-Code는 완성된 운영 방식을 가져온다

Claude Code의 기본 기능을 조립하는 대신 이미 설계된 하네스를 선택할 수도 있다. OMO는 에이전트 역할, 모델 선택, Skills, Memory, Hooks, MCP와 백그라운드 작업을 omo.jsonc 중심으로 구성한다. 문서가 제시하는 설치를 마치면 작업을 역할 그래프로 나누고 각 범주에 다른 모델을 배정할 수 있다. (omo.dev)

Gajae-Code는 별도 gjc 런타임으로 동작한다. 문서상 기본 흐름은 deep-interview에서 요구를 구체화하고 ralplan으로 계획을 만든 뒤 ultragoal로 실행하는 순서다. 필요하면 tmux 워커와 격리된 worktree를 사용하고 실행 증거를 남긴다. (github.com)

선택 기준은 기능 수가 아니다. 여러 모델을 역할별로 바꾸고 싶다면 OMO의 구성 방식이 맞을 수 있다. 계획과 작업 증거, 격리 실행이 중요하면 Gajae-Code가 후보가 된다. 기존 Claude Code 작업을 조금씩 다듬으려면 기본 기능만으로도 충분하다.

써본 사람들 사이에서는 관리형 하네스가 편하지만 토큰 소비가 크다는 반응이 있다. 기능이 많은 오픈 하네스는 설정과 도구 설명이 컨텍스트를 부풀린다는 불만도 나온다. 어느 쪽이든 설치 직후의 인상보다 실제 작업 기록이 더 정확하다.

비용은 싼 모델보다 짧고 검증 가능한 실행에서 줄어든다

에이전트는 한 번 답하는 챗봇보다 많은 호출을 만든다. 도구 결과가 대화에 누적되고 서브에이전트가 별도 컨텍스트를 쓰며 실패하면 같은 경로를 반복한다. Anthropic도 에이전트가 성능을 얻는 대신 지연과 비용을 늘릴 수 있다고 설명한다. (anthropic.com)

개인 개발자나 소규모 팀은 동일한 실제 작업을 최소 세 번 돌려보는 편이 좋다. 성공 여부, 총 토큰, 도구 호출 수, 경과 시간, 사람이 고친 부분을 기록한다. 모델과 프롬프트를 고정한 채 CLAUDE.md, 도구 수, Hook, 서브에이전트를 하나씩 바꾸면 비용의 원인이 드러난다.

하네스 제작은 거대한 프레임워크를 발명하는 일이 아니다. 작업 규칙 한 파일, 재사용 절차 한 개, 결정적 검증 한 개로도 시작할 수 있다. 연구자에게 하네스 구현이 필수는 아니다. 하지만 에이전트 결과를 연구하거나 제품에 넣는 순간 하네스를 통제하지 못하면 모델도 제대로 비교할 수 없다.