출처: Addy Osmani
문서유형: 번역·해설
#AgentHarness #HarnessEngineering #AIAgent #OpenClaw #TechLLM #Subagent
핵심 요약
AI 에이전트의 성능은 모델 하나로 결정되지 않습니다. 모델을 둘러싼 프롬프트, 도구, 파일 시스템, 샌드박스, 메모리, 훅, 서브에이전트, 검증 루프까지 합쳐져야 실제로 일을 끝내는 에이전트가 됩니다. Addy Osmani는 이 전체 구조를 **하네스(harness)**라고 부릅니다.
Addy Osmani의 글 **“Agent Harness Engineering”**에서 가장 중요한 문장은 이겁니다.
Agent = Model + Harness
우리는 지난 몇 년 동안 “어떤 모델이 더 똑똑한가”에 집중했습니다. Claude가 나은지, GPT가 나은지, Codex가 코드를 더 잘 쓰는지 같은 이야기 말입니다. 물론 모델은 중요합니다. 하지만 실제로 일을 끝내는 AI 에이전트는 모델 하나만으로 만들어지지 않습니다.
모델을 둘러싼 프롬프트, 도구, 파일 시스템, 샌드박스, 메모리, 훅, 서브에이전트, 검증 루프까지 모두 합쳐져야 비로소 “작업을 완료하는 에이전트”가 됩니다. 이 전체 구조가 바로 하네스입니다.
좋은 모델보다 좋은 하네스가 더 큰 차이를 만든다
글의 핵심은 단순합니다.
괜찮은 모델 + 좋은 하네스는 뛰어난 모델 + 나쁜 하네스를 이길 수 있습니다.
AI 에이전트가 실수했을 때 우리는 흔히 “모델이 아직 부족하네”라고 말합니다. 하지만 하네스 엔지니어링 관점에서는 다르게 봅니다.
- 에이전트가 프로젝트 규칙을 몰랐다면
AGENTS.md에 규칙을 추가합니다. - 위험한 명령을 실행하려 했다면 훅으로 차단합니다.
- 긴 작업에서 길을 잃는다면 Planner와 Worker를 분리합니다.
- 깨진 코드를 완료했다고 착각한다면 테스트와 타입체크를 루프에 넣습니다.
즉, 실패를 모델 탓으로만 넘기지 않고 시스템의 학습 재료로 삼는 겁니다.
실수는 한 번으로 끝내야 한다
하네스 엔지니어링의 가장 강력한 습관은 “모든 실수를 규칙으로 바꾸는 것”입니다.
에이전트가 테스트를 주석 처리한 채 PR을 만들었다면, 다음에는 AGENTS.md에 “테스트를 주석 처리하지 말 것”을 넣습니다. 더 나아가 pre-commit 훅에서 .skip, xit 같은 패턴을 검사하게 만들 수 있습니다. 리뷰어 서브에이전트가 이를 blocker로 잡게 만들 수도 있습니다.
중요한 건 규칙을 상상으로 늘리지 않는 것입니다. 좋은 하네스의 규칙은 대부분 실제 실패에서 나옵니다. 실패가 있었고, 그 실패를 다시 반복하지 않기 위해 프롬프트, 도구, 훅, 검증 루프가 추가됩니다.
하네스는 실행 환경까지 포함한다
하네스는 단순한 프롬프트 모음이 아닙니다. 파일 시스템, Git, bash, 브라우저, 샌드박스, 로그, 테스트 러너까지 포함합니다.
파일 시스템은 에이전트에게 지속 가능한 작업 공간을 줍니다. Git은 되돌리기와 비교, 실험 분기를 가능하게 합니다. Bash와 코드 실행은 에이전트가 필요한 도구를 직접 조합하게 해줍니다. 샌드박스는 그 실행을 안전하게 격리합니다.
여기서 중요한 점은 모델이 실행 환경을 스스로 설계하지 않는다는 것입니다. 어디서 실행할지, 어떤 도구를 쓸 수 있는지, 어떤 명령을 막을지, 어떤 검증을 통과해야 완료로 볼지는 모두 하네스 설계자의 결정입니다.
컨텍스트 관리도 하네스의 핵심이다
모델은 컨텍스트 안에 있는 것만 보고 판단합니다. 그래서 긴 작업에서는 컨텍스트가 오염되거나 너무 커지면서 성능이 떨어지는 문제가 생깁니다. Addy는 이를 context rot으로 설명합니다.
이를 막기 위한 방법은 여러 가지입니다.
- 오래된 대화를 요약해 남기는 compaction
- 긴 로그나 출력은 파일로 빼고 필요한 부분만 다시 읽게 하는 tool-call offloading
- 모든 지침을 처음부터 넣지 않고 필요한 skill만 열어주는 progressive disclosure
- 아주 긴 작업에서는 새 세션을 열고 hand-off 파일로 이어받는 context reset
결국 하네스는 좋은 컨텍스트를 적절한 시점에 공급하는 시스템입니다. “많이 넣는 것”보다 “필요한 것을 정확히 넣는 것”이 중요합니다.
훅은 말이 아니라 강제력이다
프롬프트에 “테스트를 실행해”라고 쓰는 것과, 실제로 테스트가 실패하면 완료를 막는 것은 완전히 다릅니다.
훅은 하네스의 강제력입니다. 파일 수정 후 lint를 돌리고, 커밋 전 테스트를 실행하고, rm -rf나 git push --force 같은 위험 명령을 차단합니다. 성공하면 조용히 지나가고, 실패하면 에러만 에이전트에게 돌려줘서 스스로 수정하게 만듭니다.
이 구조가 잘 잡히면 에이전트는 단순 생성기가 아니라, 실패를 관찰하고 고치는 실행 루프가 됩니다.
모델이 좋아져도 하네스는 사라지지 않는다
재미있는 점은 모델이 발전해도 하네스의 필요성이 사라지지 않는다는 것입니다. 다만 위치가 바뀝니다.
예전에는 모델이 긴 작업에서 불안해하며 빨리 마무리하려는 문제를 막기 위한 장치가 필요했습니다. 더 좋은 모델이 나오면 그런 장치는 줄어들 수 있습니다. 하지만 더 어려운 작업이 가능해지면서 새로운 문제가 생깁니다.
예를 들면 며칠짜리 작업의 메모리 정책, 여러 전문 에이전트의 협업, 생성된 UI의 품질 평가 같은 것들입니다. 모델이 올라가면 천장도 같이 올라가고, 그 천장에 맞는 새로운 하네스가 필요해집니다.
우리 시스템에 적용하면 좋은 점
이 글은 우리 TechLLM/OpenClaw/Blogger 시스템에도 바로 적용할 만한 포인트가 많습니다. 이미 우리는 랍스터식 Plan → Work → Review 흐름, subagent 분업, AGENTS.md, MEMORY.md, skill 기반 작업, preview-before-push 규칙을 갖고 있습니다. 즉, 기본 하네스의 뼈대는 이미 있습니다.
다만 더 좋아질 수 있는 지점이 분명합니다.
첫째, 실패를 규칙으로 남기는 ratchet 구조를 더 강화하면 좋습니다. 블로그 글에서 자주 생기는 문제, 예를 들어 원문 링크 누락, 이미지 alt 누락, Hugo 빌드 경고, 너무 직역투인 문장 같은 실패를 발견하면 매번 임시로 고치는 데서 끝내지 말고 Blogger 전용 체크리스트나 skill 규칙으로 승격해야 합니다.
둘째, preview-before-push를 훅처럼 강제할 수 있습니다. 지금은 작업 원칙에 가깝지만, 더 좋은 하네스라면 push 전에 hugo --minify, front matter 확인, 원문 footer 확인, 이미지 경로 존재 확인을 자동으로 검사해야 합니다. 성공은 조용히, 실패는 구체적으로 알려주면 됩니다.
셋째, Plan → Work → Review의 산출물을 파일로 남기는 방식이 유용합니다. 긴 글이나 번역 글에서는 초안, 검토 메모, 최종본을 분리해두면 context rot을 줄일 수 있습니다. 특히 원문이 길 때는 요약본과 인사이트 추출본을 별도 파일로 두고, 최종 작성 에이전트가 그 파일을 읽게 하는 방식이 안정적입니다.
넷째, 서브에이전트 역할을 더 명확히 나누면 좋습니다. 예를 들어 리서처는 원문과 이미지 수집, 라이터는 한국어 글쓰기, 리뷰어는 사실성·SEO·Hugo 호환성·우리 시스템 적용성만 검토하게 만드는 식입니다. 자기 글을 자기가 평가하는 것보다 분리된 리뷰어가 보는 편이 더 안전합니다.
다섯째, AGENTS.md와 MEMORY.md는 길게 늘리기보다 실제 실패에서 얻은 짧은 규칙만 남기는 방식이 좋습니다. 좋은 규칙은 브레인스토밍한 이상론이 아니라 과거 실패의 흔적이어야 합니다.
정리
Agent Harness Engineering의 핵심은 “모델을 고르는 일”에서 “모델이 제대로 일하게 만드는 구조를 설계하는 일”로 관심을 옮기는 것입니다.
AI 에이전트의 성능은 모델만으로 결정되지 않습니다. 무엇을 기억하게 할지, 어떤 도구를 줄지, 어디서 실행하게 할지, 어떤 실패를 막을지, 언제 사람에게 확인받을지, 어떻게 리뷰할지까지 모두 합쳐져 결과가 나옵니다.
우리 TechLLM/Blogger 시스템도 마찬가지입니다. 좋은 글을 쓰는 모델도 중요하지만, 더 중요한 건 좋은 글이 반복해서 나오도록 만드는 하네스입니다. 실패를 규칙으로 바꾸고, 검증을 자동화하고, 역할을 분리하고, push 전에 확인하는 구조를 더 단단히 만들면 블로그 제작 품질은 모델 교체보다 훨씬 안정적으로 올라갈 가능성이 큽니다.