Harness Engineering

“모델 자체 성능”이 아니라, 모델이 일하는 입력/도구/규칙/검증/피드백 루프를 설계해
일관성, 정확도, 재현성, 통제 가능성을 확보하는 Engineering.

Prompt Engineering: “한 번에 잘 시키기”

Harness Engineering: “여러 단계에서 틀리지 않게 운영하기”

하네스(Harness)는 원래 말(馬)에 장착하는 마구(馬具), 즉 말의 힘을 안전하게 제어하고 유용한 방향으로 이끌기 위한 도구를 가리키는 단어이다. 동사로는 '강력한 것을 제어하여 유익하게 활용한다'는 의미로도 쓰인다.

표준 Harness 아키텍처

원칙

• 상시 레이어는 짧고 강하게

• 긴 문서는 필요 시점에만 로드

• “요약본→원문” 2단계 접근 (Progressive Disclosure)

A. Always-on Layer (상시 레이어)

역할/금지사항/출력형식/안전규칙

예: rules.md, policy.md, style.md

B. Conditional Layer (조건부 레이어)

Skill, Subagent, Tool spec, 도메인지식

필요할 때만 로드 (Progressive Disclosure)

C. Execution Layer

Planner → Worker → Verifier 분리

도구 호출 권한/순서/제약 제어

D. Control Loop

Plan → Act → Check → Repair 루프

실패 시 재시도 정책(원인 분류 기반)

E. Eval & Observability

오프라인 평가셋 + 온라인 운영지표

실패 로그를 규칙/검증에 다시 반영

Claude 권장 Workflow

전략	이전	이후
검증 기준 제공	“이메일 주소를 검증하는 함수를 구현하세요”	“validateEmail 함수를 작성하세요. 예제 테스트 케이스: user@example.com은 true, invalid는 false, user@.com은 false입니다. 구현 후 테스트를 실행하세요.”
UI 변경 사항을 시각적으로 검증	“대시보드를 더 좋게 보이게 하세요”	“[스크린샷 붙여넣기] 이 디자인을 구현하세요. 결과의 스크린샷을 찍고 원본과 비교하세요. 차이점을 나열하고 수정하세요.”
증상이 아닌 근본 원인 해결	“빌드가 실패하고 있습니다”	“빌드가 이 오류로 실패합니다: [오류 붙여넣기]. 수정하고 빌드가 성공하는지 확인하세요. 근본 원인을 해결하고 오류를 억제하지 마세요.”
작업 범위 지정. 어떤 파일, 어떤 시나리오, 테스트 선호도를 지정하십시오.	“foo.py에 대한 테스트 추가”	“사용자가 로그아웃된 경우의 엣지 케이스를 다루는 foo.py에 대한 테스트를 작성하세요. 모의 객체를 피하세요.”
소스 지적. Claude를 질문에 답할 수 있는 소스로 안내하십시오.	“ExecutionFactory가 왜 그렇게 이상한 API를 가지고 있습니까?”	“ExecutionFactory의 git 히스토리를 살펴보고 API가 어떻게 되었는지 요약하세요.”
기존 패턴 참조. Claude를 코드베이스의 패턴으로 지적하십시오.	“캘린더 위젯 추가”	“홈 페이지에서 기존 위젯이 어떻게 구현되는지 살펴보고 패턴을 이해하세요. HotDogWidget.php는 좋은 예입니다. 패턴을 따라 사용자가 월을 선택하고 앞뒤로 이동하여 연도를 선택할 수 있는 새로운 캘린더 위젯을 구현하세요. 코드베이스에서 이미 사용 중인 라이브러리 외에는 라이브러리를 사용하지 않고 처음부터 빌드하세요.”
증상 설명. 증상, 가능한 위치, “수정됨”의 모습을 제공하십시오.	“로그인 버그 수정”	“사용자가 세션 시간 초과 후 로그인이 실패한다고 보고합니다. src/auth/의 인증 흐름, 특히 토큰 새로 고침을 확인하세요. 문제를 재현하는 실패한 테스트를 작성한 다음 수정하세요.”

1. 탐색

Plan Mode를 입력하십시오. Claude는 파일을 읽고 변경을 수행하지 않고 질문에 답합니다.

/src/auth를 읽고 세션 및 로그인을 어떻게 처리하는지 이해하세요.
또한 비밀에 대한 환경 변수를 어떻게 관리하는지 살펴보세요.

2. 계획

Claude에게 상세한 구현 계획을 작성하도록 요청하십시오.

Google OAuth를 추가하고 싶습니다. 어떤 파일을 변경해야 합니까?
세션 흐름은 무엇입니까? 계획을 작성하세요.
Ctrl+G를 눌러 Claude가 진행하기 전에 텍스트 편집기에서 계획을 열어 직접 편집하십시오.

3. 구현

Normal Mode로 전환하고 Claude가 코드를 작성하도록 하여 계획에 대해 검증하십시오.

계획에서 OAuth 흐름을 구현하세요. 콜백 핸들러에 대한 테스트를 작성하고,
테스트 스위트를 실행하고 실패를 수정하세요.

4. 커밋

Claude에게 설명적인 메시지로 커밋하고 PR을 생성하도록 요청하십시오.

설명적인 메시지로 커밋하고 PR을 열기

컴퓨터의 비유

하나의 컴퓨터가 있다고 해보자

Claude (Sonnet , opus) , GPT (codex), Gemini 같은 모델은 CPU 라고 볼 수 있다.

컨텍스트 윈도우는 RAM 정도다.

하네스는 이 CPU 와 컨텍스트 윈도우를 통제할 수 있는 운영체제 같은 느낌이다.

모델을 관리하고 , 모델이 어떤 도구를 호출할지 결정한다.

또 너무 용량이 커진 컨텍스트 윈도우를 정리하기도 한다.

Claude Code, Opencode , Cursor 같은 것들은 하네스의 역할을 어느 정도 수준에서 해준다.

각자의 처리방식 ( 각자의 OS ) 가 다르고 , 다른 방식으로 처리 할 뿐이다.

하네스 의 의미

같은 모델이라도 서로 다른 하네스에 넣으면 완전히 다르게 작동한다.

객관적인 지표가 안 좋은 모델이라도 좋은 하네스를 구축하면 그 성능이 훨씬 좋아질 수 있고,

객관적인 지표가 좋은 모델이더라도 좋지 않은 하네스를 구축하면 그 성능이 훨씬 떨어질 수 있으며,

하네스 없이 모델과 대화만 주고 받는 다면 그 모델의 성능 100% 도 쓰고있는 것이 아니다.

우리는 우리의 업무에서 인간의 개입을 최소화하고, 꼭 필요한 곳만 사람이 승인하며 최대한 많은 토큰을 생성해야 한다

토스 블로그 하네스 관련 글

위 글에서 언급하듯

결국 이 모든 흐름이 향하는 곳은 ‘우리 조직 , 또는 본인 에 최적화된 하네스(Harness)의 구축’이라고 생각한다.