Harness Engineering

 

Harness Engineering 이란

개념

AI Agent는 Model로만 구성되는 것이 아니라 여러 요소가 결합된 Agent Application 또는 Agent System 형태로 만들어짐.

 

AI Agent = Model + Harness

  - Model => 두뇌

  - Harness => 그 두뇌가 실제 작업을 수행할 수 있게 해주는 작업 구조 전체 

 

사용자
  ↓
Agent Application
  ↓
Agent Runtime
  ↓
Model
  ↕
Harness
  ↕
실제 실행 환경

File / Git / Shell
API / DB / Test ...

 

구분	의미
AI Agent	목표를 수행하는 전체적인 Agent
Model	Agent 안에서 판단·추론을 담당
Harness	Model/Agent가 Tool과 환경을 사용하며 실행되도록 지원·제어하는 구조
Environment	실제 파일, Shell, Git, API, DB, Browser 등 작업 대상

 

 

ex) AI 개발 뉴스 Agent 

: 매일 지정 시간 실행 → 오늘 실행 여부 확인 → AI 뉴스 Agent 실행 → 뉴스 조사 / 평가 → 블로그 글 작성 → Notion 저장 → 실행 결과 기록

AI News Application
│
├─ Scheduler                ← Application
├─ Daily Run Check          ← Application
├─ Notion 저장              ← Application
├─ SQLite                   ← Application
│
└─ Agent Runtime
    ├─ Model
    │
    └─ Harness
        ├─ Context
        ├─ Web Search 접근
        ├─ Tool 실행
        ├─ 결과 반환
        ├─ 반복 제어
        └─ 검증

 

 

의의

좋은 Model을 사용한다고 해서 Agent가 항상 좋은 결과를 내는 것은 아님. 

 

Model이 실제 환경에서 필요한 정보를 얻고, Tool을 사용하고, 결과를 확인하며, 안전하게 작업을 완료할 수 있도록 실행 구조를 설계

좋은 Model
+
적절한 Context
+
Tool
+
State 관리
+
Feedback
+
Verification
+
Permissions
        ↓
안정적인 Agent 작업

 

 

ex) 
기존 개발 : 개발자 → 테스트 코드 작성 →  테스트 →  수정 → 배포

하네스 엔지니어링 : 개발자 → 목표와 규칙 설계 → AI가 코드 작성 → AI가 테스트/검증 → 개발자가 판단/관리 

 

---

 

비교 : Prompt Engineering  / Context Engineering / Harness Engineering

 

세 개념은 서로 완전히 대체되는 개념이 아니라, AI 시스템을 설계할 때 관심 범위가 어디에 있느냐의 차이로 보는 것이 좋다. 

 

구분	설명	주요 대상	예시 (AI 개발 뉴스 Agent)
Prompt Engineering	Model에게 어떻게 지시할 것인가?  => 사용자의 의도와 원하는 결과를 Model이 잘 이해하도록 프롬프트를 설계하는 영역	Instrunctions, Role, Output Format	최신 AI 개발 뉴스를 조사하고 기술적 중요도가 높은 내용만 선별해라.
Context Engineering	Model이 판단할 때 어떤 정보를 제공할 것인가?  ex) 어떤 정보를 넣을지, 무엇을 제외할지, 언제 추가 정보를 가져올지, Tool 결과를 어떤 형태로 전달할지	문서, 대화, 검색 결과, Tool 결과, 상태	오늘 검색된 뉴스 공식 발표 기존 블로그 후보 이전 검색 결과
Harness Engineering	Model이 실제 환경에서 어떻게 행동하고, 결과를 확인하며, 작업ㅇ르 끝까지 수행하게 할 것인가? => Model이 실제 환경과 상호작용하는 실행 구조 전반을 다룸	Tools, Agent Loop, State, Permissions, Verification	Web Search Tool 제공 → 검색 결과를 Model에 반환 → 부족하면 추가 검색 가능 → 기존 후보 조회 가능 → 최대 반복 횟수 제한 → 중복 여부 검증 → 최종 결과 검증

 

---

 

주요 구성 요소

 

구성요소	설명	예
Context	Model이 현재 작업을 수행하기 위해 필요한 정보를 구성하고 전달하는 역할 ex) 사용자의 요청, 프로젝트 규칙, 관련 소스 코드, 검색 결과, 이전 Tool 실행 결과, 현재 작업 상태 => 현재 작업에 필요한 정볼르 선택해서 Model에 제공하는 것이 중요	README, AGENTS.md, 관련 Source Code
Tools	Model이 실제 환경에서 행동할 수 있도록 외부 기능에 접근할 수 있게 함 ex) 어떤 Tool을 사용할 수 있는지, 어떤 Parameter를 전달할 수 있는지, Tool 실행 결과를 어떻게 반환할지, Tool 실행 실패를 어떻게 처리할지 등	File Search, Read, Edit, Shell, Git
Meomory / State	Agent가 긴 작업을 수행할 때 이전 정보와 현재 작업 상태를 유지하는 역할 - Memory : 이전 작업이나 프로젝트에서 유지해야 할 정보 - State : 현재 작업이 어디까지 진행되었는지에 대한 상태	현재 작업 단계, 수정한 파일, Test 결과
Agent Loop	Model과 Tool사이의 반복 실행 흐름을 관리	탐색 → 수정 → Test → 재수정
Observaility	Agent가 어떤 행동을 했는지 추적할 수 있도록 하는 기능  ex) 어떤 Tool을 호출했는가? 어떤 파일을 수정했는가?	실행 Command, Tool Call, 변경 기록
Verification	Agent가 작업을 수행한 뒤 실제로 요구사항을 만족했는지 확인하는 역할	Test, Build, Lint, Git Diff
Permissions	Agent가 어떤 행동까지 수행할 수 있는지 제한하는 역할	파일 수정 범위, Shell 제한, 승인 정책

 

 

 

---

 

Harness 설계 시 중요한 원칙

 

AI가 스스로 읽고+실행하고+검증하고+고칠 수 있는 구조를 만들기
Model이 예측 가능한 범위 안에서 필요한 작업을 수행하도록 만들기
=> 위 구조를 강제한다.

 

원칙	설명
Tool은 많을수록 좋은 것이 아님	Agent가 사용할 수 있는 Tool이 많아질수록 선택지가 늘어나지만, 동시에 잘못된 Tool선택이나 불필요한 호출 가능성도 증가함.  => 작업에 필요한 Tool만 제공 + Tool의 역할을 명확하게 분리
Context는 많이 넣는 것보다 필요한 정볼를 찾게 하는 것이 중요함	프로젝트 전체 파일을 한 번에 Context에 넣는 방식은 비효율적일 수 있다.  : 관련 없는 정보가 증가하면, 중요한 정보가 묻힐 수 있음  => 기본 프로젝트 규칙 제공 → Model이 필요한 정보 판단 → 검색 → 관련 파일만 조회 → 필요하면 추가 조회  AGENTS.md를 큰 설명서로 만들면 X => 백과사전처럼 쓰지 않고, 목차처럼 사용 ex) AGENTS.md ARCHITECTURE.md docs/   design-docs/   exec-plans/   product-specs/   references/   RELIABILITY.md   SECURITY.md
Model이 판단할 부분과 코드가 결정할 부분을 구분	모든 판단을 Model에게 맡길 필요는 없음.  명확한 규칙 => Code   ex) 오늘 Agent를 실행해야 하는가? 최대 재시도 횟수는 몇 번인가? Tool 호출 횟수가 제한을 넘 었는가? Production DB 접근을 허용하는가? 상황에 따른 판단 => Model   ex) 어떤 파일이 오류와 관련 있는가? 검색 결과 중 무엇이 중요한가? 실패 원인이 무엇인가? 다음에는 어떤 Tool을 사용할 것인가?
완료 조건을 명확하게 정의	Agent가 스스로 작업을 완료했다라고 하는 것을 완료 조건으로 사용하는 것은 위험.  작업마다 확인 간으한 기준을 두는 것이 좋다.  ex) Coding Agent => 관련 Test Pass + Build PASS + Lint Pass + 예상하지 않은 파일 변경 없음.
실패를 정상적인 실행 흐름으로 취급	실패 유형에 따라 처리 방식을 정하기  - 일시적인 오류 → 재시도 - Test 실패 → 결과를 Model에 전달하고 재분석 - Permission 오류 → 다른 방법 선택 - 반복 실패 → 중단 또는 사용자 확인
무한 반복을 방지	다음과 같은 제한들을 둔다 => 최대 Agent Step, 최대 Tool 호출 횟수, 최대 실행 시간, 동일 Tool 반복 횟수, 최대 실패 횟수 일정 조건을 넘으면 중단 또는 사용자 확인 요청
Tool 결과는 Model이 이해하기 쉬운 형태로 반환	구조화된 결과가 유용하다.  ex) status: failed tool: run_test test: LoginTest error: Expected 401 Actual 500
권한은 작업 위험도에 따라 나누기	모든 Tool을 같은 수준으로 취급할 필요는 없음 => 위험도가 높아질수록 권한을 강화하는 방식
실행 과정을 확인할 수 있어야 함	Agent가 실패했을 때, 실패원인을 모르는 상태가 되면 Harness를 개선하기 어려움.  => 따라서 최소한 다음 정도는 확인할 수 있는 것이 좋다.  - 어떤 Tool을 호출했는지 - 어떤 입력값을 사용했는지 - Tool 결과가 무엇이었는지 - 몇 번 반복했는지 - 어디에서 실패했는지 - 최종 Verification 결과

 

---

 

하네스의 3가지 기둥

하네스 주요 기둥

기둥	설명
컨텍스트 파일	AI가 작업을 시작할 때 가장 먼저 읽는 파일 ex) claude.md 등
자동 강제 시스템 (자동 교정 루프)	린터 빨간불 → 에이전트가 스스로 수정 →  사람 개입 불필요 (성공은 조용히, 실패는 시끄럽게)
가비지 컬렉션	AI가 만들어 놓은 안좋은 코드를 주기적으로 자동 청소  의의] AI는 기존 코드를 보고 따라하기 때문에 → 나쁜 패턴이 눈덩이 처럼 불어남 구현방법] 주기적 청소 에이전츠 - 문서가 실제 코드와 달라진 건 없는지 - 규칙을 위반한 코드가 생겼는지 - 사용하지 않는 코드가 쌓였는지

 

구성

프로젝트 루트/
│
├── AGENTS.md          ← ① 지시 문서
├── src/
│   ├── api/
│   │   └── AGENTS.md  ← API 레이어 전용 규칙
│   └── services/
│       └── AGENTS.md  ← 서비스 레이어 전용 규칙
├── .eslintrc          ← ② 아키텍처 제약
│
├── tests/             ← ③ 피드백 루프
│   └── ...
│
└── docs/
├── decisions/          # 기술 결정 기록 (ADR)
│   ├── 001-database.md
│   ├── 002-auth.md
│   └── 003-caching.md
│
├── conventions/        # 코딩 규칙 상세 설명
│   ├── naming.md
│   ├── error-handling.md
│   └── testing.md
│
├── domain/             # 비즈니스 도메인 지식
│   ├── glossary.md     # 용어 사전
│   └── workflows.md    # 주요 업무 흐름
│
└── failures/           # 실패 기록
    ├── 001-celery.md
    └── 002-graphql.md

구분	설명	내용
지시문서	에이전트가 작업을 시작하기 전에 읽는 메뉴얼 좋은 지시 문서의 조건] - 목차형 구조 : 에이전트가 필요한 섹션을 빠르게 찾을 수 있게 - 구체적인 규칙  - 금지 사항 명시 - 짧고 명확하게	- 코드스타일, 네이밍 규칙 - 절대 건드리면 안되는 파일 / 디렉토리 - PR 작성 방식, 커밋 메시지 형식
아케텍처 제약	잘못된 코드를 구조적으로 차단 => 린터, 타입 검사, 디렉토리 규칙처럼 코드가 저장되거나 병합되기 전에 자동으로 검사하는 장치 - 접근 1. 정적 분석 : 코드 저장 시 자동 검사   ex) 린터, 타입 검사 2. 구조적 제약 : 디렉토리/파일 구조로 경계 설정   ex) import 규칙, 경로 제한	- 허용되지 않은 import 경로 차단 - 코드 스타일 자동 교정 - 특정 패턴 사용 금지
피드백 루프	에이전트 행동을 실시간으로 교정 => 에이전트가 작업한 결과가 올바른지 즉시 알려주는 장치 (빠를 수록 좋음) 구성]  1. 가이드 : 올바른 방향을 미리 안내 => 실수 예방    ex) 예제 코드, 테스트 케이스 2. 센서 : 잘못된 결과를 감지 => 실수 포착   ex) CI 실패, 린터 경고, 테스트 실패  순서] 에이전트 작업 시작       ↓ [가이드] AGENTS.md 예시 참고 → 올바른 방향으로 코드 작성       ↓ [센서] pre-commit 린터 실행 → 형식 오류 즉시 차단       ↓ [센서] CI 테스트 실행 → 로직 오류 감지       ↓ 실패 시: 에이전트가 오류 메시지를 읽고 스스로 수정       ↓ 통과 시: PR 생성
가이드 설계	에이전트는 설명보다 예시에서 더 많은 것을 학습함 => 지식문서에 올바른 예시를 직접 넣어두기
지식 저장소	사람의 결정과 맥락을 축적 => 사람이 내린 결정, 채택한 이유, 포기한 대안을 기록해 둠 - AGENTS.md에서 참조해야 함.  - 처음부터 모든 문서를 만들 필요는 없음 => 에이전트가 잘못된 방향을 제안할 때마다 그 이유를  decisions/ 또는 failures/ 에 기록 저장하는 것] - 결정기록(ADR) - 왜 이방식을 선택했는가   ex) Redis 대신 PostgreSQL을 캐시로 쓰는 이유 - 실패기록 - 시도했다가 포기한 방법    => 특히 중요, 에이전트는 이미 실패한 방법을 모르면 같은    시도 반복   ex) Celery 도입 실패 - 운영 복잡도 과다. - 도메인 지식 - 비지니스 규칙과 용어   ex) 주문 상태 전이 규칙
가비지 컬렉션	하네스를 구축해도 시간이 지나면 흐트러진다.  => 드리프트를 자동으로 감지하고 정리하는 장치 드리프트 = 에이전트가 임시 파일을 남기고, 사용하지 않는 코드가 쌓이고, 지시 문서와 실제 코드가 어긋나기 시작 - 코드 드리프트 : 사용하지 않는 코드 누적   ex) 미사용 함수, 죽은 import - 문서 드리프트 : 코드와 문서가 어긋남   ex) AGENTS.md의 규칙이 실제와 다름 - 구조 드리프트 : 디렉토리 규칙 붕괴   e)X 임시 파일, 규칙 밖 경로