한줄 요약
AI 에이전트 성능의 핵심은 모델 스펙이 아니라, 모델을 감싸는 실행 환경 설계다.
무엇이 달라지나?
AI 코딩 도구를 쓰다 보면 자연스럽게 이런 생각이 든다. "이 모델이 문제인가, 아니면 설정이 문제인가?" Addy Osmani는 이 질문에 명확한 답을 내놓는다. 지난 2년간 업계의 시선이 "어떤 모델이 더 똑똑한가"에 과도하게 쏠려 있었다는 진단이다.
그가 정리한 핵심 개념은 **하네스(Harness)**다. 모델 자체를 제외한 모든 것, 즉 시스템 프롬프트, 외부 도구, 컨텍스트 관리 정책, 자동 검사 메커니즘(hook), 샌드박스 실행 환경, 보조 AI(sub-agent), 피드백 루프, 복구 흐름까지를 통틀어 가리키는 말이다. Viv Trivedy는 이를 한 문장으로 정식화했다. "AI agent = model + harness."
Claude Code, Cursor, Codex, Aider, Kline 같은 제품들은 모두 하네스다. 내부에 동일한 모델이 들어가 있어도 우리가 체감하는 동작 품질은 하네스가 결정한다. 실제로 Claude Opus 동일 모델을 기본 하네스에서 커스텀 하네스로 교체했을 때, Terminal Bench 2.0 기준 하위권에서 상위권으로 순위가 급등한 사례가 보고됐다. Viv의 팀은 같은 모델을 30위권에서 5위권으로 끌어올렸는데, 바꾼 것은 모델이 아니라 하네스뿐이었다.
HumanLayer의 표현을 빌리면, 이건 모델 문제가 아니라 "설정 문제(skill issue)"다.
실무에서 어떤 의미인가?
하네스 엔지니어링이 실무에 시사하는 바는 크게 세 가지로 정리된다.
첫째, 실패를 규칙으로 전환하는 래칫(Ratchet) 원칙이다. AI가 한 번 저지른 실수는 우연이 아니라 영구적인 신호로 취급한다. 해당 패턴을 탐지하는 검사기를 추가하고, 규칙 문서에 한 줄을 기록하고, 자동 차단 메커니즘을 붙인다. 좋은 규칙 문서의 모든 줄은 실제로 발생한 구체적인 실패와 연결되어야 한다. 이 구조가 쌓이면 팀의 지식은 개인이 바뀌어도 하네스 안에 남는다.
둘째, 원하는 동작에서 역방향으로 설계한다. "이런 동작을 원한다 → 이를 가능하게 하는 하네스 컴포넌트는 무엇인가"의 순서로 접근한다. 한 문장으로 존재 이유를 설명할 수 없는 컴포넌트는 제거하는 것이 낫다.
셋째, 컨텍스트 관리가 하네스의 핵심 역할이다. 컨텍스트 창이 차오를수록 모델의 판단력은 눈에 띄게 떨어진다. 오래된 내용을 요약 압축하고, 대형 로그는 앞뒤만 남긴 뒤 본문을 파일로 내보내고, 도구와 지시문은 필요한 시점에만 노출하는 "점진적 공개" 방식을 쓴다. 장기 작업에서는 요약 압축만으로 부족하고, 구조화된 인수인계 문서를 만들어 새 창에서 재시작하는 방식도 권장된다.
Hook의 역할도 분명히 구분해야 한다. "AI에게 그렇게 하라고 말하는 것"과 "시스템이 그렇게 강제하는 것"은 다르다. Hook은 도구 사용 직전, 파일 수정 후, 커밋 직전 같은 시점에 자동으로 개입한다. 검사를 통과하면 아무 소리도 내지 않고, 실패하면 에러 메시지를 AI 흐름에 직접 주입해 스스로 수정하게 만든다.
AGENTS.md 같은 규칙 문서는 짧을수록 강력하다. HumanLayer는 60줄 이하를 권장한다. 길어질수록 각 줄의 비중이 희석된다. 도구도 마찬가지다. 비슷한 기능의 도구 50개보다 명확한 도구 10개가 낫다. 그리고 외부 MCP 서버를 검증 없이 붙이는 건 보안 위협이 된다. 도구 설명 텍스트 자체가 AI에게 읽히기 때문에, 악의적으로 작성된 지시문이 그 안에 숨어 있을 수 있다.
모델이 발전하면 하네스는 사라지는가? 그렇지 않다. 모델이 좋아지면 일부 컴포넌트는 불필요해지지만, 모델이 새로 닿을 수 있게 된 영역에서 새로운 약점이 드러나고, 다시 하네스가 그 자리를 채운다. Anthropic의 표현처럼, "모든 하네스 컴포넌트는 모델이 아직 혼자 못 하는 것이 무엇인지에 대한 가정을 담고 있다."
도입 전 체크포인트
하네스 엔지니어링을 본격적으로 적용하기 전에 점검할 사항들이다.
- 현재 규칙 문서(AGENTS.md 등)가 실제 실패 사례에서 나온 것인가, 아니면 막연한 스타일 가이드인가? 후자라면 래칫 원칙부터 다시 시작해야 한다.
- Hook이 없다면, 지금 AI에게 요청하는 것들 중 시스템이 강제해야 할 것과 그냥 요청해도 될 것을 구분하는 작업부터 시작한다.
- 도구 개수를 세어봐라. 비슷한 기능이 중복되거나 이름이 모호한 도구가 있다면 컨텍스트 낭비다.
- 외부 MCP 서버 출처를 검토했는가? 검증되지 않은 서버는 연결 전에 반드시 도구 설명 텍스트를 직접 확인해야 한다.
- Harness-as-a-Service(HaaS) 옵션을 고려해봐라. Claude Agent SDK, Codex SDK, OpenAI Agents SDK처럼 루프, 컨텍스트 관리, 훅, 샌드박스를 묶어서 제공하는 도구들이 늘고 있다. 도메인 지식에 집중하고 인프라는 위임하는 선택지다.
