하네스 엔지니어링 — CLAUDE.md만 쓴다고 끝나지 않는다 (3대 구성요소)
하네스 엔지니어링 — CLAUDE.md만 쓴다고 끝나지 않는다 (3대 구성요소)
CLAUDE.md를 썼는데도 Claude가 같은 실수를 반복한다면, 그건 CLAUDE.md가 부족해서가 아니다. 하네스 엔지니어링이 부족해서다. CLAUDE.md는 하네스의 한 구성요소일 뿐이다. 안드레 카파시(전 OpenAI 창립 멤버, 전 Tesla AI 책임자)가 17분짜리 영상에서 정의한 이 개념의 핵심은 한 줄로 압축된다. “모델이 아닌 모든 것이 하네스다.”
요약: CLAUDE.md만으로는 Claude가 같은 실수를 반복한다. 하네스 엔지니어링은 컨텍스트 파일, 자동 강제 시스템, 가비지 컬렉션 3가지로 이뤄진다. 이 글은 카파시 프레임의 한국어 정리에 더해, 1인 운영자가 실제로 어떻게 굴리고 있는지 메커니즘 한두 개씩 보여준다. CLAUDE.md “어떻게 쓰나”는 이전 글에서 다뤘다.
이 글은 Claude Code를 매일 쓰면서 같은 실수를 반복하는 사람을 위해 썼다. 입문자라면 이전 글이 먼저다.
이런 적 있다면 이 글이 도움이 된다
- CLAUDE.md에 “console.log 금지”라고 썼는데 며칠 뒤 또 console.log가 박힌 코드를 받은 적이 있다.
- pre-commit이 없어서 타입 에러 그대로 push된 코드를 배포한 적이 있다.
- 에이전트가 만든 임시 함수와 미사용 import가 6개월째 쌓여 있는 코드를 본 적이 있다.
세 가지 모두 같은 원인이다. 부탁만 했고, 강제하지 않았다. 카파시는 영상에서 한 줄로 정리했다. “프롬프트 = 부탁, 하네스 = 강제.”
1. 컨텍스트 파일 — CLAUDE.md
CLAUDE.md는 매 세션 시작에 Claude가 항상 읽는 기준 문서다. 작성법은 별도 글에서 다뤘으니, 여기서는 운영 메커니즘 하나만 보여준다.
| 위치 | 적용 범위 | 용도 |
|---|---|---|
~/.claude/CLAUDE.md |
모든 프로젝트 | 개인 전역 규칙 |
프로젝트루트/CLAUDE.md |
해당 프로젝트만 | 프로젝트별 규칙 |
하위폴더/CLAUDE.md |
해당 폴더만 | 폴더별 규칙 |
내가 운영하는 글로벌 CLAUDE.md는 짧다. 짧을 수 있는 이유는 세부 규칙을 별도 파일로 분리하기 때문이다. 코딩 스타일, git 워크플로우, 검증 절차, fail-fast 룰, 보안 규칙을 각각 다른 파일로 두고 글로벌 CLAUDE.md에서는 @파일명(Claude Code의 import 문법)으로 참조만 한다.
이 분리가 중요한 이유는 우선순위 보존이다. 한 파일에 다 넣으면 Claude가 우선순위를 잃는다. 매뉴얼 100줄을 매 세션 처음에 읽으면 “전부 중요”가 되고, 그러면 “전부 안 중요”가 된다. 글로벌 CLAUDE.md는 항상 적용되는 톱레벨 규칙(예: “아첨 금지”)만 두고, 코딩 스타일처럼 작업 중에만 트리거되는 규칙은 분리해 필요할 때만 적용된다.
핵심: CLAUDE.md는 부탁이 아니라 기준이다. 그러나 부탁만으론 부족하다. 그래서 다음으로 자동 강제 시스템이 필요하다.
2. 자동 강제 시스템
CLAUDE.md에 “console.log 금지”라고 100번 써도 Claude는 까먹는다. 강제하려면 코드가 멈춰야 한다.
| 유형 | 예시 |
|---|---|
| 저장 전 훅 | pre-commit, pre-save |
| 게이트 | 타입 검사, 문법 검사, 테스트 |
| 권한 경계 | 도구 접근 범위 제한 |
| 자동 교정 루프 | 실패 시 자동으로 되돌려 고치기 |
핵심 철학은 “성공은 조용히, 실패만 크게 알리기”다. 모든 작업마다 알림이 오면 알림 자체가 노이즈가 된다. SRE(사이트 신뢰성 엔지니어링)에서 말하는 alert fatigue(알림 피로) 방지와 같은 원리다.
메커니즘 사례 — fail-fast 룰
자동 강제의 한 사례다. 내 글로벌 규칙 중에 fail-fast 룰이 있다. 박영록(한국 시니어 개발자, NDC 강연자, 2026-04-30 Threads 시리즈)의 비판을 흡수해 만들었다. 그의 한 줄은 이렇다. “에러가 날 만한 상황에서 에러가 나게 두라. 정확한 원인을 찾아 해결하라. fallback으로 에러를 가려서 다음 단계에 오류를 누적시키지 마라.”
이 룰이 트리거되는 패턴은 명시적이다.
try ... except안에pass또는 무명 default 반환 → 거부null/undefined검사 후 침묵 → 거부- 필수 값에
or 0,or {}같은 기본값 → 거부
이 패턴이 코드에 들어가면 룰에 걸려 멈춘다. Claude에게 “에러 가리지 마”라고 부탁한 게 아니라, 가리는 패턴 자체가 게이트에서 막히도록 만든 것이다. 부탁이 아니라 강제. 이 룰이 추가된 계기는 운영 환경 silent failure(조용한 실패) 사건이다. 외부 API 호출 실패를 try-except로 감췄고, 다음 단계가 잘못된 데이터로 진행했다. 실수 1건이 새 규칙 1건이 됐다.
3. 가비지 컬렉션
에이전트가 만든 나쁜 패턴은 누적된다. 미사용 import, 임시 함수, 문서-코드 불일치, 규칙 위반. 주기적으로 청소하지 않으면 6개월 뒤 코드베이스가 무너진다.
주기 점검 항목.
- 문서-코드 불일치
- 규칙 위반
- 미사용 코드
- 테스트 커버리지 틈새
나도 이 부분은 미완성이다. 자동화는 부분적이고(미사용 import linter는 돌지만), 정기 청소는 우선순위에 밀려 간헐적으로 수동으로 한다. 왜 미완성인지도 분석해봤다. 가비지는 “오늘 안 해도 죽지 않는” 일이라 항상 더 급한 작업에 밀린다. 자동화하려면 알림 자체가 강제력 있어야 하는데, 그 알림이 또 alert fatigue 문제로 돌아온다. 결국 처음 문제로 돌아오는 순환이다.
이 정직함이 중요한 이유는 두 가지다. 하나, 3번을 못 갖추고도 1, 2번만 잘하면 체감상 효과의 대부분은 나온다. 둘, “완벽한 시스템”을 권하는 글이 아니라 “어디까지 갖춰지면 어떤 효과가 나는지”의 솔직한 매핑이 더 유용하다.
실수 1건 = 새 규칙 1건
하네스의 가장 강력한 속성은 학습한다는 점이다. 실수가 발생하면 그 실수를 방지하는 규칙을 하네스에 추가한다. 시간이 지날수록 보호막이 두꺼워진다.
내 사례 둘.
- try-except로 에러를 가렸다가 운영 환경에서 silent failure가 났다. 그 후 fail-fast 룰을 글로벌 규칙에 추가. 이제는 같은 패턴이 코드에 들어오면 룰에 걸린다.
git stash --include-untracked path사용 시 stash가 비고 untracked 파일이 사라지는 사건이 났다. 그 후 “stash 후 항상git stash show로 검증” 메모리를 추가. 이제는 stash 시 자동으로 검증 단계가 돈다.
다만 이 원칙은 함정이기도 하다. 규칙을 무한정 추가하면 끝이 없다. 카파시도 같은 경고를 했다. “아이디어가 모호하면 하네스부터 만들지 말고 결과물을 먼저 만들라.” 입력 품질이 상위 제약이다. 하네스가 좋아도 입력이 나쁘면 결과는 나쁘다.
1인 운영자가 굴리는 본질
3가지를 다 갖추고 굴려본 본질은 한 줄로 정리된다.
“실수 1건이 새 규칙 1건이 되도록 시스템을 짜라. 그 시스템을 매번 다듬어라.”
CLAUDE.md만 쓰는 사람은 부탁만 한다. pre-commit만 쓰는 사람은 강제만 한다. 가비지 컬렉션만 하는 사람은 청소만 한다. 셋이 맞물려야 하네스는 학습하는 시스템이 된다.
지금 시작하려면 CLAUDE.md를 한 줄 더 쓰면 된다. 오늘 Claude가 또 까먹은 규칙 한 줄. 남은 디테일은 아래 FAQ에서 다룬다.
자주 묻는 질문
CLAUDE.md만 잘 써도 충분하지 않나?
충분하지 않다. CLAUDE.md는 컨텍스트 파일 하나일 뿐이다. 자동 강제 시스템과 가비지 컬렉션이 빠지면 Claude는 결국 같은 실수를 반복한다. 단 1, 2만 갖춰도 체감상 효과의 대부분은 나온다.
하네스 엔지니어링은 누가 만든 개념인가?
안드레 카파시가 17분짜리 영상에서 정의했다. 모델이 아닌 모든 것(문서, 도구 연결, 실행 훅, 검증 루프)을 하네스라고 부른다. 모델 자체가 아니라 외부 설계가 성능과 안정성을 좌우한다는 관점이다.
모델이 발전하면 외부 하네스는 필요 없어지나?
장기적으론 비중이 줄 수 있다. 모델이 컨텍스트 부패와 권한 경계를 안에서 해결하면 외부 하네스의 역할은 줄어든다. 그러면 이 글은 시한부 자산이다. 다만 지금은 ROI 격차가 압도적으로 하네스 쪽이다. 모델 세대 간 호출당 비용은 수 배 단위로 오를 수 있지만, CLAUDE.md 100줄 작성은 30분이면 끝난다. 이 격차가 좁혀지기 전까지는 갖추는 게 합리적이다.
어디서부터 시작해야 하나?
처음부터 완벽하게 만들지 마라. 가장 자주 까먹는 규칙 한 줄을 CLAUDE.md에, 가장 자주 잘못 push하는 패턴 한 개를 pre-commit에 넣는다. 실패 사례가 생길 때마다 한 줄씩 보강한다. 입력이 모호하면 하네스부터 만들지 말고 결과물을 먼저 만든다.
관련 글
마지막 업데이트: 2026-05-03
작성자: cd4761 — 블로그 자동화와 AI 에이전트 운영을 1인으로 굴리며 배운 것을 기록한다.
태그: #하네스엔지니어링 #ClaudeCode #CLAUDEmd #AI에이전트 #카파시 #프롬프트엔지니어링
댓글
댓글 쓰기