[AI] #1: Harness Engineering

 

지금껏 Claude를 사용해서 개발을 해오면서도 claude가 어느 단계에서 어떤 Agent를 호출해서 사용하는지, 혹은 어떻게 Agent나 Skill을 구성해야하는 지에 대한 생각을 깊게 해오지 않았다.

정말 아무것도 모를 때에는 Claude.md 파일에 모든 내용과 지침을 때려넣는 것도 해봤으니 말 다했다.

 

Claude를 '잘' 사용할 수 있게 되면 클로드가 MCP를 직접 호출하거나 Agent가 다른 Agent를 호출해서 여러 역할을 동시에 수행하게 하는 등의 일도 가능하고, 퇴근 시간에도 스스로 계속해서 일을 하는 노예(?)를 만들어 놓을 수도 있다.

 

 

이제는 프롬프트를 잘 쓰는 것 뿐만 아니라, "AI가 스스로 일할 작업환경을 얼마나 잘 설계해두는가"가 중요하게 되었다.

이 작업환경을 설계해두는 개념을 "하네스 엔지니어링(Harness Engineering)"이라고 부른다

 

이번에는 이 하네스 엔지니어링은 무엇이고, Claude를 더 잘 사용하기 위한 하네스를 공부해보고자한다.

---

1. 언어 모델과 에이전트는 다르다

먼저 두 개념을 구분해야 한다.

 

언어 모델(Language Model) 은 텍스트를 받아서 텍스트를 돌려주는 엔진이다. 질문을 하면 답을 한다. 코드를 보여주면 설명을 해준다. 하지만 모델 자체는 파일을 열거나, 터미널 명령어를 실행하거나, Slack에 메시지를 보내는 것을 직접 할 수 없다. 텍스트의 세계 안에만 존재한다.

 

에이전트(Agent) 는 다르다. 에이전트는 목표를 받으면 스스로 계획을 세우고, 필요한 도구를 꺼내 쓴다. 결과를 보고 다시 판단한다. 작업이 끝날 때까지 이 과정을 반복한다. 파일을 실제로 열고, 코드를 실행하고, 에러 메시지를 확인하고, 수정하는 행동을 직접 한다.

핵심 차이를 한 문장으로 정리하면 이렇다.

 

'말만 잘하는 언어 모델'을 '실제로 행동하는 에이전트'로 만드는 것은 바로 하네스다.

---

2. 하네스란 무엇인가

하네스(Harness) 는 언어 모델 주위를 감싸서, 모델이 실제 세상과 상호작용할 수 있도록 도구·환경·규칙·안전장치를 제공하는 인프라 골격이다.

 

 

아직 감이 잘 오지 않는다면 다음 비유를 생각해보자.

 

아주 유능한 시니어 개발자가 있다. 10년 경력에 모든 기술 지식을 갖추고 있다. 그런데 오늘 완전히 낯선 회사에 첫 출근을 했다. 이 사람에게 아래의 것들이 없다면 아무것도 할 수 없다.

• 노트북과 코드 저장소 접근 권한 (도구)
• 이 회사가 사용하는 코딩 컨벤션 문서 (컨텍스트)
• Jira 같은 작업 관리 시스템 (할 일 목록)
• 실수했을 때 되돌릴 수 있는 Git (안전장치)

 

이 모든 '업무 인프라'가 곧 하네스다.

중요한 포인트가 있다. 개발자(모델)의 능력은 이미 충분하다. 우리가 설계해야 하는 것은 그 능력이 발휘될 무대, 즉 하네스다.

---

3. 에이전트 루프

하네스에서 가장 핵심적인 부분은 에이전트 루프(Agent Loop) 다. 이 루프는 에이전트가 작업을 처리하는 반복 구조이다.

사용자 입력
    │
    ▼
┌─────────────────────┐
│   컨텍스트 수집        │  ← 관련 파일, 기억, 규칙 등을 불러온다
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   모델 추론           │  ← Claude가 "다음에 무엇을 해야 할까?"를 판단한다
└──────────┬──────────┘
           │
    도구를 써야 하나?
     예 /       \ 아니오
      /           \
     ▼             ▼
┌─────────┐   ┌──────────┐
│ 도구 실행 │   │  응답 출력 │  ← 작업 완료
│ (파일,   │   └──────────┘
│  명령어, │
│  검색…)  │
└────┬────┘
     │
     ▼
┌─────────────────────┐
│  결과를 컨텍스트에      │  ← "파일을 읽었더니 이런 내용이었다"를 기록
│  추가                │
└──────────┬──────────┘
           │
      작업이 끝났나?
     예 /       \ 아니오
      /           \
     ▼             ▼
┌──────────┐   [모델 추론]으로 돌아가서 반복
│ 응답 출력  │
└──────────┘

 

이 루프에서 주목해야 할 점이 있다. 루프 자체는 매우 단순하다. "모델에게 보내고 → 결과를 받고 → 도구를 실행하고 → 다시 모델에게 보내고"를 반복하는 구조다. 복잡한 AI가 따로 있는 게 아니다. 아주 뛰어난 모델이 이 단순한 루프 안에서 작동하는 것만으로 복잡한 작업을 해낸다.

 

그래서 하네스 엔지니어링의 목표는 루프 자체를 복잡하게 만드는 것이 아니라, 루프가 잘 돌아갈 수 있는 환경을 잘 설계하는 것이다.

---

4. 하네스의 핵심 구성요소

잘 만들어진 하네스에는 공통적으로 등장하는 구성요소들이 있다. Claude Code를 기준으로 살펴보면 다음과 같다.

구성요소	하는 일	쉬운 비유
모델 인터페이스	언어 모델과 통신하는 창구	팀원에게 업무를 지시하는 팀장
도구 레지스트리	모델이 사용할 수 있는 도구 목록과 실행기	사무실 비품 창고 + 사용 설명서
컨텍스트 관리자	모델에게 보낼 정보를 취사선택하고 정리	회의 전에 필요한 자료만 추려 브리핑하는 비서
실행 엔진	도구 호출을 실제로 처리	설계도를 받아 실제로 시공하는 팀
메모리 시스템	단기(현재 대화)·장기(이전 세션) 기억 관리	회의 메모장 + 업무 일지
피드백 루프	도구 실행 결과를 다시 컨텍스트에 입력	실험 결과를 노트에 적고 다음 실험을 설계하는 과정
안전 장치	위험한 작업 차단 및 사용자 승인 게이트	중요 결제 전 상사 결재를 받는 절차
오케스트레이션	여러 에이전트를 조율하는 상위 계층	여러 팀을 동시에 관리하는 프로젝트 매니저

 

각각의 역할을 조금 더 들여다보자.

 

도구 레지스트리: 모델에게 '손'을 붙여주는 곳

언어 모델은 텍스트만 주고받는다. 하네스는 도구(Tool) 를 통해 모델이 실제 세계와 상호작용할 수 있게 한다. Claude Code의 내장 도구는 파일 읽기·쓰기·편집, bash 명령어 실행, 웹 검색, 브라우저 제어 등이다. 도구 레지스트리는 이 목록과 각 도구의 사용법 설명을 모델에게 전달한다. 모델은 "read_file과 bash를 쓸 수 있다"는 것을 인식하고 적절한 상황에서 꺼내 쓴다.

여기서 중요한 포인트가 있다. 모델은 파일 시스템을 직접 건드리지 않는다. 모델이 "이 파일을 읽어야겠다"고 판단하면, 하네스의 실행 엔진이 실제로 파일을 열어 그 내용을 컨텍스트에 넣어준다. 모델은 항상 텍스트만 주고받고, 나머지는 하네스가 처리한다.

 

컨텍스트 관리자: 하네스에서 가장 까다로운 문제

언어 모델에는 컨텍스트 윈도우(Context Window) 라는 한계가 있다. 모델이 한 번에 볼 수 있는 정보의 양이다. 작업이 길어질수록 대화 기록, 파일 내용, 도구 실행 결과가 쌓여서 이 공간이 가득 찬다.

컨텍스트 관리자는 이 공간을 효율적으로 쓰기 위해 무엇을 계속 보여주고, 무엇을 요약하거나 제거할지 끊임없이 판단한다. 컨텍스트를 잘 관리하지 못하면 모델이 이전에 받은 규칙을 잊거나, 작업이 중간에 멈추는 문제가 생긴다. 그래서 컨텍스트 관리는 하네스 품질을 좌우하는 가장 중요한 요소 중 하나다.

 

안전 장치: "이건 확인받고 하겠습니다"

하네스가 없는 모델은 데모 수준에 머문다. 프로덕션 수준의 하네스에는 반드시 안전 장치가 있어야 한다. Claude Code가 파일을 삭제하거나 중요한 명령어를 실행하려 할 때 사용자에게 승인을 요청하는 것이 바로 이 장치다. 아무리 모델이 자신 있어도, 되돌릴 수 없는 행동 앞에서는 멈추고 확인을 받아야 한다.

 

---

5. Claude Code를 하네스로 다시 보기

이제 Claude Code를 하네스 관점으로 다시 본다.

┌─────────────────────────────────────────────────┐
│                   Claude Code                    │
│                                                  │
│  ┌───────────────────────────────────────────┐   │
│  │              하네스 (Harness)              │   │
│  │                                           │   │
│  │   도구 레지스트리     컨텍스트 관리자            │   │
│  │   실행 엔진           안전 장치              │   │
│  │   메모리 시스템       오케스트레이션            │   │
│  │                                          │   │
│  │   ┌───────────────────────────────────┐  │   │
│  │   │         언어 모델 (Claude)          │   │   │
│  │   │      추론과 판단은 여기서 일어남         │   │  │
│  │   └───────────────────────────────────┘   │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

 

공식 문서는 Claude Code를 이렇게 정의한다. "Claude라는 언어 모델에 도구, 컨텍스트 관리, 실행 환경을 제공해 코딩 에이전트로 만들어주는 에이전트 하네스." claude 명령어를 실행하는 순간, 이미 잘 설계된 하네스를 갖춘 에이전트를 손에 쥔 것이다.

 

---

6. 그래서 하네스 설계가 왜 중요한가

"Claude Code가 이미 다 해주는데, 하네스를 내가 왜 알아야 하나?"라는 의문이 생길 수 있다. 두 가지 이유가 있다.

첫째, 같은 모델도 하네스에 따라 성능이 크게 달라진다. Anthropic의 엔지니어링 팀도 "아무리 뛰어난 프론티어 모델이라도 하네스 설계가 나쁘면 성능이 크게 저하된다"고 강조한다. 컨텍스트를 잘못 관리하거나 도구를 어설프게 제공하면, 세계 최고의 모델도 엉뚱한 결과를 낸다.

둘째, Claude Code는 하네스를 직접 확장할 수 있도록 설계되어 있다. 팀의 규칙, 반복 작업, 외부 서비스 연동, 자동화 스크립트를 하네스에 직접 연결할 수 있다. 이 기능들이 하네스의 어느 부분에 연결되는지 이해해야 제대로 활용할 수 있다. 2편에서는 이 확장 기능들을 하나씩 살펴본다.

---

마치며

이번 편의 핵심을 정리해보자.

개념	한 줄 정리
언어 모델	텍스트를 받아 텍스트를 돌려주는 추론 엔진
에이전트	목표를 받아 스스로 행동을 반복하는 존재
하네스	모델을 에이전트로 만들어주는 인프라 골격
에이전트 루프	추론 → 도구 실행 → 결과 반영을 반복하는 심장부
Claude Code	Claude 모델 + 잘 설계된 하네스

 

 

다음 편에서는 Claude Code가 제공하는 하네스 확장 기능 — CLAUDE.md, Skills, MCP, Subagents, Hooks — 을 하나씩 뜯어보도록 하자.

각 기능이 하네스의 어느 구성요소에 연결되는지, 실제로 어떻게 쓰는지를 구체적인 예시와 함께 살펴본다.

 

---

참고하면 좋은 자료 링크

https://news.hada.io/topic?id=28232

코딩 에이전트의 구성 요소 | GeekNews

https://news.hada.io/topic?id=28966

하네스 엔지니어링: 모델보다 중요한 작업 환경 설계의 시대 | GeekNews