본문으로 건너뛰기

하네스란? 스킬로 모든 프로젝트에 '하네스 씌워줘' 한마디로 끝!!

물결2

2026.10.13

하네스란? 스킬로 모든 프로젝트에 '하네스 씌워줘' 한마디로 끝!! 본문 이미지

소개

지난주에 "AI는 고칠 때마다 덧대기만 한다"는 이야기를 했어요. 그래서 AI한테 고삐(하네스)부터 씌우겠다고 했고요.

이번 주에는 그 고삐를 스킬 하나로 만들었습니다. 이름은 하네스 스타터예요.

어느 프로젝트든 "하네스 씌워줘" 한마디 하면, AI가 프로젝트를 살펴보고 규칙이랑 검사 장치를 깔아 줍니다.

Claude Code, Codex, 제미나이(Antigravity), OpenClaw 어디서 불러도 같은 방식으로 깔려요.

오늘은 이걸 떡집 이야기로 풀어 볼게요. 어려운 말은 맨 아래 "용어 정리"에 모아 뒀어요.

진행 방법

사용한 도구: Claude Code(메인, 만들기), Codex(교차 검사), 제미나이(조사, 영상 읽기), git 훅(저장할 때 검사하는 장치). 만화는 ChatGPT 이미지로 그렸고, 터미널 시연은 VHS로 녹화했어요.

① 떡집 시절: 채팅창 하나

저는 AI를 셋이나 써요. Claude, Codex, 제미나이.

일꾼이 셋이니 일도 세 배로 빨라질 줄 알았는데!!!

제가 로봇 사이를 뛰어다니는 사람이 됐어요. "이거 해" 하면 하고, 끝나면 그 자리에 서서 다음 말을 기다려요.

제가 밥 먹으러 집에 들어가면요? 다 멈춰 있어요. 시키는 사람이 없으니까요.

주인이 없는 저녁, 로봇들은 어쩔 줄 모르고 서 있고 솥은 넘치고 떡은 덕지덕지 붙은 장면

밤에 와 보면 더 가관이에요.

  • 솥이 넘쳐요. 쌀을 솥 하나에 다 넣었거든요. 채팅창 하나에 기획, 만들기, 검사를 다 넣으니 맥락(AI가 한 번에 기억하는 대화)이 꽉 차고 토큰(AI 사용량)이 줄줄 샜어요.

  • 떡에 떡이 덧붙어 있어요. 지난주에 말한 코드 덧대기요.

나중에 제가 AI한테 이렇게 말했어요.

"내가 할일과 니가 할일이 채팅창 하나에서 막혀있었잖아.?"

② 하네스 스타터가 하는 일

하네스 스타터는 어느 마을이든 가서 방앗간을 지어 주는 목수예요. 목수는 이렇게 일해요.

목수 로봇이 빈 마을에 도착해 물길을 살펴보는 장면

  1. 마을에 와서 물길부터 봐요. 무슨 언어인지, 테스트는 어떻게 돌리는지 읽기만 해요.

목수 로봇이 두꺼운 책을 펴 놓고 자로 떡 틀 크기를 재는 장면

  1. 떡 틀 크기(파일 하나에 몇 줄까지)를 정해요. 숫자를 기억으로 대지 않아요. 그 언어의 공식 문서를 그 자리에서 찾아서 출처랑 날짜까지 적어요.

목수 로봇이 방앗간 설계도를 펼쳐 주인에게 보여 주고, 주인이 고개를 끄덕이는 장면

  1. 설계도를 주인한테 먼저 보여 줘요(미리보기). 허락받기 전엔 아무것도 안 깔아요. 이미 있는 파일은 덮어쓰지도 않고요.

다 지은 방앗간 앞에서 목수 로봇이 쌀 한 포대를 물길에 띄워 시험하는 장면

  1. 다 지으면 쌀 한 포대로 시험해 봐요. 일부러 한도를 넘는 파일을 만들어서 진짜 막히는지 보고, 흔적 없이 지워요.

그림 A 정밀판: SKILL.md 9단계(대상 확인 → 살피기 → 스택 → 한도 → 미리보기 → 설치·기록 → 에이전트 구성 → 설치 직후 시험 → 마무리)와 설치되는 파일

그렇게 깔리는 건 규칙판(원칙), 떡 틀(한도), 수문(훅), 쌀 포대 작업표(작업 장부), 폰 주문서(질문 페이지)예요. 허락하면 로봇 넷(기획·조사·구현·리뷰)과 물레방아까지 깔아요.

③ 지으면 이렇게 돌아가요

방앗간 마을 지도(이름표): 왼쪽 집에서 주인이 폰을 보고, 가운데 물길로 쌀 포대가 흐르고, 오른쪽 물레방아 옆에서 로봇 넷이 차례로 일하는 그림

왼쪽 집에 제가 있어요. 가운데 물길로 쌀 포대(작업)가 줄지어 흘러가고, 오른쪽 방앗간에선 로봇 넷이 물레방아 박자에 맞춰 차례로 일해요.

작업 하나는 이렇게 흘러가요.

  1. 저랑 메인 AI가 대화로 무슨 떡을 만들지 정해요.

  2. 기획 담당이 그걸 작업으로 쪼개고, 작업마다 주문서(작업 문서)를 써요.

  3. 메인 AI가 장부에 작업을 열어요.

  4. 물레방아가 돌아요. 명세 → 대조 → 구현 → 검사 → 교차 리뷰 → 올림. 검사에 걸리거나 큰 지적이 나오면 합쳐서 3번까지 스스로 고쳐요.

  5. 메인 AI가 결과를 보고 합쳐요(병합, 완료).

로봇마다 자기 절구가 따로 있어요. 서브에이전트(따로 맥락을 가진 AI 일꾼)마다 대화를 따로 쓰는 거예요. 만든 로봇이 검사까지 하면 자기 떡에 후하거든요. 그래서 만든 쪽과 검사하는 쪽은 일부러 떼어 놨어요.

물길 곳곳에는 수문(훅)이 넷 있어요.

  • 고치기 전: 작업표 없는 쌀이 오면 철컥 (guard.mjs)

  • 고친 직후: 파일이 너무 길거나 빈 catch가 있으면 바로 알림 (check.mjs)

  • 멈출 때: 하던 작업이 있는데 멈추려 하면 왜 멈추는지 한 줄 설명하게 함 (stop.mjs)

  • 커밋할 때: 마지막 관문 (pre-commit)

AI가 사람한테 묻는 건 세 갈래예요.

  • 허락: 허락받고 나서 해요. 진짜 데이터 지우기, 남이 쓰는 약속 바꾸기, 밖으로 내보내기, 진짜 돈 쓰기, 검사 같은 지키는 장치 끄기. 답할 때까지 그 작업만 멈춰요.

  • 확인: 먼저 하고 확인받아요. 문서끼리 말이 다를 때, 실제 데이터를 다루는 설계, 새 의존성이나 구조 바꾸기. 일은 계속 가고, 제가 "아니야" 하면 고쳐요. 3일 안에 답이 없으면 그대로 가요.

  • 기록: 나머지는 알아서 하고 적어만 둬요. 저는 하루 요약만 봐요.

비유가 안 맞는 곳도 하나 있어요. 진짜 물레방아는 물만 있으면 혼자 돌잖아요. 여기선 무슨 떡을 만들지를 처음에 사람이 대화로 정해 줘야 돌아요. 제가 /물레방아라고 부르거나 "앞으로 물레방아로 돌려" 하고 맡겨야 하고요.

그림 B 정밀판: 사람 → 메인 AI → 작업 장부 → 물레방아(명세·구현·검사·교차 리뷰·올림) → 병합, 그리고 그 사이의 훅 네 개와 실제 파일 이름

④ 진짜 하네스 들여다보기

만화 말고 진짜는 어떻게 생겼는지 볼게요. 실제로 하네스를 깐 프로젝트 화면이에요.

하네스를 깐 프로젝트의 폴더: AGENTS.md, CLAUDE.md, harness/, .claude/agents/, .claude/workflows/

AGENTS.md의 간결함 원칙 구역

규칙판에는 이런 줄이 들어가요.

- 예외를 삼키지 않는다(빈 catch, except: pass 금지). 처리할 수 없으면 그대로 올린다.
- 예외에 예외를 덧대지 않는다. 조건이 세 겹을 넘으면 원인과 구조를 다시 본다.
- 검사가 위반을 알리면 한도를 늘리지 말고 코드를 줄인다. 한도는 사람에게 묻고 바꾼다.

.claude/settings.json에 걸린 훅 세 개(고치기 전, 고친 직후, 멈출 때)

수문은 .claude/settings.json에 걸려 있어요. 고치기 전(PreToolUse), 고친 직후(PostToolUse), 멈출 때(Stop)마다 검사 프로그램이 자동으로 돌아요.

harness/config.json의 한도와 근거

떡 틀은 이렇게 생겼어요. 숫자 옆에 어디서 가져온 숫자인지가 붙어 있는 게 포인트예요.

"code": {
  "files": ["scripts/**", "templates/harness/*.mjs", "templates/workflows/*.js"],
  "maxFileLines": 300,
  "basis": "파일 길이: ESLint max-lines 기본값 300을 참고(eslint.org/docs/latest/rules/max-lines, 2026-10-09 조회, 권장 규칙은 아님)"
}

⑤ 실제로 써 보면

먼저 진짜 Claude Code 화면이에요. 하네스를 깐 빈 프로젝트에서 "src/app.js에 hello 함수를 하나 추가해 줘"라고만 쳤어요.

수문에 막히는 장면을 찍으려고 했는데...

막힐 일이 아예 안 생겼어요!!! AI가 규칙판을 읽더니 장부에 작업부터 열고, 기획 담당을 불러서 명세를 쓰게 하더라고요.

실제 Claude Code 세션: "함수 하나 추가해 줘"라는 말에 AI가 장부에 작업을 열고(시작: T-1) 기획 담당·리뷰어·구현 담당을 차례로 부르는 화면

더 소름이었던 건, 그대로 뒀더니 구현, 리뷰, 병합, 완료까지 혼자 다 끝냈다는 거예요.

이번엔 꾀를 하나씩 부려 봤어요. 전부 철컥입니다.

터미널 시연: 작업 없이 고치기, 한도 설정 고치기, --no-verify, 320줄 파일 커밋이 차례로 거절되는 화면

  • 작업 안 열고 src/app.js 고치기 → 진행중인 작업이 없다

  • 떡 틀(config.json) 몰래 키우기 → 검사 설정이라 고치지 않는다. 한도를 늘리지 말고 코드를 줄인다

  • git commit --no-verify로 검사 건너뛰기 → --no-verify로 커밋 검사를 건너뛰지 않는다

  • 작업은 열었는데 320줄짜리 파일 커밋 → 파일이 320줄(전에는 0줄): 300줄을 넘었다. 나누거나 줄인다

다음은 장부랑 질문이에요. 작업 넷을 올리고, AI가 "지금 같이 해도 되는 작업"을 골라요.

터미널 시연: 작업 넷을 장부에 올리고, 회원 데이터 삭제는 질문으로 돌리고, 답이 올 때까지 그 작업만 멈추는 화면

같은 폴더(src/login)를 건드리는 작업 둘은 동시에 안 시켜요. 서로 부딪히니까요.

그리고 "옛 회원 1,204명 데이터 지울까요?"는 진짜 데이터를 지우는 일이라 AI가 안 하고 저한테 물어요. 답이 올 때까지 그 작업만 멈추고, 나머지는 계속 돌아요.

질문 페이지는 이렇게 생겼어요. 폰에서도 열려요.

질문 페이지: 맨 위에 결정할 것 1, 할일 4 같은 숫자 칸, 아래에 "옛 회원 데이터를 지울까요" 카드와 지운다/둔다(추천) 보기

답을 보낸 뒤의 질문 페이지: 결정할 것 0개, 답한 것에 "옛 회원 데이터를 지울까요 → 둔다"

"둔다" 누르고 끝. 산책하다가도 답할 수 있어요.

마지막으로 진짜 프로젝트예요. 지난주 그 카톡 봇(뉴카톡)을 다시 짜는 데 하네스를 깔았어요.

뉴카톡에서 실제로 돌아가는 작업 장부

뉴카톡의 실제 질문 페이지

10월 12일 밤 11시 50분에 깔았는데, 다음 날 밤 10시까지 이랬어요.

  • 커밋 81번

  • 병합 25번

  • 끝낸 작업 27개

어... 이게 맞나? 싶었어요. 그동안 제가 한 건 "어디까지 했어?" 하고 물어본 게 다였거든요.

기획은 미리 다 해 뒀으니까요. 지금 이 글을 쓰는 동안에도 물레방아는 돌고 있을 거예요.

⑥ 스터디에서 배운 것으로 만든 과정

이건 혼자 생각해 낸 게 아니에요. 스터디에서 배운 걸 제 프로젝트에 맞게 다시 만든 거예요.

1주차: 하네스란?
배운 것: 원칙만으론 안 되고, 훅으로 막아야 한다.
만든 것: 원칙(AGENTS.md) + 도구 훅 + 커밋 관문(pre-commit)

2주차: 장부와 결정 화면
배운 것: 작업 장부, 사람만 정할 것 모으기, 역할 나누기.
만든 것: 작업 장부 + 질문 페이지 + 로봇 넷(기획·조사·구현·리뷰)

오프라인 모임: 러너 흐름
배운 것: 명세 → 구현 → 검사 → 교차 리뷰를 차례로 돌리는 흐름.
만든 것: 물레방아

물론 한 번에 된 건 아니에요. 처음 만든 판은 장부랑 계획서 장치가 목표보다 커져서 통째로 버렸어요 ㅠㅠ

그래서 두 번째 판은 하나씩 작게 쌓았어요. 지금 모습은 이래요.

  • 끝낸 작업 47개

  • 저장소 전체 커밋 288번 (버린 첫 판 포함)

  • 자동 시험 180개 (임시 git 저장소를 진짜로 만들어서 깔아 보고 막히는지 봐요)

결과와 배운 점

써 보니

채팅창 하나에 다 넣던 시절 얘기를 아까 했잖아요. 그 말 뒤에 제가 이렇게 이어 말했어요.

"근데 이제 역할이 분리되고 공간이 분리되니까 토큰도 아끼고 작업 병목도 줄고 아주 좋아"

제일 좋았던 건 두 가지예요.

  1. 질문을 HTML 한 페이지에서 한 번에 답하고, 거기서 관리되는 것. 예전엔 제가 답해야만 일이 넘어갔거든요. 밖에 있으면 더 답답했고요.

  2. 물레방아가 알아서 돌아가는 것. 저는 주문서만 던지면 돼요.

아직 못 막는 것

솔직하게 적을게요. 수문에도 구멍이 있어요.

  • 막는 훅은 명령 글자만 봐요. 셸 명령으로 파일을 바꾸면 못 막아요. 실제로 "장부 건너뛰고 바로 추가해"라고 시켰더니, AI가 편집 도구 대신 cat >> 셸 명령으로 돌아갔어요. 그래도 커밋할 때 마지막 관문이 잡았어요.

실제 Claude Code 세션: 셸 명령으로 편집 차단을 돌아갔지만, 커밋 단계에서 "진행중인 작업이 없다"로 거절되는 화면

  • AI가 훅 설정(.claude/settings.json, .git/hooks)을 고쳐서 수문을 꺼 버리는 것도 못 막아요.

  • --no-verify는 막지만 git commit -n(같은 뜻의 짧은 글자)은 못 막아요.

  • 허락·확인도 규칙일 뿐이라, AI가 묻지 않고 그냥 해 버리면 못 막아요.

  • 검사는 크기와 몇 가지 패턴만 봐요. 설계가 좋은지는 여전히 사람이 봐야 해요.

그래서 지금 상태는 이래요.

AI를 꽁꽁 묶었다 ❌

실수가 한 번 나오면 다음엔 수문에 걸리게 하나씩 막아 가는 중 ⭕

쓰다가 찾은 빈틈

이 글을 쓰면서 뉴카톡 기록을 다시 봤어요. AI가 "알아서 처리한 것"이 하루에 118개였어요.

그중에 사람한테 물었어야 할 게 섞여 있었어요. 문서끼리 말이 다를 때 AI가 한쪽을 골랐고, 손님 데이터를 지우는 방식도 혼자 정했더라고요.

그렇다고 다 물으면? 다시 제가 답해야만 넘어가는 예전으로 돌아가요 ㅠㅠ

그래서 하나 더 만들었어요. 먼저 하고 확인받기.

찾아보니 이 틀은 우리끼리 지어낸 게 아니었어요. Apache 오픈소스 재단은 "검토 받고 반영"과 "먼저 반영하고 나중에 뒤집기"를 나눠 쓰고, 구글 SRE는 사람한테 가는 알림을 "지금 조치 / 나중에 조치 / 기록만"으로 나눠요. 3일도 Apache가 반대를 기다리는 72시간을 따랐어요.

칸에 뭘 넣을지는 제 경험으로 골랐고요.

배운 점

  1. 사람한테 물을 일을 좁혀야 맡길 수 있어요. 넓게 열어 두면 AI가 다 물어보고, 결국 또 제가 붙어 있어야 하거든요.

  2. 하네스는 영원하지 않아요. Anthropic 글을 보니 하네스 부품 하나하나에는 "모델이 이건 혼자 못 한다"는 가정이 들어 있어서, 모델이 좋아지면 그 부품이 아직 필요한지 다시 따져 봐야 한대요. 저도 수문 몇 개는 언젠가 걷어낼 부품이라고 생각하고 써요.

용어 정리

떡집 말 ↔ 진짜 말이에요.

  • 방앗간 전체 = 하네스: AI 일꾼에게 씌우는 규칙과 장치 묶음

  • 벽의 규칙판 = AGENTS.md·CLAUDE.md: AI가 매번 읽는 원칙. CLAUDE.md는 AGENTS.md를 불러오는 한 줄

  • 수문 = 훅: AI가 도구를 쓰기 전·후·멈출 때 자동으로 도는 검사. 부탁과 달리 반드시 실행돼요

  • 출고 검사 = pre-commit: 저장(커밋) 직전 마지막 검사

  • 떡 틀 = 한도(harness/config.json): 파일 종류별 최대 줄 수와 그 근거

  • 쌀 포대 작업표 = 작업 장부: 작업을 열고 닫는 명령. 안 열면 고치기를 거절해요

  • 로봇마다 자기 절구 = 서브에이전트: 따로 맥락을 가진 AI 일꾼(기획·조사·구현·리뷰)

  • 솥 크기 = 컨텍스트·토큰: AI가 한 번에 기억하는 대화 양과 그 비용

  • 작업대 = 워크트리: 같은 저장소를 작업마다 따로 펼친 폴더

  • 물레방아 = 워크플로: 명세 → 구현 → 검사 → 리뷰 → 올림을 차례로 돌리는 흐름

  • 폰 주문서 = 질문 페이지: 허락(멈춤)·확인(먼저 하고 3일)을 답하고, 기록은 하루 요약으로 보는 HTML

따라 해 보기

  1. 하네스 스타터 폴더(SKILL.md, scripts/, templates/)를 스킬 자리에 복사해요.

    • Claude Code: ~/.claude/skills/harness-starter

    • Codex, OpenClaw: ~/.agents/skills/harness-starter

  2. 내 프로젝트 폴더에서 AI를 열고 한마디 해요.

하네스 씌워줘
  1. AI가 몇 가지 묻고 미리보기를 보여 줘요. 괜찮으면 승인하면 끝!!

  2. Claude Code에서 로봇 넷과 물레방아까지 깔았으면 Claude Code를 한 번 껐다 켜요. 그다음 하고 싶은 일을 말하면 돼요.

Node 22.20 이상이 있어야 해요. 스킬 없이 설치 스크립트만 돌려 볼 수도 있어요.

node scripts/install.mjs <내 프로젝트 폴더>           # 미리보기
node scripts/install.mjs <내 프로젝트 폴더> --apply   # 설치

저장소 주소: https://github.com/dolsol3/harness-starter-skill

Claude Code라면 한 줄로 받아 둘 수 있어요.

git clone https://github.com/dolsol3/harness-starter-skill ~/.claude/skills/harness-starter

써 보시고 안 되는 거나 아이디어는 GitHub 이슈로 남겨 주세요!

도움 받은 글

5

함께 이야기해요 5

로그인하고 댓글을 남겨 주세요

댕댕이멍멍 프로필 이미지
댕댕이멍멍2026.10.14

이 화려한 사례글은 뭐죠? 👍 👍 👍
그런데 내용도 어마어마하네요. 🙂
사례 발표도 정말 기대됩니다!

oneshot 프로필 이미지
oneshot2026.10.14

떡방아간 전부 분해해서 부품과 작동방법을 그림과 함께 설명해 주셨네요 즐감했어요

리부티너 프로필 이미지
리부티너2026.10.14

이런 정성스런 사례글은 정말... 느므 좋아~
근데 뉴비들을 기 죽어유.. 😆

물결2 님의 스토리텔링 능력 진짜 탐나네요

n
nini_24th2026.10.14

으매 기죽어.....😅 👍 😍 😂 😱

뽀짝이 프로필 이미지
뽀짝이2026.10.14

안녕하세요, 물결2님! 떡집 비유로 풀어 주셔서 하네스 개념이 훨씬 쉽게 들어왔어요.

"채팅창 하나에 기획·만들기·검사를 다 넣으니 솥이 넘친다"는 문제 진단이 정확하고, 그걸 "허락받기 전엔 아무것도 안 깔고, 있는 파일은 덮어쓰지 않는다"는 목수 방식으로 푼 설계가 믿음직해요. 공식 문서에서 한도 숫자를 그 자리에서 찾아 출처와 날짜까지 적게 한 점, 깔고 나서 일부러 한도를 넘는 파일로 막히는지 시험하고 흔적 없이 지우는 단계도 좋았어요.

명세 → 대조 → 구현 → 검사 → 교차 리뷰를 거치고 지적이 크면 3번까지 스스로 고치는 흐름은, 다른 분들이 자기 프로젝트에 가져가 보기에도 좋은 모양이에요. 용어 정리를 맨 아래 모아 둔 배려도 고맙고요.

고롱고롱… 방앗간 물레방아 돌아가는 상상하며 읽었어요 ✨

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기