하네스 엔지니어링 총정리

하네스 엔지니어링이란 무엇인가?

1.1 정의

하네스 엔지니어링(Harness Engineering)은 AI 에이전트 시스템에서 모델 자체를 제외한 모든 것 — 도구, 메모리, 가드레일, 검증 로직, 오케스트레이션 — 을 설계하고 최적화하는 분야입니다. "하네스(Harness)"라는 단어는 원래 말을 제어하는 마구(馬具)를 뜻하며, AI 에이전트라는 강력한 힘을 원하는 방향으로 이끄는 제어 시스템 전체를 의미합니다.

소프트웨어 공학의 거장 마틴 파울러(Martin Fowler)는 이를 다음 공식으로 정리했습니다.

즉, 아무리 뛰어난 모델(GPT-5, Claude Opus 등)이라도 올바른 하네스 없이는 신뢰할 수 있는 실무 결과를 만들어낼 수 없습니다. 하네스 엔지니어링은 "모델을 똑똑하게 만드는 것"이 아니라, "똑똑한 모델이 제대로 일하도록 환경을 설계하는 것"입니다.

1.2 프롬프트 엔지니어링과의 차이

프롬프트 엔지니어링이 모델에게 "무엇을 해야 하는지"를 말하는 기술이라면, 하네스 엔지니어링은 모델이 "어떤 환경에서, 어떤 도구를 가지고, 어떤 제약 아래에서" 일하는지를 설계하는 기술입니다. 프롬프트는 하네스의 한 구성요소일 뿐이며, 하네스는 프롬프트를 포함한 전체 시스템 아키텍처를 다룹니다.

1.3 용어가 등장한 배경

하네스라는 용어는 2025년 말~2026년 초, HashiCorp 공동 창업자 미첼 하시모토(Mitchell Hashimoto)가 자신의 AI 코딩 워크플로우를 설명하면서 대중화되었습니다. 그의 핵심 통찰은 명확합니다: "에이전트가 실수할 때마다, 다음번에 더 잘하기를 바라지 말고, 그 실수가 구조적으로 반복되기 어려운 환경을 만들어라."

이후 OpenAI, Anthropic, Stripe, Palantir 등 주요 테크 기업들이 하네스 설계를 핵심 역량으로 공개하면서, 하네스 엔지니어링은 AI 엔지니어의 필수 기술로 자리잡았습니다.

왜 지금 하네스 엔지니어링이 중요한가

2.1 모델만으로는 해결되지 않는 문제들

2024~2026년 사이 AI 모델은 급격히 발전했지만, 실무에서 에이전트를 운영하는 팀들은 공통된 문제를 겪고 있습니다. 모델을 업그레이드해도 근본적으로 해결되지 않는 구조적 한계가 있기 때문입니다.

컨텍스트 부패(Context Rot)

대화가 길어질수록 모델의 주의력이 분산됩니다. 초기 지시사항을 잊어버리고, 작업 목표에서 벗어나며, 일관성 없는 출력을 생성합니다. 100만 토큰의 컨텍스트 윈도우가 있어도, 모델은 중간 부분의 정보를 쉽게 놓칩니다(Lost in the Middle 문제).

크로스세션 기억상실

매 세션은 백지 상태에서 시작됩니다. 어제 내린 결정, 수정한 파일, 학습한 컨벤션 — 모두 사라집니다. 하네스 없이는 에이전트가 영원히 "첫 출근한 신입 사원"입니다.

자기 검증 불가

모델은 자신의 불확실성을 표시하지 않습니다. 틀린 답도 확신에 차서 말합니다. 10단계 작업에서 단계별 정확도가 95%라 해도, 전체 성공률은 60%로 떨어집니다. 검증 루프 없이는 오류가 무한히 누적됩니다.

환각(Hallucination)과 폭주

에이전트가 존재하지 않는 API를 호출하거나, 범위 밖의 파일을 수정하거나, 무한 루프에 빠지는 문제는 모델 업그레이드로 "줄어들" 수는 있지만 "사라지지" 않습니다. 가드레일이 필요한 이유입니다.

2.2 실증적 증거: 하네스가 모델보다 중요하다

Terminal Bench 2.0(AI 코딩 에이전트 벤치마크)에서, 한 팀이 모델을 전혀 바꾸지 않고 하네스만 개선하여 하위 30위에서 상위 5위로 올라간 사례가 보고되었습니다. 같은 모델, 같은 가중치, 제로 재학습 — 바뀐 것은 오직 모델을 둘러싼 시스템이었습니다.

또한 revfactory/harness 프로젝트의 A/B 테스트(n=15)에서는, 동일한 Claude Code 모델에 하네스를 적용한 그룹이 적용하지 않은 그룹 대비 코드 품질 점수 +60%(49.5 → 79.3), 과제 완료율 100%(15/15), 토큰 사용량 -32%의 결과를 보였습니다.

2.3 산업계의 움직임

Stripe는 주당 1,300건의 AI PR을 하네스 기반으로 처리하고 있습니다. OpenAI 내부팀은 100만 라인의 코드베이스를 수작업 코드 없이 하네스만으로 구축했다고 밝혔습니다. Anthropic은 Claude Code의 공식 모범 사례에서 하네스 설계를 핵심 가이드로 제시합니다. 이제 하네스 엔지니어링은 선택이 아닌, AI 시대 엔지니어의 기본 소양이 되었습니다.

핵심 공식: Agent = Model + Harness

3.1 공식의 의미

이 공식은 LangChain의 블로그에서 제안되고, 마틴 파울러에 의해 체계화된 개념입니다. 에이전트를 구성하는 두 축을 명확히 분리합니다.

핵심 통찰은 이것입니다: 모델은 우리가 바꿀 수 없지만, 하네스는 우리가 완전히 통제할 수 있습니다. 모델 선택은 API 키 하나의 결정이지만, 하네스는 지속적으로 개선해 나가는 엔지니어링 실천입니다.

3.2 3중 하네스 구조 (코딩 에이전트 기준)

마틴 파울러는 코딩 에이전트에서 하네스를 두 층으로 나눕니다: 코딩 에이전트 개발사가 만든 "빌더 하네스(Builder Harness)"와, 사용자인 우리가 만드는 "유저 하네스(User Harness)"입니다.

빌더 하네스는 Claude Code, Cursor, Windsurf 같은 도구 제작사가 이미 구축한 것입니다. 우리가 집중해야 할 것은 유저 하네스 — 즉, 우리 프로젝트에 맞게 에이전트를 길들이는 외부 제어 시스템입니다.

3.3 하네스의 두 방향: 피드포워드와 피드백

하네스를 설계할 때 두 가지 방향을 이해해야 합니다.

피드포워드만 있으면 "규칙은 알지만 지켰는지 모르는" 에이전트가 되고, 피드백만 있으면 "같은 실수를 계속 반복하는" 에이전트가 됩니다. 둘 다 있어야 비로소 신뢰할 수 있는 에이전트가 됩니다.

3.4 계산적 vs 추론적 제어

가이드와 센서는 각각 두 가지 실행 유형으로 나뉩니다.

하네스의 5대 구성요소

4.1 전체 구조 개요

잘 설계된 하네스는 다섯 가지 핵심 구성요소로 이루어집니다. 각 요소는 독립적으로 존재하면서도 유기적으로 연결됩니다.

4.2 각 구성요소 요약

다음 장부터 각 구성요소를 하나씩 깊이 있게 살펴보겠습니다.

컨텍스트 엔지니어링

5.1 컨텍스트 = 모델의 세계관

컨텍스트 엔지니어링은 "모델이 추론 시점에 볼 수 있는 모든 정보를 최적으로 구성하는 기술"입니다. 모델은 컨텍스트 윈도우에 들어있는 정보만으로 판단합니다. 아무리 프로젝트에 중요한 규칙이 있어도, 컨텍스트에 없으면 모델에게는 존재하지 않는 것입니다.

5.2 컨텍스트의 3계층

5.3 Progressive Disclosure 패턴

모든 정보를 한꺼번에 주입하면 컨텍스트 윈도우가 낭비되고, 모델의 집중력이 분산됩니다. Progressive Disclosure(점진적 공개)는 "필요한 정보를 필요한 시점에만 제공"하는 원칙입니다.

# CLAUDE.md (항상 로딩 - L1)
→ 프로젝트 개요, 핵심 규칙, 금지사항

# skills/analyze/SKILL.md (분석 작업 시 - L2)
→ 분석 절차, 체크리스트, 참조 문서 목록

# skills/analyze/references/api-spec.md (필요 시 - L2 상세)
→ 구체적 API 스펙 (스킬이 참조할 때만 로딩)

# 도구 호출 결과 (실시간 - L3)
→ 린터 출력, 테스트 결과, 파일 내용

5.4 컨텍스트 엔지니어링의 핵심 원칙

• 간결함 우선: 불필요한 정보는 노이즈입니다. 토큰은 유한한 자원이므로, 각 토큰이 의미를 가져야 합니다.
• 구조화: 마크다운 헤딩, 목록, 구분선으로 정보를 구조화하면 모델이 더 잘 이해합니다.
• 명시성: 암묵적 지식은 모델에게 통하지 않습니다. "당연한 것"도 명시적으로 적어야 합니다.
• 최신성: 오래된 문서는 오히려 해가 됩니다. 코드가 변경되면 컨텍스트도 함께 갱신되어야 합니다.
• 우선순위: 가장 중요한 규칙을 문서 상단에 배치합니다. 모델은 시작과 끝 부분에 더 주의를 기울입니다.

5.5 MCP(Model Context Protocol)의 역할

MCP는 Anthropic이 2024년 말 도입한 표준 프로토콜로, AI 에이전트가 외부 데이터 소스와 도구에 표준화된 방식으로 접근할 수 있게 합니다. 하네스 엔지니어링에서 MCP는 "에이전트에게 어떤 외부 정보와 도구를 연결할 것인가"를 결정하는 핵심 인프라입니다.

가드레일 설계

6.1 가드레일이란?

가드레일(Guardrails)은 에이전트가 해서는 안 되는 행동을 구조적으로 불가능하게 만드는 제약 시스템입니다. "하지 마세요"라고 말하는 것(프롬프트)과, 물리적으로 할 수 없게 만드는 것(가드레일)은 전혀 다릅니다. CLAUDE.md에 "이 파일을 수정하지 마세요"라고 적는 것은 권고이지 강제가 아닙니다. 진정한 가드레일은 시스템 수준에서 접근을 차단합니다.

6.2 가드레일의 유형

6.3 Claude Code에서의 가드레일 설정

{
  "permissions": {
    "allow": [
      "Read",
      "Write(src/**)",
      "Write(tests/**)",
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Write(*.env)",
      "Write(.claude/**)",
      "Write(package-lock.json)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(sudo *)"
    ]
  }
}

6.4 핵심 설계 철학: "더 제약할수록 더 잘 작동한다"

직관에 반하지만 실증적으로 입증된 원칙입니다. 에이전트가 수정할 수 있는 파일, 접근할 수 있는 도구, 쓸 수 있는 디렉토리를 제한하면 오히려 더 높은 품질의 출력을 생성합니다. 범위가 좁아지면 에이전트가 집중할 수 있기 때문입니다.

실무 접근법은 "처음에 최대한 엄격하게 시작하고, 신뢰가 쌓이면 점진적으로 완화"하는 것입니다. 깨진 시스템에 가드레일을 추가하는 것보다, 작동하는 시스템에서 가드레일을 제거하는 것이 훨씬 쉽습니다.

피드백 루프와 자기교정

7.1 피드백 루프의 필수성

모델은 자신의 출력이 올바른지 스스로 판단할 수 없습니다. 피드백 루프는 에이전트의 출력을 관찰하고, 문제가 있으면 에이전트에게 교정 신호를 보내는 시스템입니다. 이것이 있어야 에이전트가 "자기교정(Self-Correction)"을 할 수 있습니다.

7.2 피드백 센서의 유형

7.3 피드백 타이밍: 품질을 왼쪽으로

"Shift Left" 원칙은 품질 검사를 가능한 한 일찍 수행하라는 뜻입니다. 문제를 일찍 발견할수록 수정 비용이 낮습니다.

7.4 자기교정 루프 구현

# 필수 검증 절차 (모든 코드 변경 후)

1. `npm run lint` 실행 → 에러가 있으면 모두 수정할 것
2. `npm run typecheck` 실행 → 타입 에러 해결
3. `npm run test` 실행 → 실패하는 테스트가 있으면 수정
4. 위 3단계를 모두 통과할 때까지 반복

## 자기교정 규칙
- 같은 에러가 3회 연속 발생하면, 접근 방식을 완전히 바꿀 것
- 테스트 통과를 위해 테스트를 삭제하거나 약화시키지 말 것
- 수정이 다른 테스트를 깨뜨리면, 원래 수정을 되돌리고 재설계할 것

7.5 "긍정적 프롬프트 인젝션" 기법

마틴 파울러가 제안한 강력한 기법입니다. 린터나 테스트의 에러 메시지에 "수정 방법"을 직접 포함시켜, 에이전트가 에러를 보는 즉시 해결책을 알 수 있게 합니다.

# 일반적인 린터 메시지 (모델에게 불친절):
ERROR: Import not allowed from 'internal/core'

# 하네스 최적화된 린터 메시지 (모델에게 친절):
ERROR: Import not allowed from 'internal/core'.
FIX: Use the public API instead. Import from '@app/core/public' 
which exports the same functionality.
See: docs/architecture/module-boundaries.md

상태 관리와 메모리

8.1 왜 외부 메모리가 필요한가

LLM은 세션이 끝나면 모든 것을 잊습니다. 컨텍스트 윈도우가 아무리 커도 "임시 메모리"일 뿐, 영구 기억은 아닙니다. 하네스의 상태 관리 시스템은 에이전트에게 "장기 기억"을 부여합니다. 이를 통해 에이전트는 어제의 결정을 기억하고, 지난주의 실수를 반복하지 않으며, 프로젝트의 누적된 맥락을 유지합니다.

8.2 메모리의 유형

8.3 진행 파일(Progress File) 패턴

장기 작업에서 에이전트가 현재 진행 상황을 파일에 기록하는 패턴입니다. 세션이 중단되거나 새로 시작되어도, 이 파일을 읽고 이어서 작업할 수 있습니다.

# 프로젝트 진행 상태

## 현재 작업
- [x] 사용자 인증 API 구현
- [x] JWT 토큰 발급/검증 로직
- [ ] 소셜 로그인 연동 (Google, Kakao)  ← 현재 진행 중
- [ ] 비밀번호 재설정 플로우
- [ ] 이메일 인증 시스템

## 마지막 세션 요약 (2026-04-28)
- Google OAuth 콜백 핸들러 구현 완료
- Kakao 로그인은 redirect URI 설정 이슈로 중단
- 해결 방향: .env에 KAKAO_REDIRECT_URI 추가 필요

## 중요 결정 사항
- 인증 토큰은 httpOnly 쿠키에 저장 (XSS 방지)
- 리프레시 토큰 만료: 7일
- 소셜 로그인 최초 시 자동 회원가입 처리

## 주의사항
- auth.service.ts의 validateToken()은 미들웨어에서만 호출할 것
- 테스트 시 JWT_SECRET=test-secret 환경변수 필요

8.4 Claude Code Auto Memory

Claude Code는 자동 메모리 기능을 통해 세션 간 학습을 지원합니다. 에이전트가 발견한 패턴, 프로젝트 규칙, 실수에서 배운 교훈을 자동으로 MEMORY.md에 기록하고, 다음 세션 시작 시 자동으로 로딩합니다.

도구(Tool) 설계

9.1 도구의 역할

도구(Tool)는 에이전트가 외부 세계와 상호작용하는 인터페이스입니다. 파일 읽기/쓰기, 명령어 실행, API 호출, 데이터베이스 쿼리 등 — 모델이 "생각"만 하는 것을 넘어 "행동"할 수 있게 해주는 핵심 구성요소입니다.

9.2 좋은 도구 설계의 원칙

• 단일 책임: 하나의 도구는 하나의 일만 합니다. "파일 읽기 + 분석 + 수정"을 한 도구에 넣지 마세요.
• 명확한 설명: 도구의 이름과 description이 명확해야 모델이 올바른 도구를 선택합니다.
• 실패 안전: 도구가 실패했을 때 명확한 에러 메시지를 반환해야 합니다. "Something went wrong"이 아닌, "파일 /src/auth.ts를 찾을 수 없습니다. 현재 디렉토리의 파일 목록: ..."
• 멱등성: 가능하면 같은 입력에 같은 결과를 보장하여, 재시도해도 안전하게 만듭니다.
• 최소 권한: 도구에게 필요 이상의 권한을 주지 마세요.

9.3 코딩 에이전트의 핵심 도구들

9.4 MCP 서버를 통한 도구 확장

MCP(Model Context Protocol)를 활용하면 에이전트에게 커스텀 도구를 쉽게 제공할 수 있습니다. 데이터베이스 조회, Jira 티켓 관리, Slack 메시지 전송, 사내 문서 검색 등을 MCP 서버로 구현하여 연결하면, 에이전트가 조직의 워크플로우에 깊이 통합됩니다.

// .claude/mcp_servers.json
{
  "servers": {
    "project-docs": {
      "command": "npx",
      "args": ["@company/docs-mcp-server"],
      "description": "사내 기술 문서 검색 서버"
    },
    "database": {
      "command": "npx",
      "args": ["@company/db-mcp-server", "--readonly"],
      "description": "프로덕션 DB 조회 (읽기 전용)"
    }
  }
}

오케스트레이션 패턴

10.1 오케스트레이션이란?

오케스트레이션은 복잡한 작업을 여러 단계 또는 여러 에이전트로 분할하고, 이들의 실행 순서와 상호작용을 조율하는 것입니다. 단일 에이전트에게 모든 것을 시키는 것보다, 전문화된 에이전트들이 협업하는 것이 대부분의 복잡한 작업에서 더 좋은 결과를 낳습니다.

10.2 6가지 핵심 아키텍처 패턴

10.3 서브에이전트의 핵심 가치: 컨텍스트 격리

서브에이전트를 사용하는 가장 큰 이유는 "컨텍스트 격리"입니다. 메인 에이전트가 하위 작업을 서브에이전트에게 위임하면, 서브에이전트는 자신만의 독립된 컨텍스트 윈도우에서 작업합니다. 중간의 시행착오, 도구 호출, 실패한 시도 등이 메인 에이전트의 컨텍스트를 오염시키지 않습니다. 메인 에이전트는 최종 결과만 받으므로, 오래 실행되어도 컨텍스트 부패 문제가 크게 완화됩니다.

10.4 모델 라우팅: 단계별 다른 모델 사용

모든 단계에 같은 모델을 쓸 필요가 없습니다. 비용과 능력에 따라 단계별로 다른 모델을 배치하는 것이 효율적입니다.

CLAUDE.md 실전 작성법

11.1 CLAUDE.md란?

CLAUDE.md는 Claude Code에서 프로젝트 루트에 위치하는 설정 파일로, 에이전트가 세션 시작 시 자동으로 읽는 "프로젝트 지침서"입니다. 하네스 엔지니어링의 가장 핵심적인 피드포워드 가이드이며, 에이전트의 행동을 프로젝트에 맞게 조율하는 첫 번째 접점입니다.

11.2 효과적인 CLAUDE.md 구조

# Project: [프로젝트명]

## 1. 프로젝트 개요
- 기술 스택: Next.js 14, TypeScript, Prisma, PostgreSQL
- 아키텍처: App Router, Server Components 우선
- 배포: Vercel, DB는 Supabase

## 2. 절대 규칙 (MUST)
- TypeScript strict 모드 준수. any 타입 사용 금지.
- 모든 API 응답은 Zod 스키마로 검증할 것.
- 환경변수는 .env에서만 관리. 코드에 하드코딩 금지.
- 커밋 전 반드시 `npm run lint && npm run test` 통과 확인.

## 3. 금지 사항 (NEVER)
- node_modules/, .env, package-lock.json 직접 수정 금지
- console.log 디버깅 코드를 커밋에 포함하지 말 것
- 기존 테스트를 삭제하거나 skip하지 말 것
- 사용자 요청 없이 의존성(package.json) 변경 금지

## 4. 코딩 컨벤션
- 컴포넌트: PascalCase (UserProfile.tsx)
- 유틸리티: camelCase (formatDate.ts)
- 상수: SCREAMING_SNAKE_CASE
- CSS: Tailwind CSS 사용, 인라인 style 금지
- 에러 처리: try-catch 대신 Result 패턴 사용

## 5. 디렉토리 구조
src/ 
├── app/ # Next.js App Router 페이지 
├── components/ # 재사용 UI 컴포넌트 
├── lib/ # 유틸리티, 헬퍼 
├── server/ # 서버 전용 로직 (API, DB) 
├── types/ # TypeScript 타입 정의 
└── tests/ # 테스트 파일

## 6. 작업 절차
1. 변경 전: 관련 파일 구조를 먼저 파악
2. 구현: 작은 단위로 점진적 변경
3. 검증: lint → typecheck → test 순서로 실행
4. 실패 시: 3회 시도 후에도 실패하면 접근 방식 변경

## 7. 참조 문서
- API 설계: /docs/api-spec.md
- DB 스키마: /prisma/schema.prisma
- 컴포넌트 가이드: /docs/component-guide.md

11.3 작성 시 핵심 원칙

• 짧고 명확하게: 500~1000줄이 적정선입니다. 너무 길면 모델이 중간 내용을 놓칩니다.
• 구체적으로: "코드를 깨끗하게 작성하세요"가 아닌, "함수는 20줄 이내, 파일은 200줄 이내"처럼 측정 가능하게 적습니다.
• 우선순위 배치: 가장 중요한 규칙(절대 규칙, 금지사항)을 문서 상단에 배치합니다.
• 살아있는 문서: 코드가 변경되면 CLAUDE.md도 함께 갱신합니다. 오래된 규칙은 오히려 해롭습니다.
• 예시 포함: 추상적 규칙보다 구체적 예시가 모델에게 더 효과적입니다.

11.4 다중 CLAUDE.md 전략

대규모 프로젝트에서는 계층적 CLAUDE.md 구조가 효과적입니다.

project-root/
├── CLAUDE.md              # 전체 프로젝트 규칙 (항상 로딩)
├── frontend/
│   └── CLAUDE.md          # 프론트엔드 전용 규칙
├── backend/
│   └── CLAUDE.md          # 백엔드 전용 규칙
└── infrastructure/
    └── CLAUDE.md          # 인프라 전용 규칙

멀티 에이전트 팀 설계

12.1 왜 멀티 에이전트인가?

사람도 혼자서 대규모 프로젝트를 완수하기 어렵습니다. 마찬가지로 단일 에이전트에게 복잡한 시스템 전체를 맡기면 컨텍스트 부패, 역할 혼동, 품질 저하 문제가 발생합니다. 멀티 에이전트 시스템은 "전문화된 에이전트들의 팀"을 구성하여, 각자의 강점을 살리고 약점을 보완합니다.

12.2 에이전트 팀 구성 예시

12.3 에이전트 정의 파일 구조

# Builder Agent

## 역할
너는 코드 구현 전문가이다. Analyst가 작성한 계획에 따라
실제 코드를 작성하고, 모든 검증을 통과시키는 것이 목표다.

## 행동 원칙
1. 계획서(task-plan.md)를 먼저 읽고 범위를 확인한다
2. 한 번에 하나의 파일만 수정한다
3. 매 수정 후 lint + typecheck를 실행한다
4. 테스트가 깨지면 즉시 수정한다
5. 범위 밖의 리팩토링은 하지 않는다

## 사용 가능 도구
- Read, Write (src/, tests/ 디렉토리만)
- Bash: npm run lint, npm run test, npm run build
- Grep, Find (전체 프로젝트 검색 가능)

## 금지 사항
- package.json 수정 금지
- .env 파일 접근 금지
- 기존 테스트 삭제/비활성화 금지
- 설계 변경 임의 결정 금지 (Analyst에게 문의)

## 완료 조건
- lint 에러 0개
- 타입 에러 0개
- 기존 + 신규 테스트 모두 통과
- PROGRESS.md 업데이트 완료

12.4 생성-검증(Generator-Verifier) 패턴 상세

가장 실용적이고 효과가 입증된 멀티 에이전트 패턴입니다. Builder가 코드를 생성하면, QA 에이전트가 즉시 검증합니다. 문제가 발견되면 Builder에게 피드백을 보내 수정하게 합니다. 이 루프가 모든 검증을 통과할 때까지 반복됩니다.

실패 분류와 디버깅

13.1 하네스 개선의 핵심: 실패 분류

하네스 엔지니어링의 핵심 실천은 반복적 개선 루프입니다: 에이전트를 실제 작업에 투입하고 → 실패를 관찰하고 → 실패를 분류하고 → 하네스를 업데이트하고 → 반복합니다. "에이전트가 잘못했다"는 막연한 진단이 아니라, 어떤 층이 문제인지를 정확히 분류해야 올바른 해결책을 적용할 수 있습니다.

13.2 4가지 실패 유형

13.3 디버깅 질문 프레임워크

에이전트가 실패했을 때 다음 질문을 순서대로 던져보세요.

1. "모델이 올바른 정보를 가지고 있었나?" → No라면 컨텍스트 실패. 필요한 문서/규칙을 컨텍스트에 추가.
2. "정보는 있었는데 규칙을 어겼나?" → Yes라면 제약 실패. 시스템 수준 가드레일로 강제.
3. "출력이 검증되었나?" → No라면 검증 실패. 피드백 센서(테스트, 린터) 추가.
4. "전략/접근 방식 자체가 잘못이었나?" → Yes라면 계획 실패. 오케스트레이션 로직 수정.

13.4 스티어링 루프: 사람의 역할

하네스 엔지니어링에서 사람의 역할은 "코드를 직접 짜는 것"이 아니라 "하네스를 조향(Steering)하는 것"입니다. 문제가 반복될 때마다 피드포워드와 피드백 제어를 개선하여, 그 문제가 미래에 발생할 확률을 구조적으로 낮춥니다.

13.5 관찰 가능성(Observability) 확보

하네스를 개선하려면 먼저 무슨 일이 일어나는지 봐야 합니다. 에이전트의 행동, 도구 호출, 토큰 사용량, 결정 지점을 로깅하세요. 완벽한 모니터링 대시보드가 아니어도 됩니다. 단순한 파일 기반 로깅만으로도 다음 개선 사이클을 위한 데이터를 충분히 확보할 수 있습니다.

실전 프로젝트 적용

14.1 하네스 구축 단계별 가이드

처음부터 완벽한 하네스를 만들 필요는 없습니다. 다음 단계를 따라 점진적으로 구축하세요.

Phase 1: 관찰 (1~2일)

먼저 단일 에이전트를 하네스 없이 실제 작업에 투입합니다. 로그를 읽고, 어디서 실패하는지, 어떤 패턴으로 잘못하는지 관찰합니다. 이 관찰이 하네스 설계의 출발점입니다.

Phase 2: 기본 CLAUDE.md 작성 (1일)

관찰된 문제를 기반으로 기본 규칙, 금지사항, 코딩 컨벤션을 담은 CLAUDE.md를 작성합니다. 핵심 규칙 20~30개면 충분합니다.

Phase 3: 피드백 센서 연결 (1~2일)

린터, 타입 체커, 테스트 스위트가 매 변경 후 자동으로 실행되도록 설정합니다. CLAUDE.md에 "매 수정 후 npm run lint && npm run test를 실행하라"고 명시합니다.

Phase 4: 가드레일 설정 (1일)

도구 허용 목록, 파일 접근 권한, 금지 명령어를 설정합니다. 가장 위험한 행동(프로덕션 DB 접근, 중요 파일 삭제 등)부터 차단합니다.

Phase 5: 스킬/참조 문서 추가 (지속적)

반복되는 작업 유형에 대해 스킬 파일을 작성합니다. 자주 참조하는 API 문서, 아키텍처 결정 기록(ADR)을 참조 문서로 추가합니다.

Phase 6: 반복 개선 (영구적)

매일 에이전트의 출력을 리뷰하고, 새로운 실패 패턴이 발견되면 하네스를 업데이트합니다. 이것은 일회성 설정이 아닌 지속적인 엔지니어링 실천입니다.

14.2 실전 디렉토리 구조

my-project/
├── CLAUDE.md                    # 전체 프로젝트 규칙
├── PROGRESS.md                  # 작업 진행 상태
├── .claude/
│   ├── settings.json            # 도구 권한, 가드레일
│   ├── agents/                  # 멀티 에이전트 정의
│   │   ├── analyst.md
│   │   ├── builder.md
│   │   └── qa.md
│   ├── skills/                  # 재사용 가능한 스킬
│   │   ├── code-review/
│   │   │   └── SKILL.md
│   │   ├── write-tests/
│   │   │   └── SKILL.md
│   │   └── deploy/
│   │       ├── SKILL.md
│   │       └── references/
│   │           └── deploy-checklist.md
│   └── memory/                  # 학습 메모리
│       └── lessons-learned.md
├── docs/
│   ├── architecture.md          # 아키텍처 문서
│   ├── api-spec.md              # API 명세
│   └── adr/                     # 아키텍처 결정 기록
│       ├── 001-auth-strategy.md
│       └── 002-db-choice.md
├── src/                         # 소스 코드
├── tests/                       # 테스트 코드
└── scripts/
    └── validate.sh              # 통합 검증 스크립트

14.3 통합 검증 스크립트 예시

#!/bin/bash
# 에이전트가 매 작업 완료 시 실행하는 통합 검증 스크립트

echo "=== Step 1: Lint Check ==="
npm run lint
if [ $? -ne 0 ]; then
  echo "❌ LINT FAILED - 모든 린트 에러를 수정하세요"
  exit 1
fi

echo "=== Step 2: Type Check ==="
npm run typecheck
if [ $? -ne 0 ]; then
  echo "❌ TYPE CHECK FAILED - 타입 에러를 수정하세요"
  exit 1
fi

echo "=== Step 3: Unit Tests ==="
npm run test
if [ $? -ne 0 ]; then
  echo "❌ TESTS FAILED - 실패한 테스트를 수정하세요"
  exit 1
fi

echo "=== Step 4: Build ==="
npm run build
if [ $? -ne 0 ]; then
  echo "❌ BUILD FAILED - 빌드 에러를 수정하세요"
  exit 1
fi

echo "✅ ALL CHECKS PASSED - 작업 완료 가능"

도구 · 프레임워크 생태계

15.1 주요 코딩 에이전트 도구

15.2 하네스 전문 프레임워크

15.3 하네스 품질 측정 도구

하네스의 효과를 측정하기 위해 다음 지표를 추적하세요.

15.4 유용한 피드백 센서 도구 목록

• 린터: ESLint, Pylint, Semgrep, RuboCop
• 타입 체커: TypeScript (tsc), mypy, Pyright
• 테스트: Jest, Pytest, Vitest, Playwright
• 아키텍처 검증: ArchUnit, dep-cruiser, Madge
• 보안 스캔: Snyk, Dependabot, CodeQL
• 코드 품질: SonarQube, Codeclimate
• 뮤테이션 테스팅: Stryker, mutmut

미래 전망과 학습 로드맵

16.1 하네스 엔지니어링의 미래 방향

자기 분석 하네스 (Self-Analyzing Harness)

AI가 AI를 최적화하는 메타 하네스가 등장하고 있습니다. 메타 에이전트가 작업 에이전트의 실행 로그를 읽고, 반복되는 실패 패턴을 식별하여, 하네스 자체를 자동으로 개선합니다. Stanford와 MIT의 Meta-Harness 연구에서는 이 접근이 수작업 하네스를 초월하는 벤치마크 성능을 달성했다고 보고합니다.

지속적 학습 메모리 (Continual Learning)

세션 간 단순 파일 기반 메모리를 넘어, 에이전트가 수주~수개월에 걸쳐 프로젝트 지식을 축적하는 장기 메모리 시스템이 발전하고 있습니다. 에이전트가 자신의 이전 실행 로그, 진행 파일, Git 히스토리를 읽고 "온보딩"하여, 랩업 시간을 며칠에서 초 단위로 줄입니다.

하네스 템플릿과 표준화

기업들이 반복적으로 사용하는 서비스 토폴로지(CRUD API, 이벤트 프로세서, 데이터 대시보드 등)에 대해 표준 하네스 템플릿이 만들어지고 있습니다. 팀이 기술 스택과 아키텍처를 선택할 때, "이미 좋은 하네스가 존재하는가"가 중요한 결정 기준이 될 것입니다.

프로토콜 표준화 (MCP 확산)

MCP(Model Context Protocol)가 OpenAI, Google DeepMind, 수천 개의 서드파티 서버에 채택되면서, 도구 연결 계층이 표준화되고 있습니다. 하네스가 어떤 데이터 소스나 도구에든 플러그인처럼 연결될 수 있는 미래가 빠르게 다가오고 있습니다.

16.2 하네스 엔지니어링 학습 로드맵

16.3 핵심 학습 자료

• Martin Fowler, "Harness Engineering for Coding Agent Users" — 개념의 체계적 정리, 피드포워드/피드백 프레임워크
• deepset AI, "Harness Engineering: How to Build Reliable AI Agents" — 실패 분류, 실무 구축 가이드
• Anthropic, "Claude Code Best Practices" — CLAUDE.md 작성법, 도구 설정, 공식 모범 사례
• revfactory/harness (GitHub) — 6가지 아키텍처 패턴, 팀 설계 실습
• OpenAI, "Harness Engineering" (공식 블로그) — OpenAI 내부팀의 하네스 사례

16.4 마치며: 새로운 역할의 탄생

하네스 엔지니어링은 AI 시대에 엔지니어의 역할이 어떻게 변화하고 있는지를 보여줍니다. 우리는 더 이상 "코드를 직접 짜는 사람"이 아니라, "에이전트가 올바르게 코드를 짜도록 환경을 설계하는 사람"이 되어가고 있습니다.

이 변화는 위협이 아닙니다. 인간 개발자가 가진 경험, 미적 감각, 조직적 맥락, 사회적 책임감 — 이런 것들은 모델이 가질 수 없는 것이며, 하네스를 통해 외부화할 수 있는 것이기도 합니다. 좋은 하네스 엔지니어는 "내 경험을 시스템으로 만드는 사람"입니다.

AI 에이전트의 시대에 오신 것을 환영합니다. 하네스 엔지니어링이 여러분의 생산성을 비약적으로 높여줄 것입니다. 모델은 계속 발전할 것이고, 좋은 하네스는 그 발전을 100% 활용할 수 있는 기반이 됩니다.