하네스 엔지니어링 (Harness Engineering)¶

정의¶

AI 에이전트가 잘못된 일을 구조적으로 못 하게 만드는 시스템을 설계하는 일입니다. 프롬프트(부탁) 대신 환경(구조)으로 에이전트의 행동 경계를 제어합니다.

마구(Harness) 비유 말(AI 에이전트)에게 "뛰어!" 라고 말하는 것이 프롬프트입니다. 말이 엉뚱한 방향으로 달리면 매번 소리쳐 잡아줄 수도 있지만, 마구(Harness)를 채우면 말이 달리는 방향 자체를 구조적으로 제어할 수 있습니다.

시대 진화¶

프롬프트(단어) → 컨텍스트(입력 공간) → 하네스(환경) → Loop(메커니즘) → 그래프(구조) 순으로 인간 노력의 단위가 올라가며, 하네스는 2026 초 환경 설계 — CLAUDE.md, hooks, skills, 라이프사이클 단계입니다. 전체 진화 표는 concept-graph-engineering을 참조합니다.

OpenAI 5개월 내부 실험: 100만 줄의 코드를 생성했지만 인간이 작성한 코드는 0줄이었습니다. 병목은 모델이 아니라 환경이었습니다.

2026-06 Peter Steinberger의 X 게시물("이제 에이전트에게 프롬프트를 주는 루프를 설계해야 한다", 650만 조회) 이후 하네스의 다음 단계로 "루프"가 호명되기 시작했습니다. 하네스가 환경이라면, 루프는 그 환경 안에서 사람이 매번 입력하던 자리까지 자동화하는 단계입니다. → concept-loop-engineering 참조.

왜 프롬프트로는 부족한가¶

교통 규칙 vs 물리적 구조물 "이 길로 가지 마세요"라는 표지판(프롬프트)은 무시될 수 있습니다. 중앙 분리대(시스템/구조)는 물리적으로 막습니다. 프롬프트는 표지판이고, 하네스는 중앙 분리대입니다.

구체적 한계: 1. 희석 효과: 대화 맥락이 길어질수록 초반 지시가 잊힙니다. 2. 부정 명령의 역설: NEVER do X 같은 부정 명령은 모델이 내부적으로 X를 먼저 떠올린 후 억제하는 구조 → 실패율이 높습니다. 3. 검증 불가능: 프롬프트는 "지켰는지" 외부에서 확인할 수 없지만, hook은 실행 여부로 확인 가능합니다.

핵심 원칙 4가지¶

#	원칙	설명
1	부탁 대신 구조	프롬프트는 부탁이고, 시스템은 강제합니다. guard.sh가 막으면 에이전트는 실행하지 못합니다.
2	실패가 규칙이 된다	같은 실수가 두 번 나오면 즉시 CLAUDE.md에 추가합니다. "다음엔 잘 해줘"로 넘어가지 않습니다. (Hashimoto 원칙)
3	검증 가능한 목표	`[단계] → verify: [확인법]` 형식으로 씁니다. 성공 기준이 없으면 루프를 멈춥니다.
4	하네스는 자산이다	CLAUDE.md + hooks + skills는 팀이 쌓는 경쟁 우위입니다. 모델·팀원이 바뀌어도 남습니다.

3개 층위 구조¶

세 가지 핵심 소스가 만드는 층:

선언 층 (Karpathy CLAUDE.md) → concept-claude-md
에이전트에게 무엇을 기대하는가 (4원칙)
인프라 층 (OpenAI Harness Eng.) → concept-claude-hooks, concept-multi-agent-pattern
어떤 환경을 만드는가 (hooks, 컨텍스트 방화벽)
피드백 루프 (Mitchell Hashimoto)
어떻게 진화시키는가 (주간 리뷰, 실패 → 규칙 변환)

엔트로피 관리와 Rippable Harness¶

장기 프로젝트에서 에이전트 출력이 점점 발산하는 문제(Drift)에 대응해 주간 하네스 리뷰 루틴을 둡니다. 동시에 과적합 함정을 피해야 합니다:

Opus 4.6 사례: 자기 하네스에서 33위였던 모델이 다른 하네스에서는 5위권이었습니다. 즉, 모델 개선 시 일부 하네스 규칙은 버려야 합니다.
삭제 기준: 지난 4주 동안 위반이 0건이면 삭제를 검토합니다. 단 위반 0건이어도 한 번의 위반이 큰 피해로 이어지는 안전장치(예: .env 커밋 차단)는 유지합니다.

이 점검을 Rippable Harness 점검이라 부릅니다.

적용 시작점¶

베이스라인 측정: 하네스 없이 태스크 3개 실행, 성공률/불필요한 변경/방향 이탈 기록.
실패 패턴 감사: 반복되는 실수 3가지를 "프롬프트로 막을 수 있는가 vs 시스템으로 막아야 하는가"로 분류.
CLAUDE.md 초안 → hooks 설치(+자기검증 루프) → AGENTS.md 추가 → 주간 리뷰 순으로 확장.