클로드코드 하네스 뜻, 쉽게 작성하는 팁

클로드코드를 매일 쓰면서 여러 사이트를 만들고 있는데, 어느 순간부터 유튜브나 커뮤니티에서 "하네스"라는 단어가 자꾸 보이기 시작했습니다. 처음에는 무슨 말인지 몰라서 그냥 넘겼습니다. 하네스 설정 없이도 클로드코드는 잘 돌아갔으니까요. 그런데 개념을 알고 나서 직접 적용해보니, 왜 다들 하네스 이야기를 하는지 이해가 됐습니다. 이 글에서는 하네스가 무엇인지, 그리고 제가 실제로 어떻게 쉽게 작성했는지 경험 그대로 정리합니다.

하네스 뜻

하네스(Harness)를 한 줄로 정리하면 이렇습니다.

에이전트 = 모델 + 하네스. 모델이 아닌 것은 전부 하네스다.

하네스는 원래 말이 마차를 끌 수 있게 해주는 마구(가죽끈 세트)를 뜻합니다. AI 모델은 그 자체로는 코드를 작성하는 두뇌일 뿐입니다. 그 두뇌가 실제로 내 프로젝트의 파일을 읽고, 명령을 실행하고, 결과를 확인해서 다음 작업에 반영하게 만들어주는 모든 설정과 규칙이 바로 하네스입니다.

클로드코드 기준으로 하네스에 해당하는 것들을 정리하면 다음과 같습니다.

구성 요소	역할
CLAUDE.md	프로젝트 규칙과 맥락을 알려주는 문서
Skills	반복 작업의 절차를 문서화
Subagents	탐색, 구현, 검증 등 역할 분리
Hooks	테스트, 린트 등 필수 확인 자동화
Permissions	허용 도구와 권한 제어

이 중에서 가장 기본이 되는 것이 CLAUDE.md입니다. 처음이라면 이것 하나만 제대로 만들어도 충분합니다.

하네스가 왜 필요한가

같은 모델을 써도 하네스에 따라 결과물 차이가 큽니다. 코딩 에이전트 벤치마크에서도 모델은 그대로인데 기본 설정과 커스텀 하네스의 점수 차이가 무시할 수 없을 정도로 크게 나왔다는 결과가 있습니다. 흥미로운 점은 과제 난이도가 높을수록 하네스의 효과가 커진다는 것입니다. 간단한 작업은 하네스 없이도 잘 되지만, 프로젝트가 커지고 작업이 복잡해질수록 차이가 벌어집니다.

제 경험도 비슷했습니다. 하네스 없이 쓸 때는 매번 같은 규칙을 반복해서 설명해야 했습니다. 코드 스타일, 배포 방식, 건드리면 안 되는 파일 같은 것들을 세션마다 다시 알려주는 게 은근히 피곤했습니다. 하네스는 이걸 한 번 정리해두면 모든 세션에 자동으로 적용되는 구조입니다.

문제는 "막상 쓰려니 뭘 써야 할지 모른다"

개념을 이해한 뒤 CLAUDE.md를 직접 작성하려고 에디터를 열었는데, 빈 화면 앞에서 막혔습니다. 다른 사람들이 공유한 템플릿을 봐도 제 프로젝트와는 상황이 달라서 그대로 쓰기 애매했습니다. 규칙을 뭐라고 적어야 할지, 어디까지 적어야 할지 감이 안 왔습니다.

아마 하네스를 처음 접하는 분들 대부분이 여기서 막힐 겁니다.

해결법: 클로드코드에게 작성시키기

고민하다가 발상을 바꿨습니다. 내가 쓰는 게 아니라, 클로드코드에게 시키면 되지 않을까.

실제로 사용한 요청은 이런 식이었습니다.

※ "그동안 우리가 작업했던 내용과 내가 너에게 반복해서 강조했던 규칙들을 기반으로, 이 프로젝트의 CLAUDE.md 하네스를 작성해줘."

결과물이 생각보다 괜찮았습니다. 클로드코드는 이미 저와의 작업 이력을 통해 제가 어떤 스타일을 선호하는지, 어떤 지시를 반복했는지 알고 있습니다. 그걸 기반으로 작성하니 남의 템플릿을 베낀 것이 아니라 제 실제 작업 패턴에서 나온 하네스가 만들어졌습니다. 이론적으로 완벽한 하네스보다 이런 게 실전에서 더 잘 작동합니다.

하네스는 한 번에 완성하는 게 아니다

한 가지 더 중요한 포인트가 있습니다. 하네스는 한 번 만들고 끝이 아니라, 코드처럼 계속 다듬어야 합니다.

처음에 잘 작동하던 설정도 프로젝트가 커지거나 새로운 유형의 작업을 시키면 어긋나는 부분이 생깁니다. 그럴 때마다 저는 그냥 대화로 해결합니다. "이런 실수가 반복되니까 하네스에 규칙으로 추가해줘", "이 부분은 앞으로 이렇게 처리하도록 반영해줘" 정도면 충분합니다. 문제가 생길 때마다 대화로 수정하는 루프 자체가 하네스 관리입니다.