하네스 엔지니어링 활용편 — 내 프로젝트에 당장 적용하는 법

개념을 이해했고(3편), Anthropic의 구현을 살펴봤다(4편). 이제 남은 질문은 하나다. 내 프로젝트에 어떻게 적용하는가?

이 글에서는 하네스 엔지니어링을 실무에 활용하는 구체적인 방법과, 이 패러다임이 가져올 개발자 역할의 변화를 다룬다.

원칙 1: 실패에서 시작하라

Mitchell Hashimoto의 원칙이자, HumanLayer 팀이 독립적으로 같은 결론에 도달한 것.

이상적인 하네스를 미리 설계하려 하지 마라. 에이전트가 실패할 때마다, 그 실패를 구조적으로 방지하는 장치를 추가하라.

HumanLayer 팀의 표현: "출하 편향을 가져라. 에이전트가 실제로 실패한 경우에만 하네스를 건드려라."

이것은 TDD(Test-Driven Development)의 사고방식과 닮아 있다. 실패하는 테스트를 먼저 만들고, 그것을 통과시키는 코드를 작성하는 것처럼 — 에이전트가 실패하는 패턴을 관찰하고, 그것을 방지하는 하네스 요소를 추가한다.

ETH Zurich의 연구가 이 원칙을 뒷받침한다. 138개 에이전트 설정 파일을 테스트한 결과:

LLM이 생성한 설정 파일: 성능 저하 + 비용 20% 이상 증가
사람이 작성한 설정 파일: 겨우 4% 개선
코드베이스 개요, 디렉터리 목록: 아무 도움도 안 됨

에이전트는 저장소 구조를 스스로 충분히 탐색한다. 핵심은 보편적으로 적용되는 최소한의 지침만 투입하는 것이다.

원칙 2: 적게 넣어라

하네스 엔지니어링에서 가장 반직관적인 원칙이다. 더 많은 규칙, 더 많은 도구, 더 많은 에이전트가 항상 더 나은 결과를 만들지 않는다.

Vercel의 사례: 초기에 모든 도구를 제공했지만, 도구를 줄이자 오히려 성능이 향상됐다.

MCP 서버를 많이 연결하면? 도구 정의 자체가 시스템 프롬프트의 토큰을 소비한다. 200K 컨텍스트 윈도우가 MCP 도구가 너무 많으면 실제로는 70K밖에 안 될 수 있다.

HumanLayer의 해결책: Linear MCP 서버 대신 핵심 기능만 감싼 경량 CLI를 제작했다. 수천 토큰을 절약했다.

권장사항: CLI가 이미 훈련 데이터에 충분히 포함된 도구(GitHub, Docker, 데이터베이스 등)라면, MCP 서버 대신 CLI를 쓰도록 프롬프트하는 것이 더 효율적이다.

1단계: 컨텍스트 파일 작성

가장 먼저 할 일은 프로젝트 루트에 컨텍스트 파일을 만드는 것이다. Claude Code에서는 CLAUDE.md, OpenAI Codex에서는 AGENTS.md다.

## 빌드

- `npm run dev`로 개발 서버 실행
- `npm test`로 테스트 실행
- `npm run build`로 프로덕션 빌드

## 코딩 규칙

- TypeScript strict 모드 사용
- React 컴포넌트는 함수형으로 작성
- 상태 관리는 Zustand 사용
- API 호출은 React Query로 캐싱

## 아키텍처

- 패키지 의존 방향: types → utils → hooks → components → pages
- 역방향 의존 금지
- 공유 컴포넌트는 src/components/shared/에 배치

## 커밋

- Conventional Commits 규칙 준수
- 커밋 메시지는 한국어, 마침표 없이 작성

핵심: 처음에는 짧게 시작한다. 에이전트가 반복적으로 틀리는 부분이 있으면 해당 규칙을 추가해나간다. Mitchell Hashimoto의 접근과 동일하다 — "에이전트가 실수할 때마다 같은 실수를 방지하는 지시를 쌓아가는 것."

디렉토리별 분산

프로젝트가 커지면 하나의 거대한 파일은 비효율적이다. Claude Code는 디렉토리별 CLAUDE.md를 지원한다. 에이전트가 특정 디렉토리에서 작업할 때 해당 디렉토리의 규칙만 로드된다.

project/
├── CLAUDE.md              # 전역 규칙 (빌드, 커밋, 코딩 스타일)
├── src/
│   ├── CLAUDE.md          # src 전용 규칙
│   ├── components/
│   │   └── CLAUDE.md      # 컴포넌트 작성 규칙
│   └── api/
│       └── CLAUDE.md      # API 레이어 규칙
└── tests/
    └── CLAUDE.md          # 테스트 작성 규칙

OpenAI 팀이 발견한 것처럼, AGENTS.md를 **목차(Map)**로 취급하고 근처 지시 파일만 읽도록 구조화하는 것이 효과적이다.

2단계: MCP 연결 (선별적으로)

에이전트가 자주 참조하는 외부 시스템을 MCP(Model Context Protocol)로 연결한다.

# GitHub 연결
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

# 데이터베이스 연결
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres

# 브라우저 자동화 (Playwright)
claude mcp add --transport stdio playwright -- npx -y @anthropic/mcp-playwright

하지만 필요한 것만 선별적으로 연결한다. 도구 정의 자체가 토큰을 소비한다는 것을 항상 기억하라.

권장 설정:

전체 MCP 서버: 20~30개 이하
동시 활성화: 10개 미만
활성 도구: 80개 미만

GitHub, Docker, 기본적인 데이터베이스 CLI는 이미 모델의 훈련 데이터에 충분히 포함되어 있다. MCP 서버로 감싸는 것보다 CLI를 직접 사용하도록 프롬프트하는 것이 토큰을 절약한다.

3단계: 훅 설정

에이전트의 행동에 자동화된 검증과 피드백을 추가한다.

필수 훅: 코드 품질 자동 검증

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx biome check --write $FILE_PATH",
        "description": "파일 수정 후 자동 포맷팅"
      },
      {
        "matcher": "Edit|Write",
        "command": "npx tsc --noEmit",
        "description": "TypeScript 타입 체크"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo $COMMAND | grep -q '\\-\\-no-verify' && exit 1 || exit 0",
        "description": "git commit --no-verify 차단"
      }
    ]
  }
}

추천 훅: 세션 학습

{
  "hooks": {
    "Stop": [
      {
        "command": "node scripts/evaluate-session.js",
        "description": "세션 종료 시 학습 가능한 패턴 추출"
      }
    ],
    "SessionStart": [
      {
        "command": "node scripts/load-context.js",
        "description": "이전 세션 컨텍스트 로딩"
      }
    ]
  }
}

훅의 핵심 가치: 에이전트 행동 중에 자동으로 실행되며, Claude에게 보이지 않는다. 우회할 수 없는 강제력을 가진다.

4단계: 점진적 작업 강제

Anthropic이 발견한 가장 큰 개선 사항이다. 한 번에 하나의 기능만 작업하게 강제하라.

구현 방법:

각 작업 완료 후 Git 커밋을 강제
진행 노트를 남기게 지시
다음 세션이 깨끗한 상태에서 시작할 수 있도록 설계

이것을 CLAUDE.md에 이렇게 기술할 수 있다:

## 작업 방식

- 한 번에 하나의 기능만 작업한다
- 기능 구현 완료 후 반드시 Git 커밋한다
- 커밋 전에 관련 테스트를 실행하고 통과를 확인한다
- 여러 기능을 동시에 수정하지 않는다
- 작업 시작 전 현재 상태를 확인한다 (git status, 테스트 실행)

OpenAI 팀도 동일한 발견을 했다: "에이전트가 고전하면 그것을 신호로 삼아라. 무엇이 빠져 있는지(도구, 가드레일, 문서) 파악하고, 에이전트가 직접 수정하게 하라."

5단계: 서브 에이전트 활용

복잡한 작업은 서브 에이전트로 분리한다. 목적은 역할 분담이 아니라 컨텍스트 격리다.

효과적인 서브 에이전트 프롬프트 작성법

나쁜 예: "이 버그를 조사해줘"
좋은 예: "src/auth/session.ts의 refreshToken 함수에서 만료 토큰 
갱신 시 race condition이 의심된다. 동시 요청 시나리오를 분석하고, 
문제가 확인되면 mutex 또는 debounce 패턴으로 수정안을 제시해라."

핵심은 쿼리뿐 아니라 목적(objective context)을 함께 전달하는 것이다. 서브 에이전트는 상위 에이전트의 대화 맥락을 모른다. 방금 방에 들어온 똑똑한 동료처럼 브리핑해야 한다.

모델 선택 전략

작업 유형에 따라 서브 에이전트의 모델을 다르게 할당한다:

작업 유형	추천 모델	이유
코드 탐색/검색	Haiku	빠르고 저렴
일반 코딩 (90%)	Sonnet	비용 대비 성능
아키텍처/보안 리뷰	Opus	깊은 추론 필요
문서 작성	Haiku	간단한 생성 작업
복잡한 디버깅	Opus	다단계 추론 필요

반복 검색 패턴

서브 에이전트의 결과가 불충분할 때:

오케스트레이터가 서브 에이전트 반환값 평가
후속 질문 전달
서브 에이전트가 추가 조사 후 반환
충분해질 때까지 반복 (최대 3회)

6단계: 린터와 CI 연동

생성 코드가 기존 아키텍처 규칙을 따르는지 자동으로 검증한다. 이미 있는 린터와 CI를 에이전트가 읽을 수 있도록 연결하면, CI 실패 로그를 보고 스스로 수정하는 피드백 루프가 형성된다.

## CI 연동 (CLAUDE.md에 추가)

- PR 생성 전 `npm run lint && npm test && npm run build` 실행
- CI 실패 시 로그를 읽고 자동 수정 시도
- 린트 에러는 절대 무시하지 않는다
- 타입 에러가 있는 상태로 커밋하지 않는다

OpenAI 팀이 강조한 기계적 강제: 프롬프트로 "이렇게 하라"고 지시하는 것보다, 린터와 테스트로 위반을 차단하는 것이 훨씬 효과적이다. 에이전트는 지시를 무시할 수 있지만, 린터 에러는 무시할 수 없다.

7단계: 관찰 가능성 도구 제공

에이전트에게 자기 작업을 디버깅할 수 있는 도구를 제공한다.

로그 접근: 에이전트가 생성한 코드의 런타임 로그를 직접 읽을 수 있게 한다
브라우저 자동화: Playwright MCP로 실제 화면을 확인하게 한다
메트릭 접근: 성능 데이터, 에러 비율 등을 확인하게 한다

Anthropic이 Puppeteer MCP를 제공했을 때 발생한 일: 코드만 봐서는 발견할 수 없었던 브라우저 네이티브 얼럿 모달 관련 버그를 에이전트가 직접 찾아 수정했다. "기능 완료"를 선언하기 전에 실제 사용자처럼 테스트하게 만드는 것이 핵심이다.

보안: 반드시 지켜야 할 것들

하네스가 강력해질수록 보안 위험도 커진다.

Anthropic의 최소 보안 기준

에이전트 ID를 개인 계정과 분리
단기 스코프 자격 증명 사용
비신뢰 작업은 컨테이너/VM에서 격리 실행
아웃바운드 네트워크 기본 차단
비밀 정보가 담긴 경로 접근 제한
파일/HTML/스크린샷 정제 후 전달
도구 호출, 승인, 네트워크 시도 로깅
프로세스 그룹 킬과 데드맨 스위치 구현

실제 발생한 보안 사고

CVE-2025-59536 (CVSS 8.7): startup trust dialog 구현 버그로 코드 조기 실행. v1.0.111에서 수정
CVE-2026-21852: ANTHROPIC_BASE_URL 악용으로 신뢰 확인 전 API 요청 가능. v2.0.65에서 수정
Snyk ToxicSkills 보고서: 공개된 3,984개 스킬 중 36%에서 프롬프트 인젝션 발견

Anthropic의 철학: "악의적인 텍스트가 컨텍스트에 들어올 것을 전제하고 만들어라. 도구 설명이 거짓말할 수 있다고 전제하고 만들어라. 모델이 악의적 입력에 설득당하더라도 시스템이 안전하게 동작하도록 만들어라."

미래: 하네스 엔지니어링이 바꾸는 것들

하네스의 서비스 템플릿화

Thoughtworks의 Birgitta Böckeler가 제기한 질문이 흥미롭다. 대부분 조직은 2~3개의 주요 기술 스택만 사용한다. 모든 애플리케이션이 고유한 눈송이는 아니다.

가능한 미래: 애플리케이션 유형별로 미리 갖춘 하네스를 출발점으로, 팀이 점진적으로 맞춤화하는 서비스 템플릿 시스템.

이미 이 방향의 프로젝트가 등장하고 있다:

agent-skills (Google Cloud AI 디렉터 Addy Osmani): 19개 구조화된 스킬
GBrain (YC CEO Garry Tan): 개인 지식 베이스, 20개 MCP 도구 내장
Awesome Design.MD: 60개 이상 서비스 디자인 시스템을 마크다운으로 패키징

기술 스택 선택 기준의 변화

현재: "개발자 경험이 좋은 프레임워크"를 선택한다.
미래: **"좋은 하네스가 갖춰진 프레임워크"**를 선택하게 될 수 있다.

"AI 친화성"이 프레임워크 선택의 핵심 기준이 되는 것이다. 개발자 개인 취향이나 인터페이스의 사소한 비효율은 덜 중요해진다.

자기 개선 하네스

Meta AI의 HyperAgents 연구: 에이전트가 스스로 하네스를 설계하는 자기참조적 프레임워크. 영속 메모리, 성능 추적, 다단계 검증 파이프라인을 자동 구축한다.

LangChain이 탐구 중인 방향:

병렬 오케스트레이션: 수백 개의 에이전트가 공유 코드베이스에서 병렬 작업
자기 개선 루프: 에이전트가 자신의 실행 트레이스를 분석해 하네스 수준의 실패 원인을 스스로 찾아 수정
적응형 하네스: 사전 구성 없이 작업에 따라 동적으로 도구와 컨텍스트를 조립

레거시 코드의 격차

AI 에이전트와 함께 처음부터 만든 코드베이스와, 하네스 이전 시대의 레거시 코드베이스 사이에 격차가 생긴다.

레거시에 하네스를 소급 적용하는 것은 정적 분석 도구를 처음 돌려보는 것과 비슷하다. 경고 메시지의 홍수가 예상된다. 하지만 어딘가에서 시작해야 한다.

지금 당장 시작하는 체크리스트

복잡하게 생각하지 말자. 오늘 할 수 있는 것부터 시작하면 된다.

즉시 적용 가능:

프로젝트 루트에 CLAUDE.md 작성 (빌드 명령어, 코딩 규칙, 커밋 컨벤션)
에이전트가 실수할 때마다 해당 규칙을 CLAUDE.md에 추가
git commit --no-verify 차단 훅 설정

1주일 안에 적용:

파일 수정 후 자동 포맷팅/타입체크 훅 추가
필요한 MCP 서버 선별적 연결 (3~5개)
서브 에이전트를 활용한 작업 분리 시도

1달 안에 적용:

디렉토리별 CLAUDE.md 분산
CI/CD 파이프라인과 에이전트 피드백 루프 연결
세션 간 상태 관리 패턴 도입 (진행 파일, 기능 리스트)
보안 체크리스트 점검

마무리: 병목은 모델이 아닌 환경이다

세 편에 걸쳐 하네스 엔지니어링을 다뤘다. 개념(3편), 구현(4편), 활용(5편).

핵심은 하나다. 에이전트 성능의 병목은 모델 지능이 아니라 환경 설계인 경우가 많다.

모델 성능은 빠르게 상향 평준화되고 있다. GPT가 앞서면 Claude가 따라오고, Claude가 앞서면 Gemini가 따라온다. 하지만 하네스는 팀이 직접 쌓아야 하는 자산이다. 도구 연결, 에러 복구 로직, 아키텍처 제약, 문서 구조 — 이것들은 범용 모델처럼 한 번에 배포되지 않는다.

1년 전, 이 시리즈의 1편에서 프롬프트 엔지니어링의 퇴장을 이야기했다. 그때 예감했던 것이 현실이 됐다. 변화의 주기는 6개월에서 한 주로 줄었고, 중요한 것은 AI에게 무엇을 물어보느냐가 아니라, AI가 올바르게 일할 수 있는 환경을 어떻게 만드느냐가 됐다.

"코드를 짜는 엄밀함"이 "환경을 설계하는 엄밀함"으로 이동하고 있다.

우리는 지금 그 전환의 한가운데에 있다. 그리고 하네스 엔지니어링은 그 전환에서 가장 실용적인 출발점이다.

코딩 에이전트가 기대만큼 작동하지 않으면, 모델을 탓하기 전에 하네스를 점검하라. 답은 거의 항상 거기에 있다.

사랑을 직접 올리지 않는 설계

- 4월 09, 2026

자세한 내용 보기

이 블로그 검색

goldtag