요약 (TL;DR)

저는 판매 CSV 파일을 입력받아 전체 ABC XYZ 분석을 자동으로 수행하는 Claude Code 서브에이전트(subagent)를 구축했습니다. 매번 수동으로 프롬프트를 입력할 필요 없이 항상 동일한 출력 형식을 유지합니다. 여기에는 정확한 설정 방법, 발생했던 문제점, 그리고 5번의 프롬프트 재작성을 통해 실제로 무엇이 바뀌었는지에 대한 내용이 담겨 있습니다.

제가 해결하려 했던 문제

지난 포스트에서 저는 스프레드시트 수식, 수동 정렬, 시트 간 결과 복사 및 붙여넣기 등을 통해 ABC XYZ 분석을 수동으로 진행하는 과정을 설명했습니다.

작동은 했습니다. 하지만 저는 이 작업을 몇 달마다 반복합니다. 그리고 매번 다음과 같은 과정을 거쳐야 했습니다:

• 필요한 형식에 맞춰 데이터를 재구성
• 동일한 분석 로직을 처음부터 다시 작성
• 그날의 질문 방식에 따라 약간씩 달라지는 결과값

저는 CSV 파일을 던져주고 "이것을 분석해줘"라고 말하면, 매번 동일한 구조와 동일한 임계값(thresholds)을 가진 일관된 보고서를 받을 수 있기를 원했습니다.

Claude Code는 서브에이전트(subagents)를 지원합니다. 이는 한 번 설정해 두면 필요할 때마다 호출할 수 있는 특화된 에이전트입니다. 이것이 바로 적합한 도구였습니다.

Claude Code 서브에이전트란 무엇인가

Claude Code는 로컬 파일에 접근할 수 있는 상태로 터미널에서 Claude를 직접 실행합니다. 그 내부에서 여러분은 서브에이전트를 생성할 수 있습니다. 서브에이전트는 자체적인 시스템 프롬프트(system prompt)와 도구(tool) 접근 권한을 가지며, .claude/agents/ 디렉토리에 마크다운(markdown) 파일로 저장됩니다.

메인 Claude는 작업 설명과 에이전트의 설명 필드를 기반으로 작업을 적절한 서브에이전트에게 자동으로 라우팅(routing)합니다.

에이전트를 한 번 작성해 두면, 그 이후에는 원하는 내용을 설명하기만 하면 Claude Code가 어떤 에이전트를 사용할지 결정합니다.

에이전트 파일

최종 버전은 다음과 같습니다:

name: abc-xyz-analyst
description: "ABC XYZ 세분화(segmentation)를 사용하여 판매 데이터를 분석합니다. 월간 판매 수치가 포함된 CSV 또는 테이블이 주어지고, 매출 및 수요 안정성에 따라 제품이나 고객을 세분화하라는 요청이 있을 때 사용합니다."
tools:

• Read
• Write

당신은 분석 전문가입니다. 판매 데이터가 주어지면 전체 ABC XYZ 분석을 수행하십시오.

분석 규칙 (ANALYSIS RULES):

• 모든 항목을 총 매출액(Total Revenue) 기준으로 내림차순 정렬합니다.
• 각 항목의 총 매출액 대비 점유율을 계산합니다.
• 누적 매출 점유율(Cumulative revenue share)을 계산합니다.
• ABC 그룹: A = 누적 80%까지, B = 80-95%, C = 95-100%
• XYZ: 월별 항목당 변동 계수(Coefficient of variation, 표준편차 / 평균)를 계산합니다.
• X = CoV 0.10 미만, Y = 0.10-0.25, Z = 0.25 초과

출력 형식 (OUTPUT FORMAT):

1. 전체 테이블: 항목(Item) | 총 매출액(Total Revenue) | 매출 비중(Revenue %) | 누적 비중(Cumulative %) | ABC | CoV | XYZ | 세그먼트(Segment)
2. 주요 결과(Key findings) - 최대 5개의 불렛 포인트, 구체적인 관찰 사항만 작성
3. 세그먼트별 권장 사항(Recommendations per segment) - 일반적인 조언이 아닌 구체적인 다음 조치 사항
4. 데이터 문제 섹션(Data issues section) - 누락된 값, 일관되지 않은 형식, 이상치(Outliers) 표시

중요: 데이터가 불분명할 경우 추측하지 마십시오. 가정을 명시적으로 기술하십시오.
호출 방법:

작업 내용을 설명하기만 하면 됩니다 - Claude Code가 라우팅(Routing)을 처리합니다

"sales_q1.csv를 ABC XYZ 분석을 사용하여 분석해줘"
Claude Code는 설명 필드를 읽고 이를 작업과 매칭하여 서브에이전트(Subagent)로 라우팅합니다. 에이전트는 파일을 읽고, 분석을 실행하며, 보고서를 작성합니다.

실제로 효과가 있었던 점

라우팅(Routing)이 신뢰할 수 있습니다. 설명 필드가 충분히 구체적이면, 제가 에이전트의 이름을 지정하지 않아도 Claude Code가 일관되게 올바른 에이전트를 선택합니다. 저는 그저 "이 판매 데이터를 분석해줘"라고 말하기만 하면 적절한 곳으로 연결됩니다.

일관성(Consistency). 이것이 핵심이었습니다. 매 실행마다 동일한 임계값(Thresholds), 동일한 테이블 구조, 동일한 섹션 순서가 유지됩니다. 더 이상 "지난번에는 A 기준을 75%로 했나, 80%로 했나?"라고 고민할 필요가 없습니다.

제가 빠르게 지나치는 부분을 잡아냅니다. 에이전트는 지치지 않고 모든 행에 동일한 규칙을 적용합니다. 40개 제품 카탈로그에 이 작업을 실행했을 때, 저는 AZ 경계에 있는 BZ 항목을 대충 훑고 지나갔지만, 에이전트는 이를 명시적으로 표시했습니다. 에이전트가 더 똑똑해서가 아니라, 단지 더 일관적이기 때문입니다.

효과가 없었던 점

데이터 형식에 대한 가정(Data format assumptions). 에이전트는 월별로 하나의 열(Column)이 있는 형식을 기대합니다. 연간 합계, 주간 데이터, 또는 전치된(Transposed) 테이블을 주면 에러가 발생하거나 조용히 잘못된 숫자를 생성합니다. 프롬프트에 데이터 검증(Data validation) 지침을 추가했지만, 특이한 형식에 대해서는 여전히 취약합니다.

"이유(why)"의 공백. 에이전트는 특정 제품이 AZ(높은 매출, 불안정한 수요)라고 알려줍니다. 하지만 그것이 계절성 때문인지, 경쟁사의 출시 때문인지, 아니면 8개월 전의 일회성 캠페인 때문인지는 말해주지 못합니다. 저는 권장 사항(recommendations)이 더 진단적(diagnostic)이기를 기대했습니다. 하지만 그렇지 않았습니다. 권장 사항은 원인이 아니라 세그먼트(segment)를 기반으로 한 처방적(prescriptive)인 내용이었습니다. 그 맥락은 여전히 사용자가 직접 제공해야 합니다.

초기 권장 사항들은 쓸모가 없었습니다. 버전 1은 "AZ 그룹에 대한 추가 조사가 필요합니다"와 같은 결과를 반환했습니다. 그것은 권장 사항이 아닙니다. 이를 수정하는 데 두 번의 재작성(rewrites)이 필요했습니다.

5번의 재작성 - 실제로 무엇이 바뀌었나

v1: "데이터에 대해 ABC XYZ 분석을 실행하세요"
결과: 일관성 없는 임계값(thresholds), 정의되지 않은 출력 형식, 때로는 XYZ 부분을 완전히 건너뜀

v2: 정확한 임계값 추가 (ABC는 80/95, XYZ는 0.10/0.25)
결과: 임계값은 이제 일관적이지만, 출력 형식은 여전히 가변적임

v3: 열 이름(column names)을 포함한 명시적인 출력 형식 추가
결과: 표(table)는 일관적이었으나, 권장 사항 섹션이 모호함

v4: "일반적인 조언이 아닌 구체적인 다음 조치" 추가
결과: 권장 사항은 개선되었으나, 데이터에 공백이 있을 때 에이전트가 이를 알리는 대신 추측을 함

v5: "추측하지 마세요 - 가정을 명시적으로 기술하세요" 추가
결과: 이것이 현재 제가 사용 중인 버전입니다.
모든 재작성은 출력 결과에서 저를 짜증 나게 했던 구체적인 요소들에 의해 트리거되었습니다. 저는 이 모든 것을 사전에 계획하지 않았습니다. 일단 실행해 보고, 무엇이 잘못되었는지 확인한 뒤, 그 한 가지 문제를 수정했습니다.

내가 과소평가했던 것

좋은 에이전트 프롬프트(agent prompt)를 작성하는 것은 보기보다 어렵습니다.

Claude는 당신이 의도한 것이 아니라, 당신이 쓴 그대로 수행합니다. "ABC XYZ 분석을 실행하세요"라는 문구는 해당 방법론을 아는 사람에게는 명확하게 들립니다. 하지만 Claude에게는 모호합니다. 어떤 임계값을 사용할 것인가? 어떤 출력 형식을 사용할 것인가? 누락된 데이터는 어떻게 처리할 것인가?

프롬프트의 모든 모호한 지침은 출력의 불일치를 야기하는 원인이 됩니다. 기술적인 설정(파일 생성, 올바른 디렉토리에 배치)은 아마 10분 정도 걸렸을 것입니다. 하지만 프롬프트를 제대로 맞추는 데는 5번의 반복 과정을 거치며 몇 시간이 걸렸습니다.

다음 단계

비교 모드 추가 - 서로 다른 기간의 CSV 파일 두 개를 전달하여, 어떤 제품이 어떤 방향으로 세그먼트(segment)가 변경되었는지 보여주는 차이점(diff)을 받아옵니다. 분기 사이에 AX에서 AZ로 이동한 제품은 현재의 분류 상태만 보는 것보다 더 흥미로운 정보를 제공합니다.

Tags: #ai #claude #automation #tutorial #productivity #beginners