Agent Harness Engineering — AI 에이전트 성능을 결정하는 진짜 변수

Addy Osmani가 최근 공개한 글의 핵심은 한 문장으로 정리된다.

Agent = Model + Harness. 모델이 아닌 것은 전부 harness다.

Terminal Bench 2.0에서 Claude Opus 4.6은 기본 Claude Code보다 낮은 성능을 기록했다. 같은 모델인데 harness만 바꾸자 Top 5로 올라섰다. 모델 선택의 격차보다 harness 설계 격차가 더 크다는 얘기다.

Harness가 뭔데

에이전트는 AI 모델 + 모델을 둘러싼 모든 코드와 설정의 합이다. Harness는 모델에게 상태(state), 도구 실행, 피드백 루프, 강제 가능한 제약을 부여하는 레이어다.

비유하면 공장의 지그(jig)와 비슷하다. 숙련공이 없어도 공정이 정해진 품질을 냈으면 하는 게 지그고, 모델이 달라져도 일관된 행동을 내줬으면 하는 게 harness다.

6가지 핵심 요소로 구성된다.

설계 원칙 3가지

원칙 1: 행동에서 역방향으로 설계한다

기능을 먼저 쌓지 않는다. 에이전트가 보여줘야 할 구체적인 행동을 먼저 정의하고, 그 행동을 만들어내는 요소를 추가한다. 이름을 붙일 수 없는 기능은 지운다.

원칙 2: Ratchet — 실수가 규칙이 된다

매번 에이전트가 실수할 때마다 그 실수가 다시 일어나지 못하도록 harness를 업데이트한다. AGENTS.md에 규칙을 추가하거나, pre-commit hook을 달거나, 평가 에이전트가 플래그를 세우게 만든다.

AGENTS.md의 각 줄은 구체적인 과거 실패로 추적 가능해야 한다. "항상 Jest를 써라"라는 규칙이 있다면, 한때 Vitest를 혼용해서 파이프라인이 터진 사건이 그 뒤에 있어야 한다.

패키지 관리자: pnpm (npm, yarn 금지 — CI 잠금 파일 충돌 이력)
테스트: Jest (Vitest 혼용 금지 — 2026-03 파이프라인 장애)
금지 구역: /legacy 디렉토리 접근 금지
로깅: 반드시 내부 logger 모듈 사용 (console.log 금지)

60줄 이하로 유지하는 걸 권장한다. 파일럿 체크리스트처럼, 비행 전에 읽고 체크할 수 있는 분량이어야 한다.

원칙 3: 성공은 침묵, 실패는 시끄럽다

타입체크가 통과하면 아무 말도 하지 않는다. 실패하면 오류 텍스트를 루프에 주입해서 에이전트가 자동으로 고치게 한다. 수동 개입 없이 피드백이 순환하는 구조다.

AGENTS.md 설정법

[💡 잠깐! 이 용어는?] AGENTS.md: 에이전트가 코드베이스에서 작업할 때 따라야 할 규칙을 담은 파일. Claude Code의 CLAUDE.md와 같은 역할을 한다.

프로젝트 루트에 AGENTS.md를 두고 에이전트 행동 규칙을 명시한다. 핵심은 추상적 지침보다 구체적 제약이다.

## 환경
- Node.js 22 LTS
- pnpm 9.x
 
## 테스트
- Jest + ts-jest
- 커버리지 80% 이상 유지
 
## 절대 하지 말 것
- /src/legacy 디렉토리 수정
- console.log 직접 사용 (logger 모듈 사용)
- 테스트 skip 또는 주석 처리
 
## 커밋 전 체크
- pnpm typecheck
- pnpm lint
- pnpm test

Hooks — 강제 레이어

Hooks는 라이프사이클 특정 지점에서 실행되는 강제 장치다.

{
  "hooks": {
    "afterToolCall:Edit": "pnpm typecheck && pnpm lint",
    "afterToolCall:Write": "pnpm typecheck",
    "beforeToolCall:Bash": "echo '명령 실행: 확인 필요'"
  }
}

에이전트가 파일을 수정할 때마다 타입체크가 돌아가면, 타입 오류는 발생 즉시 피드백 루프로 들어가 자동 수정된다. 사람이 나중에 PR에서 오류를 발견하는 시나리오가 사라진다.

Context Management — 3가지 기법

컨텍스트 윈도우는 유한하다. 긴 작업에서 윈도우를 잘 관리하지 않으면 중요한 정보가 밀려나거나 비용이 기하급수적으로 늘어난다.

1. Compaction(압축) 오래된 컨텍스트를 지능적으로 요약한다. 세부 내용보다 결정과 결과만 남긴다.

2. Tool-call Offloading 큰 출력(파일 목록, 로그)을 파일시스템으로 옮긴다. 에이전트가 필요할 때만 읽게 한다.

async function offloadLargeOutput(content: string, path: string) {
  await fs.writeFile(path, content)
  return `출력을 ${path}에 저장했다. 필요하면 읽어라.`
}

3. Progressive Disclosure 도구 목록을 한꺼번에 노출하지 않는다. 현재 작업에 필요한 도구만 공개하고, 단계가 진행되면 추가로 노출한다.

Ralph Loop — 장기 작업 패턴

단일 세션으로 완료할 수 없는 작업은 Ralph Loop로 처리한다. 완료 목표에 도달할 때까지 새 컨텍스트로 에이전트를 재시작하는 구조다.

def ralph_loop(goal: str, max_iterations: int = 10):
    iteration = 0
    while iteration < max_iterations:
        result = run_agent(goal, fresh_context=True)
        if result.completed:
            return result
        goal = result.remaining_work  # 남은 작업을 다음 이터레이션으로
        iteration += 1
    raise Exception("목표 미달성")

Planning은 목표를 단계별로 분해하고 계획 파일로 저장한다. Planner와 Evaluator를 분리해서 자기평가 편향을 줄인다. "내가 만든 걸 내가 평가한다"는 구조는 실제 버그를 잘 잡지 못한다.

도구 설계 — 적게, 명확하게

10개의 집중형 도구 > 50개의 겹치는 도구

각 도구의 이름, 설명, 스키마는 매 요청마다 프롬프트에 포함된다. 도구가 많아질수록 모델이 선택 장애를 겪고, 프롬프트 길이도 늘어난다.

도구 설계 원칙:

• 단일 책임: 한 도구는 한 가지 일만
• 명확한 이름: execute_command보다 run_test_suite
• 보안 주의: MCP 서버는 신뢰할 수 있는 텍스트를 다루므로 프롬프트 인젝션 위험을 항상 고려

Harness-as-a-Service 전환

현재 에이전트 생태계는 LLM API에서 Harness API로 무게중심이 이동 중이다. Claude Agent SDK, Codex SDK, OpenAI Agents SDK가 이 전환을 가속하고 있다. 모델을 직접 호출하는 대신, harness가 내장된 서비스를 호출하는 패턴이다.

미래는 동적 도구/컨텍스트 조립으로 향한다. "사전 설정된 harness"가 아니라, 작업에 맞게 필요한 도구와 규칙을 런타임에 컴파일하는 컴파일러 같은 harness다.

마무리

• 모델보다 harness 설계 격차가 크다 — Terminal Bench 2.0이 이미 증명
• AGENTS.md 각 줄은 과거 실패 이력 — 추상적 지침은 무시된다
• Ratchet 원칙 — 실수가 곧 규칙이 되는 시스템을 만들어라
• 적은 도구, 명확한 피드백, 자동 강제 — harness의 3요소

지금 당장 할 수 있는 일은 하나다. 에이전트가 가장 자주 실수하는 것 하나를 골라 AGENTS.md에 규칙을 추가하고, hook으로 강제하는 것이다.

참고:

• Agent Harness Engineering: https://addyosmani.com/blog/agent-harness-engineering/