2026.04.14

하네스 엔지니어링 입문 가이드

AI에게 "그냥 만들어줘" 대신, 설계도를 먼저 세우고 맡기는 방법. 바이브 코딩의 다음 단계입니다.

하네스(Harness)란?

하네스는 원래 "안전 장비"라는 뜻입니다. 암벽등반의 안전줄처럼, AI 에이전트가 엉뚱한 방향으로 가지 않도록 구조·규칙·검증 기준이라는 안전 장비를 먼저 세팅하는 방법론입니다.

2026년 초 등장한 개념으로, 바이브 코딩(Vibe Coding)의 한계를 보완합니다. 바이브 코딩이 "감으로 시키기"라면, 하네스 엔지니어링은 "설계하고 맡기기"입니다.

바이브 코딩 vs 하네스 엔지니어링

같은 "2D 액션 게임 만들어줘"를 두 가지 방법으로 시도하면 결과가 완전히 달라집니다.

하네스의 4가지 요소

1. 설계 (CLAUDE.md)

프로젝트의 기술 스택, 제약 조건, 금지 사항을 CLAUDE.md 파일에 정의합니다. AI는 매 세션마다 이 파일을 자동으로 읽습니다.

2. 단계 (Phase)

전체 작업을 독립적인 Phase로 나눕니다. "Phase 1: 게임 루프 → Phase 2: 입력 처리 → Phase 3: 충돌 판정" 처럼요. 한 번에 한 Phase만 진행합니다.

3. 검증 (테스트 기준)

각 Phase마다 "이게 되면 완료"라는 기준을 미리 정합니다. "Phase 3 완료 조건: 벽 통과 불가, 대각선 끼임 없음." AI가 스스로 체크합니다.

4. 가드레일 (금지 규칙)

AI가 하면 안 되는 것을 명시합니다. "기존 코드 리팩토링 금지", "2개 Phase 동시 진행 금지". 이게 없으면 AI가 기존 코드를 망가뜨립니다.

실전 예시: 2D 액션 게임

CLAUDE.md에 이렇게 적습니다:

# 🎮 Slash Knight — 2D 액션 게임
HTML5 Canvas + Vanilla JS, 단일 HTML 파일

# 구현 순서 (엄수!)
Phase 1: 게임 루프 + 캔버스 렌더링
Phase 2: 플레이어 이동 + 입력 처리
Phase 3: 충돌 판정 (AABB)
Phase 4: 적 AI (순찰 → 추적 → 공격)
Phase 5: 체력 시스템 + HUD
Phase 6: 스테이지 전환 + 점수

# 각 Phase 완료 조건
Phase 1: 60fps 유지 확인
Phase 2: WASD + 터치 모두 동작
Phase 3: 벽 통과 불가, 코너 끼임 없음
Phase 4: 거리 내 접근 시 추적 전환

# 금지 사항
- 다음 Phase 전 현재 테스트 필수
- 2개 Phase 동시 구현 금지
- 기존 코드 임의 리팩토링 금지

그리고 Claude Code에서 이렇게 시킵니다:

claude > Phase 1부터 시작해. CLAUDE.md 완료 조건 확인해.

✓ Phase 1 — 게임 루프 + 캔버스: 60fps 확인 ✓

claude > Phase 2 진행.

✓ Phase 2 — 입력 처리: WASD + Arrow + 터치 ✓

claude > Phase 3 진행.

✓ Phase 3 — AABB 충돌: 벽 차단 ✓, 코너 끼임 없음 ✓

하네스가 AI를 교정하는 순간

Phase 4 작업 중, AI가 기존 Player 코드를 리팩토링하려고 시도합니다. 바이브 코딩이었다면 그대로 진행해서 Phase 2~3이 전부 깨졌을 거예요.

하지만 CLAUDE.md에 "기존 코드 리팩토링 금지"라는 가드레일이 있기 때문에, AI가 스스로 멈추고 안전한 방식으로 전환합니다:

⚠️ CLAUDE.md 규칙 위반 감지:
   "기존 코드 리팩토링 금지"
   → Player를 Entity 상속으로 변경 시도 중단
   → 기존 구조 유지, Enemy만 별도 구현

✓ Phase 4 완료

이게 하네스의 핵심 가치입니다. AI가 실수하려는 순간, 규칙이 자동으로 잡아줍니다.

체크리스트

어떤 프로젝트든 이 4가지를 CLAUDE.md에 적으면 하네스가 됩니다.