# 클로드 코드 멀티 에이전트로 상세페이지 현지화 #1 - 설계편 아마존에 제품 올려본 적 있으세요? **_국내에서 잘 팔리는 제품을 해외 아마존에 올리려면, 상세페이지를 통째로 바꿔야 해요_**. 번역만 하면 될 것 같지만 전혀 아니더라고요. 제품 설명을 현지 톤에 맞게 다시 쓰고, 이미지 속 한국어 텍스트를 바꾸고, 모델도 현지인으로 교체하면 더 좋겠죠. 진출 국가가 4곳이면 이걸 4번 반복해야 하죠🤣🤣 지인이 운영하는 헤어케어 브랜드가 해외 국가 진출을 준비하고 있었는데, 제품 하나 현지화하는 데 꽤 오랜 시간이 걸린다고 하더라고요. 번역하고, 최적화하고, 디자이너가 이미지 수정하고.. 이 과정이 제품마다 반복됩니다. "그거 자동화 해줄까?"라고 했다가, 생각보다 큰 프로젝트가 됐습니다. (왜 그랬을까, 가마니 있을걸걸걸) **결과물부터 말하면**: "이 제품을 미국이랑 일본용으로 현지화해줘" 한마디에, 시장 조사부터 번역, 카피라이팅, 이미지 생성, 품질 검수까지 Claude Code가 알아서 돌리게 되었어요. 이 시리즈에서는 이 시스템을 어떻게 설계하고 만들었는지 과정을 공유할게요. - **1편 (이 글)**: 전체 설계와 아키텍처 - **2편**: 파이프라인 - 6명의 AI가 순서대로 일하는 법 - **3편**: 이미지 생성의 함정과 삽질 기록 --- ## 상세페이지 현지화, 번역만 하면 되는 거 아닌가요 현실은 그렇게 단순하지 않습니다. **💬 번역** - "송이버섯 추출물"을 영어로 뭐라고 쓸지부터 고민입니다. "Matsutake Extract"가 맞는지, 그냥 "Mushroom Extract"가 나은지. "탈모 예방"이라고 쓰면 미국 FDA 규정에 걸립니다. "supports healthy hair"로 바꿔야 해요. **✏️ 카피라이팅** - 나라마다 톤도 다릅니다. 미국은 직접적이고 자신감 있게, 일본은 공손하고 섬세하게. 국가별 '말맛'이라는 게 있겠죠. **🎨 이미지** - 한국인 모델 사진을 미국 아마존에 그대로 쓸 순 있지만, 현지화 모델이면 더 좋겠죠. 실제 모델을 섭외하고 촬영까지 하려면 얼마나 돈이 많이 들까요. **❌ 검수** - 금지 표현 없는지, 브랜드명이 일관되는지, 이미지에서 제품이 변형되지 않았는지 하나하나 확인해야 합니다. 이거 다 하는 데 한 달은 걸리게 생겼어요. 4개 나라면 4달. 제품이 10개면? 으악 ![Image](https://upload.cafenono.com/image/slashpagePost/20260213/220122_o46x53bHqJxNCVNyPO?q=80&s=1280x180&t=outside&f=webp) ## 하나의 AI한테 다 시키면 안 되는 이유 Claude Code한테 "이 제품 현지화해줘"라고 한방에 시켜봤습니다. 결과가 어땠냐면... 번역은 괜찮은데 SEO 키워드가 빠져 있고, 이미지 프롬프트는 너무 대충 나오고, 검수는 아예 건너뛰더라고요. 당연한 겁니다. **번역하면서 동시에 SEO 최적화하고 이미지까지 분석하라고 하면, 사람도 못해요.** 컨텍스트 윈도우에 정보가 너무 많이 들어가니까 하나하나의 품질이 떨어져요. **한 명한테 다 시키지 말고, 전문가 여러 명한테 나눠서 시키자.** ## Claude Code의 스킬(Skill)과 서브에이전트(Sub-Agent) Claude Code에는 **스킬(Skill)**과 **서브에이전트(Sub-Agent)**라는 두 가지 개념이 있습니다. ```javascript 📚 스킬 = 매뉴얼 / 지침서 Claude가 읽고 따르는 지식 같은 대화 안에서 참조됨 예: 번역 용어집, 아마존 SEO 가이드, 이미지 생성 규칙 🤖 서브에이전트 = 전문 담당자 별도 대화창에서 독립적으로 실행 맡은 일만 하고 결과만 돌려줌 예: 번역 담당, 카피 담당, 이미지 생성 담당 ``` 왜 둘을 나눠야 할까요? **스킬만 쓰면** - 모든 지침이 하나의 대화에 쌓입니다. 번역 용어집 + SEO 가이드 + 이미지 규칙 + QA 체크리스트를 한꺼번에 넣으면 컨텍스트가 터집니다. **서브에이전트만 쓰면** - 각자 독립적으로 돌아가니까 좋은데, 에이전트한테 "이 규칙 따라"라고 매번 프롬프트에 다 쓸 수 없습니다. 그래서 **스킬에 지침을 적어두고, 에이전트가 그 스킬을 참조하면서 일하는 구조**로 만들었어요. 번역 에이전트가 실행되면 `translation` 스킬에 적힌 용어집, 금지 표현, 단위 변환 규칙을 자동으로 참조합니다. 에이전트는 "실행자", 스킬은 "참고서" 역할이에요. ## 최종 설계: 6명의 에이전트와 6개의 스킬 이렇게 해서 만든 전체 구조입니다. ```javascript ┌─────────────────────────────────────────────────────────────┐ │ 📚 ORCHESTRATOR (메인 컨트롤 타워) │ │ 전체 워크플로우를 관리하는 지침서 │ └─────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Phase 1: 🔍 시장 조사 │ │ │ │ 🤖 Market Research Agent │ │ → 타겟 국가 트렌드, 경쟁사 분석, 모델 선호도 │ └─────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Phase 2: 📝 번역 & 카피라이팅 [순차 실행] │ │ │ │ 🤖 Translation Agent ────→ 🤖 Copywriting Agent │ │ (📚 translation 스킬) (📚 copywriting 스킬) │ │ → 정확한 번역 → 아마존 SEO 카피 최적화 │ │ │ └─────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Phase 3: 🖼️ 이미지 현지화 [순차 실행] │ │ │ │ 🤖 Image Analysis Agent ──→ 🤖 Image Generation Agent │ │ (📚 image-generation 스킬) │ │ → 이미지 의도 분석 → Gemini API로 이미지 생성 │ │ │ │ ⚠️ 제품 이미지 변형 절대 금지 / with-text + without-text 2버전 │ └─────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Phase 4: ✅ 검수 │ │ │ │ 🤖 QA Reviewer Agent (📚 qa 스킬) │ │ → 텍스트 + 이미지 동시 검수 │ │ → 실패 시 Phase 2~3 재실행 │ └─────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Phase 5: 📤 저장 (📚 output-manager 스킬) │ │ │ │ Google Sheets (텍스트) + Google Drive (이미지) + Figma │ └─────────────────────────────────────────────────────────────┘ ``` 이 다이어그램에서 눈여겨볼 점이 있습니다. **에이전트(🤖) 옆에 스킬(📚)이 같이 표시된 것들**이 있죠? 그게 "이 에이전트는 이 매뉴얼을 참조하면서 일한다"는 뜻입니다. Market Researcher나 Image Analyst처럼 스킬이 없는 에이전트는 자체 판단으로 일해요. 각 Phase가 실제로 어떻게 돌아가는지는 2편에서 자세히 다룰게요! ## 폴더 구조가 곧 아키텍처다 에이전트 시스템에서 폴더 구조가 생각보다 중요합니다. Claude Code가 어떤 파일을 읽고, 어디에 저장하고, 뭘 참조하는지가 전부 경로로 결정되거든요. ```javascript project/ │ ├── .claude/ │ ├── skills/ ← 📚 매뉴얼 모음 │ │ ├── translation/ │ │ │ ├── SKILL.md ← 번역 원칙 │ │ │ └── references/ │ │ │ ├── beauty-glossary-us.md ← 미국 뷰티 용어집 │ │ │ ├── beauty-glossary-jp.md ← 일본 뷰티 용어집 │ │ │ └── forbidden-claims.md ← 금지 표현 목록 │ │ ├── copywriting/ │ │ │ ├── SKILL.md │ │ │ └── references/ │ │ │ ├── amazon-seo-guide.md │ │ │ ├── tone-guide-us.md │ │ │ └── tone-guide-jp.md │ │ ├── image-generation/ │ │ ├── qa/ │ │ ├── orchestrator/ │ │ └── output-manager/ │ │ │ ├── agents/ ← 🤖 에이전트 정의 │ │ ├── market-researcher.md │ │ ├── translator.md │ │ ├── copywriter.md │ │ ├── image-analyst.md │ │ ├── image-generator.md │ │ └── qa-reviewer.md │ │ │ └── settings.json ← MCP 서버 설정 │ ├── config/ │ ├── countries.yaml ← 타겟 국가 목록 │ ├── brands.yaml ← 브랜드 목록 │ └── market-research/ ← 시장 조사 캐시 │ ├── brand-assets/ ← 제품 원본 이미지 (변형 금지!) │ └── {brand}/products/{product}/ │ ├── cuts/ ← 누끼컷 (AI 참조용) │ ├── photoshoots/ ← 촬영컷 │ └── product-info.json │ └── data/ ├── processing/ ← 중간 결과 └── output/ ← 최종 결과물 ``` 여기서 짚고 넘어갈 포인트가 3가지 있어요. ### 1. 스킬 폴더 안의 references 디렉토리 번역 스킬의 SKILL.md가 메인 지침이고, 그 안에서 `[US 용어집](references/beauty-glossary-us.md)`처럼 참조 문서를 링크합니다. 에이전트가 실행될 때 이 참조 문서까지 자동으로 읽어요. 예를 들어 "송이버섯"을 "Matsutake"로 번역하라는 것도, "탈모 예방"을 "supports healthy hair"로 완화하라는 것도 전부 이 참조 문서에 적혀 있습니다. ### 🔥 2. brand-assets: 이 시스템에서 가장 중요한 폴더 🔥 **brand-assets는 절대 건드리면 안 되는 영역이자, 이 시스템에서 가장 중요한 폴더입니다.** AI로 이미지를 생성할 때 제품이 변형되는 게 가장 위험한데 - 민트색 병이 초록색이 되거나, 라벨이 뭉개지거나 - 이걸 막는 유일한 방법이 **원본 사진을 최대한 많이 넣어서 참조하게 하는 것**입니다. 누끼컷(배경 제거된 제품 사진) 정면, 측면, 라벨 클로즈업. 촬영컷(실제 촬영된 사진) 여러 각도. 이런 에셋을 최대한 많이 준비해서 brand-assets에 넣어두세요. Gemini API 호출할 때 이 이미지들을 참조로 보내면, AI가 "아 이 제품은 이렇게 생긴 거구나"를 훨씬 정확하게 인식합니다. 저도 처음에는 누끼컷 1장만 넣었다가 제품 색상이 매번 바뀌어서 고생했는데, **3장 이상 넣으니까 일관성이 눈에 띄게 올라갔습니다.** **에셋이 많을수록 좋아요.** Gemini는 참조 이미지를 최대 14개까지 받으니까, 제품 관련 이미지는 넉넉하게 6장 정도 넣어도 됩니다. 여기서 아끼면 나중에 재생성 비용으로 더 나갑니다. ### 3. 국가 확장은 YAML 한 줄 `config/countries.yaml`에 새 국가를 추가하면 에이전트 코드를 건드릴 필요 없이 바로 적용됩니다. ```javascript - code: MY language: ms-MY name: Malaysia alternate_platforms: - shopee.com.my special_considerations: - halal_certification - hijab_models ``` 말레이시아를 추가하면서 할랄 인증이나 히잡 모델 같은 특수 고려사항까지 설정에 넣을 수 있게 했습니다. ## MCP 서버로 외부 서비스 연결하기 Claude Code가 Google Sheets, Drive, Figma, Gemini API와 통신하려면 MCP(Model Context Protocol) 서버를 설정해야 합니다. ```javascript { "mcpServers": { "google-sheets": { "command": "npx", "args": ["-y", "@anthropic/mcp-google-sheets"] }, "google-drive": { "command": "npx", "args": ["-y", "@anthropic/mcp-google-drive"] }, "figma-read": { "command": "npx", "args": ["-y", "@anthropic/mcp-figma"] }, "gemini-image": { "command": "python", "args": ["gemini-mcp-server.py"] } } } ``` 이렇게 해두면: - **Google Sheets** - 스프레드시트에서 제품 정보 읽고, 번역 결과를 옆 컬럼에 바로 작성 - **Google Drive** - 이미지 다운/업로드, 국가별 하위폴더 자동 생성 - **Figma** - 디자이너한테 넘길 프레임 자동 구성 - **Gemini** - 이미지 현지화 생성 입력도 출력도 기존에 쓰던 도구에서 바로 이루어지니까, 별도 대시보드가 필요 없습니다. 지인 회사 입장에서는 Google Sheets랑 Drive만 쓰면 되는 거예요. ## 다음 편 예고 설계는 여기까지입니다. 구조를 요약하면: - 6개 서브에이전트 + 6개 스킬(매뉴얼) - 스킬에 지침을 쓰고, 에이전트가 참조하면서 실행 - YAML 설정으로 국가/브랜드 확장 - MCP 서버로 외부 서비스 연결 근데 이 에이전트들이 **어떤 순서로 일하는지**가 더 중요합니다. 시장 조사가 번역에 영향을 주고, 번역 결과가 이미지 생성에 영향을 주고, 그 사이에 사람이 한번 확인하는 체크포인트가 있어요. 2편에서는 이 6단계 파이프라인이 실제로 어떻게 돌아가는지 보여드릴게요. --- **Claude Code 멀티 에이전트로 상세페이지 현지화 자동화** [#1 설계편](https://zoey.day/claude-code-agent-product-page-localization) [#2 파이프라인편](https://zoey.day/claude-code-agent-product-page-localization-pipeline) [#3 이미지 생성 삽질편](https://zoey.day/claude-code-agent-product-page-localization-image) For the site tree, see the [root Markdown](https://zoey.day/.md).