같은 AI 모델을 사용하고 있음에도 불구하고, 채팅 화면과 에이전트 도구에서 나오는 결과가 완전히 다르게 느껴진 경험이 없으신가요?
이러한 차이를 만들어내는 것이 바로 '하네스(Harness)'입니다. AI의 실력은 단순히 모델 자체의 지능뿐만 아니라, 그 모델을 어떻게 구동시키는지에 따라 크게 달라집니다.
원래 하네스는 말갖춤(馬具)을 의미합니다. 말의 힘을 수레를 끄는 일이라는 '작업'으로 변환시키는 도구입니다.
AI도 이와 같습니다. 모델이 '말의 힘'이라면, 하네스는 '그 힘을 작업으로 변환하는 메커니즘'에 해당합니다. 모델이 생각하고, 하네스가 파일을 읽게 하고, 커맨드를 실행시키며, 그 결과를 다시 모델에게 반환하는 구조입니다.
하네스의 요소들은 AI를 '막 배치된 유능한 신입 사원'에 비유하면 정리하기 쉽습니다. 지적 능력(모델)이 뛰어나더라도, 자료나 권한을 주지 않으면 업무가 진행될 수 없습니다.
| 요소 | 신입사원에 비유하자면 | 역할 |
|---|
| 지시 파일 (CLAUDE.md, AGENTS.md 등) | 매일 아침 읽는 온보딩 자료 | 프로젝트의 전제나 규약을 매번 반드시 전달함 |
| ... | | |
채팅 화면에서 사용하는 AI는 이 중 극히 일부만을 가지고 있습니다. 그렇기 때문에 같은 모델이라도 수행할 수 있는 작업에 차이가 발생하는 것입니다.
매번 필요한 전제 → 지시 파일. 다만 너무 많이 작성하면 매번 읽어야 할 양이 늘어나 시스템 부하가 커집니다. -
때때로 필요한 절차 (PDF 작성 방법, 리뷰 관점 등) → Skills. 필요한 때만 읽히기 때문에, 많이 준비해도 방해가 되기 어렵습니다. -
작업 전체를 위임하고 싶을 때 (광범위한 조사 등) → Agents. 메인 대화에 중간 과정이 쌓이지 않아 이야기가 꼬이기 어렵게 합니다. -
반드시 매번 수행해야 하는 작업 (포맷, 테스트 실행) → Hooks. AI에게 '해줘'라고 요청하는 것이 아니라, 시스템적으로 강제합니다.
한마디로 요약하면, 지시 파일은 '상식', Skills는 '매뉴얼', Agents는 '동료', Hooks는 '규칙'입니다.
프로젝트 루트 디렉토리에 두는 지시 파일에는 예를 들어 다음과 같은 내용을 작성할 수 있습니다 (가상의 프로젝트 예시).
# 이 프로젝트에 대하여
- 사내 근태 관리 시스템. 백엔드는 TypeScript, DB는 PostgreSQL.
# 규약
...
이는 신입사원에게 '우리 팀에서는 이렇게 하세요'라고 처음에 전달하는 내용과 같습니다. 이것만 있어도 매번 지시 사항을 훨씬 짧게 줄일 수 있습니다.
Skills는 절차서를 폴더에 모아두는 시스템입니다. 예를 들어 '단위 테스트 작성 방법'이라는 Skill이라면 다음과 같은 구조가 됩니다.
skills/
unit-test/
SKILL.md ← 언제 사용하며, 어떻게 작성해야 하는지에 대한 절차
...
SKILL.md의 맨 앞에는 '단위 테스트를 작성할 때 사용하는'과 같은 설명을 적어둡니다. AI는 이 설명을 보고, 테스트 작성이 필요할 때만 내부 내용을 읽어옵니다. 평소 대화에서는 읽히지 않기 때문에, 절차서를 많이 준비해도 방해가 되지 않습니다.
Hooks는 '파일을 수정하면 반드시 포매터(formatter)를 실행한다', '작업을 완료하기 전에 반드시 테스트를 실행한다'와 같은 처리를 시스템적으로 등록하는 것입니다.
지시 파일에 '수정 후에는 포맷해 주세요'라고 적어도, AI가 잊어버릴 때가 있습니다. Hooks라면 AI의 판단과 관계없이 반드시 실행됩니다. 설정 방법은 도구마다 다르므로, 사용 중인 도구의 공식 문서를 확인해야 합니다.
하네스는 도구를 만드는 사람만의 것이 아닙니다. 사용하는 쪽에서도 다음 순서대로 개선할 수 있습니다.
지시 파일에 규약을 작성한다. 코딩 규약이나 테스트 작성법, 해서는 안 되는 것을 적어둡니다. '시니어 엔지니어의 관점에서'라고 매번 입력하지 않아도, 전제가 전달되도록 할 수 있습니다. -
사양서를 Markdown으로 변환하여 리포지토리에 둔다. Word나 Excel보다 AI가 읽기 쉬운 Input이 됩니다. -
단위 테스트를 정비한다. 테스트가 있으면, AI가 자신의 변경 사항의 정확성을 스스로 확인할 수 있게 합니다. -
권한을 구분한다. 자동으로 처리해도 되는 것과 반드시 확인 과정을 거쳐야 하는 것을 결정합니다. -
같은 지적을 3회 반복했다면, 시스템화한다. 지시 파일에 적을지, Skill로 할지, Hooks로 할지를 고민해봅니다.
사소한 작업처럼 보일 수 있지만, 이곳을 정비할수록 AI는 더욱 믿음직한 작업자가 됩니다.
지시 파일에 모든 것을 기록하여 거대하게 만드는 것
알아낸 것을 전부 추가하다 보면 지시 파일은 금세 길어집니다. 매번 전체를 읽어야 하므로 부하가 커질 뿐만 아니라 중요한 규칙이 묻히게 됩니다. 가끔 사용되는 절차는 Skills로 옮기는 것이 좋습니다.
오래된 지침이 남아 모순되는 경우
규약(Rules)이 변경되었음에도 불구하고 지시 파일(Instruction File)을 수정하는 것을 잊으면 AI는 오래된 규칙을 따릅니다. 지시 파일 역시 코드와 마찬가지로, 변경 사항이 생겼다면 업데이트해야 한다고 생각해야 합니다.
권한을 너무 많이 부여하는 경우
승인 절차가 번거롭다고 해서 모든 것을 자동으로 허용하게 되면, 예상치 못한 조작이 발생했을 때 막을 수 없습니다. 삭제나 외부 전송 등 되돌릴 수 없는(Irreversible) 작업은 반드시 확인 과정을 거쳐야 합니다.
도구 및 연동을 너무 많이 추가하는 경우
MCP를 통해 외부 서비스를 많이 연결하면 편리해 보일 수 있습니다. 하지만 사용할 도구가 너무 많으면, AI가 어떤 것을 선택해야 할지 혼란스러워할 수도 있습니다. 우선 정말 필요한 것들만 사용하는 것이 좋습니다.
'AI의 정확도가 별로다'라고 느낀다면, 모델을 바꾸기 전에 하네스(Harness)를 재검토해 보세요.
사양서(Specification)를 Markdown화하거나 단위 테스트(Unit Test) 환경을 갖추는 것 역시 사실 AI를 위한 하네스 정비입니다. 인간에게 읽기 쉽고 검증하기 쉬운 환경은, AI에게도 작동하기 좋은 환경이 됩니다.
본 기사는 Zenn에도 게시되었습니다.
