Harness Engineering이란? 쉽게 이해하기
AI 에이전트는 엄청나게 강력합니다. 하지만 길들이지 않으면 위험할 수 있습니다. Harness Engineering은 AI 에이전트가 프로덕션 환경에서 안전하고 예측 가능하게 동작하도록 만드는 시스템 설계 원칙의 집합체입니다.
Harness는 말의 고삐와 마구를 뜻합니다. 강력한 말을 제어 가능하게 만드는 도구처럼, Harness Engineering은 강력한 AI 에이전트를 프로덕션에서 믿고 쓸 수 있게 만드는 기술입니다. 2025~2026년 AI 에이전트가 실무에 본격 투입되면서 생겨난 개념으로, 단순히 "AI를 쓴다"가 아니라 "AI를 안전하게 운영한다"에 초점을 맞춥니다.
5가지 핵심 원칙과 실제 구현 방법
1. Tool Orchestration — 도구 조율
에이전트가 사용할 수 있는 도구를 명시적으로 정의하고, 허용되지 않은 도구 호출은 자동 차단합니다.
실제 구현:
- Claude Code:
.claude/settings.json에allowed_tools배열로 허용할 도구만 나열. 예:["Bash", "Read", "Edit"]만 허용하면 WebFetch, Write 등은 자동 차단 - LangChain:
tools=[]파라미터로 에이전트에 바인딩할 도구 목록 명시적 전달 - CLAUDE.md: "절대 프로덕션 DB에 직접 쓰기 금지", "git push --force 금지" 등 자연어 규칙으로 행동 제한
핵심 원칙: 에이전트에게 필요한 도구만 줄 것. 모든 도구를 다 주면 예상치 못한 방향으로 행동할 수 있습니다.
2. Guardrails — 가드레일
에이전트가 절대 넘어선 안 되는 경계를 사전에 정의합니다.
실제 구현:
- 비용 가드레일: API 호출 횟수 상한선 설정. LangChain의
max_iterations, Claude Code의 세션당 토큰 한도 - 데이터 가드레일: 특정 파일 경로(
.env,secrets/) 접근 금지..claude/settings.json의denyOnly경로 목록 - 액션 가드레일: 이메일 대량 발송, 결제 API 호출, 프로덕션 DB
DELETE등 고위험 액션은 실행 전 검증 로직 삽입 - 루프 감지: 동일 작업 N회 반복 시 강제 중단. 비용 폭발 방지
3. Error Recovery — 오류 복구
에이전트가 실패했을 때 스스로 복구하거나 안전하게 종료합니다.
실제 구현:
- 멱등성(Idempotency) 설계: 같은 작업을 두 번 실행해도 결과가 동일하도록. DB
INSERT ... ON CONFLICT DO NOTHING, API 요청에 고유 ID 부여 - 롤백 전략: Git worktree에서 작업하여 실패 시 브랜치 삭제로 되돌리기. DB 트랜잭션으로 원자적 처리
- 재시도 로직: 네트워크 오류 등 일시적 실패는 exponential backoff으로 자동 재시도 (3회 이내)
- 폴백 경로: 주 경로 실패 시 대안 경로 자동 선택. 예: API 실패 → 캐시 데이터 사용
4. Observability — 관찰 가능성
에이전트의 모든 행동을 추적하고 이상 징후를 감지합니다.
실제 구현:
- 액션 로깅: 에이전트가 무엇을 했는지, 왜 했는지, 결과가 무엇인지 구조화된 로그로 저장
- 비용 추적: 세션별 토큰 사용량, API 호출 비용 실시간 모니터링
- 이상 감지: 평소보다 10배 이상 API를 호출하거나, 특정 파일을 반복 수정하는 패턴 알림
- Audit Trail: 누가, 언제, 어떤 에이전트가, 무슨 작업을 했는지 완전한 감사 기록
5. Human-in-the-Loop — 인간 개입 지점
고위험 작업 전에는 반드시 인간의 승인을 받습니다.
실제 구현:
- Claude Code Permission: 파일 쓰기, Bash 실행 등 위험 액션은 사용자 승인 후 실행
- 승인 임계값 설정: 결제 금액 $100 이상, 이메일 수신자 100명 이상이면 자동 중단 후 승인 요청
- Dry-run 모드: 실제 실행 전 "이런 작업을 하려 합니다" 미리 보여주기
- 비상 정지(Kill Switch): 언제든 에이전트를 즉시 멈출 수 있는 메커니즘
실제 도입 사례
- Anthropic Claude Code:
.claude/settings.json+ CLAUDE.md로 Harness Engineering 내장. 허용 도구 제한, 경로 차단, 인간 승인 플로우가 기본 탑재 - Cursor: 코드 변경 전 diff 미리보기 → 사용자 확인 → 적용 순서로 human-in-the-loop 구현
- GitHub Copilot Workspace: PR 생성 전 변경 사항 전체 요약 → 개발자 리뷰 → 머지
- LangGraph: 워크플로우에
interrupt()노드 삽입으로 체크포인트 구현
