조이의 연습장

클로드 코드 멀티 에이전트로 상세페이지 현지화 #1 - 설계편

조이

Feb 13, 202625d ago

상세페이지 현지화, 번역만 하면 되는 거 아닌가요

현실은 그렇게 단순하지 않습니다.

💬 번역 - "송이버섯 추출물"을 영어로 뭐라고 쓸지부터 고민입니다. "Matsutake Extract"가 맞는지, 그냥 "Mushroom Extract"가 나은지. "탈모 예방"이라고 쓰면 미국 FDA 규정에 걸립니다. "supports healthy hair"로 바꿔야 해요.

✏️ 카피라이팅 - 나라마다 톤도 다릅니다. 미국은 직접적이고 자신감 있게, 일본은 공손하고 섬세하게. 국가별 '말맛'이라는 게 있겠죠.

🎨 이미지 - 한국인 모델 사진을 미국 아마존에 그대로 쓸 순 있지만, 현지화 모델이면 더 좋겠죠. 실제 모델을 섭외하고 촬영까지 하려면 얼마나 돈이 많이 들까요.

❌ 검수 - 금지 표현 없는지, 브랜드명이 일관되는지, 이미지에서 제품이 변형되지 않았는지 하나하나 확인해야 합니다.

이거 다 하는 데 한 달은 걸리게 생겼어요. 4개 나라면 4달. 제품이 10개면? 으악

하나의 AI한테 다 시키면 안 되는 이유

Claude Code한테 "이 제품 현지화해줘"라고 한방에 시켜봤습니다.

결과가 어땠냐면... 번역은 괜찮은데 SEO 키워드가 빠져 있고, 이미지 프롬프트는 너무 대충 나오고, 검수는 아예 건너뛰더라고요.

당연한 겁니다. 번역하면서 동시에 SEO 최적화하고 이미지까지 분석하라고 하면, 사람도 못해요. 컨텍스트 윈도우에 정보가 너무 많이 들어가니까 하나하나의 품질이 떨어져요.

한 명한테 다 시키지 말고, 전문가 여러 명한테 나눠서 시키자.

Claude Code의 스킬(Skill)과 서브에이전트(Sub-Agent)

Claude Code에는 스킬(Skill)과 서브에이전트(Sub-Agent)라는 두 가지 개념이 있습니다.

📚 스킬 = 매뉴얼 / 지침서
   Claude가 읽고 따르는 지식
   같은 대화 안에서 참조됨
   예: 번역 용어집, 아마존 SEO 가이드, 이미지 생성 규칙

🤖 서브에이전트 = 전문 담당자
   별도 대화창에서 독립적으로 실행
   맡은 일만 하고 결과만 돌려줌
   예: 번역 담당, 카피 담당, 이미지 생성 담당

왜 둘을 나눠야 할까요?

스킬만 쓰면 - 모든 지침이 하나의 대화에 쌓입니다. 번역 용어집 + SEO 가이드 + 이미지 규칙 + QA 체크리스트를 한꺼번에 넣으면 컨텍스트가 터집니다.

서브에이전트만 쓰면 - 각자 독립적으로 돌아가니까 좋은데, 에이전트한테 "이 규칙 따라"라고 매번 프롬프트에 다 쓸 수 없습니다.

그래서 스킬에 지침을 적어두고, 에이전트가 그 스킬을 참조하면서 일하는 구조로 만들었어요.

번역 에이전트가 실행되면 translation 스킬에 적힌 용어집, 금지 표현, 단위 변환 규칙을 자동으로 참조합니다. 에이전트는 "실행자", 스킬은 "참고서" 역할이에요.

최종 설계: 6명의 에이전트와 6개의 스킬

이렇게 해서 만든 전체 구조입니다.

┌─────────────────────────────────────────────────────────────┐
│                📚 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가 어떤 파일을 읽고, 어디에 저장하고, 뭘 참조하는지가 전부 경로로 결정되거든요.

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에 새 국가를 추가하면 에이전트 코드를 건드릴 필요 없이 바로 적용됩니다.

- 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) 서버를 설정해야 합니다.

{
  "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단계 파이프라인이 실제로 어떻게 돌아가는지 보여드릴게요.

Subscribe to 'zoeylog'

Subscribe to my site to be the first to receive notifications and emails about the latest updates, including new posts.
Join Slashpage and subscribe to 'zoeylog'!