하네스 엔지니어링 (Harness Engineering)
하네스 엔지니어링은 에이전트를 둘러싼 제어 시스템을 설계합니다. 즉, 에이전트가 무엇을 편집할 수 있는지, 어떻게 피드백을 받는지, 상태를 어디에 기록하는지, 실패 시 어떻게 복구하는지, 그리고 되돌릴 수 없는 작업을 누가 승인할 수 있는지 등을 정의합니다. 하네스는 단순히 도움이 되는 에이전트 세션과 목표를 손상시키지 않고 며칠 동안 실행될 수 있는 자율 루프의 차이를 만듭니다.
활성화 시점 (When to Activate)
다음과 같은 경우 이 스킬을 활성화하세요:
- 자율 연구 또는 실험 루프를 구축할 때
- 잠긴 메트릭과 편집 가능한 코드/콘텐츠를 갖춘 에이전트 환경을 설계할 때
- PR 생성 또는 백그라운드 에이전트를 만들 때
- 에이전트가 빈번한 인간 프롬프트 없이 안전하게 실행될 수 있는지 평가할 때
- 에이전트 워크플로우에 참신성, 절제(ablation), 가지치기, 롤백 또는 영구 로깅을 추가할 때
- 에이전트가 벤치마크를 조작하거나, Rubric을 약화시키거나, 압축 과정에서 상태를 잃는 것을 방지할 때
인접 작업이 다른 스킬에 속하므로 이 스킬을 활성화하지 마세요:
- 자율 제어 표면이 없는 일반 품질 게이트, 회귀 테스트 스위트, 또는 결과 메트릭:
evaluation - 하네스 도구를 위한 도구 스키마, 응답 형식, 복구 오류:
tool-design - 프로젝트 수준의 작업-모델 적합성, 파이프라인 형태, 비용 계획:
project-development - 원격 샌드박스, 웜 풀, 호스티드 세션 인프라:
hosted-agents
핵심 개념 (Core Concepts)
하네스 경계 (Harness Boundary)
에이전트를 에이전트가 작동하는 환경과 분리하세요. 에이전트는 작업을 제안하고, 하네스는 허용된 표면, 피드백, 지속성, 승격 규칙을 정의합니다.
네 가지 표면 클래스를 사용하세요:
| 표면 | 예시 | 규칙 |
|---|---|---|
| 잠금 (Locked) | 평가 메트릭, Rubric, 검증 스크립트, 병합 정책 | 에이전트는 읽고 변경을 제안할 수 있지만, 수정된 규칙으로 스스로를 평가할 수 없음 |
| 편집 가능 (Editable) | 스킬 초안, 실험 파일, 프롬프트, 테스트 중인 설정 | 에이전트가 루프 중에 변경할 수 있음 |
| 추가 전용 (Append-only) | 결과 로그, 연구 스레드, 거부된 아이디어 | 에이전트는 추가만 가능하고 다시 쓸 수 없음 |
| 인간 제어 (Human-controlled) | 병합, 프로덕션 배포, 자격 증명, 파괴적 작업 | 명시적인 인간 승인 필요 |
빠른 피드백 루프 (Tight Feedback Loops)
자율성은 피드백이 빠르고, 명확하며, 조작하기 어려울 때 제대로 작동합니다. Karpathy의 autoresearch가 최소 패턴입니다: 하나의 편집 가능한 파일, 하나의 잠긴 평가 파일, 고정된 벽시계 예산, 하나의 스칼라 메트릭, Git 롤백, 영구 결과 로그. 교훈은 모든 하네스가 하나의 메트릭을 필요로 한다는 것이 아니라, 모호한 피드백이 모호한 자율성을 만든다는 것입니다.
개방형 연구-스킬 작업의 경우, 스칼라 메트릭을 잠긴 Rubric, 결정론적 구조 검사, 소스 추적성, 인간 검토 임계값으로 대체하세요.
영구 상태 (Durable State)
장기 실행 에이전트는 상태를 외부화해야 합니다. 계획, 소스 큐, 결과, 실패, 핸드오프를 파일에 저장하여 미래 에이전트가 채팅 기록에 의존하지 않고 재개할 수 있도록 하세요. Prime Intellect의 자율 nanoGPT 작업은 복구, 모니터링, 감사를 위한 영구 스크래치패드와 THREAD.md 스타일 로그의 가치를 보여주었습니다.
다음 항목에는 추가 전용 로그를 사용하세요:
- 시도한 내용
- 개선되거나 실패한 내용
- 후보가 유지, 폐기 또는 검토 대상으로 분류된 이유
- 확인된 업스트림 소스
- 다음 에이전트가 해야 할 일
탐색 규율 (Search Discipline)
에이전트는 가장 가까운 표면을 이용하고, 복잡성을 쌓으며, 가지치기를 덜 실행하는 경향이 있습니다. 명시적인 탐색 규칙을 추가하세요:
- 업스트림 소스를 정기적으로 새로 고침하세요.
- 큰 예산을 사용하기 전에 참신성 검사를 요구하세요.
- 재발견을 방지하기 위해 거부된 시도를 보존하세요.
- 스택에 여러 추가 사항이 있을 때 leave-one-out 가지치기를 실행하세요.
- 품질이 동등할 때 단순화에 보상하세요.
- 승격 전에 별도의 검증을 사용하세요.
메커니즘 레지스트리 (Mechanism Registry)
연구-스킬 시스템의 경우, 수용된 메커니즘을 산문과 별도로 추적하세요. 메커니즘 레코드에는 안정적인 mechanism_id, owning_skill, status, 활성화 시나리오, 동작 변경, 증거, 실패 모드가 포함되어야 합니다. 참신성 게이트는 더 넓은 코퍼스 중복성을 사용하기 전에 이 레지스트리와 비교해야 합니다. 키워드 중복성은 오래된 표현을 잡아내는 반면, 메커니즘 비교는 실제 중복을 잡아내기 때문입니다.
거버넌스 (Governance)
자율 에이전트는 PR을 준비할 수 있지만, 거버넌스는 명시적이어야 합니다. 에이전트는 변경 사항을 초안 작성하고, 검사를 실행하며, PR 요약을 작성할 수 있습니다. 사용자가 특정 작업에 대해 명시적으로 권한을 부여하지 않는 한, 에이전트는 병합, 배포, 푸시를 해서는 안 됩니다.
상세 주제 (Detailed Topics)
Autoresearch 스타일 루프 (Autoresearch-Style Loop)
안정적인 평가자에 대해 아티팩트를 최적화할 때 이 패턴을 사용하세요:
잠긴 컨텍스트 읽기 -> 가설 선택 -> 허용된 표면 편집 -> 커밋/체크포인트
-> 평가자 실행 -> 결과 기록 -> 더 나으면 유지 -> 더 나쁘면 폐기 또는 롤백
-> 반복
필수 속성:
- 평가자는 편집 가능한 표면 외부에 있어야 합니다.
- 피드백 주기는 시도를 비교할 수 있을 만큼 고정되어야 합니다.
- 실패한 시도는 감사 추적을 남겨야 합니다.
- 롤백은 저렴해야 합니다.
- 에이전트는 충돌 및 시간 초과에 대한 정책을 가지고 있어야 합니다.
연구-스킬 루프 (Research-To-Skill Loop)
소스가 스킬 변경으로 이어질 때 이 패턴을 사용하세요:
발견 -> 검색 -> 게이트 -> 점수 매기기 -> 메커니즘 추출
-> 기존 또는 새 스킬에 매핑 -> 제안 초안 작성 -> 구조 검증
-> PR 준비 -> 인간 검토
잠긴 평가자는 소스 Rubric, 스킬 변경 Rubric, 구조 검사, 검토자 승인의 조합입니다. 편집 가능한 아티팩트는 제안된 스킬 델타입니다.
메트릭 조작 저항성 (Metric Gaming Resistance)
최적화하는 에이전트가 하네스를 학습할 것이라고 가정하세요. 다음을 방어하세요:
- 평가 코드나 Rubric을 편집한 후 새 버전을 자체 승인에 사용하는 행위
- 판사를 기쁘게 하지만 스킬 활성화를 해치는 장황한 콘텐츠 추가
- 검색되지 않은 소스 인용
- 중요한 차원에서 실패하면서 전체 점수 최적화
- 로그에서 실패한 결과를 생략
완화 방법: 실행별로 Rubric을 잠그고, 차원별 점수를 보고하며, 소스 검색 증거를 요구하고, 거부된 시도를 보존하며, 거버넌스 변경을 인간 검토로 전환하세요.
모니터링 에이전트 (Monitoring Agents)
장기 실행에는 모니터링 에이전트를 사용하되, 명시적으로 다른 작업이 할당되지 않는 한 읽기 전용 보고로 제한하세요. 모니터링 출력은 다음을 보고해야 합니다:
- 현재 최고 후보
- 활성 작업 또는 초안
- 마지막 업스트림 새로 고침
- 실패했거나 오래된 루프
- 로그와 주장된 상태 간의 불일치
- 다음 작업 및 차단 항목
실용 지침 (Practical Guidance)
하네스 설계 체크리스트 (Harness Design Checklist)
- 목표를 한 문장으로 정의하세요.
- 잠금, 편집 가능, 추가 전용, 인간 제어 표면을 식별하세요.
- 피드백 메커니즘을 선택하세요: 스칼라 메트릭, Rubric, 결정론적 테스트, 인간 검토, 또는 이들의 조합.
- 유지, 폐기, 충돌, 시간 초과, 검토 상태를 정의하세요.
- 루프가 시작되기 전에 영구 스레드 로그를 생성하세요.
- 장기 실행 루프를 위해 소스 새로 고침, 메커니즘 레지스트리 참신성, 가지치기 규칙을 추가하세요.
- 에이전트가 묻지 않고 수행할 수 있는 작업과 승인이 필요한 작업을 정의하세요.
- 하나의 알려진 좋은 아티팩트와 하나의 알려진 나쁜 아티팩트로 하네스를 검증하세요.
파일 레이아웃 (File Layout)
research-run/
THREAD.md
sources/
queue.md
evaluations/
proposals/
logs/
results.tsv
rejected.md
drafts/
추가 전용 기계 판독 가능 로그에는 TSV 또는 JSONL을 사용하세요. 핸드오프 및 검토자 대상 요약에는 Markdown을 사용하세요.
예시 (Examples)
예시 1: 잠긴 메트릭 (Locked metric)
에이전트가 train.py를 최적화하지만, prepare.py가 데이터 로딩 및 평가를 담당합니다. 에이전트는 모델을 편집할 수 있지만 메트릭은 변경할 수 없습니다. 실패한 실험은 기록되고 롤백됩니다.
예시 2: 잠긴 Rubric (Locked rubric)
에이전트가 새로운 Anthropic 또는 OpenAI 엔지니어링 게시물을 평가하지만, 소스 큐레이션 Rubric은 실행 중에 잠겨 있습니다. 소스가 통과하면 에이전트가 스킬 제안서를 초안 작성합니다. Rubric 임계값을 낮춰 소스를 수용할 수 없습니다.
예시 3: 자동 PR, 자동 병합 없음 (Auto-PR without auto-merge)
에이전트가 소스, 스킬, 구조 검사를 통과한 후 브랜치와 PR 본문을 준비합니다. PR은 해결되지 않은 위험을 명시하고 인간의 병합 승인을 기다립니다.
지침 (Guidelines)
- 루프를 시작하기 전에 평가자를 잠그세요.
- 편집 가능한 표면을 안정적인 diff를 위해 충분히 좁게 유지하세요.
- 컨텍스트 압축이 상태를 지울 수 있기 전에 영구 로그를 작성하세요.
- 전체 점수만 보고하지 말고 차원별 점수를 보고하세요.
- 인용 전에 소스 검색을 요구하세요.
- 광범위한 탐색을 위한 참신성 게이트와 복잡한 스택을 위한 가지치기 게이트를 추가하세요.
- 품질이 동등할 때 단순화를 선호하세요.
- PR 준비와 병합 권한을 분리하세요.
- 하네스 변경 사항을 이전 및 새 평가자로 재검증하세요.
- 중단된 자율 루프를 에이전트 성격 문제가 아니라 하네스 실패로 취급하세요.
주의 사항 (Gotchas)
- 변경 가능한 평가자 (Mutable evaluator): 에이전트가 메트릭을 편집할 수 있으면 작업 대신 벤치마크를 최적화할 수 있습니다. Rubric과 평가 코드를 실행 중에 잠그세요.
- 채팅 전용 메모리 (Chat-only memory): 계획이 대화 기록에만 있을 경우 압축 후 장기 실행이 실패합니다. 처음부터 스레드 로그와 결과 파일을 작성하세요.
- 폐기 기록 없음 (No discard record): 거부된 시도 로그가 없으면 에이전트가 실패한 아이디어를 반복합니다. 재발견을 피하기 위해 충분한 세부 정보와 함께 실패를 보존하세요.
- 복잡성 축적 (Complexity accretion): 에이전트는 변경 사항을 쌓고 거의 제거하지 않습니다. 가지치기 라운드를 요구하고 동등한 품질의 단순화에 보상하세요.
- 조기 참신성 주장 (Premature novelty claims): 에이전트는 재조합을 참신하다고 레이블을 붙입니다. 참신성을 주장하기 전에 기존 리포지토리 스킬, 소스 큐, 거부된 로그와 비교하세요.
- 모니터 오정보 (Monitor misreporting): 모니터링 에이전트가 오래되었거나 일관성 없는 상태를 요약할 수 있습니다. 주장 뒤에 있는 파일이나 로그를 인용하도록 요구하세요.
- 인간 승인 모호성 (Human approval ambiguity): "PR 준비"는 "PR 병합"이 아닙니다. 하네스에서 승인 경계를 명시적으로 만드세요.
- 변동하는 소스 드리프트 (Volatile source drift): 빠르게 움직이는 연구소의 주장은 빠르게 노후화됩니다. 날짜가 있는 증거를 참조에 포함하고 재검증을 예약하세요.
통합 (Integration)
이 스킬은 다음에 연결됩니다:
- evaluation - Rubric 및 품질 게이트는 잠긴 피드백 표면을 제공합니다.
- advanced-evaluation - 쌍별 비교 및 편향 완화는 제안 검토를 개선합니다.
- filesystem-context - 영구 로그, 스크래치패드, 스레드 파일은 상태를 보존합니다.
- multi-agent-patterns - 연구자, 검증자, 모니터, 작성자 에이전트는 격리된 컨텍스트가 필요합니다.
- tool-design - 하네스 도구는 명확한 계약과 복구 오류를 노출해야 합니다.
- project-development - 파일 기반 파이프라인 및 작업-모델 적합성 분석은 루프를 단순하게 유지합니다.
- hosted-agents - 백그라운드 실행에는 샌드박스, 스냅샷, 승인 경계가 필요합니다.
참조 (References)
내부 참조:
researcher/README.md- 리포지토리 네이티브 연구-스킬 운영 체제를 구현할 때 읽으세요.researcher/rubrics/harness-change.md- 에이전트 하네스 변경 사항을 평가할 때 읽으세요.researcher/runbooks/autonomous-research-loop.md- 소스-스킬 루프를 실행할 때 읽으세요.
외부 리소스:
- Karpathy
autoresearch- 잠긴 평가가 있는 제약된 자율 실험 루프. - Prime Intellect 자율 nanoGPT speedrun - 영구 스크래치패드, 핸드오프, 모니터링, 자율성 실패 모드.
- AlphaEvolve 및 FunSearch - 체계적인 평가자와 쌍을 이루는 LLM 생성 후보.
- HELM 및 LM Evaluation Harness - 투명하고 재현 가능한 평가 인프라.
스킬 메타데이터 (Skill Metadata)
생성일: 2026-05-14 최종 업데이트: 2026-05-15 작성자: Agent Skills for Context Engineering Contributors 버전: 1.1.0