AI 바이브코딩 하네스 프레임워크란? Claude Code 토큰 아끼는 가난한 하네스

바이브코딩이 커지면 생기는 문제

AI 에이전트에게 “앱 만들어 줘”라고 한 번에 맡기면 처음에는 빠르게 진행됩니다. 그런데 대화가 길어질수록 에이전트는 앞에서 정한 규칙을 잊고, 폴더 구조를 제멋대로 바꾸고, 테스트 없이 코드를 쌓기 시작합니다. 한 세션의 맥락(context)에 이전 시행착오가 계속 쌓이면서 판단이 흐려지는 것도 원인입니다.

하네스 프레임워크란?

하네스(harness, 말의 마구)는 에이전트가 정해진 길로만 가게 묶어 두는 장치입니다. 프롬프트를 잘 쓰는 기술이 아니라, 에이전트가 일하는 환경과 절차를 설계하는 방식이라 “하네스 엔지니어링”이라고도 부릅니다. 핵심은 다섯 가지입니다.

1. 문서가 기준 — 기획(PRD)·아키텍처·기술 결정(ADR)·규칙(AGENTS.md)을 먼저 씁니다.
2. 작게 쪼갠 계획 — /harness가 문서를 읽고 작업을 step 지시서(phases/{phase}/step{N}.md)로 나눕니다. 사람이 검토하고 승인합니다.
3. step마다 새 세션 — scripts/execute.py가 step 하나마다 새 Claude 세션을 열고, 규칙 문서를 매번 넣어 주고 앞 step의 요약만 넘겨서 맥락이 오염되지 않습니다.
4. 스스로 검증 — 각 step은 실행 가능한 완료 조건(npm run check 등)을 통과해야 끝납니다. 실패하면 에러를 다시 넣어 최대 3회 고칩니다.
5. 안전장치 — 훅이 위험한 명령과 테스트 없는 구현을 막고, 끝나면 /review로 한 번 더 걸러냅니다.

하네스 작업 흐름

문서 작성 (PRD · ARCHITECTURE · ADR · specs)
   ↓
/harness ── step 계획 생성 → 사람이 승인
   ↓
execute.py ── step마다 새 세션: 구현 → 검증 → 커밋
   ↓
/review ── 규칙 위반 탐지·수정
   ↓
마일스톤 체크리스트로 사람이 직접 테스트 → PR

사람은 문서를 쓰고, step 계획을 승인하고, 마일스톤이 끝날 때 직접 테스트합니다. 그 사이의 구현·검증·커밋은 하네스가 step 단위로 반복합니다.

하네스의 숨은 비용: 토큰

하네스는 step마다 새 세션을 열고 그때마다 규칙 문서를 통째로 읽습니다. 맥락이 깨끗해지는 대신 토큰이 녹습니다. Claude 구독에는 5시간·주간 사용량 한도가 있어서, 밤에 phase를 걸어 두고 자면 이런 일이 생깁니다.

1. 밤에 phase를 걸어 두고 잔다.
2. 새벽 3시에 사용량 한도에 걸려 step이 실패로 끝난다.
3. 아침에 일어나 그걸 발견하고, 리셋까지 다시 기다린다.
4. “이어서 하기”를 직접 누른다.

가난한 사람을 위한 하네스, harness_framework_poor

그래서 저(BitKitTools 운영자)는 추가 사용량을 결제하는 대신, 기다리는 것까지 하네스에게 맡긴 하네스를 만들었습니다. 이름도 솔직하게 harness_framework_poor입니다. 돈 대신 시간으로 냅니다.

⏳ 사용량 한도 자동 대기·이어 하기

• claude -p를 stream-json으로 실행해 매번 5시간·주간 사용량과 리셋 시각을 확인합니다.
• 사용량이 95% 이상이면 새 step을 시작하지 않고, 리셋 시각까지 기다렸다가 스스로 시작합니다.
• step 도중에 한도에 걸려 끊겨도 실패로 치지 않습니다. 리셋 후 --resume으로 같은 세션을 이어서 하던 맥락 그대로 마저 끝냅니다.
• 기준은 --limit-threshold 0.9처럼 바꿀 수 있습니다. Windows에서는 기다리는 동안 PC가 절전으로 들어가지 않게 막습니다.

py -3 scripts/execute.py m0-foundation                         # Windows
python3 scripts/execute.py m0-foundation                       # macOS / Linux
py -3 scripts/execute.py m0-foundation --limit-threshold 0.9   # 더 일찍 멈추기

📚 다시 하는 일을 줄이는 문서 체계

토큰을 아끼다 보면 “한 번에 제대로” 끝내는 게 가장 싸다는 걸 알게 됩니다. 그래서 문서를 보강했습니다.

• docs/progress.md — 마일스톤 체크리스트와 결정 대기(블로커) 표. 체크리스트 1개 = step 1개 = 커밋 1개
• docs/milestone-checklist.md — 마일스톤이 끝나면 사람이 직접 확인하는 테스트 목록
• docs/specs/ — 시스템별 상세 스펙. 스펙 없이 코드부터 쓰지 않습니다. 필요한 스펙만 step에 넣어 토큰을 아낍니다.
• docs/tech-debt-tracker.md — 에이전트는 git log를 읽지 않으므로 알려진 부채를 여기 남겨 매 step에 전달

🧭 /harness · /review 강화

• /harness — 체크리스트 단위로 step을 나누고, 순수 로직·테스트 → 서버 → 클라이언트 → E2E 순서를 지키며, 스펙이 없거나 결정이 안 된 게 있으면 계획 전에 먼저 묻습니다.
• /review — 눈으로 보던 체크리스트를 grep 자동 탐지로 바꿔 any 타입, 레이어 위반, 시크릿 노출, 테스트 누락을 찾고, 위반이 0이 될 때까지 반복합니다.

원본 하네스와 비교

뼈대는 전부 원본 jha0313/harness_framework에서 왔습니다. poor 버전은 그 위에 가난 대응 기능과 문서·커맨드 보강을 얹은 것입니다.

이 사이트도 하네스로 만들었습니다

BitKitTools는 2026년 7월 3일부터 8월 7일까지 하네스로 18개 phase, 72개 step을 실행해 만들었습니다. 기반 설정부터 JSON Formatter·JWT Decoder 같은 툴 16개, 배포 자동화, GA4·Search Console·Clarity 데이터 수집과 주간 리포트 자동화까지 모두 phase 단위로 쌓았습니다. 하네스를 쓰면서 겪은 토큰 문제가 harness_framework_poor를 만든 이유입니다.

빠르게 시작하기

필요한 것: Claude Code CLI, Python 3.10+, Node 20+, git, bash(Windows는 Git for Windows).

1. 저장소 파일을 새 프로젝트 폴더에 복사하고 git init 후 첫 커밋을 합니다.
2. AGENTS.md, docs/PRD.md, docs/ARCHITECTURE.md, docs/ADR.md의 { } 부분을 채웁니다.
3. docs/progress.md에 마일스톤 체크리스트를, docs/specs/에 첫 마일스톤 스펙을 씁니다.
4. Claude Code에서 /harness를 실행하고 step 계획을 검토해 승인합니다.
5. execute.py로 실행하고 잡니다. 일어나면 /review → 마일스톤 체크리스트로 직접 테스트 → PR.

쓰기 전에 알아둘 것

• step 세션은 --dangerously-skip-permissions로 실행됩니다(권한 확인 없이 파일 수정·명령 실행). 신뢰할 수 있는 저장소에서만 쓰고 훅을 끄지 마세요.
• 자동 대기는 Claude 구독 사용량 기준입니다. 종량제 API 키에는 한도 대신 비용이 청구되므로 해당되지 않습니다.
• 주간 한도까지 다 쓰면 며칠을 기다릴 수도 있습니다. 노트북 덮개를 닫으면 절전 방지도 소용없으니 전원을 꽂아 두세요.