> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# Harness Engineering

> 이 문서는 **[AI 동향](/ai-trends/overview)** 섹션의 일부입니다.

> AI 에이전트를 프로덕션 환경에서 안정적으로 작동시키기 위해, 에이전트를 감싸는 시스템, 제약 조건, 피드백 루프를 설계하는 엔지니어링 분야

***

## 개요

**Harness Engineering** 은 2026년 초부터 독립적인 용어로 자리잡은 AI 엔지니어링 분야입니다. 핵심 아이디어는 단순합니다: **AI를 마법 상자로 취급하지 말고, 구조화된 환경(harness) 안에서 작동하는 컴포넌트로 설계하라.**

"harness"는 에이전트 내부에서 돌아가는 **for-loop** — 매 대화 턴마다 시스템 프롬프트와 사용자 프롬프트를 받아 처리하는 루프 — 을 의미합니다. 이 루프에 도구 접근, 가드레일, 피드백, 관찰 가능성을 체계적으로 설계하는 것이 Harness Engineering입니다.

***

## 왜 지금 Harness Engineering인가

### 프롬프트 엔지니어링의 한계

| 시기       | 패러다임                    | 핵심            | 한계          |
| -------- | ----------------------- | ------------- | ----------- |
| **2023** | 프롬프트 엔지니어링              | 단일 프롬프트 최적화   | 멀티스텝 작업 불가  |
| **2024** | RAG + Tool Use          | 외부 데이터/도구 연결  | 오류 복구 불가    |
| **2025** | Agentic 워크플로우           | 멀티스텝, 자율적 작업  | 프로덕션 안정성 부족 |
| **2026** | **Harness Engineering** | 에이전트 환경 전체 설계 | 현재 진행형      |

프로덕션 AI는 단일 프롬프트로 해결할 수 없습니다. 멀티스텝 워크플로우, 도구 사용, 외부 데이터 검색, 오류 복구, 사람의 검토 체크포인트 — 이 모든 것을 하나의 프롬프트에 담을 수 없기 때문에 **환경(harness)** 을 설계해야 합니다.

***

## Anthropic의 Harness 아키텍처

Anthropic은 2026년 3월, 엔지니어링 블로그에서 **세 에이전트 harness 시스템** 을 공개했습니다.

### 3-Agent Harness

```
┌─────────────────────────────────────────────────┐
│                  Harness Loop                    │
│                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │ Planner  │ →  │Generator │ →  │Evaluator │   │
│  │ Agent    │    │ Agent    │    │ Agent    │   │
│  └──────────┘    └──────────┘    └──────────┘   │
│       ↑                               │          │
│       └───────── 피드백 ──────────────┘          │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ claude-progress.txt (장기 메모리)         │   │
│  │ + Git History (코드 변경 이력)             │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘
```

| 에이전트          | 역할        | 구체적 동작                                          |
| ------------- | --------- | ----------------------------------------------- |
| **Planner**   | 작업 계획 수립  | 티켓/요구사항 분석 → 구현 계획 → 서브태스크 분할                   |
| **Generator** | 코드/콘텐츠 생성 | 계획에 따라 코드 작성, 파일 수정, 테스트 작성                     |
| **Evaluator** | 결과 검증     | Playwright MCP로 실행 중인 앱을 클릭하여 UI 테스트, 단위 테스트 실행 |

### 장기 작업 메모리 문제 해결

AI 에이전트의 가장 큰 문제 중 하나는 **장기 작업에서 컨텍스트를 잃는 것** 입니다. Anthropic은 두 가지 방법으로 이를 해결합니다:

| 방법                      | 설명                                                        |
| ----------------------- | --------------------------------------------------------- |
| **claude-progress.txt** | 에이전트가 작업 진행 상황을 텍스트 파일에 기록. 컨텍스트가 초기화되어도 이 파일을 읽어 작업을 이어감 |
| **Git History**         | 코드 변경 이력이 암묵적 메모리 역할. "지금까지 무엇이 바뀌었는지"를 Git에서 파악          |

***

## Harness의 핵심 구성 요소

| 구성 요소      | 역할                   | 구현 예시                     |
| ---------- | -------------------- | ------------------------- |
| **도구 정의**  | 에이전트가 사용할 수 있는 도구 목록 | MCP 서버, Bash 명령, 파일 I/O   |
| **가드레일**   | 에이전트의 행동 범위 제한       | 허용 파일 경로, 금지 명령, 토큰 예산    |
| **피드백 루프** | 결과 검증 → 자기 수정        | 테스트 실행 → 실패 시 코드 수정 → 재실행 |
| **관찰 가능성** | 에이전트의 행동 모니터링        | 로그, 트레이스, 중간 결과 기록        |
| **체크포인트**  | 사람이 검토하는 지점          | PR 리뷰, 승인 게이트             |
| **진행 추적**  | 장기 작업 상태 유지          | progress 파일, 태스크 목록       |

***

## Context Engineering — Harness의 하위 개념

**Context Engineering** 은 에이전트에게 최적의 컨텍스트(문맥)를 제공하는 기술입니다. Harness Engineering의 핵심 구성 요소 중 하나입니다.

### 주요 기법

| 기법              | 설명                         | 예시                       |
| --------------- | -------------------------- | ------------------------ |
| **CLAUDE.md**   | 프로젝트별 규칙과 컨텍스트를 파일로 관리     | 코딩 스타일, 금지 패턴, 아키텍처 규칙   |
| **기술 문서 마크다운화** | 기존 문서를 AI가 읽을 수 있는 형식으로 변환 | API 문서, 아키텍처 설명 → .md 파일 |
| **컨텍스트 계층화**    | 전역/프로젝트/디렉토리 수준으로 분리       | CLAUDE.md 계층 구조          |
| **동적 컨텍스트**     | MCP Server로 런타임에 관련 정보 주입  | DB 스키마, API 스펙, 실시간 로그   |
| **컨텍스트 가지치기**   | 불필요한 정보 제거                 | 관련 파일만 선별 제공             |

### 핵심 원칙

> **"더 많은 컨텍스트 = 더 좋은 결과"가 아니다. "적절한 컨텍스트 = 최고의 결과"다.**

1M 토큰 컨텍스트 윈도우가 있어도, 관련 없는 정보로 채우면 오히려 성능이 저하됩니다. 에이전트가 **지금 이 순간** 에 필요한 정보만 정확하게 제공하는 것이 핵심입니다.

***

## Spec-Driven Development

Harness Engineering의 대표적 실천법인 **스펙 기반 개발** 패턴입니다.

### 워크플로우

```
[1. 요구사항 분석]
    ↓
[2. 구현 스펙 문서 작성 (사람 + AI)]
    ↓
[3. 스펙 리뷰 및 승인 (사람)]
    ↓
[4. AI 에이전트가 스펙에 따라 구현]
    ↓
[5. 자동 테스트 검증 (Evaluator)]
    ↓
[6. 사람이 최종 리뷰]
```

### 왜 효과적인가

| 이유         | 설명                               |
| ---------- | -------------------------------- |
| **명확한 계약** | 스펙이 "무엇을 구현해야 하는가"를 명확하게 정의      |
| **검증 가능**  | Evaluator가 스펙 대비 구현 결과를 객관적으로 검증 |
| **변경 추적**  | 스펙 변경 이력이 요구사항 변경의 기록 역할         |
| **병렬 작업**  | 여러 에이전트가 다른 스펙을 동시에 구현 가능        |

***

## 실제 사례

### Databricks Traffic Platform 팀

| 프로젝트                                   | 자율 코딩 시간 | 설명                          |
| -------------------------------------- | :------: | --------------------------- |
| **Multi-Tenant Secure Egress Gateway** |   \~4시간  | 멀티 테넌트 보안 이그레스 게이트웨이 구현     |
| **Envoy-native Network Readiness**     |   \~6시간  | Envoy 네이티브 네트워크 준비 상태 체크 구현 |

핵심은 `/generate-spec`과 `/node-envoy-review-loop` 같은 Claude Code 스킬을 만들어, 스펙 생성과 코드 리뷰를 자동화한 것입니다.

### Anthropic 내부

Anthropic 자체도 프론트엔드 개발에 3-Agent harness를 사용합니다. 새 기능의 디자인부터 구현, 테스트까지 harness가 자율적으로 수행하고, 개발자는 결과를 리뷰합니다.

***

## 시작하기

### 1단계: CLAUDE.md 작성

```markdown theme={null}
# 프로젝트 CLAUDE.md

## 아키텍처
- 이 프로젝트는 FastAPI + React + PostgreSQL 스택
- API는 /api/v1/ 경로 아래에 구성

## 코딩 규칙
- 타입 힌트 필수 (Python)
- SQL 인젝션 방지: 파라미터화 쿼리만 사용
- 에러 응답은 RFC 7807 형식

## 금지 사항
- .env 파일 수정 금지
- 프로덕션 DB 직접 접근 금지
```

### 2단계: 테스트 커버리지 확보

에이전트가 자기 수정을 하려면 **테스트가 필수** 입니다. 테스트 없이는 "무엇이 잘못되었는지"를 판단할 수 없습니다.

### 3단계: 피드백 루프 구성

```bash theme={null}
# Claude Code hooks 예시
# 코드 변경 후 자동으로 테스트 실행
"hooks": {
  "afterEdit": "npm test"
}
```

### 4단계: 점진적 자율성 확대

처음에는 사람이 모든 결과를 검토하고, 신뢰가 쌓이면 점진적으로 에이전트의 자율성을 확대합니다.

***

**참고 자료:**

* [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
* [Anthropic: Harness Design for Long-Running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)
* [Red Hat Developer: Harness Engineering](https://developers.redhat.com/articles/2026/04/07/harness-engineering-structured-workflows-ai-assisted-development)