클로드 AI 실행 에이전트를 위한 실용적인 프롬프트 구조

실행 에이전트를 위한 프롬프트 엔지니어링

실제 작업(API 호출, 데이터 추출, 다단계 의사결정 트리, 오류 복구)을 수행하는 Claude AI 에이전트를 몇 달간 구축한 경험이 있는 개발자가 지속적인 환각 문제를 해결한 프롬프트 구조를 공유합니다. 초기 시도에서는 에이전트가 필드를 환각적으로 만들어내고, 불필요한 API 호출을 연쇄적으로 실행하며, 오류를 조용히 삼키고, 모든 것이 정상인 것처럼 부분 데이터를 반환하는 문제가 발생했습니다.

핵심 프롬프트 구조 원칙

• 프롬프트를 지시가 아닌 계약서처럼 작성하세요: "관련 리드를 찾아 개인화된 메시지를 보내세요"와 같은 자연어 프롬프트는 즉흥성을 유도합니다. 효과적인 방법: 입력(정확한 스키마, 유형, 경계 사례), 출력(오류 상태를 포함한 정확한 형태), 의사결정 규칙(X이면 Y, Z이면 중지)을 정의하는 것입니다.
• 프롬프트 토큰의 40%를 오류 처리에 할당하세요: 명시적인 오류 경로 없이는 Claude가 무한 재시도하거나 조용히 쓰레기 값을 반환합니다. 모든 가능한 실패 모드에는 각각의 지침이 필요합니다: API가 429를 반환할 때 어떻게 할지, 필수 필드가 누락되었을 때 어떻게 할지, 데이터가 모호해 보일 때 어떻게 할지 등입니다.
• "대기"와 "중지"를 분리하세요: Claude는 "아직 행동할 충분한 정보가 없음"과 "정보가 나쁨, 중단"을 구분할 수 없습니다. 두 경우 모두 명시적으로 설명해야 합니다. 한 에이전트는 모호한 데이터에서 일시 중지해야 했지만, 대신 100% 깨끗하지 않은 모든 것을 건너뛰었습니다. 두 상태에 대한 명시적 지침을 추가하자 정확도가 하룻밤 사이에 향상되었습니다.
• 역할 놀이보다 패턴 매칭: "당신은 시니어 엔지니어입니다"는 실행 품질에 거의 영향을 미치지 않습니다. 실제 좋은 출력 예시를 붙여넣고 "이 패턴을 정확히 따라하세요"라고 말하는 것이 10배 더 효과적입니다. Claude는 추상적인 페르소나를 해석하는 것보다 구체적인 예시를 복제하는 데 더 능숙합니다.
• 습관이 아닌 복잡도에 따라 라우팅하세요: 컨텍스트와 경계 사례가 중요한 다단계 의사결정에는 Opus만 독점적으로 사용하세요. 그 외 모든 것은 Sonnet이나 Haiku로 보내세요. 대부분의 에이전트 작업에는 Opus가 필요하지 않으며, 비용 차이는 빠르게 누적됩니다. 적절한 라우팅으로 API 비용이 가혹한 수준에서 관리 가능한 수준으로 떨어졌습니다.
• 모든 행동 전에 사고의 연쇄를 강제하세요: 이는 약 15% 더 많은 토큰을 소비할 수 있지만, 새벽 2시에 무언가 고장 나면 에이전트가 왜 그런 결정을 내렸는지 정확히 읽을 수 있습니다. 이것 없이는 맹목적으로 디버깅하게 됩니다.

이 개발자는 (단순히 텍스트를 생성하는 것이 아닌) 실제 작업을 수행하는 에이전트를 구축할 때 이 프롬프트 구조가 모델 선택보다 훨씬 더 중요하다고 언급합니다.