에이전트 하네스 엔지니어링(Agent Harness Engineering): AI 코딩 에이전트 성능을 결정하는 진짜 경쟁력

AI 모델보다 중요한 것은 '하네스(Harness)'입니다

최근 AI 코딩 에이전트는 빠르게 발전하고 있습니다. 많은 사람들이 어떤 AI 모델이 더 뛰어난지, 어떤 모델이 더 정확한 코드를 생성하는지에 집중하지만, 실제 현장에서는 모델 자체보다 에이전트를 둘러싼 실행 환경(Harness) 이 더 큰 성능 차이를 만들어내는 경우가 많습니다.

Agent Harness Engineering은 이러한 실행 환경을 지속적으로 개선하여 AI 에이전트가 같은 실수를 반복하지 않도록 만드는 엔지니어링 방법론입니다. 단순히 더 좋은 모델을 사용하는 것이 아니라 프롬프트, 도구, 실행 환경, 메모리, 피드백 시스템 등을 함께 설계하여 에이전트의 성능을 극대화하는 것이 핵심입니다.

이번 글에서는 Agent Harness Engineering의 개념부터 구성 요소, 주요 기술, 실제 적용 방식, 그리고 앞으로의 발전 방향까지 정리해보겠습니다.

반응형

---

Agent Harness Engineering이란?

Agent Harness Engineering은 AI 모델 자체가 아닌, 모델을 둘러싼 모든 실행 환경을 설계하고 개선하는 기술입니다.

핵심 개념은 다음과 같습니다.

Agent = Model + Harness

여기서 Harness는 AI 모델을 제외한 모든 요소를 의미합니다.

즉, 단순한 LLM은 에이전트가 아니며, Harness가 추가되어야 비로소 실제 작업을 수행하는 AI Agent가 됩니다.

Harness에는 다음과 같은 요소들이 포함됩니다.

• 시스템 프롬프트(System Prompt)
• AGENTS.md, CLAUDE.md 등 규칙 파일
• Tool 및 MCP(Server)
• 파일 시스템
• Sandbox 환경
• 실행 오케스트레이션
• Sub Agent
• Hook
• Middleware
• Context 관리
• Feedback Loop
• Logging 및 Monitoring

즉, AI가 작업을 수행하는 모든 기반 인프라가 Harness라고 볼 수 있습니다.

---

왜 Harness가 중요한가?

기존에는 AI가 잘못된 결과를 만들면 대부분 모델의 성능 문제라고 생각했습니다.

하지만 Harness Engineering에서는 다음과 같이 접근합니다.

AI가 실수했다면 모델을 바꾸는 것이 아니라 Harness를 개선한다.

예를 들어,

• 특정 코딩 규칙을 지키지 않았다.
• 위험한 명령어를 실행했다.
• 테스트를 통과하지 못했다.
• 너무 긴 작업에서 중간에 종료했다.

이러한 문제들은 대부분 Harness를 통해 해결할 수 있습니다.

즉,

• 규칙 추가
• Hook 추가
• 자동 검증
• Planner 추가
• Evaluator 추가

등으로 동일한 실수가 다시 발생하지 않도록 만드는 것이 Harness Engineering입니다.

---

Harness를 구성하는 주요 요소

1. System Prompt 및 규칙 파일

AI가 항상 따라야 하는 규칙을 정의합니다.

대표적인 파일

• AGENTS.md
• CLAUDE.md
• Skill File

예를 들어

• 항상 npm 대신 pnpm 사용
• Legacy 디렉터리 수정 금지
• Logger 반드시 사용
• 테스트 없이 PR 생성 금지

와 같은 프로젝트 규칙을 정의합니다.

좋은 규칙 파일은 짧고 명확하며, 실제 발생했던 문제를 기반으로 작성하는 것이 중요합니다.

---

2. Tool과 MCP

AI는 Tool을 통해 실제 작업을 수행합니다.

예를 들어

• Git
• Browser
• Search
• File Editor
• Terminal
• Context7
• MCP Server

등이 있습니다.

좋은 Harness는 필요한 Tool만 제공하여 AI가 효율적으로 작업하도록 돕습니다.

---

3. File System

파일 시스템은 Agent의 장기 기억 공간 역할을 합니다.

모델은 Context Window 안의 정보만 직접 사용할 수 있지만, 파일 시스템을 활용하면

• 코드
• 문서
• 작업 계획
• 중간 결과

등을 저장하고 다시 불러올 수 있습니다.

또한 여러 Agent가 같은 프로젝트를 협업할 수도 있습니다.

---

4. Git 통합

Git은 단순한 버전 관리가 아니라 Agent의 작업 이력을 관리하는 핵심 요소입니다.

Git을 통해

• 변경 이력 관리
• Rollback
• Branch 실험
• 진행 상황 추적

등이 가능해집니다.

---

5. Bash 및 코드 실행

최근 AI Agent는 대부분 ReAct Loop 기반으로 동작합니다.

즉,

생각 → Tool 실행 → 결과 확인 → 다음 행동

을 반복합니다.

이때 가장 강력한 Tool이 바로 Bash입니다.

Bash를 제공하면 AI는 필요한 도구를 직접 실행하거나 새로운 스크립트를 만들어 문제를 해결할 수 있습니다.

---

6. Sandbox

AI가 생성한 코드를 로컬 환경에서 실행하는 것은 위험할 수 있습니다.

Sandbox는 격리된 환경에서

• 코드 실행
• 패키지 설치
• 테스트 수행
• 브라우저 자동화

등을 안전하게 수행하도록 지원합니다.

또한

• 명령어 제한
• 네트워크 차단
• 환경 초기화

등도 가능합니다.

---

7. Memory와 Search

AI는 학습 이후의 새로운 정보를 알지 못합니다.

이를 해결하기 위해 Harness는

• AGENTS.md
• Memory File
• Web Search
• 최신 문서 검색
• Context7

등을 활용하여 최신 정보를 Context에 주입합니다.

이를 통해 지속적인 학습과 유사한 효과를 제공합니다.

---

Context Rot 문제와 해결 방법

AI는 Context가 길어질수록 성능이 떨어지는 문제가 있습니다.

이를 Context Rot이라고 합니다.

Harness에서는 다음과 같은 방법으로 해결합니다.

Context Compaction

오래된 Context를 요약하여 새로운 Context를 확보합니다.

---

Tool Output Offloading

수천 줄의 로그를 Context에 모두 넣지 않고,

전체 로그는 파일에 저장하고 필요한 부분만 Context에 전달합니다.

---

Progressive Skill Loading

필요한 Tool과 Skill만 필요한 시점에 Context에 추가합니다.

이를 통해 Context 낭비를 줄일 수 있습니다.

---

Full Context Reset

장시간 작업에서는 Context를 완전히 새로 시작하고

필요한 작업 내용만 요약하여 전달합니다.

이는 새로운 개발자가 프로젝트를 인수받는 방식과 유사합니다.

---

장시간 작업(Long Horizon Execution)

복잡한 프로젝트에서는 AI가

• 작업을 중간에 종료하거나
• 계획을 잃거나
• Context가 꼬이는

문제가 발생합니다.

이를 해결하기 위해 Harness에서는 다양한 기법을 사용합니다.

Planner

먼저 작업 계획을 파일로 작성합니다.

예)

1. 요구사항 분석
2. 코드 수정
3. 테스트
4. 문서 작성

AI는 각 단계를 완료하면서 계획을 갱신합니다.

---

Verification

각 단계 이후

• Type Check
• Unit Test
• Lint

등을 자동 수행하여 오류를 다시 AI에게 전달합니다.

---

Planner / Generator / Evaluator 분리

하나의 AI가

• 생성
• 검토

를 모두 수행하면 자기 평가에 관대한 문제가 있습니다.

따라서

• Planner
• Generator
• Evaluator

를 서로 다른 Agent로 분리하면 더 높은 품질을 얻을 수 있습니다.

---

Hook: 규칙을 강제하는 핵심 기술

Hook은 특정 시점마다 자동 실행되는 스크립트입니다.

예를 들어

• 파일 수정 후 Lint 실행
• Commit 전 Test 실행
• 위험한 Bash 명령 차단
• Main Branch Push 승인 요청
• 코드 자동 포맷팅

등을 자동화할 수 있습니다.

Harness에서는

성공은 조용하게, 실패는 자세하게

라는 원칙을 사용합니다.

즉,

성공하면 아무것도 하지 않고,

실패하면 오류 내용을 AI에게 전달하여 스스로 수정하도록 합니다.

---

Harness Engineering의 핵심 원칙

Harness Engineering에서 가장 중요한 원칙은 다음과 같습니다.

모든 실수는 새로운 규칙이 된다.

예를 들어

AI가 테스트 코드를 주석 처리한 채 Pull Request를 생성했다면,

다음부터는

• AGENTS.md에 규칙 추가
• Hook에서 .skip() 검사
• Evaluator가 차단

등을 추가하여 같은 실수를 다시 하지 않도록 만듭니다.

즉, Harness는 프로젝트의 실패 경험을 지속적으로 반영하며 발전하는 구조입니다.

---

Harness as a Service(HaaS)

최근에는 Harness 자체를 서비스 형태로 제공하는 흐름도 등장하고 있습니다.

기존에는 개발자가 직접

• Tool 호출
• Loop 관리
• Context 관리
• 승인 프로세스

등을 구현해야 했습니다.

하지만 이제는 다음과 같은 Agent SDK가 이러한 기능을 기본 제공하며, 개발자는 필요한 설정만 추가하면 됩니다.

• Claude Agent SDK
• Codex SDK
• OpenAI Agents SDK

이를 통해 개발자는 에이전트를 처음부터 구현하는 대신, 도메인에 맞는 프롬프트와 도구 설계에 집중할 수 있습니다.

---

앞으로의 발전 방향

AI 모델이 발전한다고 해서 Harness의 중요성이 줄어드는 것은 아닙니다.

오히려 더 복잡한 작업을 수행할 수 있게 되면서 새로운 형태의 Harness가 필요해지고 있습니다.

향후에는 다음과 같은 방향으로 발전할 것으로 예상됩니다.

• 여러 AI Agent가 하나의 프로젝트를 병렬로 협업하는 구조
• 작업 기록을 분석하여 Harness를 스스로 개선하는 에이전트
• 작업에 맞는 Tool과 Context를 실시간으로 조합하는 동적 Harness
• 정적인 설정 파일이 아닌 컴파일러처럼 동작하는 지능형 Harness

이처럼 Harness는 단순한 실행 환경을 넘어 AI 에이전트의 성능과 안정성을 결정하는 핵심 요소로 자리 잡고 있습니다.

---

728x90

Agent Harness Engineering은 AI 모델의 성능을 높이는 기술이 아니라, AI가 안정적이고 일관되게 작업을 수행할 수 있도록 실행 환경 전체를 설계하는 방법론입니다.

핵심은 "Agent = Model + Harness"라는 개념에 있습니다. 동일한 AI 모델이라도 어떤 Harness를 적용하느냐에 따라 성능과 결과물의 품질은 크게 달라질 수 있습니다.

또한 Harness는 한 번 구축하고 끝나는 것이 아니라, 실제 운영 과정에서 발생한 실패 사례를 규칙과 자동화로 축적하며 지속적으로 개선됩니다. 이러한 반복적인 개선 과정은 AI 에이전트를 더욱 신뢰할 수 있는 시스템으로 발전시키는 기반이 됩니다.

앞으로 AI 에이전트가 더욱 복잡한 업무를 수행하게 될수록, 모델 자체의 성능뿐 아니라 Harness를 얼마나 효과적으로 설계하고 운영하는지가 AI 시스템의 경쟁력을 결정하는 중요한 요소가 될 것입니다.

300x250

https://www.oreilly.com/radar/agent-harness-engineering/

Agent Harness Engineering