🔧 하네스(Harness)와 스킬(Skill)은 뭐가 다를까? — AI 에이전트 시대의 핵심 개념 정리
by gasbugs2026. 4. 14.
에이전트가 '무엇을 할 수 있는가'가 스킬이라면, '어떻게 운영되는가'가 하네스다.
🎯 이 글에서 다루는 것
OpenAI의 하네스 엔지니어링 실험 — 100만 줄 코드, 인간 작성 0줄
Anthropic이 정의한 장기 실행 에이전트 하네스 구조
스킬(Skill)과 하네스(Harness)의 근본적 차이점
두 개념이 왜 혼동되는지, 어떻게 구분해야 하는지
실무에서 하네스를 직접 설계하는 방법
📌 도입 — 왜 이 구분이 중요해졌나
2025년 말부터 2026년 초, AI 에이전트 세계에 두 편의 중요한 글이 등장했다.
하나는 OpenAI가 Codex 에이전트를 활용해 약 100만 줄의 코드를 인간의 손 없이 완성한 내부 실험을 정리한 "Harness Engineering" 포스트였고, 다른 하나는 Anthropic이 Claude Agent SDK를 이용해 여러 컨텍스트 윈도우에 걸쳐 에이전트가 일관되게 작업을 이어나가도록 설계한 방법론을 소개한 엔지니어링 블로그였다.
두 글 모두 "하네스(Harness)"라는 단어를 사용했다. 그런데 현장에서는 이 개념이 "스킬(Skill)"과 뒤섞여 혼용되는 경우가 많다.
에이전트를 직접 설계하거나 운영하려는 엔지니어라면, 이 두 개념의 차이를 정확하게 이해하고 있어야 한다.
🔍 스킬(Skill)이란 무엇인가
스킬은 에이전트가 외부 세계와 상호작용하는 단위 능력이다. 쉽게 말하면, 에이전트가 "무엇을 할 수 있는가"의 목록이다.
분류
예시
기본 도구
bash 실행, 파일 읽기/쓰기, git 조작
MCP 서버
Puppeteer(브라우저 자동화), Slack, Google Drive
외부 API
웹 검색, 데이터베이스 쿼리, 코드 실행
서브에이전트
특정 역할에 특화된 하위 에이전트 위임
스킬은 에이전트의 런타임 또는 주변 장치(peripherals)로 볼 수 있다 — 모델이 환경과 어떻게 상호작용하는가를 정의한다.
인간으로 비유하면, 스킬은 개인의 역량이다. 파이썬을 코딩할 수 있다, 영어로 커뮤니케이션할 수 있다, 데이터를 분석할 수 있다 — 이런 것들이 스킬이다.
🔍 하네스(Harness)란 무엇인가
하네스는 에이전트를 둘러싼 실행 환경 전체다. 에이전트 하네스는 AI 모델을 감싸고, 그 라이프사이클·컨텍스트·도구 접근·검증·안전성을 관리하는 인프라 레이어다. 모델이 텍스트를 생성한다면, 하네스는 모델이 무엇을 보는지, 무엇을 할 수 있는지, 언제 멈춰야 하는지, 잘못됐을 때 무슨 일이 일어나는지를 결정한다.
하네스는 에이전트를 생산적이고 올바른 방향으로 유지하는 제약 조건, 도구, 문서화, 피드백 루프의 집합이다.
다시 인간으로 비유하면, 스킬이 "개인 역량"이라면 하네스는 회사의 온보딩 시스템, 코드 리뷰 프로세스, KPI, 문서화 체계 같은 것이다. 아무리 뛰어난 개인 역량을 가진 직원도, 제대로 된 업무 환경 없이는 일관되게 좋은 결과물을 낼 수 없다.
🔍 두 개념의 핵심 차이
구분
스킬 (Skill)
하네스 (Harness)
정의
에이전트의 개별 능력 단위
에이전트를 감싸는 실행 환경
질문
"무엇을 할 수 있는가?"
"어떻게 운영되는가?"
구성 요소
도구, MCP 서버, API, 함수
제약, 피드백 루프, 컨텍스트 관리, 문서 구조
적용 시점
에이전트가 행동할 때
에이전트가 존재하는 내내
설계 주체
도구 제공자(개발자)
환경 설계자(엔지니어링 팀)
비유
직원의 개인 기술
회사의 업무 체계/프로세스
🔍 OpenAI의 하네스 엔지니어링
OpenAI의 5개월 내부 실험에서 엔지니어들은 코드를 직접 작성하지 않았다. 그들이 설계한 것은 신뢰할 수 있는 코드 생성을 가능하게 하는 환경이었으며, 그 환경에 붙인 이름이 바로 하네스다.
OpenAI 하네스의 구성 요소는 다음과 같다.
1. AGENTS.md — 목차 역할의 지식 지도
단일 거대 문서 대신, 약 100줄 분량의 짧은 AGENTS.md를 컨텍스트에 주입하고, 이를 목차로 사용한다. 실제 지식 베이스는 구조화된 docs/ 디렉토리에 존재하며, 설계 문서, 실행 계획, 아키텍처 맵이 단일 정보 소스로 관리된다.
2. 계층형 아키텍처 강제
Types → Config → Repo → Service → Runtime → UI 순서의 엄격한 의존성 레이어를 커스텀 린터와 구조 테스트로 강제한다. 에이전트는 이 모듈 경계를 위반할 수 없다.
3. 드리프트 감지 에이전트
백그라운드 에이전트가 주기적으로 낡은 문서를 스캔하고 정리 PR을 열었다 — 에이전트를 위한 문서를, 에이전트가 작성하는 구조였다.
🔍 Anthropic의 하네스 — 장기 실행 에이전트 문제 해결
Anthropic이 직면한 핵심 과제는 에이전트가 여러 컨텍스트 윈도우에 걸쳐 일관된 진행을 유지하는 것이었다. 각 새 세션은 이전에 무슨 일이 있었는지 아무 기억 없이 시작된다. 교대 근무 엔지니어들이 서로 인수인계 없이 일하는 상황과 같다.
Anthropic의 해결책은 두 가지 에이전트로 역할을 분리한 것이다.
이니셜라이저 에이전트(Initializer Agent)
최초 세션에서 동작하며, init.sh 스크립트, claude-progress.txt 진행 로그, 초기 git 커밋을 설정한다.
특히 기능 목록(Feature List)을 JSON 형식으로 작성하는 것이 핵심이다.
{
"category": "functional",
"description": "New chat button creates a fresh conversation",
"steps": [
"Navigate to main interface",
"Click the 'New Chat' button",
"Verify a new conversation is created"
],
"passes": false
}
JSON을 선택한 이유는 에이전트가 Markdown 파일보다 JSON 파일을 부적절하게 수정하거나 덮어쓸 가능성이 낮기 때문이다.
코딩 에이전트(Coding Agent)
이후 모든 세션에서 한 번에 하나의 기능만 작업하도록 요청받는다. 세션 종료 시 git 커밋과 진행 상황 파일 업데이트를 통해 다음 에이전트가 빠르게 컨텍스트를 파악할 수 있도록 환경을 정리한다.
🔍 에이전트 실패 모드와 하네스의 해결 방식
에이전트의 주요 실패 패턴은 두 가지였다. 첫째, 한 번에 너무 많은 것을 구현하려다 컨텍스트 중간에 종료되어 다음 세션이 절반만 완성된 코드를 이어받는 문제. 둘째, 일부 기능이 완성되자 나머지도 완성됐다고 선언해버리는 문제였다.
이런 실패를 막는 것이 바로 하네스의 역할이다.
실패 패턴
이니셜라이저 에이전트 대응
코딩 에이전트 대응
조기 완료 선언
JSON 기능 목록 파일 생성
세션 시작 시 기능 목록 확인
미문서화 진행 상황
초기 git + 진행 노트 설정
세션 시작/종료 시 업데이트
테스트 없이 완료 처리
브라우저 자동화 도구 설정
모든 기능 직접 검증 후 통과 표시
앱 실행 방법 탐색 낭비
init.sh 스크립트 작성
세션 시작 시 init.sh 실행
💻 하네스 구조 직접 만들어보기
아래는 Anthropic 블로그를 참고한 최소한의 하네스 구조 예시다.
project/
├── AGENTS.md # 에이전트용 목차 (100줄 이하)
├── docs/
│ ├── architecture.md # 시스템 아키텍처
│ ├── decisions/ # 설계 결정 이력
│ └── api-contracts/ # 인터페이스 계약
├── init.sh # 개발 서버 기동 스크립트
├── feature_list.json # 기능 목록 (passes: false → true)
└── claude-progress.txt # 세션 간 인수인계 파일
feature_list.json 기능 항목 업데이트 예시:
import json
def mark_feature_done(feature_id: str):
with open("feature_list.json", "r+") as f:
data = json.load(f)
for feature in data["features"]:
if feature["id"] == feature_id:
feature["passes"] = True
feature["completed_at"] = "2026-04-14"
f.seek(0)
json.dump(data, f, indent=2)
f.truncate()
claude-progress.txt 작성 패턴:
## Session 2026-04-14
### Completed
- [FEAT-012] 로그인 폼 유효성 검사 구현
- [FEAT-013] JWT 토큰 발급 로직 추가
### Current State
- 개발 서버 정상 동작 중 (port 3000)
- 기본 인증 플로우 동작 확인 완료
### Next Priority
- [FEAT-014] 리프레시 토큰 처리 로직 (미시작)
⚠️ 주의사항 — 흔한 설계 실수
스킬을 많이 주면 하네스가 강해진다는 착각
Vercel이 도구 수를 80% 줄였을 때 성능이 오히려 향상됐다. 프로덕션 하네스는 태스크 단계에 따라 사용 가능한 도구를 동적으로 제한한다. 스킬 과부하는 에이전트를 혼란스럽게 만든다.
단일 거대 지침 파일의 함정
단일 거대 매뉴얼은 낡은 규칙의 무덤이 된다. 에이전트는 무엇이 아직 유효한지 구분할 수 없고, 인간은 유지보수를 멈추며, 그 파일은 조용히 유해한 방해물이 된다.
컨텍스트 과부하
컨텍스트 사용률이 약 40%를 넘으면 성능이 저하된다. 도구, 장황한 문서, 누적된 히스토리로 에이전트를 가득 채우면 오히려 성능이 떨어진다.
✅ 정리
항목
스킬
하네스
핵심 질문
무엇을 할 수 있나?
어떻게 운영되나?
주요 구성
도구, MCP, API
문서 구조, 제약, 피드백 루프, 컨텍스트 관리
설계 대상
에이전트의 능력
에이전트의 환경
실패 시 증상
특정 작업 불가
일관성 없는 결과, 드리프트, 루프
에이전트 시대의 엔지니어링 분야는 코드 작성에서 환경 설계로 이동하고 있다. 가장 효과적인 엔지니어는 가장 빠른 코더가 아니라, 에이전트가 그 안에서 추론할 수 있도록 저장소를 구조화하는 방법을 이해하는 최고의 환경 설계자다.
스킬은 에이전트에게 날개를 달아주는 것이고, 하네스는 그 날개가 올바른 방향으로 날 수 있게 해주는 항공 관제 시스템이다.
