클로드코드 하네스 뜻, 쉽게 작성하는 팁
Claude Code 하네스의 의미와 반복되는 실수를 줄이는 프로젝트 규칙, 작업 절차를 쉽게 구성하는 방법을 설명합니다.
클로드코드를 매일 쓰면서 여러 사이트를 만들고 있는데, 어느 순간부터 유튜브나 커뮤니티에서 “하네스”라는 단어가 자꾸 보이기 시작했습니다. 처음에는 무슨 말인지 몰라서 그냥 넘겼습니다. 하네스 설정 없이도 클로드코드는 잘 돌아갔으니까요. 그런데 개념을 알고 나서 직접 적용해보니, 왜 다들 하네스 이야기를 하는지 이해가 됐습니다. 이 글에서는 하네스가 무엇인지, 그리고 제가 실제로 어떻게 쉽게 작성했는지 경험 그대로 정리합니다.
하네스 뜻
하네스(Harness)를 한 줄로 정리하면 이렇습니다.
모델이 실제 작업을 수행하도록 둘러싼 도구, 규칙과 실행 환경을 묶어 부르는 말이라고 이해했습니다.
하네스는 Claude Code 설정 화면의 단일 공식 기능 이름이라기보다 에이전트 주변 체계를 설명할 때 넓게 쓰이는 표현입니다. 그래서 사람마다 포함하는 범위가 다를 수 있습니다. 이 글에서는 프로젝트 지침, 도구 권한, 반복 절차와 자동 검사를 합친 작업 환경이라는 뜻으로 사용합니다.
클로드코드 기준으로 하네스에 해당하는 것들을 정리하면 다음과 같습니다.
| 구성 요소 | 역할 |
|---|---|
| CLAUDE.md | 프로젝트 규칙과 맥락을 알려주는 문서 |
| Skills | 반복 작업의 절차를 문서화 |
| Subagents | 탐색, 구현, 검증 등 역할 분리 |
| Hooks | 테스트, 린트 등 필수 확인 자동화 |
| Permissions | 허용 도구와 권한 제어 |
이 중에서 가장 기본이 되는 것이 CLAUDE.md입니다. 처음이라면 이것 하나만 제대로 만들어도 충분합니다.
하네스가 왜 필요한가
같은 모델을 사용해도 제공한 맥락과 허용된 도구에 따라 결과가 달라질 수 있습니다. 다만 특정 하네스가 항상 성능을 높인다거나 복잡한 작업일수록 일정한 비율로 효과가 커진다고 일반화할 근거는 확인하지 못했습니다. 제가 직접 체감한 효과는 반복 설명과 실수를 줄이는 데 있었습니다.
제 경험도 비슷했습니다. 하네스 없이 쓸 때는 매번 같은 규칙을 반복해서 설명해야 했습니다. 코드 스타일, 배포 방식, 건드리면 안 되는 파일 같은 것들을 세션마다 다시 알려주는 게 은근히 피곤했습니다. 하네스는 이걸 한 번 정리해두면 모든 세션에 자동으로 적용되는 구조입니다.
문제는 “막상 쓰려니 뭘 써야 할지 모른다”
개념을 이해한 뒤 CLAUDE.md를 직접 작성하려고 에디터를 열었는데, 빈 화면 앞에서 막혔습니다. 다른 사람들이 공유한 템플릿을 봐도 제 프로젝트와는 상황이 달라서 그대로 쓰기 애매했습니다. 규칙을 뭐라고 적어야 할지, 어디까지 적어야 할지 감이 안 왔습니다.
아마 하네스를 처음 접하는 분들 대부분이 여기서 막힐 겁니다.
해결법: 클로드코드에게 작성시키기
고민하다가 발상을 바꿨습니다. 내가 쓰는 게 아니라, 클로드코드에게 시키면 되지 않을까.
실제로 사용한 요청은 이런 식이었습니다.
※ “현재 프로젝트 구조와 기존 문서를 먼저 확인하고, 내가 아래에 적은 반복 규칙을 바탕으로 CLAUDE.md 초안을 작성해줘. 추측한 규칙은 별도로 표시해줘.”
결과물이 생각보다 괜찮았습니다. 다만 Claude Code가 과거의 모든 작업과 선호를 자동으로 기억한다고 가정하면 안 됩니다. 현재 대화에 없는 규칙은 직접 제공하고, 프로젝트 파일에서 확인할 수 없는 내용은 추측하지 말라고 요청했습니다. 이렇게 만들면 남의 템플릿을 복사하는 것보다 현재 프로젝트에서 실제로 필요한 규칙에 가까운 초안을 얻을 수 있습니다.
하네스는 한 번에 완성하는 게 아니다
한 가지 더 중요한 포인트가 있습니다. 하네스는 한 번 만들고 끝이 아니라, 코드처럼 계속 다듬어야 합니다.
처음에 잘 작동하던 설정도 프로젝트가 커지거나 새로운 유형의 작업을 시키면 어긋나는 부분이 생깁니다. 그럴 때마다 저는 그냥 대화로 해결합니다. “이런 실수가 반복되니까 하네스에 규칙으로 추가해줘”, “이 부분은 앞으로 이렇게 처리하도록 반영해줘” 정도면 충분합니다. 문제가 생길 때마다 대화로 수정하는 루프 자체가 하네스 관리입니다.
정리
- 하네스는 모델을 감싸는 모든 설정과 규칙입니다. 시작은 CLAUDE.md 하나면 됩니다.
- 빈 파일 앞에서 고민하지 말고, 클로드코드에게 그동안의 작업과 규칙을 기반으로 작성해달라고 요청해 보세요.
- 완성형은 없습니다. 쓰면서 대화로 계속 고쳐나가면 됩니다.
하네스를 너무 어렵게 생각할 필요 없습니다. 결국 클로드코드와 대화하면서 자연스럽게 쌓아가는 것이 가장 현실적인 방법입니다.
처음에는 긴 문서보다 다음 네 가지만 적어도 충분했습니다.
- 프로젝트의 목적과 중요한 경로
- 실행해야 할 빌드·테스트 명령
- 수정하면 안 되는 파일이나 서비스
- 작업 완료 전에 확인할 체크리스트
규칙이 너무 많거나 서로 충돌하면 오히려 중요한 지시를 놓칠 수 있습니다. 실제로 반복되는 문제만 추가하고 더 이상 필요하지 않은 규칙은 지우는 편이 관리하기 쉽습니다.
참고한 공식 문서