harness2 딥다이브
— 모델 대신 에이전트의 일하는 방식을 고치는 실험실

1프로젝트 한줄 요약

harness2는 모델 가중치를 고정한 채 에이전트의 실행 환경을 반복해서 개선하는 프레임워크입니다. 여기서 실행 환경은 프롬프트, 행동 제약, 기억, 도구 사용 안내, 하위 에이전트, 스킬, 보조 스크립트, 플러그인을 말합니다. 이 저장소가 바꾸는 것은 모델의 머릿속 지식이 아니라, 그 모델이 과제를 수행하는 방법입니다.

실제 코드가 보여 주는 최소 사례

harness2/demo.py의 BASE_SCRIPT는 거래 금액을 합산하면서 양수만 포함하는 잘못된 스크립트입니다. DemoProposer.call()은 그 필터를 제거합니다. 이는 모델을 호출하는 구현이 아니라, 수정 결과를 정해 둔 교육용 구현입니다.

# harness2/demo.py의 BASE_SCRIPT에서 핵심 부분 발췌
amounts = [Decimal(row['amount']) for row in csv.DictReader(source)]
total = sum((amount for amount in amounts if amount > 0), Decimal(0))

# DemoProposer.call()이 적용하는 수정
script.write_text(script.read_text().replace(" if amount > 0", ""))

첫 과제의 금액은 100.25, -20.10, 5.00입니다. 기존 스크립트의 합계는 손으로 계산하면 105.25, 수정 후에는 85.15입니다. 이 작은 차이가 제안·실행·비교·기억이라는 전체 흐름을 보여 줍니다.

2왜 주목받는가

2-1. 좋은 프롬프트를 찾는 일을 실행 증거와 연결한다

TrendShift Weekly #4의 선정 대상이며, 2026-10-23 GitHub 기준 스타는 18,196개입니다. 저장소 생성일은 2026-10-06입니다. 짧은 기간에 관심을 모았다는 것은 알 수 있지만, 이 수치만으로 유입 경로나 사용자의 만족도를 설명할 수는 없습니다. 여기서는 코드에서 드러나는 주목할 이유를 살펴봅니다.

하네스를 바꾼 뒤 말로만 좋아졌다고 설명하는 대신, 같은 과제를 다시 수행한 기록을 비교 재료로 삼습니다. harness2/core/recursion.py의 run_parallel()과 run_sequential()이 이 과정을 구체화합니다. 수정안의 설득력보다 수정 전후의 행동 차이를 근거로 삼는 점이 핵심입니다.

2-2. 실행기와 개선기를 분리하는 확장성

OpenCode와 Codex는 이 저장소에서 과제를 수행하는 실행기로 연결됩니다. Harness²는 그 위에서 설정을 고치고 비교하는 역할을 맡습니다. 따라서 둘을 완전히 대체하는 경쟁 제품으로 읽으면 구조를 오해하게 됩니다.

비교 표는 제품별 성능 순위가 아니라 개입하는 위치의 차이입니다. 다른 방법보다 무조건 빠르거나 저렴하다는 뜻은 아닙니다.

2-3. 공개 성과는 어디까지 믿어야 할까

README는 세 전문 업무 벤치마크와 네 모델–하네스 구성에서 개선을 보고합니다. 최대 향상 폭은 WorkBuddy-Bench 11.5점, JobBench 4.5점, LAB의 부분 통과율 11.8퍼센트포인트라고 설명합니다. 이는 README의 연구 결과 주장이며 독립 재현 수치는 아닙니다.

점수와 퍼센트포인트는 같은 단위가 아닙니다. 또 최대값은 모든 모델·모든 과제에서 얻는 평균 향상을 뜻하지 않습니다. dependencies/PINNED.md도 과거 논문 실험이 공개 실행 절차와 다른 과제·모델 배포·추가 도구를 사용했을 수 있다고 밝힙니다.

2-4. 초보자가 볼 만한 이유는 실패를 다루는 방식

tests/test_workflow.py는 예산·재개, 증거 완전성, 잘못된 수정 재시도, 경험 미생성 처리, 선택 실패 후 평가 방지를 다루는 5개 테스트 메서드를 담고 있습니다. 성공하는 경로만큼 실패했을 때 무엇을 남기고 무엇을 재사용하지 않는지가 학습 재료입니다.

3기술 스택 전체 지도

3-1. 백엔드에 해당하는 부분: CLI와 Python 조정 코드

일반적인 웹 서비스의 상시 백엔드 서버가 중심은 아닙니다. argparse로 명령을 받고, 파일과 하위 프로세스를 조정하는 Python 패키지가 중심입니다. pyproject.toml의 프로젝트 버전은 0.1.0이며 지원 Python 범위는 아래와 같습니다.

# pyproject.toml에서 발췌
[build-system]
requires = ["setuptools>=77", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "harness2"
version = "0.1.0"
requires-python = ">=3.12,<3.14"
dependencies = []

dependencies = []는 핵심 패키지의 필수 Python 배포 의존성이 없다는 뜻입니다. 실제 모델 실행, 벤치마크 데이터, 문서 변환 도구까지 필요 없다는 뜻으로 넓혀 읽어서는 안 됩니다.

3-2. 선택 설치와 외부 도구의 실제 버전

이 버전은 커밋 1cfe254에 기록된 요구값입니다. 현재 권장 최신 버전이라는 의미는 아닙니다. node:20-slim도 이미지 다이제스트로 고정한 형태는 아닙니다.

3-3. 프론트엔드: 별도 웹 앱은 없다

이 커밋에는 자체 웹 프론트엔드의 package.json, React·Vue 코드, 프론트엔드 빌드 설정이 없습니다. 사용자의 접점은 CLI와 결과 파일입니다. harness2-report도 캐시된 평가 JSON을 읽는 보고 명령입니다.

harness2/cli/bridge.py는 LiteLLM 프로세스를 시작해 모델 호출 인터페이스를 연결합니다. 직접 FastAPI 앱을 정의한 웹 제품으로 읽으면 안 됩니다. WorkBuddy의 web 하위 집합은 평가 대상 과제 종류이지 이 프로젝트의 화면이 아닙니다.

3-4. 인프라·빌드: Python 설치만으로 끝나지 않는다

harness2/cli/setup.py는 외부 저장소를 고정 커밋으로 가져오고 패치를 적용한 뒤, OpenCode에는 bun install --frozen-lockfile --ignore-scripts, 벤치마크에는 uv sync --locked --python 3.12를 사용하도록 작성돼 있습니다.

주요 고정 커밋은 config.DEPENDENCY_PINS 기준으로 다음과 같습니다.

루트에 .github/workflows/는 없으므로 자동 CI가 구성됐다고 단정할 수 없습니다. pyproject.toml에는 Ruff 대상 py312, 줄 길이 100, 검사 선택 E4/E7/E9/F/I가 있습니다. Ruff 자체의 설치 버전은 이 파일에서 고정하지 않습니다.

4아키텍처 심화 분석

진입점은 pyproject.toml의 harness2 = "harness2.cli.run_sweep:main"입니다. CLI가 벤치마크 어댑터와 편집자를 만든 뒤 schedule.run_sweep()에 넘깁니다. 핵심 호출 관계를 단순화하면 다음과 같습니다.

설계 패턴 1. 인터페이스로 세 축을 분리한다

harness2/core/spec.py의 BenchmarkAdapter(Protocol)은 과제 목록, 도메인, 지시문, 실행, 산출물 읽기 등의 계약을 선언합니다. harness2/benchmarks/jobbench.py의 JobBenchAdapter, harness2/benchmarks/lab.py의 LabAdapter, harness2/benchmarks/workbuddy.py의 WbAdapter가 실제 차이를 담당합니다.

# harness2/core/spec.py의 계약 일부를 줄여 표시
class BenchmarkAdapter(Protocol):
    spec: BenchSpec
    substrate: SubstrateLike

    def tasks(self, split: str = "all") -> list[str]: ...
    def task_prompt(self, task_id: str) -> str: ...
    def execute(self, task_id: str, harness_dir: Path | None,
                run_id: str, *, timeout: int | None = None) -> Path: ...

방법은 제안·합성 절차, 실행 기반은 OpenCode·Codex, 벤치마크는 과제와 평가 방식입니다. 여기에 편집 모델로 연결하는 ChannelSpec도 별도 값으로 둡니다. 편집자가 사용하는 채널과 과제를 푸는 실행기를 같은 개념으로 취급하지 않는 것이 중요합니다.

설계 패턴 2. 두 가지 스케줄을 같은 예산으로 비교한다

recursion.run_parallel()은 기본 실행을 공유한 상태에서 일반 개선 INV와 도메인 개선 DOM을 각각 k개 제안합니다. 이 2k개 후보를 시험한 뒤, 전체 증거를 보고 독립적인 합성 하네스 agg1..aggk를 만듭니다.

recursion.run_sequential()은 현재 하네스로부터 INV·DOM을 제안하고 시험한 뒤 c1을 합성합니다. 그 하네스와 누적 기록이 다음 회차에 들어갑니다. 코드의 current_harness = comp.tree와 history 갱신이 깊이를 만드는 연결점입니다.

harness2/core/ledger.py는 한 모드·한 과제의 논리적 예산을 다음처럼 검사합니다. 실행 예산을 코드의 불변식으로 두면, 실험 방식이 달라도 같은 기준으로 비교할 수 있습니다.

# harness2/core/ledger.py의 예산 정의
def expected_rollouts(k: int) -> int:
    return 4 * int(k)

def expected_sessions(k: int) -> int:
    return 3 * int(k)

# R = 기본 k + 후보 2k + 합성 k
# P = INV 제안 k + DOM 제안 k + 합성 k

Ledger.assert_identity()는 개수뿐 아니라 중복 라벨도 검사합니다. k=1이면 한 모드의 R은 4, P는 3입니다. 두 모드를 함께 실행할 때 기본 실행은 공유하므로 과제 실행 예산은 k + 3k + 3k = 7k개입니다.

이 수식은 API 요청 총횟수나 총요금이 아닙니다. 편집 세션 안에도 여러 모델 호출이 있을 수 있고, 재시도·선택·회고·평가는 별도입니다. session_attempts와 논리적 단계 수를 구분해야 합니다.

설계 패턴 3. 증거를 파일로 만들고 과거 경험만 전달한다

harness2/core/context.py의 build()는 편집자가 읽을 증거 디렉토리를 구성합니다. mission()은 거대한 본문을 붙이는 대신 어디에 무엇이 있는지 알려 줍니다. 파일을 필요할 때 읽는 방식은 입력을 구조화하지만, 모델의 읽기 비용과 문맥 한도까지 없애 주지는 않습니다.

build()는 assert_no_leak_paths()와 assert_no_grader_verdicts()를 호출합니다. 정답 파일 경로와 평가 결과의 알려진 표식을 검사합니다. WorkBuddy의 harness2/benchmarks/wb_render.py:_admit()는 산출물로 읽을 위치를 허용 목록으로 제한합니다.

다만 “전체 기록”이라는 표현에도 범위가 있습니다. BenchSpec.obs_trunc의 기본값은 관찰 하나당 50,000자이며, WorkBuddy의 TRAJ_MAX_CHARS는 2,000,000자입니다. 파일로 제공한다는 것과 원시 로그를 한 글자도 자르지 않는다는 것은 다릅니다.

harness2/core/library.py의 Library.add()는 채택한 하네스 전체와 EXPERIENCE.md를 저장합니다. 경험은 cue·lesson·evidence가 모두 있어야 합니다. 벡터 검색이나 별도 데이터베이스가 아니라, 도메인별 파일과 INDEX.md를 사용하는 구조입니다.

schedule.run_domain()은 과제를 순서대로 처리하며 Library.retain()에 이전 과제 목록만 넘깁니다. agg와 seq의 경험 저장소도 나뉩니다. 이후 과제의 결과가 앞선 과제에 섞이는 시간 순서 누출을 줄이는 설계입니다.

설계 패턴 4. 변경 검증과 재개 검증을 따로 둔다

harness2/core/tree.py는 하네스를 dict[str, str], 즉 “상대 경로 → 내용”으로 표현합니다. SurfaceSpec은 실행기별 허용 경로·길이·스킬 규칙을 값으로 기술합니다. normalize_rel()은 절대 경로와 .. 경로를 거부합니다.

harness2/substrate/opencode.py의 상시 지침 상한은 24,000자, harness2/substrate/codex.py의 상한은 8,000자입니다. 이는 len(body)로 검사하는 문자 수이며 토큰 수가 아닙니다. Codex는 AGENTS.md, OpenCode는 네 상시 지침 파일을 사용하므로 같은 개념도 실제 배치는 다릅니다.

파일 이름이 있다고 완료로 취급하지도 않습니다. harness2/core/runmark.py는 .adapt_complete와 하네스 지문을 기록합니다. harness2/cli/run_sweep.py:_check_identity()는 모델·과제·시드 등이 다른 실험을 기존 결과에 섞지 못하게 합니다.

5디렉토리 구조 해부

줄 수로 보는 무게중심

커밋 1cfe254의 텍스트 파일 규모는 확장자별로 다음과 같습니다. 아래는 빈 줄·주석을 포함한 물리적 줄 수이며, .git과 바이너리 자산은 제외합니다. 외부 저장소를 설치했을 때 추가되는 코드까지 포함한 수치가 아닙니다.

Python 중 harness2/가 39파일·12,747줄, third_party/가 13파일·2,591줄, scripts/가 5파일·294줄, 테스트가 1파일·229줄입니다. 본체 안의 harness2/core/는 5,688줄로, 인터페이스와 실험 제어를 집중해서 읽기 좋은 크기입니다.

6학습 포인트 (기술별)

초보자가 가져갈 가장 큰 기술은 AI 호출법보다, 바뀌는 외부 환경을 작은 계약 뒤에 가두는 설계법입니다. 아래 항목은 서로 독립적으로 연습할 수 있습니다.

7하드웨어 / 시스템 요구사항

하네스 개선은 모델 학습이 아니므로, 먼저 챙길 자원은 GPU보다 실행 환경과 반복 호출 예산입니다. 다만 이 말이 모든 외부 벤치마크가 가볍다는 뜻은 아닙니다.

공식 최소 사양이 없는 부분은 숫자를 만들어 채우지 않는다

README와 설치 문서에는 최소 CPU 코어 수, RAM 용량, 디스크 용량, GPU VRAM이 수치로 정리돼 있지 않습니다. 따라서 “메모리 몇 GB면 전체 벤치마크가 된다”고 단정할 근거는 없습니다. 기본 경로는 원격 모델 호출이므로 자체 모델 가중치를 GPU에 올리는 과정은 포함하지 않습니다.

schedule._write_summary()가 사용하는 fcntl, Shell 실행기, 외부 도구 의존성을 함께 보면 Linux 권장에는 이유가 있습니다. pyproject.toml의 POSIX 분류만으로 모든 macOS·Windows 조합이 검증됐다고 해석해서는 안 됩니다.

시간과 비용을 예상하는 더 좋은 기준

한 과제·한 모드에서 k=2면 과제 실행 8개와 개선 단계 6개가 논리적 기본량입니다. 여기에 최종 후보 선택, 회고, 재시도, 사후 평가를 더해야 합니다. 토큰 길이와 모델 단가가 없으므로 이 횟수를 달러 요금으로 바로 바꿀 수는 없습니다.

8직접 해볼 수 있는 실습 과제

아래 과제는 저장소 파일을 변경하지 않고 수행할 수 있습니다. 실행 전에 예상 결과와 실패 조건을 적어 보는 습관이, 자동화된 에이전트를 이해하는 가장 빠른 연습입니다.

9관련 기술 심화 학습 로드맵

주당 4~6시간을 기준으로 한 학습 제안입니다. Python 기본 문법이 낯설다면 1주 차를 더 길게 잡으세요. 매주 읽은 코드의 입력·출력·실패 조건을 한 장으로 정리하면, 추상적인 설계 용어가 실제 동작과 연결됩니다.

여유가 생기면 이어 볼 주제

• 실험 통제: 같은 모델·과제·네트워크를 유지한 채 k와 모드만 바꾸는 비교 설계.
• 관측 가능성: 성공 여부, 산출물 존재, 평가 완료 여부를 각각 기록하는 상태 모델.
• 배포 재현성: Git 커밋 고정과 잠금 파일만으로 충분하지 않은 외부 모델·데이터의 변화.
• 장기 경험 관리: 파일 라이브러리가 커질 때 어떤 정보를 선별하고 오래된 교훈을 어떻게 검증할지 설계.

10핵심 키워드 사전

11참고 링크

프로젝트와 연구 배경

• 공식 저장소 — 변경 이력과 배포 상태를 확인하는 출발점.
• 커밋 1cfe254의 README — 두 재귀 수준, 연구 성과 주장, 공식 지원 범위.
• 프로젝트 웹사이트 — README에서 연결하는 공식 소개 페이지.
• Harness² 논문 — README가 연결하는 연구 원문. 성과 수치는 실험 조건과 함께 읽기.
• TrendShift — 오픈소스 관심 흐름을 살펴보는 참고 서비스.

바로 찾아 읽을 소스와 안내

• harness2/demo.py · harness2/core/spec.py — 가장 작은 예제와 인터페이스 계약.
• harness2/core/recursion.py · harness2/core/ledger.py — 재귀 스케줄과 예산 불변식.
• harness2/core/context.py · harness2/core/library.py — 증거와 과거 경험 구성.
• harness2/core/selection.py · harness2/core/schedule.py — 최종 후보 선택과 재개 판정.
• tests/test_workflow.py — 성공·실패·재개 조건의 구체적인 예.
• 설치 안내 · 벤치마크 안내 · 실험 안내.
• pyproject.toml · harness2/config.py · 외부 저장소 고정 정보 — 버전 근거.

기초 기술 공식 문서

• Python 데이터 클래스 · Protocol과 타입 힌트.
• Python 작업 풀 · 하위 프로세스 제어.
• uv 공식 문서 · Docker Engine 공식 문서.
• OpenCode 저장소 — 실행기와 하네스 개선 계층의 책임을 비교하며 읽기.

현재 상태 (2026-10-23 확인)

문서와 소스를 함께 볼 때 드러나는 차이

dependencies/PINNED.md에는 실행기 파일이 harness2/third_party/에 속하며 이 사본에는 없다는 문장이 남아 있습니다. 그러나 이 커밋에는 루트 third_party/에 파일이 있고, config.THIRD_PARTY = ROOT / "third_party"와 install.overlays()도 그 경로를 사용합니다. 해당 문장을 실제 디렉토리 구조보다 우선해서 읽으면 안 됩니다.

배포 설명도 일치 여부를 추가 확인해야 합니다. third_party/README.md는 실행기 자산이 wheel에 포함된다고 설명하지만, MANIFEST.in의 관련 경로는 harness2/third_party이고 실제 위치와 다릅니다. 이 정적 차이만으로 특정 배포 파일의 구성을 확정할 수는 없으므로, 소스 트리에서 확인한 구조와 wheel 설치 환경의 동작을 동일시하지 않는 편이 정확합니다.