대부분의 Claude 에이전트 튜토리얼은 "hello world" 수준에서 끝납니다.
도구를 호출하는 방법, 기본 루프를 설정하는 방법, 간단한 장난감 작업에 대해 자율적으로 응답하는 방법을 보여줍니다.
그런 다음 실제 무언가를 만들려고 하면 모든 것이 산산조각납니다.
작업이 너모 모호합니다. 에이전트가 막힙니다. 출력이 일관되지 않습니다. 세션이 종료되고 아무것도 저장되지 않습니다. 다음 번에 처음부터 다시 시작해야 합니다.
튜토리얼에서 작동하는 Claude 에이전트와 프로덕션에서 작동하는 Claude 에이전트 사이의 차이는 Claude의 역량 차이가 아닙니다.
에이전트가 어떻게 설계되었는지의 차이입니다.
이 가이드는 그 차이를 완전히 메워줍니다.
이 가이드를 마치면 실제 워크플로우를 안정적으로 실행하는 Claude 에이전트를 갖게 됩니다. 데모가 아닙니다. 장난감 작업이 아닙니다. 일관된 출력을 생성하고, 예외 상황을 우아하게 처리하며, 시간이 지남에 따라 개선되고, 사용자가 모든 단계를 직접 시작하지 않아도 실행되는 워크플로우입니다.
실제 에이전트를 다르게 만드는 요소
무엇을 만들기 전에 실제 에이전트와 튜토리얼 에이전트를 구분하는 요소를 이해하십시오.
튜토리얼 에이전트는 깨끗한 입력으로 깨끗한 작업을 실행하고 깨끗한 출력을 생성합니다. 작업이 잘 정의되어 있습니다. 입력이 정확히 예상된 형식으로 제공됩니다. 예상치 못한 일은 발생하지 않습니다. 성공 여부는 명확하고 이분법적입니다.
실제 에이전트는 지저분한 입력으로 지저분한 작업을 실행하고 어쨌든 유용한 출력을 생성해야 합니다. 작업이 부분적으로 정의되어 있습니다. 입력이 다양한 형식으로 도착합니다. 예상치 못한 일이 정기적으로 발생합니다. 성공은 정도의 문제이며 평가에 판단력이 필요합니다.
네 가지 속성이 에이전트가 실제 세계와의 접촉에서 살아남을 수 있는지 결정합니다.
견고한 작업 정의. 에이전트는 무엇을 해야 할 뿐만 아니라 실제로 직면하게 될 작업의 20가지 변형을 어떻게 처리해야 하는지 알고 있습니다. 지침은 해피 패스뿐만 아니라 예외 상황도 다룹니다.
영구 메모리. 에이전트는 세션 간에 컨텍스트를 축적합니다. 지난주에 했던 작업이 오늘 하는 작업에 정보를 제공합니다. 매 세션마다 처음부터 시작하지 않습니다.
우아한 실패 처리. 문제가 발생하면 에이전트는 중단하지 않고 복구합니다. 발생한 상황을 기록하고, 대안을 시도하며, 복구가 불가능할 때만 사람에게 알립니다.
품질 자체 검증. 에이전트는 출력을 전달하기 전에 정의된 기준에 대해 자체 출력을 확인합니다. 처음에 생성한 것을 그대로 반환하지 않고 자체 피드백 루프를 닫습니다.
대부분의 튜토리얼 에이전트는 이러한 속성 중 어느 것도 갖추지 못했습니다. 이 가이드는 네 가지를 모두 구축합니다.
에이전트 아키텍처
아키텍처는 함께 작동하는 네 가지 구성 요소로 구성됩니다.
작업 정의 계층
작업, 프로세스, 예외 상황 처리 및 품질 기준을 정의하는 구조화된 스킬 파일입니다. 이것은 프롬프트가 아닙니다. 에이전트가 모든 실행 전에 읽는 완전한 운영 사양입니다.
메모리 계층
에이전트가 수행한 작업, 학습한 내용, 세션 간에 기억해야 할 사항을 저장하는 영구 데이터베이스입니다. Hermes Agent를 통해 SQLite 기반으로 구축되거나 파일 기반 로깅으로 수동 구현됩니다.
실행 계층
실제 작업을 수행하는 실제 Claude API 호출입니다. 워크플로우의 각 단계에 적합한 모델, 적절한 컨텍스트 및 올바른 도구를 사용하도록 구성됩니다.
품질 계층
출력을 전달하기 전에 정의된 기준에 대해 확인하고, 출력이 기준에 미치지 못할 경우 특정 수정 사항을 포함하여 재시도하는 검증 루프입니다.
기초 설정하기
필요한 도구 설치하기:
Hermes Agent 설치 (오케스트레이션 및 메모리용)
git clone https://github.com/NousResearch/hermes-agent
cd hermes-agent
npm install
도구 액세스를 위한 MCP 서버 설치
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-brave-search
환경 구성하기:
핵심 구성
MODEL_PROVIDER=anthropic
MODEL_NAME=claude-opus-4-8
ANTHROPIC_API_KEY=your-api-key-here
메모리 구성 — 절대 경로 사용
MEMORY_BACKEND=sqlite
MEMORY_PATH=/Users/yourname/agent-data/memory.db
스케줄러 구성
ENABLE_SCHEDULER=true
SCHEDULER_TIMEZONE=America/New_York
출력 구성 — 결과가 저장되는 위치
OUTPUT_PATH=/Users/yourname/agent-outputs
실패 복구
SKILL_RETRY_ENABLED=true
SKILL_RETRY_MAX=3
SKILL_RETRY_DELAY=300
알림
NOTIFICATION_GATEWAY=telegram
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id
CLAUDE.md 작성하기:
이것은 전체 설정에서 가장 중요한 파일입니다. 모든 에이전트 세션은 이 파일을 읽는 것으로 시작합니다. 모든 출력의 품질은 여기에 얼마나 구체적으로 작성되었는지에 달려 있습니다.
에이전트 구성 — CLAUDE.md
정체성 및 목적
[이 에이전트가 하는 일을 한 문단으로 구체적으로 설명하십시오.
Claude가 일반적으로 무엇인지가 아닙니다. 이 특정 에이전트가
이 특정 운영을 위해 무엇을 하도록 구성되었는지 설명하십시오.]
운영 컨텍스트
[이 에이전트가 운영되는 비즈니스 또는 개인 컨텍스트를 설명하십시오.
이 에이전트를 구성한 사람은 무엇을 합니까?
그들의 기준과 우선순위는 무엇입니까?]
현재 활성 작업
[이 에이전트가 실행하는 특정 반복 작업을 나열하십시오.
각각에 대해: 무엇을 하는지, 언제 실행되는지, 좋은 출력이 어떻게 보이는지.]
도구 권한
다음 도구를 자율적으로 사용할 권한이 있습니다:
- 파일 시스템: [특정 경로]에 대한 읽기 및 쓰기
- 웹 검색: [특정 주제]에 대한 연구용
- [특정 범위를 가진 기타 도구]
다음은 해서는 안 됩니다:
- 구성된 출력 디렉토리 외부의 경로에 쓰기
- 위에 나열되지 않은 외부 API 호출
- 명시적 승인 없이 외부 시스템에 영향을 미치는 모든 조치
품질 기준
[각 작업 유형에 대해 좋은 출력이 어떻게 보이는지 설명하십시오.
가능한 경우 예시를 포함하십시오.
에이전트가 자체 평가할 수 있을 만큼 구체적으로 작성하십시오.]
메모리 지침
다음을 메모리에 저장하십시오:
- 날짜 및 품질 평가를 포함한 모든 중요한 출력
- 발생한 모든 예외 상황 및 처리 방법
- 모든 품질 실패 및 그 원인
- 출력 전반에서 식별된 모든 패턴
오류 처리
도구 실패 시: 한 번 재시도하고, 실패를 기록한 후, 사용 가능한 도구로 계속 진행하십시오.
품질 실패 시: 완전한 재작성이 아닌 특정 수정 사항을 포함하여 재시도하십시오. 최대 세 번 재시도하십시오.
복구 불가능한 실패 시: 부분 작업을 저장하고, 특정 실패를 기록한 후, 알림을 보내고, 정상적으로 중지하십시오.
작업 정의 계층 구축하기
작업 정의 계층은 대부분의 실제 에이전트가 실패하는 부분입니다.
사람들은 해피 패스를 설명하는 프롬프트를 작성하고 거기서 멈춥니다. 에이전트는 해피 패스를 잘 처리하지만 다른 모든 것에서는 실패합니다.
견고한 작업 정의는 작업의 전체 운영 현실을 다룹니다. 템플릿은 다음과 같습니다:
[작업 이름]
목적
[한 문장: 이 스킬은 무엇을 달성합니까?]
트리거
[이것이 실행되게 하는 정확한 조건:
예약된 시간, 파일 출현, 수동 명령 등]
실행 전 검사
시작하기 전에 다음을 확인하십시오:
- [필요한 입력이 존재하고 액세스 가능한지]
- [필요한 도구가 연결되어 응답하는지]
- [출력 경로에 쓸 수 있는지]
- [메모리에 액세스할 수 있고 최신 상태인지]
검사 중 하나라도 실패하면: 실패를 기록하고 중지하십시오.
필수 조건이 없는 상태에서 진행하지 마십시오.
주요 프로세스
1단계: 컨텍스트 로딩
전체 운영 컨텍스트를 위해 CLAUDE.md를 읽으십시오.
[작업-태그]로 태그된 관련 기록을 위해 메모리를 읽으십시오.
이번 실행에 정보를 제공해야 하는
이전 실행의 패턴을 기록하십시오.
2단계: 입력 처리
[입력으로 정확히 무엇을 해야 하는지 설명하십시오.
기본 형식과 실제로 나타나는 대체 형식을
모두 다루십시오.]
표준 입력 형식의 경우:
[정확한 처리 단계]
대체 입력 형식 A의 경우:
[처리 방법]
대체 입력 형식 B의 경우:
[처리 방법]
잘못되었거나 누락된 입력의 경우:
[처리 방법 — 절대 조용히 실패하지 마십시오]
3단계: 핵심 실행
[스킬의 실제 작업입니다.
하위 단계로 나누십시오. 각 하위 단계는
Claude의 새 인스턴스가 추가 컨텍스트 없이
실행할 수 있을 만큼 구체적이어야 합니다.]
4단계: 품질 검증
출력을 저장하기 전에 다음 기준에 대해 확인하십시오:
필수: [양보할 수 없는 출력 속성]
선호: [출력을 개선하는 품질 속성]
금지: [출력에 절대 나타나서는 안 되는 것]
출력이 필수 검사를 통과하지 못한 경우:
- 구체적으로 무엇이 실패했는지 식별하십시오
- 대상 수정과 함께 재시도하십시오
- 최대 세 번의 재시도
- 세 번 후에도 실패하면: 실패 플래그와 함께 저장하십시오
5단계: 출력 및 저장
출력을 다음 위치에 저장하십시오: [특정 경로 및 파일 이름 형식]
다음과 함께 메모리에 저장하십시오: [작업-태그, 날짜]
현재 정보가 변경된 경우 CLAUDE.md를 업데이트하십시오.
알림 보내기: [알림에 포함할 내용]
예외 상황
[예외 상황 1 이름]
조건: [발생 시기]
감지: [인식 방법]
대응: [조치 방법]
[예외 상황 2 이름]
조건: [발생 시기]
감지: [인식 방법]
대응: [조치 방법]
[예외 상황 3 이름]
조건: [발생 시기]
감지: [인식 방법]
대응: [조치 방법]
품질 기준
훌륭한 출력: [구체적 설명]
수용 가능한 출력: [최소 기준]
수용 불가능한 출력: [재시도를 트리거해야 하는 것]
메모리 지침
각 실행 후 다음을 저장하십시오:
- 실행 날짜 및 기간
- 출력 품질 평가 (훌륭함/수용 가능/실패)
- 발생한 모든 예외 상황 및 처리 방법
- 향후 실행을 위해 기록할 가치가 있는 모든 패턴
첫 번째 실제 에이전트: 연구 및 브리핑 에이전트
이 아키텍처를 사용하여 구축된 완전한 실제 에이전트입니다. 이 에이전트는 매일 일련의 소스를 모니터링하고, 작업 관련 주제를 연구하며, 매일 아침 구조화된 브리핑을 제공합니다.
이것은 장난감 작업이 아닙니다. 매일 45분의 수동 연구 컴파일 작업을 대체하는 실제 워크플로우입니다.
skills/research-brief.md 생성:
research-brief
목적
구성된 소스를 모니터링하고 현재 프로젝트 및
우선순위와 관련된 개발 사항을 다루는 구조화된
인텔리전스 브리핑을 생성합니다.
트리거
매일 오전 6:00에 예약 실행됩니다.
수동: "Research brief" 또는 "Morning brief"
실행 전 검사
시작하기 전에 다음을 확인하십시오:
- CLAUDE.md를 07-SYSTEM/CLAUDE.md에서 읽을 수 있는지
- Brave Search MCP 가 응답하는지
- 출력 경로 outputs/briefings/ 에 쓸 수 있는지
- 메모리 데이터베이스에 액세스할 수 있는지
주요 프로세스
1단계: 컨텍스트 로딩
CLAUDE.md를 완전히 읽으십시오. 다음을 기록하십시오:
- 현재 활성 프로젝트 및 상태
- 모니터링 대상으로 플래그 지정된 주제
- 정보가 필요한 보류 중인 결정 사항
- 이 브리핑의 품질 기준
research-brief 로 태그된 메모리를 읽으십시오.
최근 브리핑에서 다루었던 내용을 기록하여
반복을 피하십시오.
2단계: 소스 연구
CLAUDE.md 모니터링 목록의 각 주제에 대해:
검색 쿼리: "[주제] 지난 24시간 뉴스"
수집 항목: 제목, 출처, 날짜, 주요 주장
신호 필터 적용:
포함: 새로운 개발, 데이터, 제품 출시,
중요한 성명, 연구 결과
제외: 기존 보도의 반복,
새로운 정보가 없는 의견,
지난 3개 브리핑에서 다룬 모든 내용
신호 필터를 통과한 각 결과에 대해:
초기 결과가 중요한 개발을 시사하는 경우
후속 검색으로 더 깊이 연구하십시오.
3단계: 종합
주제별로 결과를 그룹화하십시오.
각 주제 그룹에 대해 다음을 식별하십시오:
- 가장 중요한 단일 개발 사항
- 현재 프로젝트에 중요한 이유
- 함의하는 모든 조치(있는 경우)
주제 간 종합:
- 더 큰 패턴을 시사하는 연결된 두 개 이상의 결과가 있습니까?
- 활성 프로젝트나 보류 중인 결정에 직접적인 영향을 미치는 결과가 있습니까?
4단계: 품질 검증
최종 확정하기 전에 다음을 확인하십시오:
필수:
- 최소 3개의 신호 항목 (노이즈 아님)
- 모든 항목이 특정 출처에 근거해야 함
- 모든 항목이 현재 작업과의 관련성을 설명해야 함
- 마지막 5개 브리핑에서 반복된 항목 없음
선호:
- 최소 한 개의 주제 간 연결
- 특정 조치를 함의하는 최소 한 개의 항목
- 뉴스가 적은 날이었다면 정직하게 인정
금지:
- 특정 증거가 없는 일반적인 분석
- 흥미롭지만 관련 없는 항목
- 브리핑을 더 포괄적으로 보이게 하기 위한 부풀리기
브리핑이 필수 검사를 통과하지 못한 경우: 구체적으로
무엇이 누락되었는지 식별하고 재시도 전에 추가 소스를
검색하십시오. 약한 신호로 부풀리지 마십시오.
5단계: 출력 생성
정확히 이 형식으로 브리핑을 생성하십시오:
오전 인텔리전스 브리핑 — [날짜]
오늘 가장 중요한 사항
[가장 중요한 단일 개발 사항과 그것이
현재 작업에 중요한 이유. 구체적이고 근거 있게.]
신호 항목
[주제 1]
개발 사항: [무슨 일이 일어났는지]
출처: [발행물, 날짜]
관련성: [현재 프로젝트에 중요한 이유]
의미: [이것이 시사하는 모든 조치]
[주제 2]
[동일한 형식]
[각 신호 항목에 대해 계속]
연결점
[두 개 이상의 항목이 더 큰 패턴을 시사하는 방식으로
연결되는 경우 여기에 설명하십시오. 진정한 연결이 없으면 생략하십시오.]
결정 관련성
[어떤 항목이 CLAUDE.md의 보류 중인 결정과 직접적으로 관련된
경우 세부 사항과 함께 여기에 플래그 지정하십시오.]
적용 범위 참고
[정직한 평가: 포괄적인 날 / 뉴스가 적은 날.
검색된 소스 수.]
6단계: 저장 및 알림
다음 위치에 저장: outputs/briefings/[날짜]-morning-brief.md
메모리에 저장:
- 날짜: [오늘]
- 다루어진 항목: [주제 목록]
- 품질: [훌륭함/수용 가능/실패]
- 주목할 점: [모든 예외 상황 또는 패턴] 태그: research-brief
텔레그램 알림 보내기:
"오전 브리핑 준비 완료: [N]개의 신호 항목.
[한 줄로 가장 중요한 오늘의 사항]"
예외 상황
주제에 대한 신호 없음
조건: 검색 결과에 새로운 개발 사항이 없음
감지: 모든 결과가 48시간 이상 전의 것임
대응: 해당 주제에 대해 "새로운 개발 사항 없음"이라고 기록하십시오.
꾸며내거나 부풀리지 마십시오. 다음 주제로 넘어가십시오.
출처가 상충되는 정보 반환
조건: 두 출처가 상반된 사실을 보고함
감지: 특정 주장에 대한 직접적인 모순
대응: 두 버전을 모두 보고하고, 두 출처를 모두 인용하며,
상충됨을 플래그 지정하십시오. 하나를 다른 것보다 선택하지 마십시오.
검색 도구 사용 불가
조건: Brave Search MCP 가 응답하지 않음
감지: 도구 호출이 오류를 반환함
대응: 실패를 기록하십시오. 텔레그램을 통해 알리십시오.
"검색 불가 — 메모리 컨텍스트만 기반으로 한 브리핑"이라는
메모와 함께 부분 브리핑을 저장하십시오.
조용히 실패하지 마십시오.
브리핑이 어제의 최상위 항목을 반복하게 될 경우
조건: 가장 중요한 개발 사항이 어제와 동일함
감지: 메모리에서 어제의 브리핑과 상호 참조
대응: "[날짜]부터 진행 중인 개발 사항"이라고 기록하고
오늘 구체적으로 새로운 것이 무엇인지에 초점을 맞추십시오.
품질 기준
훌륭한 브리핑: 4-6개의 신호 항목. 모든 항목이 관련 있음.
최소 한 개의 주제 간 통찰력. 5분 이내에 읽을 수 있음.
수용 가능한 브리핑: 3개의 신호 항목. 모두 관련 있음.
주제 간 통찰력 없음. 5분 이내에 읽을 수 있음.
수용 불가능한 브리핑: 3개 미만의 신호 항목.
일반적이거나 현재 작업과 관련 없는 항목.
지난 3개 브리핑에서 반복된 항목.
품질 검증 계층 구축하기
품질 검증 계층은 일관된 결과를 생성하는 에이전트와 가변적인 결과를 생성하는 에이전트를 구분하는 요소입니다.
대부분의 에이전트는 이 계층을 완전히 건너뜁니다. 출력을 생성하고 반환합니다. 품질은 전적으로 생성이 얼마나 좋았는지에 달려 있습니다. 어떤 세션은 훌륭하고 어떤 세션은 평범합니다. 어떤 결과가 나올지 결코 알 수 없습니다.
품질 검증 계층은 모든 출력을 정의된 기준에 대해 확인하고 기준이 충족되지 않을 경우 특정 수정 사항을 포함하여 재시도함으로써 출력 품질을 일관되게 만듭니다.
다음은 품질 검증을 구현하는 Claude API 호출 패턴입니다:
1async function executeWithQualityVerification(prompt, qualityStandard, maxRetries = 3) {23 let attempt = 0;45 let lastOutput = null;67 let lastFailure = null;89 while (attempt < maxRetries) {1011 // 출력 생성12 const response = await fetch('https://api.anthropic.com/v1/messages', {1314 method: 'POST',1516 headers: {1718 'Content-Type': 'application/json',1920 'x-api-key': process.env.ANTHROPIC_API_KEY,2122 'anthropic-version': '2023-06-01'2324 },2526 body: JSON.stringify({2728 model: 'claude-opus-4-8',2930 max_tokens: 4096,3132 messages: [3334 {3536 role: 'user',3738 content: attempt === 03940 ? prompt4142 : `${prompt}\n\n이전 시도가 품질 검사를 통과하지 못했습니다: ${lastFailure}\n이 실패에 대해 구체적으로 수정하십시오. 모든 것을 다시 작성하지 마십시오.`4344 }4546 ]4748 })4950 });5152 const data = await response.json();5354 lastOutput = data.content[0].text;5556 // 품질 검증57 const verificationResponse = await fetch('https://api.anthropic.com/v1/messages', {5859 method: 'POST',6061 headers: {6263 'Content-Type': 'application/json',6465 'x-api-key': process.env.ANTHROPIC_API_KEY,6667 'anthropic-version': '2023-06-01'6869 },7071 body: JSON.stringify({7273 model: 'claude-opus-4-8',7475 max_tokens: 1000,7677 messages: [7879 {8081 role: 'user',8283 content: `당신은 품질 검사자입니다. 이 출력을 다음 기준에 대해 평가하십시오:8485${qualityStandard}8687평가할 출력:8889${lastOutput}9091다음으로만 응답하십시오:9293PASS : 출력이 모든 필수 기준을 충족하는 경우9495FAIL: [구체적으로 무엇이 실패했는지 설명] : 필수 기준을 충족하지 못하는 경우9697설명하지 마십시오. 개선 사항을 제안하지 마십시오. PASS 또는 FAIL과 구체적인 실패 설명만 제공하십시오.`9899 }100101 ]102103 })104105 });106107 const verificationData = await verificationResponse.json();108109 const verificationResult = verificationData.content[0].text.trim();110111 if (verificationResult.startsWith('PASS')) {112113 return { output: lastOutput, attempts: attempt + 1, passed: true };114115 }116117 lastFailure = verificationResult.replace('FAIL:', '').trim();118119 attempt++;120121 }122123 // 모든 재시도 소진124 return {125126 output: lastOutput,127128 attempts: maxRetries,129130 passed: false,131132 failure: lastFailure133134 };135136}
이 패턴은 출력을 생성하고, 정의된 기준에 대해 확인하고, 실패할 경우 특정 수정 사항으로 재시도합니다. 모든 재시도가 실패하면 충돌하는 대신 실패 플래그와 함께 최상의 출력을 반환합니다.
메모리 통합 패턴
메모리는 유능한 에이전트를 학습하는 에이전트로 변화시키는 요소입니다.
메모리가 없으면 모든 세션은 처음부터 시작합니다. 에이전트는 이전에 무엇을 했는지 알지 못합니다. 과거 실행에서 배운 것을 적용할 수 없습니다. 이미 저지른 실수를 피할 수 없습니다.
메모리가 있으면 모든 세션은 이전 세션을 기반으로 구축됩니다. 에이전트는 무엇이 효과가 있었고 무엇이 효과가 없었는지 압니다. 축적된 컨텍스트를 적용하여 현재 출력을 개선합니다. 시간이 지남에 따라 특정 작업에 더 능숙해집니다.
다음은 모든 Claude 에이전트를 위한 메모리 통합 패턴입니다:
모든 실행 시작 시:
[작업-태그]로 태그된 메모리 항목을 읽으십시오.
제한: 가장 관련성 높은 항목 20개
전략: 관련성 (단순한 최신순 아님)
이 컨텍스트 적용:
- 이전 실행의 패턴 기록
- 이전에 발생한 예외 상황 기록
- 이전에 식별된 품질 문제 기록
- 현재 실행에 학습 내용 적용
모든 실행 종료 시:
메모리에 저장:
date: [오늘]
task: [작업 이름]
quality: [훌륭함/수용 가능/실패]
notable: [기억할 가치가 있는 모든 것]
edge_case: [발생한 모든 예외 상황]
pattern: [관찰된 모든 패턴]
태그: [작업-태그], [날짜]
월간 통합:
[작업-태그]로 태그된 모든 메모리 항목 읽기
식별:
- 여러 항목에 걸쳐 나타나는 패턴
- 반복되는 예외 상황
- 반복되는 품질 문제
- 훌륭한 출력과 수용 가능한 출력의 상관 관계
단일 업데이트된 컨텍스트 항목으로 통합
90일 이상 된 개별 항목 보관
실패 복구 시스템
실제 에이전트는 실패를 경험합니다. 소스가 오프라인이 됩니다. API가 속도 제한에 걸립니다. 파일이 예상된 위치에 없습니다. 최대 재시도 후에도 출력이 품질 검사를 통과하지 못합니다.
실패 복구 시스템은 이러한 실패가 보이지 않는 일시적 오류인지 아니면 치명적인 중단인지를 결정합니다.
세 가지 계층의 실패 처리:
1계층: 자동 복구
재시도로 해결되는 일시적 실패. 도구 사용 불가. 네트워크 시간 초과. 속도 제한 도달.
1계층 복구 프로토콜
모든 도구 호출 실패 시:
- 60초 대기
- 정확히 동일한 호출 재시도
- 재시도 성공 시: 정상 계속, 오류 기록
- 재시도 실패 시: 2계층으로 에스컬레이션
2계층: 우아한 성능 저하
해결할 수 없지만 부분 완료를 허용하는 실패. 하나의 소스 사용 불가. 하나의 도구 응답 없음. 출력의 한 섹션이 품질 검사 실패.
2계층 복구 프로토콜
해결 불가능한 부분 실패 시:
- 완료할 수 있는 것을 완료
- 구체적으로 무엇이 건너뛰어졌고 그 이유를 기록
- 파일 이름에 출력이 부분적임을 플래그 지정
- 출력 자체에 명시적 메모 포함
- 알림 전송: "부분 출력 — [구체적 이유]"
- 하나의 구성 요소가 실패했다고 전체 작업을 실패로 처리하지 마십시오
3계층: 우아한 중단
전체 작업을 불가능하게 만드는 실패. CLAUDE.md를 찾을 수 없음. 출력 경로에 쓸 수 없음. 메모리 데이터베이스에 액세스할 수 없음.
3계층 복구 프로토콜
완전 실패 시:
- 특정 실패 지점 식별
- 완료된 모든 작업을 임시 위치에 저장
- 전체 실패 컨텍스트 기록
- 알림 전송: "작업 실패 — [구체적 이유]"
- 기존 출력을 손상시키지 않고 깔끔하게 중지
- 자동으로 재시도하지 마십시오 — 사람의 개입을 기다리십시오
배포 전 에이전트 테스트하기
실제 에이전트 배포에서 가장 흔한 실수는 구조화된 테스트를 건너뛰는 것입니다.
에이전트를 라이브로 전환하기 전에 세 가지 테스트 단계:
1단계: 구성 요소 테스트
전체 워크플로우를 테스트하기 전에 각 구성 요소를 개별적으로 테스트하십시오.
1# 메모리가 유지되는지 테스트2hermes chat
가장 오래된 메모리 항목은 무엇입니까?
1# 예상: 항목을 보고하거나 빈 데이터베이스를 보고해야 함2# 오류 반환 시: 메모리 구성이 잘못됨34# 도구 액세스 테스트5hermes chat
[출력 경로]의 파일을 나열하십시오
1# 예상: 실제 파일을 나열해야 함2# 오류 반환 시: 파일 시스템 MCP가 올바르게 구성되지 않음34# 검색 테스트5hermes chat
"오늘의 AI 뉴스"를 검색하고 상위 결과를 알려주십시오
1# 예상: 실제 검색 결과를 반환해야 함2# 오류 반환 시: Brave Search MCP가 올바르게 구성되지 않음
2단계: 해피 패스 테스트
깨끗한 표준 입력으로 스킬을 수동으로 실행하고 출력이 품질 기준을 충족하는지 확인하십시오.
1# 스킬 수동 실행2hermes run research-brief34# 출력 확인5cat outputs/briefings/[오늘]-morning-brief.md67# 품질 기준에 대해 확인:8# - 최소 3개의 신호 항목?9# - 모든 항목이 현재 작업과 관련 있음?10# - 일반적인 분석 없음?11# - 5분 이내에 읽을 수 있음?
3단계: 예외 상황 테스트
문서화된 각 예외 상황을 의도적으로 트리거하고 복구 동작을 확인하십시오.
1# 테스트: 인터넷 액세스 불가2# .env에서 Brave Search 비활성화3# 스킬 실행4# 예상: 3계층 실패, 깔끔한 중지, 알림 전송56# 테스트: 출력 경로에 쓸 수 없음7# OUTPUT_PATH를 존재하지 않는 디렉토리로 변경8# 스킬 실행9# 예상: 3계층 실패, 깔끔한 중지, 알림 전송1011# 테스트: 뉴스가 적은 날12# 주말이나 공휴일에 실행13# 예상: 느린 날임을 나타내는 COVERAGE NOTE가 포함된 2계층 출력
프로덕션에서 에이전트 실행하기
세 가지 테스트 단계가 모두 통과되면 스케줄러를 구성하고 프로덕션으로 전환하십시오.
1{2 "schedules": [3 {4 "skill": "research-brief",5 "cron": "0 6 * * *",6 "description": "매일 오전 6시",7 "timeout_minutes": 15,8 "on_failure": "notify_and_stop"9 }10 ]11}
백그라운드 모드에서 Hermes 시작:
1npm run start -- --daemon
첫 번째 예약된 실행 확인:
1# 오전 6시 이후 로그 확인2cat logs/hermes-[날짜].log34# 출력이 생성되었는지 확인5ls outputs/briefings/67# 메모리가 업데이트되었는지 확인8hermes chat
research-brief 메모리 항목이 몇 개 있습니까?
첫 번째 자동 실행이 좋은 출력을 생성하면 에이전트가 프로덕션에 있는 것입니다.
3개월 후 변화하는 것
첫 달: 에이전트가 안정적으로 실행됩니다. 출력이 일관됩니다. 실패가 우아하게 처리됩니다. 매일 아침 45분을 절약합니다.
2개월 차: 메모리 계층이 눈에 띄는 개선을 보이기 시작한다. 에이전트는 60 일간의 소스를 처리했으며, 어떤 소스가 고신호 콘텐츠를 제공하고 어떤 것이 노이즈인지에 대한 컨텍스트를 축적했다. 신호 필터링의 품질이 향상되는 이유는 에이전트가 어떤 소스를 추적할 가치가 있었는지 학습했기 때문이다.
3개월 차: 메모리 통합이 두 번 실행되었다. 에이전트는 90 일간의 연구 데이터에서 패턴을 식별했다. 브리프는 축적된 컨텍스트를 참조하여, 단일 세션 연구로는 생성할 수 없는 더욱 견고하고 구체적인 결과를 제공한다.
3개월 차의 에이전트는 1개월 차와 동일한 워크플로를 실행하지 않는다.
90 일간 축적된 운영 인텔리전스를 바탕으로 개선된 버전의 워크플로를 실행한다.
이것이 튜토리얼 에이전트와 실제 환경 에이전트의 차이점이다.
튜토리얼 에이전트는 작업을 수행한다.
실제 환경 에이전트는 더 나은 작업 수행 방법을 학습한다.
이번 주말에 기반을 구축하라.
일주일 동안 실행하고, 문제가 생기면 수정하라.
한 달 동안 실행하고, 개선되는 모습을 지켜보라.
3개월 동안 실행하고, 첫날에는 알려줄 수 없었던 것을 에이전트가 알고 있음을 확인하라.
이것이 실제 환경에서 제대로 작동하는 Claude 에이전트를 구축하는 모습이다.
@cyrilXBT를 팔로우하여 Claude 에이전트가 실제 환경과의 접촉에서 살아남도록 만드는 모든 에이전트 아키텍처, 스킬 템플릿, 프로덕션 배포 패턴을 확인하라.
