클로드 코드 하네스 적용기
2026.10.06

하네스 엔지니어링으로 AI 코딩 최적화하기 (24기 CTO스터디 지식전달 세션을 들은 후)
하네스 엔지니어링은 AI에게 자유를 주되 정해진 범위 안에서 일하게 만드는 방법이에요. 클로드 코드(Claude Code)에서는 CLAUDE.md로 부탁하고 hook으로 강제해요. 강의에서 배운 것: 부탁과 강제를 같이 둔다
지피터스 24기 CTO 스터디에서 하네스 엔지니어링 강의를 들었어요. 하네스는 원래 말에 채우는 마구예요. 말을 묶어 두는 게 아니라 힘을 원하는 쪽으로 쓰게 하는 장치라는 설명이 기억에 남았어요.
핵심은 통제 장치를 두 종류로 나누는 거였어요.
추론적 센서는 CLAUDE.md처럼 모델이 읽고 따르는 규칙이고, 연산적 센서는 hook처럼 프로그램이 기계적으로 막는 장치예요.
둘은 실패하는 모양이 달라요. CLAUDE.md에 ".env를 고치지 마"라고 적어도 부탁이라서, 컨텍스트가 길어지면 넘어갈 수 있어요. 반대로 hook만 걸면 AI가 왜 막혔는지 몰라서 다른 명령으로 돌아가요. 그래서 규칙으로 이유를 알려 주고 hook으로 강제하는 조합이 필요하다는 거예요.
클로드 코드 설정 점검: hook 설정의 중요성
강의 다음 날 제 클로드 코드 설정 파일(~/.claude/settings.json)을 열어 봤어요. hook이 이벤트 14개에 걸려 있길래 꽤 해 둔 줄 알았어요.
알고 보니 전부 다른 앱이 넣어 둔 기록용이었어요. 작업 상태를 앱 화면에 보여 주려고 알림만 보내고, 앱이 꺼져 있어도 작업이 멈추지 않게 되어 있었어요. 차단 목록(permissions.deny)도 비어 있었어요.
저는 부탁(CLAUDE.md 행동지침)만 있고 강제는 하나도 없는 상태였어요. 규칙을 적어 두기만 하고, 어겨도 막을 장치는 없었던 거예요.
고양이 격투 게임으로 하네스 시험하기
하네스를 시험할 프로젝트가 필요했어요. 고양이 품종 캐릭터로 싸우는 2.5D 격투 게임을 만들어 보기로 결정한 후 하네스를 만들어보기로 했어요. 키보드 하나로 둘이 붙는 방식이고, 엔진은 고도(Godot) 4예요.
게임을 고른 이유가 있어요. 기술 수치나 할 일 목록처럼 AI가 함부로 덮어쓰면 안 되는 상태 파일이 생기고, 범위도 금방 커져요. 하네스가 막아야 할 문제가 다 나오는 프로젝트예요.
범위는 일부러 작게 잡았어요. 고양이 2종, 기술 3개씩, 로컬 2인용까지만요. 온라인 대전이나 콤보는 기본 공격이 재밌는지 확인한 뒤로 미뤘어요.
하네스 설치: 파일 구성과 역할
강의 1부의 기준대로 나눴어요. Markdown은 사람이 읽고 검토하고, JSON은 도구로만 바꿔요.
CLAUDE.md: 부탁이에요. 범위와 규칙마다 이유를 한 줄씩 붙였어요.
backlog.json: 할 일 7개와 상태예요. 정해진 명령으로만 바꿔요.
moves.json: 기술 수치예요. 바꾸려면 저한테 먼저 묻게 했어요.
hook 2개: 강제예요. 위 두 JSON을 직접 고치면 막고, 파일이 300줄을 넘으면 경고해요.
progress.md: 한 일, 막힌 것, 다음 할 일을 적어서 다음 세션이 이어받게 해요.

막는 hook은 AI가 backlog.json을 직접 고치려는 순간 작업을 멈추고 이유를 돌려줘요. "할 일 상태는 tools/set-status.py로 바꾸세요"라고요. 이유를 같이 주니까 AI가 다른 명령으로 돌아가지 않고 정해진 길을 써요.

AI가 만든 첫 하네스의 한계
첫 하네스는 AI가 파일을 전부 만들어 줬어요. 빨랐는데, 읽어 보니 제 판단이 들어간 문장이 거의 없었어요. 규칙은 그럴듯한데 왜 그 규칙인지 제가 설명을 못 하겠더라고요.
스터디에서도 같은 이야기가 나왔어요. CLAUDE.md는 사람이 직접 쓰고 AI에게는 교정만 맡기는 게 낫다고요. AI 초안은 읽기만 하면 "괜찮네" 하고 넘어가기 쉽고, 우리 프로젝트만의 규칙은 AI가 코드를 봐도 알 수가 없어요.
하나 더 걸린 데가 있었어요. Godot를 화면 없이 실행하는 명령이 메인 씬이 없으면 끝나지 않고 멈췄어요. 이건 progress.md에 적어 둬서 다음 세션이 같은 데서 헤매지 않았어요.
harness-setup 스킬로 AI 코딩 개선하기
순서를 뒤집은 클로드 코드 스킬을 만들었어요. 이름은 harness-setup이고, 어느 프로젝트에서나 불러 쓸 수 있어요.

스킬이 HUMAN.md 빈 양식을 깔고 멈춰요. 목표, 범위, 절대 규칙, 완료 기준은 제가 써요.
AI는 비었거나 애매한 칸만 하나씩 물어요. "깔끔하게" 같은 말도 여기서 걸러져요.
CLAUDE.md, backlog.json, hook을 만들고, 절대 규칙마다 hook으로 막을지 표시해요.
hook을 일부러 어겨 봐요. 막혀야 할 경우와 통과해야 할 경우를 검사해요.

업무에 활용하는 방법
새 프로젝트는 HUMAN.md부터 써요. 제가 쓴 문장이 AI 행동의 기준이 돼요.
"문서로만"으로 남긴 규칙은 hook 후보 목록이에요. 같은 실수가 두 번 나오면 그때 hook으로 올려요.
공통 행동지침은 상위 폴더 CLAUDE.md 하나에 두고, 프로젝트마다 다른 것만 프로젝트 폴더에 둬요.
클로드 코드 하네스 따라 하기
스킬이 없어도 클로드 코드에서 바로 해 볼 수 있어요.
프로젝트 폴더에 HUMAN.md를 만들고 목표, 범위, 절대 규칙, 완료 기준을 직접 적어요.
아래 요청을 보내요.
제안받은 hook을 넣고, 일부러 어겨서 정말 막히는지 확인해요.
HUMAN.md를 읽고, 비었거나 확인할 수 없는 칸만 하나씩 물어봐 줘. 내 문장은 고치지 마.
그다음 [절대 규칙]마다 hook으로 막을 수 있는지, 문서로만 둘지 목록으로 정리해 줘.
하네스로 규율을 잘 잡고 만든 게임과 저의 아이디어, 프로젝트를 다음번엔 공유드릴게요:)
가능하다면 하네스를 했을 때와 안했을 때 비교도 해보려고 합니다. 기대해주세요:)
로그인하고 댓글을 남겨 주세요
HUMAN.md 정말 좋은 아이디어네요. HUMAN.md를 만들고, 물어보게 하고, 이에 맞는 hook을 제안받고 선택한다.
좋은 접근 유용하게 챙깁니다. 👍 👍
재민님, 기록용 hook이 14개나 있는데 정작 차단 규칙은 없었다는 발견이 특히 인상 깊었어요.
Godot 격투 게임의 기술 수치와 할 일 목록을 직접 수정하지 못하게 막고, 막힌 이유와 정해진 변경 명령까지 돌려주는 설계가 ‘부탁’과 ‘강제’의 차이를 잘 보여주네요.
AI가 규칙을 먼저 쓰는 대신 HUMAN.md에 목표와 절대 규칙을 직접 적고, hook을 일부러 어겨 보며 확인한 과정도 따라 해볼 만해요.
고양이 격투 게임의 다음 실험도 기대할게요. 꼬리 탁! 치고 응원하고 갈게요 🐈⬛



HUMAN.md 라는 별도의 문서를 미리 써놓고 시작하는 거군요! 발표가 기대되네요. 많이 배우도록 하겠습니다.