하네스 엔지니어링

AI 호출을 "프로그램"으로 둘러싸는 기술

프롬프트 엔지니어링이 "AI에게 뭐라 말할까", 컨텍스트 엔지니어링이 "AI가 뭘 볼까"였다면, 하네스 엔지니어링(Harness Engineering)은 그 위 레이어다 — "AI 호출을 둘러싼 전체 시스템을 어떻게 설계할까".

하네스(harness)는 원래 "말을 마차에 묶는 마구(馬具)"를 뜻한다. 천재 말 한 마리(LLM)가 있어도 마구가 없으면 마차를 끌 수 없다. AI도 똑같다.

#1. 왜 하네스 엔지니어링인가

GPT-3.5 시절에는 "질문 → 답"만 잘 짜면 됐다. 그러나 Claude Code, Devin, Cursor 같은 에이전트형 AI가 폭발하면서 새로운 문제가 생겼다.

#2. 하네스의 5가지 구성 요소

flowchart TB
    LLM["🧠 LLM 호출<br/>(천재 인턴)"]
    Tool["🔧 도구 시스템<br/>(파일·DB·API·MCP)"]
    Loop["🔁 실행 루프<br/>(계획·실행·검증·재시도)"]
    Mem["💾 메모리<br/>(장기 기억)"]
    Eval["📊 평가·관찰<br/>(품질 점검·로그)"]
    Multi["👥 다중 에이전트<br/>(전문가 분담)"]
    Tool --> LLM
    Loop --> LLM
    Mem --> LLM
    Multi --> LLM
    LLM --> Eval
    style LLM stroke:#5e35b2,stroke-width:4px

#① 도구 시스템 (Tool Use)

AI가 외부 세계에 "손을 뻗어" 할 수 있는 일들을 정의한다.

각 도구는 명확한 명세(스키마)와 결과 형식이 필요하다. 도구 설계 자체도 하네스 엔지니어링의 핵심 — 너무 많으면 AI가 헷갈리고, 너무 적으면 일을 못 한다.

#② 실행 루프 (Agentic Loop)

단순한 "질문 → 답"이 아니라 다단계 사이클이다.

flowchart LR
    P["1️⃣ 계획<br/>(Plan)"] --> A["2️⃣ 행동<br/>(Act / Tool)"]
    A --> O["3️⃣ 관찰<br/>(Observe)"]
    O --> T{"목표<br/>달성?"}
    T -->|아니오| P
    T -->|예| D["완료"]
    style P fill:#e3f2fd
    style A fill:#fff3e0
    style O fill:#f3e5f5
    style D fill:#e8f5e9

ReAct (Reasoning + Acting) 패턴이라 부른다. 생각 → 행동 → 결과 관찰 → 다시 생각. 잘못된 길로 가면 되돌아와서 다른 방법을 시도한다.

#③ 메모리 시스템

세션을 넘어 유지되는 장기 기억.

#④ 평가·관찰 (Eval & Observability)

에이전트가 잘 동작하는지 어떻게 알 수 있나? 이게 의외로 어려운 문제다.

• 로그: 각 단계의 입력·출력 기록

• 트레이스: 한 작업이 어떤 도구·LLM 호출을 거쳤는지 추적

• 평가셋(Eval set): 정답 있는 케이스로 회귀 테스트

• LLM-as-judge: 다른 LLM이 결과 품질을 평가

#⑤ 다중 에이전트 (Sub-agents / Multi-agent)

한 LLM이 모든 걸 다 하는 게 아니라 전문화된 서브에이전트로 분담한다.

Claude Code의 서브에이전트 시스템(code-reviewer, test-generator 등)이 이 패턴을 직접 구현한다.

#3. 좋은 하네스의 4가지 원칙

#원칙 1: 작은 단위로, 자주 검증

한 번에 100줄 코드를 생성하지 말고, 10줄 단위로 만들고 매번 동작 확인. 잘못된 길로 멀리 가지 않는다.

#원칙 2: 명시적 도구 > 암묵적 추론

"AI가 알아서 잘 하겠지"보다 "AI에게 git status를 실행시키고 결과를 보고 판단하게 한다"가 안전하다.

#원칙 3: 실패는 신호

도구 실행이 실패하면 그 에러를 AI에게 다시 보여주고 재시도하게 한다. "실패 → 시스템 종료"가 아니라 "실패 → 학습 신호".

#원칙 4: 사람이 마지막 검증자

자동화는 좋지만 돌이키기 어려운 작업(git push --force, DB 삭제, 메일 발송)은 사람의 확인을 받는다.

#4. Claude Code의 하네스 해부

Claude Code는 잘 설계된 하네스의 교과서 같은 사례다.

→ 사용자가 "PRD대로 앱 만들어줘" 한 줄 입력하면, 하네스가 수십~수백 번의 LLM 호출, 도구 실행, 검증 루프를 알아서 돌린다.

flowchart LR
    U["👤 사용자<br/>한 줄 지시"] --> H["⚙️ Claude Code 하네스"]
    H --> L1["LLM 호출 #1<br/>계획 세우기"]
    L1 --> T1["도구 호출<br/>git status"]
    T1 --> L2["LLM 호출 #2<br/>파일 분석"]
    L2 --> T2["도구 호출<br/>Edit file.py"]
    T2 --> L3["LLM 호출 #N<br/>검증·요약"]
    L3 --> U2["✅ 결과 보고"]
    style H stroke:#5e35b2,stroke-width:4px

#5. 평가(Eval) 엔지니어링 — 4번째 트렌드

하네스 엔지니어링과 짝을 이루는 게 평가 엔지니어링(Evaluation Engineering)이다. "이 에이전트가 잘 동작하나?"를 어떻게 측정할까.

#정리

• 하네스 엔지니어링 = LLM 호출 주변의 시스템 전체를 설계하는 기술

• 5가지 요소: 도구 · 실행 루프 · 메모리 · 관찰 · 다중 에이전트

• 원칙: 작은 단위 · 명시적 도구 · 실패를 신호로 · 사람의 마지막 검증

• Claude Code = 잘 설계된 하네스의 교과서

• 짝이 되는 평가 엔지니어링도 함께 발전 중

#4대 엔지니어링 한눈에

다음 장에서는 MCP, 즉 하네스의 핵심 부품인 "외부 도구를 AI에게 연결하는 표준"을 본다.