하네스 엔지니어링(Harness Engineering) 완전 정리 — AI가 좋은 코드를 짜게 만드는 법

2026년 3월 31일, Anthropic 엔지니어가 엄청난 실수를 했어요.

npm 패키지 업데이트 하나에 Claude Code 소스코드 50만 줄이 통째로 들어간 거예요. 몇 시간 만에 GitHub 스타 5만 개. 개발자들이 회의를 취소하고 달려들었어요.

근데 사람들이 주목한 건 모델이 아니었어요.

"모델이 아니라 모델을 감싼 구조가 진짜였다."

이게 하네스 엔지니어링(Harness Engineering)이에요.

---

하네스가 뭔가

에이전트 = 모델 + 하네스

모델:   Claude, GPT, Gemini 등 LLM
하네스: 모델 외 나머지 전부
        → 툴 실행, 퍼미션, 컨텍스트 관리,
          메모리, 피드백 루프, 에러 복구...

Claude Code 유출로 밝혀진 것들이에요.

• 퍼미션 게이트 달린 툴 40개 (파일, bash, git, LSP, MCP 등)
• 4만 6천 줄짜리 쿼리 엔진 (토큰 캐싱, 컨텍스트 관리, 재시도 로직)
• 3단계 메모리 아키텍처 (컨텍스트 엔트로피 방지)
• autoDream 백그라운드 데몬 (24시간 비활성 후 메모리 정리/재구성)

모델이 경쟁력이 아니었어요. 하네스가 경쟁력이었어요.

---

왜 하네스가 없으면 AI가 엉망이 되나

Claude Code를 만든 Anthropic 엔지니어가 실험한 결과예요.

프롬프트만 줬을 때 에이전트의 실패 패턴:
1. 한 번에 너무 많이 하려 함 (앱 전체를 한 번에 만들려 함)
2. 중간에 일찍 완료 선언 (실제로 안 됐는데)
3. 컨텍스트가 쌓일수록 이전 결정을 잊어버림
4. 파일 경로 환각, 없는 API 발명

하네스는 이 모든 실패를 구조로 막아요.

---

하네스 엔지니어링의 핵심 개념

1. 가이드 (Guides) — AI에게 규칙을 주입

CLAUDE.md / AGENTS.md / .cursorrules

프로젝트 루트에 두는 파일이에요:
- 디렉토리 구조
- 코딩 컨벤션 (네이밍, 스타일)
- 아키텍처 결정사항
- 테스트 실행 명령
- 절대 건드리면 안 되는 파일

# CLAUDE.md 예시

## 프로젝트 구조
- /backend: Rust (Axum)
- /frontend: TypeScript (Next.js)
- /infra: Helm charts

## 규칙
- 직접 main 브랜치 커밋 금지
- 모든 API 변경은 /docs/api.md 업데이트 필수
- 테스트: `cargo test` (백엔드), `npm test` (프론트)

## 절대 수정 금지
- /infra/production/*.yaml
- .env.production

이 파일 하나로 AI의 행동 범위가 완전히 달라져요.

2. 센서 (Sensors) — AI 작업 결과를 자동 검증

AI가 코드를 짜면 자동으로 검증해요. 두 종류가 있어요.

계산적 센서 (빠르고 확정적):
- 린터 (eslint, clippy)
- 타입 체커 (tsc, mypy)
- 테스트 실행 (pytest, cargo test)
- 구조 분석

추론적 센서 (느리고 확률적):
- AI 코드 리뷰 (LLM as judge)
- 시맨틱 분석
- 보안 취약점 스캔

# 하네스에 센서 연결 예시 (Claude Code hooks)
# .claude/hooks/post-edit.sh

#!/bin/bash
# 파일 수정 후 자동 실행
npm run lint
npm run typecheck
npm run test -- --changed

# 실패하면 에이전트에게 피드백 반환

3. 피드백 루프 — AI가 스스로 고치게 만들기

기본 루프:
작업 → 코드 생성 → 테스트 실행
       ↑              ↓
       ←── 실패 시 재시도 ←──

이 루프가 없으면: AI가 코드 짜고 끝
이 루프가 있으면: AI가 테스트 통과까지 스스로 반복

---

실전 — Red Hat 엔지니어의 하네스 설계

4월 7일 Red Hat 발행 사례예요. Rust 백엔드 + TypeScript 프론트엔드 + Helm 차트 멀티 레포 프로젝트에 적용했어요.

기존 방식 (실패)

Jira 티켓 붙여넣기 → "이거 구현해줘" → 예측 불가 결과
→ 없는 파일 경로 환각
→ 없는 API 발명
→ 엉뚱한 모듈 수정

하네스 적용 후 (성공)

1단계: Impact Map 생성

AI가 LSP + MCP로 레포 구조 분석 후:

trustify (backend):
  변경 필요:
  - SBOM 쿼리 결과 CSV 직렬화 추가
  - GET /api/v2/sbom/export 엔드포인트 추가

trustify-ui (frontend):
  변경 필요:
  - SBOM 목록 툴바에 "Export CSV" 버튼 추가

→ 인간이 이 맵 검토 후 승인
→ 잘못된 모듈 선택, 없는 API 발명을 여기서 잡음

2단계: 구조화된 태스크 템플릿

## Repository: trustify
## Description
SBOM 쿼리 결과용 CSV 익스포트 엔드포인트 추가

## Acceptance Criteria
- GET /api/v2/sbom/export?format=csv 응답
- Content-Type: text/csv
- 기존 쿼리 파라미터 전부 지원

## Context
- 기존 JSON 엔드포인트: /api/v2/sbom/query
- 직렬화 레이어: src/serialization/
- 테스트 위치: tests/api/

## 절대 수정 금지
- src/db/migrations/

결과: 예측 가능하고 재현 가능한 AI 코딩이 됐어요.

---

장기 실행 에이전트 하네스 — Anthropic 공개 사례

몇 시간~며칠짜리 작업을 에이전트가 처리하려면 특별한 하네스가 필요해요.

핵심 문제: 컨텍스트 리셋

긴 작업 = 여러 컨텍스트 윈도우 필요
각 새 세션 = 이전 내용 기억 없음

마치 교대 근무자가 이전 근무 내용을
전혀 모르고 출근하는 것과 같음

해결: Initializer Agent + 진행 상황 파일

# claude-progress.txt (에이전트가 직접 관리)

## 완료된 작업
- 데이터베이스 스키마 설계 완료
- API 엔드포인트 5개 구현 완료

## 현재 작업
- 인증 미들웨어 구현 중

## 다음 작업
- 프론트엔드 컴포넌트 연결
- E2E 테스트 작성

## 중요 결정사항
- JWT 대신 세션 쿠키 사용 결정 (이유: SSR 호환성)
- 데이터베이스: PostgreSQL + Prisma

하네스 구조:

초기화 에이전트 (1회):
→ 레포 분석, 작업 분해, 진행 파일 생성

코딩 에이전트 (반복):
→ 진행 파일 읽기
→ 한 기능 구현
→ 테스트 통과 확인
→ 진행 파일 업데이트
→ 세션 종료

Anthropic 내부 테스트에서 이 방식으로 Claude가 2시간 이상 연속으로 coherent하게 작업했어요. (기존 방식은 30분도 안 돼서 엉켜버렸어요)

---

Claude Code 하네스 실전 설정

# 1. CLAUDE.md 생성 (가장 중요)
cat > CLAUDE.md << 'EOF'
# 프로젝트 컨벤션

## 스택
- Backend: FastAPI + PostgreSQL
- Frontend: Next.js 15 + TypeScript

## 코딩 규칙
- 함수명: snake_case (Python), camelCase (TS)
- 모든 API 함수에 docstring 필수
- 테스트 없는 PR 금지

## 테스트 실행
- 백엔드: `pytest tests/ -v`
- 프론트: `npm test`

## 절대 수정 금지
- alembic/versions/ (DB 마이그레이션)
- .env.production
EOF

# 2. hooks 설정 (자동 검증)
mkdir -p .claude/hooks

cat > .claude/hooks/post-edit.sh << 'EOF'
#!/bin/bash
# Python 파일 수정 시 린트 + 타입 체크
if [[ "$MODIFIED_FILE" == *.py ]]; then
    ruff check "$MODIFIED_FILE"
    mypy "$MODIFIED_FILE"
fi
EOF

chmod +x .claude/hooks/post-edit.sh

---

하네스 수준별 단계

레벨 1 (기본):
CLAUDE.md로 컨벤션 주입
→ 환각 대폭 감소

레벨 2 (중급):
CLAUDE.md + 자동 테스트 피드백 루프
→ 테스트 통과까지 자동 반복

레벨 3 (고급):
Impact Map + 구조화된 태스크 템플릿 + 센서
→ 멀티 레포 작업도 예측 가능

레벨 4 (프로덕션):
장기 실행 에이전트 + 초기화/코딩 에이전트 분리
→ 며칠짜리 작업 자율 수행

---

핵심 인사이트

"AI는 마이크로매니지를 싫어하지 않는다"

인간 개발자는 제약이 많을수록 답답해해요. AI 에이전트는 정반대예요. 제약이 많을수록, 구조가 촘촘할수록 더 좋은 결과를 낸어요.

직관과 반대예요. 그래서 많은 팀이 처음에 하네스 없이 시작하다 실패해요.

잘못된 접근:
"AI가 알아서 하겠지" → 프롬프트만 잘 쓰면 되겠지

맞는 접근:
AI가 작동하는 환경 자체를 설계한다
→ 구조, 제약, 피드백 루프가 결과를 결정한다

---

마무리

하네스 엔지니어링을 한 줄로 요약하면 이래요.

"AI 코딩의 경쟁력은 모델이 아니라 모델을 감싼 구조에서 나온다."

Claude Code 유출이 증명한 게 그거예요. 누구나 Claude API를 쓸 수 있어요. 근데 Claude Code처럼 동작하는 걸 만들기는 어려워요. 50만 줄의 하네스가 거기 있었거든요.

CLAUDE.md 하나 만드는 것부터 시작해요. 거기서 차이가 나기 시작해요. 😄

---