Claude Code 하네스란? 같은 AI의 결과를 바꾸는 6가지 구성요소와 배치법

Claude Code 하네스는 모델이 실제 업무를 해낼 수 있도록 프로젝트 맥락, 지침, 도구 실행, 검증 흐름을 엮어 두는 체계입니다. 같은 Claude 모델이라도 어떤 정보를 받는지, 어떤 절차로 일하는지, 결과를 어떻게 확인하는지에 따라 산출물이 달라질 수 있어요.

그래서 저는 모델에 전달되지 않은 업무 조건부터 찾아보라고 권합니다.

예를 들어 모델이 프로젝트의 테스트 명령을 모르는 문제와 검토 순서를 빠뜨리는 문제는 겉으로는 비슷해 보여도 고칠 위치가 다릅니다. 앞의 것은 맥락이 빠진 경우이고, 뒤의 것은 절차가 빠진 경우예요. 이 둘을 처음부터 나눠 두면 지침이 늘어나도 어디에 무엇이 있는지 관리하기가 훨씬 수월합니다.

여섯 구성요소, 각각 어디에 무엇을 두나

배치 기준은 두 가지면 충분합니다. 정보가 어디까지 적용되는지, 그리고 언제 쓰이는지예요. 모든 작업에 필요한 맥락인지, 특정 파일에만 해당하는 규칙인지, 필요할 때만 꺼내 쓰는 절차인지를 먼저 가르면 자리가 정해집니다. 아래 여섯 가지는 업무 지식을 어디에 둘지 이해하기 위한 분류이고, 공식 제품 구조 전체를 뜻하지는 않습니다.

이 중에서 가장 많이 헷갈리는 건 Skills와 Commands의 관계입니다. 현재 사용자 정의 Commands는 Skills에 통합됐고, Skill도 /이름으로 호출할 수 있어요. 기존 Commands 파일도 계속 작동하니 둘을 굳이 따로 만들 필요는 없습니다. 호출 방식과 설정은 공식 Skills 문서에서 확인할 수 있어요.

Rules는 paths를 지정하면 일치하는 파일을 다룰 때만 적용되고, 지정하지 않으면 조건 없이 로드됩니다. 공통 맥락과 파일별 규칙을 어떻게 나눌지는 공식 메모리 문서를 참고하세요.

API 변경 업무라면 이렇게 나눠 봅니다

API 변경 업무를 예로 들어 볼게요. 프로젝트의 테스트 명령은 CLAUDE.md에 두고, API 파일에 적용할 입력 검증과 오류 응답 기준은 Rules에 적습니다. 변경 범위 확인에서 테스트, 결과 보고까지 이어지는 검토 순서는 Skill로 묶어 슬래시 명령으로 부를 수 있게 만들어 두세요. 따로 떼어 검토해야 하는 부분은 Subagent에 맡기고, 파일을 수정한 뒤 포매터를 돌리는 일은 Hook에 연결하면 됩니다.

같은 업무를 돕는 지침이라도 필요해지는 시점은 제각각입니다.

테스트 명령은 작업 내내 참고하는 공통 정보지만, 검토 순서는 그 절차를 밟을 때만 쓰여요. 이걸 전부 CLAUDE.md에 몰아넣으면 지금 작업과 상관없는 지침까지 매번 읽히고, 그만큼 맥락 사용량이 늘어납니다. 그래서 "이게 모든 작업에 필요한가"를 먼저 묻고, 적용 범위가 좁은 내용부터 바깥으로 빼내는 편이 낫다고 봅니다.

도입 순서는 반복해서 생기는 실패에서 출발하세요. 공통 맥락이 빠져서 생기는 문제를 먼저 고치고, 자주 빠뜨리는 절차를 Skill로 정리한 다음, 자동 검증을 붙이는 흐름입니다. Subagent는 실제로 떼어 낼 조사나 검토 업무가 생겼을 때 들이는 게 좋아요. 그래야 역할과 완료 조건을 구체적으로 정할 수 있습니다.

"테스트하라고 적었다"와 "테스트가 통과했다"는 다릅니다

Rules에 "반드시 테스트"라고 적으면 모델이 참고할 행동 기준이 하나 생깁니다. 반면 Hook은 설정한 이벤트가 일어났을 때 처리기를 실행하는 장치예요. 여기서 Hook이 실행됐는지, 테스트가 실행됐는지, 테스트가 통과했는지는 서로 다른 질문이라 하나씩 따로 확인해야 합니다. 실패했을 때 작업을 막을지, 결과를 넘기고 수정을 이어 갈지도 미리 정해 두세요. 차단이 필요하다면 그 이벤트와 처리 방식이 차단을 지원하는지 공식 Hooks 문서에서 확인해야 합니다.

완료 조건은 구체적일수록 좋습니다. "API를 잘 만들어 주세요"라는 요청은 "입력 검증 기준을 충족하고, 정해진 오류 응답을 반환하며, 관련 테스트 결과를 제시해 주세요"처럼 풀어 쓸 수 있어요. 이렇게 쓰면 무엇을 구현해야 하는지와 무엇을 증거로 검토할지가 함께 분명해집니다. 테스트를 돌리지 못한 항목이 있다면 그 이유와 함께 미해결 항목으로 남기라고 요구해 두세요.

최종 검토에서 먼저 볼 것은 별도 평가자의 동의가 아니라 실제 테스트 결과와 미해결 항목입니다. 평가자를 분리해도 판단 기준이 흐릿하면 검토는 느슨해질 수 있거든요. 통과 기준은 사람이 먼저 정하고, 실행 결과와 재현 방법이 그 기준을 실제로 뒷받침하는지를 살펴야 합니다.