클로드로 API 엔드포인트 구축하기: 70개 이상의 엔드포인트 프로젝트에서 얻은 실용적인 프롬프트 엔지니어링 교훈

행동 수행 에이전트를 위한 실용적인 프롬프트 엔지니어링

70개 이상의 엔드포인트, 서버 측 실행, Chrome 확장 프로그램 인증을 갖춘 LinkedIn 자동화 API를 구축한 한 개발자가 Claude를 사용하여 코드의 약 80%를 작성했습니다. 이 프로젝트는 API 호출, 데이터 추출, 의사결정 트리와 같은 작업을 수행하는 에이전트와 단순히 채팅만 하는 에이전트를 위한 프롬프트 구성에 대한 구체적인 교훈을 드러냈습니다.

프롬프트에 대한 계약 접근법

개발자는 "LinkedIn에서 관련 리드를 찾아 개인화된 연결 요청을 보내라"와 같은 자연어 지시는 문제를 일으킨다는 사실을 발견했습니다: Claude는 존재하지 않는 필드를 만들어내거나, 검증을 건너뛰고, 불필요한 API 호출을 연쇄적으로 실행했습니다. 효과적이었던 접근법은 모든 에이전트 프롬프트를 명시적 제약 조건을 가진 함수 시그니처처럼 다루는 것이었습니다:

• 입력: 에이전트가 정확히 무엇을 받는지 (스키마, 타입, 예외 상황)
• 경계: 에이전트가 해서는 안 되는 것 (대충 추측하지 않기, 필드 건너뛰지 않기, 데이터를 만들어내지 않기)
• 출력 계약: 반환되는 결과의 정확한 형태 (오류 상태 포함)
• 의사결정 규칙: X면 Y를 하고, Z면 멈춘다 — 모호함 없음

구체적으로 배운 교훈

"창의적으로 행동하라"는 행동 에이전트에게 문제가 됩니다: 행동 수행 프롬프트에 해석의 여지를 남길 때마다 Claude는 예상치 못한 결과를 만들어냈습니다. 실제 행동을 실행하는 에이전트의 경우, 창의성은 전혀 없는 것이 바람직하며, 창의성은 콘텐츠 생성 작업에만 사용해야 합니다.

오류 처리는 필수적입니다: 프롬프트 토큰의 약 40%가 "문제가 발생했을 때 무엇을 해야 하는지"에 할당되었습니다. 이것 없이는 Claude는 무한히 재시도하거나 오류를 조용히 무시하고 모든 것이 괜찮은 것처럼 부분적인 데이터를 반환했습니다.

사고의 연쇄(Chain-of-thought)의 장단점: 모든 에이전트가 행동하기 전에 추론 단계를 출력하도록 강제하면 약 15% 더 많은 토큰이 소요되지만 디버깅 시간을 절약합니다. 무언가가 고장 났을 때, 개발자는 에이전트가 왜 그런 결정을 내렸는지 정확히 읽을 수 있습니다.

페르소나 프롬프트보다 패턴 매칭: "당신은 시니어 엔지니어입니다"와 같은 프롬프트를 사용하는 대신, 개발자는 좋은 출력의 실제 예시를 붙여넣고 "이 패턴을 정확히 따라라"고 지시합니다. Claude는 역할 놀이보다 패턴 매칭에서 더 나은 성능을 보입니다.

모델 선택 전략: 단순한 추출 및 포맷팅 작업은 Sonnet(또는 Haiku)으로 라우팅하고, 복잡한 의사결정 작업에만 Opus를 사용합니다. 이 접근법은 대부분의 에이전트 작업이 Opus를 필요로 하지 않기 때문에 API 비용을 고통스러운 수준에서 관리 가능한 수준으로 줄였습니다.