하네스가 전부다
AI를 잘못 사용하는 이유는 올바른 모델을 찾지 못해서가 아니다. 올바른 환경을 구축하지 못해서다.
핵심 주장
하네스(Harness) = LM(언어 모델)이 동작하는 완전히 설계된 환경
- 호출 가능한 도구(tools)
- 정보 수신 형식
- 히스토리 압축·관리 방식
- 실수를 사전에 차단하는 가드레일
- 미래 세션에 작업을 인계하는 스캐폴딩
모델 자체는 거의 무관하다. 하네스가 전부다.
Part 1: 원시 능력만으로는 부족하다
컨텍스트 창은 RAM이 아니다
- 컨텍스트 창 = 에이전트의 전체 작업 의식(working consciousness)
- 불필요한 정보는 관련 정보와 주의(attention)를 경쟁함
grep결과 1만 줄 반환 → 작업 메모리 범람 → 이후 모든 추론 품질 저하
SWE-agent 논문의 핵심 발견
Princeton NLP 그룹이 발표한 SWE-agent 논문(2024):
| 조건 | SWE-bench 해결률 |
|---|---|
| GPT-4 + 표준 bash 인터페이스 | 3.97% |
| GPT-4 + 전용 ACI | 12.47% |
→ 64% 상대적 성능 향상, 모델 변경 없이 인터페이스 설계만으로 달성
Part 2: ACI (Agent-Computer Interface)
ACI란?
언어 모델 에이전트와 컴퓨터 환경 사이의 추상화 레이어. HCI(Human-Computer Interface)가 인간 인지 구조에 맞게 설계되듯, ACI는 LM 인지 구조에 맞게 설계된다.
SWE-agent ACI의 4가지 핵심 컴포넌트
1. 검색 및 탐색 (Search & Navigation)
- 표준
grep/find→ 전용 도구(find_file,search_file,search_dir)로 교체 - 결과 상한선 50개: 초과 시 “검색어를 좁히라”고 메시지 반환
- 강제로 에이전트를 더 구체적·의도적 탐색으로 유도
2. 파일 뷰어 (File Viewer)
- 100줄씩 표시 (30줄: 컨텍스트 손실 / 전체: 추적 불가)
- 세션 간 위치 상태 유지(stateful)
- 모든 줄에 행 번호 명시 → 편집 명령 시 산술 불필요
3. 린팅 통합 편집기 (File Editor with Linting)
- 편집 즉시 자동 린터 실행
- 구문 오류 시 편집 거부 + 명확한 오류 메시지 반환
- 피드백 루프 조기 차단 → 연쇄 실패 방지
4. 컨텍스트 관리 (Context Management)
- 최근 5턴 이후 오래된 관찰을 한 줄 요약으로 압축
- 현재 상태에 집중하면서도 전체 궤적의 압축 기록 유지
Part 3: Anthropic의 하네스 엔지니어링
문제: 컨텍스트 창 경계
실제 소프트웨어 프로젝트는 단일 컨텍스트 창에 담기 불가능.
컨팩션(compaction) 만으로는 부족 — 두 가지 실패 패턴 발생:
- 한꺼번에 너무 많이 시도: 전체 앱을 한 번에 구현하려다 중간에 컨텍스트 고갈
- 조기 완료 선언: 일부 기능만 완성된 상태에서 “완료”라고 판단
2에이전트 아키텍처
[초기화 에이전트] → [코딩 에이전트 (반복)]
초기화 에이전트 (Initializer Agent)
기능 개발을 위한 스캐폴딩을 생성하는 전용 첫 세션:
| 산출물 | 역할 |
|---|---|
init.sh | 개발 환경 신뢰성 있게 재시작 |
feature_list.json | 200개+ 구체적 기능 목록, 각 항목 pass/fail 상태 |
claude-progress.txt | 세션별 작업 로그 |
| 초기 git 커밋 | 복구 기점 |
코딩 에이전트 (Coding Agent)
세션 시작 시 표준화된 시작 시퀀스:
pwd실행 → 작업 디렉토리 확인claude-progress.txt+git log읽기 → 최근 작업 파악feature_list.json읽기 → 우선순위 높은 미완료 기능 선택init.sh실행 → 개발 환경 시작- 기본 E2E 테스트 실행 → 앱 정상 상태 확인
feature_list.json이 JSON인 이유
경험적으로, 모델은 Markdown 파일보다 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
}브라우저 자동화의 중요성
에이전트에게 Puppeteer MCP 서버 접근 제공 →
코드만 보는 에이전트 vs. 실제로 앱을 사용해보는 에이전트 사이의 차이는 코드만 읽는 개발자 vs. 실행해보는 개발자의 차이와 같다.
Part 4: OpenAI의 하네스 엔지니어링
실험: 수동 코드 0줄
2025년 8월 ~ 2026년 2월, Codex 팀:
- 약 100만 줄 코드 생성 (앱 로직, 테스트, CI, 문서, 관찰성 도구 포함)
- ~1,500개 PR 병합
- 3명 엔지니어, 1인당 하루 3.5개 PR
- 팀이 7명으로 확장되자 1인당 처리량 증가
핵심 인사이트: 엔지니어링 작업의 재정의
무언가 실패했을 때, 해결책은 거의 “더 열심히”가 아니었다.
항상 “에이전트가 여기서 실패하게 만드는 환경의 구조적 결함은 무엇인가?”였다.
저장소를 시스템 오브 레코드로
| 실패한 접근 | 해결책 |
|---|---|
하나의 거대한 AGENTS.md (모든 정보 포함) | 짧은 맵 파일(~100줄) + 구조화된 docs/ 디렉토리 |
거대한 단일 AGENTS.md의 4가지 실패 원인:
- 컨텍스트 희소 자원 낭비
- 과도한 가이드 = 가이드 없음
- 즉각적 노후화
- 검증 불가
애플리케이션 가독성 (Application Legibility)
에이전트가 앱을 직접 볼 수 있도록:
- git 워크트리별 앱 부팅 가능
- Chrome DevTools Protocol 연동 (DOM 스냅샷, 스크린샷, 브라우저 탐색)
- 로컬 관찰성 스택: LogQL, PromQL, TraceQL로 로그/메트릭/트레이스 접근
아키텍처 기계적 강제
- 커스텀 린터 (Codex가 작성): 의존성 방향, 경계 위반 검출
- 린터 오류 메시지에 에이전트용 수정 지침 포함
- “황금 원칙(golden principles)” → 정기적 정리 백그라운드 태스크로 자동 실행
Part 5: 반복되는 설계 패턴
패턴 1: 점진적 공개 (Progressive Disclosure)
처음부터 모든 것을 주지 말 것.
최소 오리엔테이션 정보 + 더 필요할 때 찾는 포인터만 제공.
| 구현 예시 | 적용 방식 |
|---|---|
| SWE-agent 검색 상한 | 결과 초과 시 쿼리 정제 강제 |
| OpenAI docs/ 구조 | 짧은 맵 → 깊은 진실 |
| Anthropic 시작 시퀀스 | 진행 파일 먼저, 기능 목록 나중 |
패턴 2: Git 워크트리 격리
하나의 에이전트 = 하나의 워크트리
병렬 에이전트 간 충돌 방지 + 격리된 환경에서 검증 후 병합
패턴 3: 스펙 우선, 저장소를 시스템 오브 레코드로
에이전트는 비공식 지식(Slack, Google Docs, 사람들의 머릿속)에 접근 불가.
저장소에 없으면 에이전트에게 존재하지 않는 것과 같다.
패턴 4: 기계적 아키텍처 강제
인간 코드 리뷰 → 자동화된 기계적 검사로 대체
- 위반 즉시 감지 + 수정 지침 포함 오류 메시지
- 불변성(invariants) 강제, 구현 방식은 자유
패턴 5: 통합 피드백 루프
| 피드백 없을 때 | 피드백 있을 때 |
|---|---|
| 오류 전파 | 즉시 차단 |
| 컨텍스트 오염 | 컨텍스트 보호 |
| 귀신 추적 | 정확한 디버깅 |
Part 6: 7계층 하네스 에코시스템
awesome-agent-harness 저장소 분류:
| 계층 | 역할 |
|---|---|
| L1 인간 감독 | 제안 승인, PR 리뷰, 우선순위 설정 |
| L2 계획/요구사항 | 인간 의도 → 구조화된 명세 + 태스크 DAG |
| L3 전체 라이프사이클 플랫폼 | 요구사항부터 배포까지 End-to-End 관리 |
| L4 태스크 러너 | 이슈 트래커 → 코딩 에이전트 → PR 배달 |
| L5 에이전트 오케스트레이터 | 병렬 에이전트 실행 + git 워크트리 격리 |
| L6 하네스 프레임워크/런타임 | 컴포저블 프리미티브, 지속 메모리, 예약 실행 |
| L7 코딩 에이전트 | Claude Code, Codex 등 (실행 레이어) |
실행 레이어(L7)는 이미 상품화(commodity)됐다. 경쟁 우위는 L1-L6에 있다.
최소 유효 하네스 구축 가이드
- 영구 진행 파일: 세션 시작 시 읽기, 종료 시 쓰기
- 구조화된 작업 목록: 검증 가능한 완료 기준, 상태 명시
- 버전 관리 규율: 모든 세션은 커밋 + 진행 파일 업데이트로 종료
- 브라우저 자동화: 웹앱이면 반드시 (코드만으론 감지 불가한 버그 존재)
환경 감사(Environment Audit) 질문
- 에이전트가 현재 접근할 수 없는 필요 정보는 무엇인가?
- 에이전트가 자주 막히거나 실수하는 지점은 어디인가?
- 실수를 스스로 잡을 수 있게 해줄 누락된 피드백은 무엇인가?
- 불필요한 정보로 컨텍스트가 오염되는 곳은 어디인가?
- 현재 에이전트 판단에 의존하는 강제되지 않은 제약은 무엇인가?
관련 개념
- SWE-agent · Agent-Computer Interface (ACI)
- moc-claude-code · codex
- [컨텍스트 관리] · [Prompt Engineering]
- AI 에이전트 오케스트레이션