Claude Code로 프로덕션 AI 에이전트 하네스 구축하기 — 1시간 마스터클래스 핵심 요약과 실전 팁

인공지능 코딩 에이전트가 단순한 코드 완성 도구를 넘어 자율적인 소프트웨어 엔지니어링 파트너로 진화하면서, 에이전트가 복잡한 장기 태스크를 안전하고 일관되게 완수할 수 있도록 통제하는 '에이전트 하네스(Agent Harness)' 아키텍처의 중요성이 그 어느 때보다 부각되고 있습니다. 개발자 @iiiichigo_chan(Ichigo)은 Anthropic 시니어 엔지니어가 직접 진행한 1시간 분량의 프로덕션 에이전트 하네스 마스터클래스 강의를 소개하며, 값비싼 에이전트 엔지니어링 강의를 대체할 핵심 아키텍처 요약과 실전 구축 가이드를 공유했습니다.

이미지 출처: Anthropic / YouTube (@iiiichigo_chan)

이번 강의는 Claude Code의 내부 동작 원리부터 시작하여 장기 태스크 제어를 위한 CLAUDE.md 설정, 반복 작업을 자동화하는 스킬(Skills) 모듈화, 독립된 서브에이전트 분할, 그리고 공식 Agent SDK를 활용한 자율 복구 피드백 루프까지 실무 프로덕션 환경에서 검증된 5대 핵심 커리큘럼을 다룹니다.

Claude Code 하네스의 내부 동작 원리와 Plan Mode

프로덕션 에이전트 하네스를 구축하기 위한 첫 번째 단계는 Claude Code가 터미널 환경에서 모델 컨텍스트와 도구 호출(Tool Calling)을 어떻게 조율하는지 그 내부 루프를 이해하는 것입니다.

Claude Code는 단순한 챗봇 인터페이스가 아니라, 도구 실행 결과와 에러 스택 트레이스를 다시 모델의 입력으로 환류시키는 순환 실행 하네스(Loop Execution Harness) 구조를 갖추고 있습니다. 이때 컨텍스트 윈도우 오염과 환각 누적을 방지하기 위해 핵심적인 역할을 수행하는 것이 바로 CLAUDE.md와 Plan Mode입니다.

• 계층형 컨텍스트 관리(CLAUDE.md): 에이전트가 프로젝트 루트에 진입할 때 가장 먼저 읽는 최상위 지침서로, 코딩 스타일, 절대 금지 사항, 테스트 실행 규약, 아키텍처 불변식을 명시합니다. 장기 세션에서도 모델이 프로젝트의 의사결정 경계를 이탈하지 않도록 구속하는 역할을 합니다.
• Plan Mode를 통한 사전 설계와 실행 분리: 복잡한 기능을 구현할 때 코드를 즉시 작성하지 않고, 먼저 문제를 분해하여 단계별 실행 계획(Plan)을 수립하도록 강제합니다. 사용자의 승인이나 내부 검증 게이트를 통과한 계획에 대해서만 실제 코드 수정 작업을 시작함으로써 불필요한 시행착오와 토큰 낭비를 원천 차단합니다.

반복 워크플로우의 재사용 가능한 스킬 모듈화와 서브에이전트 분할

강의의 중반부(23:38~44:01)에서는 에이전트의 작업 효율성을 극대화하기 위한 두 가지 핵심 설계 패턴으로 '스킬(Skills) 모듈화'와 '서브에이전트(Sub-agents) 분할'을 제시합니다.

동일한 검증 루프나 배포 절차, 특정 라이브러리 연동 코드를 매 세션마다 프롬프트로 장황하게 지시하는 것은 심각한 컨텍스트 낭비와 비결정적 결과를 초래합니다.

1. 워크플로우의 스킬(Skill) 캡슐화: 반복되는 빌드, 린트, 스모크 테스트, 특정 API 호출 시퀀스를 독립된 스킬 파일(SKILL.md 또는 실행 스크립트)로 추출합니다. 에이전트는 복잡한 세부 지침을 프롬프트 전체에 상시 유지할 필요 없이, 필요한 순간에만 해당 스킬을 온디맨드로 로드하여 실행합니다.
2. 독립 컨텍스트를 가진 서브에이전트 위임: 메인 에이전트가 탐색, 분석, 테스트, 문서화 등 모든 책임을 한 세션 안에서 처리하려고 하면 컨텍스트가 급격히 비대해집니다. 따라서 코드 분석가, QA 테스터, 아키텍처 검토관 등 역할별 서브에이전트를 생성하고, 메인 에이전트는 작업 분해와 최종 취합에만 집중하는 위임 구조를 구축해야 합니다.

Agent SDK 기반 피드백 루프와 자율 오류 복구 시스템

마스터클래스의 후반부(59:34)는 에이전트 팀 구성과 Anthropic의 공식 Agent SDK를 활용한 자체 치유(Self-recovering) 루프 구축을 집중적으로 다룹니다.

프로덕션 환경에서 가장 위험한 실패는 에이전트가 잘못된 코드를 작성하고도 이를 인지하지 못한 채 작업을 완료했다고 보고하는 '침묵형 오류'입니다. 이를 방지하기 위해서는 결정론적 검증 게이트와 피드백 루프가 필수적입니다.

• 결정론적 검증 게이트(Deterministic Verification): 에이전트가 작업 완료를 선언하기 전, 하네스 차원에서 실제 빌드 명령어(tsc, npm run build), 단위 테스트, 정적 타입 체크를 자동으로 강제 실행합니다.
• 실패 증거 기반 자체 복구(Self-Recovery): 테스트가 실패했을 때 모델에게 단순한 재시도를 요청하는 것이 아니라, 실패한 표준 에러(stderr), 구체적 파일 경로와 라인 번호, 기대값과 실제값의 차이를 구조화된 피드백으로 에이전트에게 다시 주입합니다. 에이전트는 제공된 에러 증거를 바탕으로 가설을 수정하고 코드를 교정하는 자율 복구 사이클을 가동합니다.
• Agent SDK를 활용한 프로덕션 팀 오케스트레이션: 다수의 전문 에이전트가 상호 감시하고 교차 검증할 수 있도록 상태 관리와 메시지 패싱을 표준화하여, 사람의 지속적인 개입 없이도 높은 완성도의 산출물을 배포할 수 있는 기반을 마련합니다.

이와 같은 하네스 엔지니어링 기법은 최신 프론티어 모델의 높은 지능을 실제 안정적인 소프트웨어 개발 프로덕션으로 전환하는 데 있어 가장 강력한 실전 프레임워크를 제공합니다.

원문 출처

• @iiiichigo_chan (Ichigo) X 포스트: Anthropic 시니어 엔지니어의 프로덕션 에이전트 하네스 마스터클래스 핵심 요약과 타임스탬프 가이드
• Anthropic 공식 유튜브 마스터클래스: Building Production-Grade AI Agent Harnesses with Claude Code
• WaveSpeed 기술 블로그 심층 분석: Claude Code Agent Harness: Architecture Breakdown & System Deep Dive