AI 자동화 하네스 완전 가이드 — 프롬프팅과 컨텍스트 엔지니어링으로 AI 워크플로우 구축하기 (2026년 3월 기준)

매번 같은 프롬프트를 복사해 붙여넣고, 조금씩 다듬고, 또 다른 도구에 같은 맥락을 다시 설명하는 작업을 반복하고 있다면 이 글이 도움이 될 것입니다. 2026년 현재, AI 자동화의 핵심은 모델 자체의 성능이 아니라 그 모델을 감싸는 하네스(harness) 설계에 달려 있습니다. 이 가이드에서는 하네스의 개념부터 실전 구축까지 Claude Code + CLAUDE.md 구조를 중심으로 단계별로 살펴봅니다.

AI 하네스란 무엇인가

AI 하네스(harness)는 원래 마차에서 말을 제어하기 위해 장착하는 장비입니다. AI 맥락에서도 의미가 같습니다. 거대언어모델(LLM)은 매 요청이 독립된 무상태(stateless) 시스템입니다. 하네스는 이 무상태 모델에 역할·기억·도구·검증을 덧씌워 지속적으로 작동하는 자동화 파이프라인으로 만들어줍니다.

2025년 발표된 논문 "Building Effective AI Coding Agents for the Terminal"은 하네스를 이렇게 정의합니다. "The runtime behavior is governed by the agent harness, the orchestration infrastructure that turns a stateless LLM into a persistent agent." 결국 하네스는 모델의 지능을 일관된 워크플로우로 묶어주는 오케스트레이션 인프라입니다.

개발자 도구(Claude Code), 콘텐츠 자동화 파이프라인, 고객 지원 봇까지 실제로 쓸 만한 AI 시스템은 모두 어떤 형태로든 하네스를 갖추고 있습니다. 하네스 없이 AI를 사용하면 매번 맥락을 처음부터 설명해야 하고, 결과의 품질이 요청마다 제각각이 됩니다.

하네스의 핵심 구성 요소

잘 설계된 하네스는 네 개의 레이어로 이뤄집니다. 각 레이어는 독립적으로 설계하고 교체할 수 있습니다. 아래에서 각 레이어의 역할과 실전 적용 방법을 살펴봅니다.

프롬프트 레이어

프롬프트 레이어는 AI에게 "당신은 누구이고 무엇을 해야 하는가"를 알려주는 레이어입니다. 시스템 프롬프트에서 역할과 제약을 선언하고, 작업 프롬프트에서 구체적인 요청을 전달합니다. 잘 작성된 시스템 프롬프트 하나가 수십 번의 반복 프롬프팅을 대체합니다.

컨텍스트 레이어

컨텍스트 레이어는 AI가 작업에 필요한 배경 지식을 갖출 수 있도록 정보를 주입하는 레이어입니다. CLAUDE.md 같은 프로젝트 설정 파일, 과거 작업 메모리, 외부 API 문서 등이 여기에 해당합니다. 컨텍스트가 풍부할수록 AI는 매번 처음부터 설명받지 않아도 됩니다.

도구/Action 레이어

도구 레이어는 AI가 실제 세계와 상호작용할 수 있게 해줍니다. 파일 읽기·쓰기, 웹 검색, API 호출, 터미널 명령 실행이 모두 여기에 포함됩니다. MCP(Model Context Protocol)는 도구 정의의 표준 인터페이스로, 한 번 구현하면 여러 AI 클라이언트에서 재사용할 수 있습니다.

검증/출력 레이어

검증 레이어는 AI 출력이 기대한 형식과 품질을 충족하는지 확인하는 레이어입니다. JSON 스키마 검사, 사실 확인 단계, 발행 전 사용자 승인 등이 여기에 포함됩니다. 검증 레이어가 없으면 AI가 잘못된 형식으로 출력을 내보내도 파이프라인이 그대로 진행됩니다.

프롬프팅 전략 설계

좋은 하네스는 좋은 프롬프팅 전략에서 시작합니다. 단순히 요청을 잘 쓰는 것이 아니라, 반복 사용 가능하고 AI가 자율적으로 판단할 수 있는 구조를 만드는 것이 목표입니다.

역할과 페르소나 정의

시스템 프롬프트의 첫 번째 역할은 AI에게 전문가 정체성을 부여하는 것입니다. "당신은 한국어 콘텐츠 에디터입니다"처럼 역할을 명확히 선언하면, AI는 그 역할에 맞는 판단 기준으로 모든 요청을 처리합니다. 역할이 모호하면 AI는 매 요청마다 다른 톤과 형식으로 응답합니다.

역할 정의에는 다음 세 가지를 포함하는 것이 좋습니다. 첫째, 전문 분야("성공지식백과의 한국어 AI 콘텐츠 에디터"). 둘째, 핵심 행동 원칙("사실 확인 후 작성, 추측 금지"). 셋째, 금지 행동("사용자 승인 없이 발행하지 않는다"). 이 세 가지가 갖춰지면 AI는 지시받지 않은 상황에서도 일관되게 행동합니다.

다음 주제로 블로그 글을 써주세요.

당신은 성공지식백과의 한국어 AI 콘텐츠 에디터입니다.
핵심 규칙:
- 리서치 먼저, 추측으로 쓰지 않는다
- docs/writing-style.md 문체 준수
- 발행 전 반드시 사용자 확인

다음 주제로 guide 타입 아티클을 작성하세요.

작업 분해와 위임

복잡한 작업을 하나의 프롬프트에 모두 담으면 품질이 떨어집니다. 하네스에서는 큰 작업을 독립 단계로 분해하고, 각 단계를 별도 AI 인스턴스(서브에이전트)에 위임하는 패턴을 사용합니다. 예를 들어 콘텐츠 자동화 파이프라인에서는 리서치 에이전트 → 작성 에이전트 → 검증 에이전트 → 발행 에이전트로 역할을 나눕니다.

서브에이전트 위임의 핵심 이점은 격리된 컨텍스트 창입니다. 각 서브에이전트는 자신의 작업에 필요한 도구와 지시만 갖고 시작합니다. 중간 과정의 토큰(검색 결과, 중간 추론 등)은 서브에이전트 안에서 소비되고, 메인 에이전트에는 최종 결과만 전달됩니다. 덕분에 메인 에이전트의 컨텍스트가 불필요하게 오염되지 않습니다.

출력 형식 명세

AI 출력을 다음 단계에서 자동으로 처리하려면 출력 형식을 미리 명세해야 합니다. "JSON으로 출력하라"는 것만으로는 부족합니다. 구체적인 스키마, 필드 이름, 배열 구조까지 예시로 보여주어야 합니다. 하네스 안에서 형식 명세가 명확할수록 파이프라인의 다음 단계가 안정적으로 실행됩니다.

컨텍스트 엔지니어링 적용

컨텍스트 엔지니어링은 AI가 요청을 처리할 때 참조하는 정보를 의도적으로 설계하는 작업입니다. 어떤 정보를 언제, 어떤 방식으로 AI에게 전달할지 결정하는 것이 핵심입니다. 모델의 성능이 같더라도 컨텍스트 설계가 좋으면 출력 품질이 크게 달라집니다.

CLAUDE.md — 프로젝트 컨텍스트 파일

CLAUDE.md는 Claude Code가 프로젝트 루트에서 자동으로 읽는 영구 컨텍스트 파일입니다. 아키텍처 결정, 코딩 규칙, 금지 패턴, 워크플로우 지시를 이 파일에 적어두면 매 세션마다 반복 설명 없이 AI가 프로젝트 문맥을 이해하고 시작합니다.

Claude Code 공식 문서는 CLAUDE.md에 코딩 스타일, 워크플로우 선호도, 자주 사용하는 명령 등을 기록할 것을 권장합니다. 프로젝트에 새로운 팀원이 합류했을 때 온보딩 문서처럼 작동하기도 합니다. 실제로 CLAUDE.md를 잘 작성해두면 AI에게 매번 "우리 프로젝트에서는 이렇게 합니다"라고 설명하는 시간이 사라집니다.

# [프로젝트명]

[프로젝트 한 줄 설명]

## 나의 역할

[AI에게 부여할 역할과 책임]

예:
- 주제를 받으면 웹 리서치 → 작성 → 검증 → 발행 순으로 처리
- 사용자 확인 없이 외부 API를 호출하지 않는다

## 도구

- **[MCP 도구명]** — [용도 설명]

## 핵심 규칙

1. **[규칙1]** — [설명]
2. **[규칙2]** — [설명]
3. **환경변수** — `$[변수명]`을 코드에 하드코딩하지 않는다

## 문서 참조 가이드

| 작업 | 읽을 문서 |
|------|----------|
| [작업명] | `docs/[파일명].md` |

작업 히스토리 관리

AI는 세션이 끊기면 이전 작업을 기억하지 못합니다. 하네스에서는 메모리 파일을 통해 이 문제를 해결합니다. 서브에이전트가 코드를 리뷰하면서 발견한 패턴과 규칙을 메모리 디렉터리에 축적하고, 다음 세션에서 그 내용을 참조합니다. Claude Code의 서브에이전트 시스템은 이 패턴을 지원합니다. 서브에이전트의 시스템 프롬프트에는 메모리 디렉터리의 MEMORY.md 첫 200줄이 자동으로 포함됩니다.

메모리 파일 관리의 핵심 원칙은 범위 지정입니다. 전체 프로젝트에 적용되는 규칙은 루트 CLAUDE.md에, 특정 서브에이전트에만 필요한 메모리는 해당 에이전트의 메모리 디렉터리에 분리해서 관리합니다. 범위가 넓을수록 컨텍스트 오염 위험도 커집니다.

외부 문서 주입

AI가 항상 최신 정보를 참조하려면 외부 문서를 컨텍스트에 동적으로 주입하는 메커니즘이 필요합니다. Context7 같은 MCP 도구는 라이브러리 공식 문서를 쿼리해서 현재 세션의 컨텍스트에 주입합니다. 직접 docs/ 디렉터리를 운영하면서 참조 가이드 파일을 관리하는 방식도 효과적입니다.

검증과 품질 관리

하네스에서 가장 자주 생략되는 레이어가 검증입니다. AI 출력을 그대로 파이프라인 다음 단계로 넘기면, 형식 오류 하나가 전체 워크플로우를 망가뜨립니다. 검증 레이어를 갖춘 하네스는 오류를 발행 전에 잡아냅니다.

검증은 세 단계로 구성하는 것이 좋습니다. 첫째, 형식 검증 — JSON 스키마 또는 스크립트로 필수 필드·타입을 확인합니다. 둘째, 사실 검증 — 부정 주장이나 중요 수치는 소스를 교차 확인합니다. 셋째, 사용자 승인 — 외부 API 호출이나 영구 변경 전에 최종 확인을 받습니다.

자동화 파이프라인이라도 사용자 승인 단계를 없애지 않는 것이 중요합니다. 완전 자동화는 매력적으로 보이지만, 한 번의 AI 오류가 실제 서비스에 영향을 미칠 수 있습니다. 중요한 행동(발행, 삭제, 외부 API 호출) 직전에 항상 사람이 개입하는 게이트를 유지해야 합니다.

실전 하네스 예시 — 성공지식백과 콘텐츠 자동화

지금까지 설명한 네 개 레이어를 실제 프로젝트에 적용한 예시로, 성공지식백과 콘텐츠 자동화 하네스를 살펴봅니다. 이 하네스는 주제를 받으면 웹 리서치 → 한국어 콘텐츠 작성 → JSON 변환 → 검증 → Sanity API 발행까지 전 과정을 처리합니다.

이 구조의 핵심은 docs/ 디렉터리입니다. CLAUDE.md에서 각 작업 단계마다 참조할 문서를 명시해두면, AI는 필요한 순간에 해당 파일을 읽어 컨텍스트를 업데이트합니다. 모든 규칙을 CLAUDE.md 하나에 넣지 않고 docs/로 분산해서 컨텍스트 창의 효율을 유지합니다.

# 프로젝트명
나의 역할: 주제 → 리서치 → 작성 → 발행

핵심 규칙:
1. 리서치 먼저 — 추측으로 쓰지 않는다
2. 발행 전 확인 — 사용자 승인 후 API 호출

claude mcp add open-websearch npx @open-websearch/mcp-server
claude mcp add context7 npx @context7/mcp-server

python3 scripts/validate.py output/draft.json
# 에러 0건 → 발행 진행
# 에러 있음 → AI에게 수정 요청

이 하네스를 운영하면서 배운 가장 중요한 교훈은, 하네스가 AI를 "제어"하는 도구가 아니라 AI와의 협업 계약서라는 점입니다. 규칙을 구체적으로 쓸수록 AI는 더 자율적으로, 더 예측 가능하게 행동합니다.

멀티에이전트 패턴으로 확장

단일 에이전트 하네스를 충분히 익혔다면, 다음 단계는 멀티에이전트 패턴입니다. 복잡한 작업을 병렬로 처리하거나, 모델을 역할별로 다르게 라우팅하는 구조입니다.

Anthropic의 멀티에이전트 연구 시스템은 이 패턴을 실전에서 사용합니다. Claude Opus 4.6이 오케스트레이터로 전략을 세우고, Claude Sonnet 4.6 서브에이전트들이 병렬로 실행합니다. 비싼 프론티어 모델은 계획과 판단을, 작고 빠른 모델은 실행을 담당합니다. 덕분에 전체 비용을 낮추면서도 출력 품질을 유지합니다.

자주 묻는 질문

AI 하네스 설계는 한 번에 완성되지 않습니다. 처음에는 간단한 CLAUDE.md 하나로 시작하고, 실제 사용하면서 규칙을 추가하고, 반복되는 오류 패턴을 발견할 때마다 개선해 나가는 과정입니다. 하네스가 성숙해질수록 AI는 더 자율적으로, 더 일관되게 작동합니다.

2026년 현재, 모델의 성능 차이보다 하네스 설계의 차이가 실제 AI 활용 결과를 더 크게 좌우합니다. 더 나은 모델을 기다리는 시간에 지금 있는 모델로 더 나은 하네스를 만드는 것이 훨씬 빠른 길입니다.

관련 가이드