하네스 엔지니어링

SWE-bench Verified

출처: https://epoch.ai/benchmarks/swe-bench-verified?view=graph&tab=release-date

• 2026년 중순 기준으로 SWE-bench Verified 최고 성적은 83%
• 문제 설명이 명확하고 테스트 케이스가 이미 준비된, 신중하게 선택된 작업들을 기반으로 한 결과
• 일상적인 요구사항, 즉 모호한 사양, 기존 테스트의 부재, 코드베이스 곳곳에 흩어져 있는 암묵적인 비즈니스 규칙 등을 입력하면 통과율은 떨어짐
• Anthropic의 실험: "레벨 에디터, 스프라이트 에디터, 엔티티 동작, 플레이 가능한 테스트 모드 등의 기능을 갖춘 2D 레트로 게임 제작 도구를 만들어 보세요."
  • 그냥: 20분 개발, 비용 9달러, 제대로 작동하지 않음
  • 계획자, 생성자, 평가자로 구성된 3개 에이전트 구조: 6시간 개발, 비용 200달러, 제대로 작동
• 동일한 모델도 어떤 구조로 일을 시키느냐에 따라 전혀 다른 결과

하네스 엔지니어링 Harness Engineering

• 하네스: 모델 외부의 모든 것, 즉 지침, 도구, 환경, 상태 관리, 검증 피드백 등을 포함

하네스의 하위 시스템

• 지침: 주로 AGENTS.md 또는 CLAUDE.md 형태의 문서. 프로젝트 개요 및 목적, 기술 스택 및 버전, 실행 명령, 제약 조건, 그리고 더 자세한 문서 링크 등
• 도구: 다양한 도구들 + 적절한 권한
• 환경: 재현 가능한 환경. 종속성을 고정하거나 런타임 버전을 지정. Docker 사용. Makefile 등.
• 상황 추적: 시간이 오래 걸리는 작업을 위해 진행 상황을 추적하고 기록. 간단히는 PROGRESS.md와 같은 파일에 기록
• 피드백: 다양한 검증 명령(테스트, 타입 체크, 린트 등)

저장소를 단일 진실의 원천으로 만들기

• "저장소에 없는 정보는 에이전트에도 존재하지 않는다"(OpenAI는 하네스 엔지니어링 관련 문서에서)
• 정보가 사람의 머릿속에만 있어서는 안됨
• 에이전트가 알아야 할 모든 정보는 문서로 작성되어 에이전트가 쉽게 찾을 수 있는 곳에 보관
• 새 세션 테스트: 저장소에 충분한 정보가 있는지 확인하기 위한 테스트
  • 완전히 새로운 에이전트 세션을 열고 저장소 콘텐츠만 제공한 다음, 다섯 가지 기본 질문에 답할 수 있는지 확인
  • "이 시스템은 무엇인가?(What is this system?)"
  • "어떻게 구조화되어 있나?(How is it organized?)"
  • "어떻게 실행하나?(How do I run it?)"
  • "어떻게 검증하나?(How do I verify it?)"
  • "어디까지 진행되었나?(Where are we now?)"

명령어를 여러 파일로 분할하기

• 에이전트가 실수를 할 때마다 AGENTS.md에 추가하면, 파일이 너무 커짐
• 문제점:
  • 컨텍스트를 소모: 에이전트의 컨텍스트는 유한. AGENTS.md만이 아니라 소스 코드, 도구 실행 출력, 사용자와 대화 기록이 컨텍스트를 차지
  • 우선순위의 충돌: 하나의 파일 안에 다양한 지침이 있어서 지침 간의 우선순위가 문제됨. 지침 간에 모순이 생기는 경우도 생김
  • 유지보수 효율성 저하: 하나의 파일 안에 여러 가지 지침이 있어서 유지 보수가 어려워짐
• AGENTS.md 50~200줄로 유지, 필수적인 항목만 포함
• 세부 지침은 별개의 문서들에 저장
• 지침에는 출처("이 규칙이 추가된 이유"), 적용 조건("이 규칙이 필요한 경우"), 만료 조건("어떤 상황에서 이 규칙을 제거할 수 있는가?")을 명시

세션 연속성 Session Continuity

• 대화 세션의 길이에는 한계가 있고, 대화 세션이 길어지면 성능이 떨어질 수 있기 때문에 새로운 대화 세션을 열어야 함
  • 새로운 세션을 시작하면 이전 세션의 대화 맥락이 사라짐
• 대화 세션 간의 연속성을 유지하기 위한 방법들이 필요
• 진행 상황 파일(PROGRESS.md): 현재 상태, 완료된 것, 진행 중인 것, 이슈 등
• 결정 기록(DECISIONS.md): 중요한 설계 결정과 그 이유를 기록
• Git 커밋: 각 작업 단위가 완료될 때마다 커밋하고, 커밋 메시지에는 수행한 작업과 그 이유를 설명
• AGENTS.md에 위의 사항들을 필요할 때 참고하도록 지시

에이전트를 위한 명확한 작업 경계 설정

• 에이전트는 프롬프트가 너무 포괄적이면 여러 작업을 동시에 시작하는 경향
• 에이전트가 생성하는 코드가 적을수록 기능 개발이 완료될 가능성이 더 높음
• 한 번에 한 가지 작업만 수행하도록 명시적으로 지시
• 모든 작업에 대한 명확한 완료 증거를 정의(코드 작성만이 아니라 동작 검증도 포함)
• 현재 어떤 작업이 진행 중이며, 어떤 작업이 완료되었고, 어떤 검증이 통과되었는지 작업 상태를 기록
• 기능별로 수행할 동작과 확인 방법, 구현 상태 등을 정리한 기능 목록을 제공
• 에이전트는 실제로 완성되지 않은 기능을 완성되었다고 판단하는 경향이 있음
  • 판단의 외부화

쓰라린 교훈 The Bitter Lesson

• 강화학습의 창시자, 리차드 서튼(Richard Sutton)의 2019년 에세이
• 인공지능 학계와 산업계에서 중요하게 받아들여지고 있음
• 70년 AI 연구의 가장 큰 교훈은 계산(computation)을 활용하는 범용적 방법이 가장 효과적이라는 점임
  • 무어의 법칙에 따른 계산 비용의 기하급수적 하락이 이러한 경향의 근본 원인
• 인간의 지식을 주입하는 방식은 단기적으로는 성과를 내지만, 장기적으로는 계산 능력을 활용한 방식에 추월 당함
• 예시: 바둑
  • 인간의 바둑 데이터 사용 → AI의 self-play 데이터
  • 바둑 특화 규칙을 직접 코딩 → 데이터로부터 학습
  • 바둑 전용 모델 AlphaGo → 모든 보드 게임을 할 수 있는 모델 AlphaZero

'쓰라린 교훈'의 본질과 반복되는 실수

• 연구자들은 자신의 사고 방식을 시스템에 내재화하려는 유혹에 빠짐
• AI 에이전트에 인간의 지식을 주입함
• 단기적으로 성능이 향상되어 연구자가 만족감을 느낌
• 장기적으로 성능 정체기에 도달하며 발전을 저해함
• 결국 탐색과 학습을 통한 계산량 확장으로 혁신적 돌파구가 마련됨
• 이 성공이 '쓰라린' 이유는 연구자가 선호하던 인간 중심적 접근법이 부정당하기 때문
• 계산 능력이 증가함에 따라 확장 가능한 탐색(Search)과 학습(Learning)에 집중해야 함
• 마음과 세상의 내용은 매우 복잡하므로 이를 단순화하여 설계하려 하지 말아야 함
• 인간이 발견한 지식을 주입하는 대신, 스스로 지식을 발견하고 포착할 수 있는 '메타 방법'을 구축해야 함

'쓰라린 교훈'이 모든 사람에게 중요한 이유

• AI를 잘 활용하는 방법의 대부분은 '쓰라린 교훈'에서 지적하는 인간 중심적 접근
• 현세대 AI가 잘 하지 못하는 것을 인간의 지식을 주입하는 방법
• AI의 발전에 따라 진부화(Obsolescence)될 가능성이 큼
• 그러나 장기-단기는 상대적인 개념
• AI를 잘 사용하기 위해 필요한 노력과 그 방법으로 AI를 활용할 수 있는 기간과 이익을 비교한 의사결정이 필요