AI 활용

클로드 코드 하네스란? 규칙 파일부터 쉽게 시작하기

목차 보기

하네스(harness)는 AI가 일을 하도록 둘러싼 규칙·도구·실행 환경을 묶어 부르는 말입니다. Claude Code의 설정 버튼 하나를 뜻하지는 않습니다. 처음에는 복잡한 도구를 모두 설정하기보다, 프로젝트의 작업 규칙을 파일로 적는 것부터 시작할 수 있습니다.

예를 들어 “홈페이지 제목을 고쳐줘”라는 요청에 “다른 페이지는 건드리지 않고, 수정 뒤 화면을 확인한다”는 규칙을 함께 주는 것입니다. 모델은 일을 하는 AI이고, 하네스는 그 AI가 어떤 자료와 도구로 어디까지 일할지를 정한 환경에 가깝습니다.

어떤 것이 하네스에 들어갈까

이 글에서는 다음 요소를 포함한 작업 환경이라는 뜻으로 사용합니다. 포함 범위는 사용하는 도구와 문맥에 따라 달라질 수 있습니다.

요소 쉬운 설명
프로젝트 지침 작업할 때 참고하는 목적·규칙·완료 조건
도구와 권한 파일 읽기·수정·명령 실행을 어디까지 허용할지
반복 절차 비슷한 작업을 매번 같은 순서로 처리하는 방법
자동 검사 수정 결과가 정해진 조건을 만족하는지 확인하는 장치

규칙을 늘리면 무조건 성능이 좋아지는 것은 아닙니다. 핵심은 매번 같은 설명을 반복하지 않고, 원하는 결과를 확인할 기준을 남기는 것입니다.

외부 서비스의 자료나 기능을 연결할 때는 MCP라는 말을 만날 수 있습니다. 규칙 파일과 도구 연결의 역할이 어떻게 다른지, 내 작업에 연결이 필요한지는 MCP 뜻과 필요성에서 짧은 예시로 설명합니다.

CLAUDE.md와 AGENTS.md는 무엇인가

둘 다 AI에게 프로젝트의 작업 지침을 전달하는 문서 파일입니다. 파일 이름을 외우기보다 “이 프로젝트에서 일할 때 먼저 읽을 안내문”이라고 이해하면 됩니다.

Claude Code는 CLAUDE.md를 프로젝트 지침으로 읽습니다. 최신 버전은 AGENTS.md도 지원하지만, 기본 설정에서는 작업 폴더나 상위 폴더에 CLAUDE.md 계열 파일이 없을 때 읽습니다. 직접 지원은 v2.1.277 이상이며 설정과 세션에 따라 달라질 수 있습니다. AGENTS.md를 공유하려면 CLAUDE.md에 @AGENTS.md로 가져오는 방법도 있습니다. 공식 지침 파일 안내 (2026년 10월 9일 확인)

규칙이 적용됐는지 확실하지 않다면 어떤 파일을 읽었는지 먼저 확인합니다. 파일을 만들었다는 사실만으로 항상 같은 내용이 적용된다고 가정하지 않습니다.

처음 적을 네 가지

항목 적을 내용의 예
목적 AI 소식을 쉽게 설명하는 매거진
검사 방법 글을 고친 뒤 사이트 빌드와 링크 확인
수정 범위 이번에 요청한 글만 수정, 기존 주소 유지
완료 조건 어려운 용어 설명, 출처 확인, 화면 확인

다음은 실제 minml 지침을 그대로 옮긴 것이 아니라, 글 수정 프로젝트를 위한 짧은 작성 예시입니다.

# 프로젝트 작업 규칙

- 일반 독자가 이해할 수 있는 말로 AI를 설명한다.
- 요청한 글만 수정하고 기존 글 주소를 유지한다.
- 바뀌는 가격과 기능은 공식 자료로 확인한다.
- 완료 전에 빌드, 링크, 실제 화면을 확인한다.

이 문서만으로 모든 검사를 자동 실행하거나 모든 실수를 막지는 못합니다. 지침은 AI가 참고하는 맥락이며 강제로 적용되는 설정은 아닙니다. CLAUDE.md의 동작과 한계

초안은 AI에게 요청해도 됩니다

빈 파일에서 막힌다면 프로젝트를 먼저 읽고 규칙 초안을 만들도록 요청할 수 있습니다.

프로젝트 구조와 기존 문서를 먼저 확인해줘. 아래에 적은 반복 규칙을 바탕으로 CLAUDE.md 초안을 만들고, 파일에서 확인할 수 없는 조건은 질문으로 남겨줘.

이때 반복 규칙은 직접 알려줍니다. “예전처럼 해줘”만으로는 어떤 조건이 필요한지 분명하지 않습니다. 자동 메모리에 무엇이 저장돼 있는지도 확인하지 않았다면 과거의 모든 요청이 이어진다고 가정하기 어렵습니다.

초안에서는 실제 명령이 맞는지, 요청 범위보다 넓은 권한을 주지 않는지, 서로 충돌하는 규칙이 없는지를 봅니다. 다른 사람의 긴 템플릿보다 현재 프로젝트에서 반복되는 조건을 짧게 적는 편이 검토하기 쉽습니다.

꼭 지켜야 할 조건은 검사로 남기기

“수정 뒤 확인한다”는 문장과, 틀린 결과를 실제로 찾아내는 검사는 역할이 다릅니다. 글 주소가 깨지면 실패하게 하는 링크 검사를 두면 AI가 설명을 잘했는지와 별개로 문제를 찾을 수 있습니다.

minml에서도 배포 파일 권한 문제를 겪은 뒤 지침에 확인 조건을 추가하고, 같은 조건을 배포 스크립트의 검사로 옮겼습니다. 중요한 조건을 매번 AI의 판단에만 맡기지 않기 위해서였습니다.

규칙 파일에는 무엇을 지킬지를 적고, 검사에는 어떻게 실패를 찾을지를 구현합니다. 정답을 명확히 판정할 수 있는 조건부터 옮기면 됩니다.

규칙이 길어지면 정리할 시점

필요한 규칙이 쌓이면 역할별 문서로 나누고 작업에 필요한 자료를 연결합니다. 중요한 조건을 찾기 어려울 정도로 길어졌다면 같은 뜻의 규칙, 더 이상 사용하지 않는 절차, 서로 충돌하는 지시를 먼저 정리합니다.

프로젝트 전체의 공통 규칙과 특정 작업에서 반복하는 절차도 나눠봅니다. 회의 정리처럼 일정한 순서와 양식을 재사용할 때는 클로드 스킬의 뜻에서 일반 요청·프로젝트 지침과의 차이를 비교할 수 있습니다.

규칙을 잘 만드는 목표는 AI에게 읽힐 문서를 많이 만드는 것이 아니라 같은 설명과 실수를 줄이는 것입니다. 파일을 둔 뒤 실제 요청과 결과를 확인하는 순서는 클로드 코드 사용방법에서 이어집니다.

공식 자료

2026년 10월 9일 확인