134개 블로그 이미지를 0 Claude 토큰으로 — Claude×Codex 멀티에이전트 분업 패턴

1. 문제 상황: 134개 글에 feature image를 일괄로 박아야 했는데

블로그 글이 134개 쌓였습니다. 그동안 feature image 없이 텍스트만 올라가던 글이 91개, 예약 발행 대기 중인 글이 38개, 곧 발행할 draft가 5개. 모두 같은 비주얼 시스템으로 통일된 카드 이미지가 박혀 있어야 메인 페이지·태그 페이지·오픈그래프가 일관됩니다.

수동으로 134개를 만든다는 건 현실적이지 않았습니다. Figma 템플릿을 복사해 글마다 헤드라인 바꾸고 본문 핵심을 시각화하면 글당 최소 10분, 총 22시간이 듭니다. 그래서 LLM에게 시킨다고 가정해 봤습니다.

가장 단순한 접근은 Claude에게 직접 시키는 것이었습니다.

사용자 → Claude
       → 각 글 본문 읽기 (134번)
       → 본문 분석해 핵심 시각 요소 추출
       → 이미지 생성 프롬프트 작성
       → 이미지 생성 API 호출
       → 결과 검수
       → Ghost API로 업로드 + feature_image 설정

그런데 이 흐름을 토큰으로 환산해 보면 곧바로 문제가 보입니다.

글당 본문: 평균 5KB (한글 + 코드 블록 포함)
→ Claude 입력 토큰: 약 3,000 토큰

134개 × 3,000 = 402,000 토큰 입력
+ 프롬프트 작성 출력: 글당 약 1,500 토큰
134개 × 1,500 = 201,000 토큰 출력

합계: 약 600,000 Claude 토큰 (입출력)

Claude Sonnet 4.6 기준으로 60만 토큰은 결코 가벼운 작업이 아닙니다. 더 큰 문제는 컨텍스트 윈도우입니다. 한 세션 안에서 134개 본문이 차례차례 컨텍스트에 쌓이면 200K 윈도우를 금세 넘기고, Claude는 앞 글의 컨텍스트를 압축하느라 정확도가 떨어집니다.

그리고 Claude가 본문을 다 읽었다 한들, 본문에서 시각 요소를 추출하는 일은 Claude의 강점도 아닙니다. 코드 알고리즘을 다이어그램화하거나 터미널 미니어처를 그릴 때 어떤 라벨이 들어가야 하는지 결정하는 것은 이미지 생성 모델(gpt-image-2)의 표현력에 맞춰 프롬프트를 정교화하는 작업입니다. Claude는 텍스트 추론을 잘하지만, 이미지 생성기에게 시각 디테일을 일일이 지시하는 건 별도 전문성입니다.

이 두 가지 — 토큰 비용과 콘텐츠 가공 전문성 — 가 같은 LLM에 묶일 이유가 없다는 게 출발점이었습니다.

2. 원인 분석: "오케스트레이션"과 "콘텐츠 가공"이 다른 책임이라는 자각

다시 작업 흐름을 분해해 보면 두 가지 종류의 일이 섞여 있습니다.

오케스트레이션은 정보량이 적습니다. 슬러그·경로·ID 같은 짧은 식별자만 있으면 됩니다. 반면 콘텐츠 가공은 본문 전체(글당 5KB)를 깊이 읽어야 합니다.

이 둘을 같은 모델에 묶으면 어떻게 되느냐. 오케스트레이션을 하는 동안에도 본문 5KB가 컨텍스트에 들어 있어야 합니다. Claude가 ghost MCP를 호출하고 다음 슬러그로 넘어가는 순간순간에 모든 본문이 컨텍스트에 살아 있으면, 토큰은 ‘작업당 1회’가 아니라 ‘작업 × 컨텍스트 크기’만큼 누적됩니다.

분업 원칙을 정리하면 이렇습니다.

결정은 비싼 모델, 실행은 저렴한 채널.

결정에 필요한 정보(슬러그·ID·경로)는 짧기 때문에 비싼 모델(Claude)에게 맡겨도 토큰이 적게 듭니다. 반면 실행에 필요한 정보(본문 전체)는 길기 때문에, 본문을 직접 읽는 일은 보조 에이전트나 스크립트가 디스크에서 처리하게 해야 합니다.

이 원칙을 적용하려면 두 가지가 필요했습니다.

1. 본문이 Claude 컨텍스트를 거치지 않을 경로: 디스크나 다른 LLM이 직접 본문을 읽는 구조
2. 이미지 생성과 본문 분석을 동시에 잘하는 보조 에이전트: 그게 마침 OpenAI의 codex CLI에 있었습니다 (/imagen 명령 + gpt-image-2 백엔드 + GPT‑5.5 기반 추론)

3. 해결: 분업 아키텍처

설계된 흐름은 다음과 같습니다.

┌──────────┐    슬러그/경로/ID 매핑     ┌─────────────┐
│ Claude   │ ─────────────────────▶   │ bash runner │
│ (메인)   │                           │ (gen-...sh) │
└──────────┘                           └──────┬──────┘
     │                                        │ 본문 파일 경로 + 브랜드 스펙 경로
     │                                        ▼
     │                                  ┌──────────┐
     │                                  │ codex    │
     │                                  │ (보조)   │
     │                                  │          │
     │                                  │ 1. brand-spec.md 읽기
     │                                  │ 2. 본문 .md 읽기
     │                                  │ 3. 프롬프트 구성
     │                                  │ 4. /imagen 호출
     │                                  │ 5. PNG 저장 + SHA1 검증
     │                                  └────┬─────┘
     │                                       │
     │           파일 경로만 회수             │
     │ ◀─────────────────────────────────────┘
     │
     │  Ghost MCP 호출
     ▼
┌───────────────┐
│ Ghost Admin   │
│ - upload PNG  │
│ - update post │
│   feature_img │
└───────────────┘

[disk]
~/blog-drafts/<slug>.md            ← 본문 (Claude 안 거침)
~/.claude/blog-feature-image/
  brand-spec.md                    ← 비주얼 시스템 락
  gen-feature-image.sh             ← codex 호출 래퍼
~/blog-drafts/images/.../<slug>.png ← 결과

핵심은 본문이 디스크에서 codex로 직행하고 Claude는 슬러그·경로만 다룬다는 점입니다. Claude는 ghost MCP 호출의 결과(짧은 메타데이터)와 스크립트 실행 결과(파일 경로 + 성공 플래그)만 컨텍스트에 둡니다.

3.1 codex 호출 래퍼: 본문을 Claude로 끌어들이지 않는다

gen-feature-image.sh가 이 분업의 핵심 인터페이스입니다. Claude는 이 스크립트에 슬러그·본문 파일 경로·타깃 이미지 경로 세 개의 짧은 인자만 넘깁니다.

#!/usr/bin/env bash
# gen-feature-image.sh <slug> <post-md-path> <target-png-path>
set -euo pipefail

SLUG="${1:?}"
POST_PATH="${2:?}"
TARGET_PATH="${3:?}"

BRAND_SPEC="${BLOG_FEATURE_IMAGE_BRAND_SPEC:-$HOME/.claude/blog-feature-image/brand-spec.md}"

# codex가 image_generation 기능을 켜고 있는지 보장
if [[ "$(codex features list 2>&1 | awk '/^image_generation/ {print $NF}')" != "true" ]]; then
  codex features enable image_generation >/dev/null
fi

mkdir -p "$(dirname "$TARGET_PATH")"

CODEX_PROMPT=$(cat <<EOF
You are designing a feature image for a Korean technical blog.

STEP 1. Read these two files in full:
  - Brand visual system spec: ${BRAND_SPEC}
  - Post content for this image: ${POST_PATH}

STEP 2. From the post content, extract:
  (a) A 2-3 word Korean headline that captures the core thesis.
  (b) A 1-line Korean subhead (around 8-12 chars).
  (c) An English monospace caption with 3-5 bullet-separated keywords.
  (d) ONE specific concrete element from the post body
      (real diagram, code snippet, UI mockup, metric)
      that should be visualized in the right two-thirds of the frame.

STEP 3. Determine the category accent color from the post tags
       (match against the brand spec's tag→accent table).

STEP 4. Construct an English image-generation prompt
       (image-studio MODE_E_THUMBNAIL output template, ~400 words)
       that includes Content Summary / Visual Hierarchy / Attention Elements /
       Text Integration / Platform Optimization / Technical Specifications /
       Anti-Patterns sections.

STEP 5. Run /imagen with that prompt and save the raw result to:
       ${TARGET_PATH}

After saving, print the SHA1 hash and confirm it matches
the generated original.

CRITICAL: Korean strings must render in-image (not post-composed).
Right-side illustration must reflect ACTUAL post content (not generic AI motif).

Slug for reference: ${SLUG}
EOF
)

codex exec \
  --skip-git-repo-check \
  "$CODEX_PROMPT"

이 스크립트의 핵심은 codex에게 두 개의 파일 경로만 알려주고, 본문을 읽는 일은 codex 자체에게 위임한다는 점입니다. Claude는 이 스크립트의 인자 3개(슬러그, 본문 경로, 타깃 경로)만 컨텍스트에 둡니다. 본문 5KB는 어디에도 들어오지 않습니다.

codex는 GPT‑5.5 기반이라 위 다단계 지시(읽기 → 추출 → 카테고리 매핑 → 프롬프트 구성 → /imagen 호출 → SHA1 검증)를 한 호출 안에서 따라갑니다. 즉 codex 자체가 작은 멀티 에이전트처럼 행동합니다.

3.2 브랜드 시스템 락: codex가 매번 같은 비주얼 언어를 따른다

134개 글에 같은 비주얼 시스템을 적용하려면 codex에게 매번 같은 디자인 토큰을 주입해야 합니다. 그래서 별도 brand-spec.md 파일을 한 번만 작성하고 매 호출에 참조시킵니다.

brand-spec.md 안에는 이런 락이 들어 있습니다.

## Format
- 16:9 widescreen, landscape
- 1672×941 (gpt-image-2 natural output)
- Format: PNG, raw output, no post-processing

## Background system
- Primary: deep navy #0F172A
- Secondary navy: #1E293B
- Diagonal grid lines 32px, color #1E293B, 5% opacity

## Layout (fixed)
- Left third: typography column
  Korean headline 64-72pt + subhead 26-28pt + English caption 14-16pt
- Right two-thirds: topic-specific illustration
- Bottom-right: ultra-subtle "blog.uppinote.dev" wordmark

## Category accent colors
| Tag pattern                          | Accent (hex) |
|--------------------------------------|--------------|
| AI/Claude Code, AI/도구활용          | #F97316      |
| 백엔드/API설계, 백엔드/Prisma...     | #14B8A6      |
| 프론트엔드/Next.js, /React, /CSS...  | #6366F1      |
| 인프라/Docker, /네트워크, /서버      | #10B981      |
| Ghost/...                            | #A855F7      |

## Anti-patterns (ALWAYS REJECT)
- ❌ Matrix code rain / holographic blue grid
- ❌ Hooded hacker silhouette
- ❌ Neural-network connected nodes motif
- ❌ Lightbulb = idea metaphor
- ❌ Corporate Memphis flat illustration
- ❌ Stock photo of person at laptop pointing at screen
- ...

이 파일이 codex에게 "어떻게 그릴지"의 전체 규칙을 한 번에 전달합니다. 134번의 호출 모두 이 같은 락을 읽으니, 결과 이미지가 시각적으로 한 가족처럼 보입니다.

3.3 배치 러너: 동시성을 Claude 밖에서 관리한다

Claude가 134번 codex를 동기 호출하면 한 호출당 1-3분, 총 4-7시간이 통째로 흐릅니다. 동시성을 Claude 내부에서 관리하면 컨텍스트가 또 무거워집니다.

그래서 동시성은 bash 러너가 책임집니다.

RESULTS=~/.claude/blog-feature-image/run-results
mkdir -p "$RESULTS"
MAX=6
N=0

while IFS=$'\t' read -r -u 3 slug src tgt; do
  N=$((N+1))
  (
    if [[ -s "$tgt" ]]; then
      echo skip > "$RESULTS/${slug}.status"
    elif bash gen-feature-image.sh "$slug" "$src" "$tgt" \
         > "$RESULTS/${slug}.log" 2>&1 < /dev/null; then
      echo ok > "$RESULTS/${slug}.status"
    else
      echo fail > "$RESULTS/${slug}.status"
    fi
  ) &
  if (( N % MAX == 0 )); then
    wait
  fi
done 3< tasks.tsv

wait

세 가지 디테일이 있습니다.

1. read -r -u 3 + 3< tasks.tsv — 부모 프로세스가 fd 3에서 슬러그 목록을 읽고, 자식 프로세스(codex)는 stdin을 건드리지 않습니다. 이 분리가 없으면 codex가 stdin에서 한 줄을 소비해 다음 슬러그가 사라지는 버그가 납니다. (실제로 처음 배치에서 wave 1만 돌고 종료된 적이 있었습니다.)
2. < /dev/null — codex 호출에 빈 stdin을 명시로 닫아 같은 문제를 이중 방어합니다.
3. wave 단위 wait — xargs -P도 가능하지만 wave 사이 진행 보고를 끼우기 쉽고 macOS 기본 bash에서 흔히 동작합니다.

Claude는 이 러너의 종합 보고(ok=X skip=Y fail=Z)만 받습니다. 134개 본문은 어디에도 거치지 않았습니다.

3.4 Claude의 책임: ID 매핑과 Ghost MCP 호출

이제 Claude가 할 일이 분명해집니다.

1. 슬러그 목록 만들기 (ghost_list_posts → 슬러그·태그·상태)
2. 슬러그 ↔ 본문 파일 경로 매핑
3. tasks.tsv 작성
4. 배치 러너 실행 → 결과 보고만 회수
5. 이미지 파일들 Ghost에 업로드 (ghost_upload_image)
6. 슬러그 ↔ 호스팅 URL ↔ post ID 매핑 후
   ghost_update_post(id, feature_image) 일괄 호출

이 단계에서 Claude 컨텍스트에 들어오는 정보는 모두 짧습니다. 본문 단 한 줄도 거치지 않습니다.

4. 정량 결과

실제 진행은 두 배치였습니다.

Claude 토큰 추정치 비교입니다.

~613K → ~11K, 약 55배 감소.

엄밀한 측정은 아닙니다(Claude API는 정확한 입출력을 보고하지만 Claude Code 안에서는 세션 누적값으로 추정). 다만 두 자릿수 배수 차이는 본문이 컨텍스트를 거치느냐 마느냐의 직접 결과입니다.

비용으로 환산하면 Sonnet 4.6 기준 약 ~$4.25가 ~$0.07로 줄어드는 정도이지만, 실제 의미는 토큰이 아니라 컨텍스트 위생입니다. 본문 134개가 컨텍스트에 쌓이지 않으니 Claude의 작업 정확도가 유지됩니다. 슬러그-ID 매핑이 망가질 일이 없습니다.

5. v1 vs v2 — 분업이 시각적으로 만든 차이

이 글의 시작은 첫 시도가 만족스럽지 않아서였습니다. 처음 3개 글로 시범 생성했을 때는 Claude가 메타데이터(제목·태그·meta_description)만 읽고 프롬프트를 직접 작성했고, 결과는 일반적인 추상 — "API 박스 → 분기 → 캐시 박스" 같은 — 이미지였습니다.

같은 글을 codex가 본문을 읽고 생성하게 했더니 결과가 달라졌습니다. "실패도 캐싱하라" 글의 v1과 v2를 비교하면 차이가 분명합니다.

• v1 (Claude가 메타로 추측): Ok<T> / Err<E> 라벨이 있는 다이어그램 (글의 일반론적인 추상)
• v2 (codex가 본문 직접 읽음): 본문에 나오는 6단계 알고리즘 (token → memory cache → fileCache → pendingRequests → API 429 → set negative cache 30s) + 실제 상수값 NEGATIVE_CACHE_SECONDS = 30, STALE_FALLBACK_SECONDS = 3600

v2는 본문에 실제로 적힌 알고리즘과 상수를 시각화했습니다. v1은 "negative caching"이라는 주제어를 보고 추측한 일반적 도식이었습니다.

이 차이는 단순한 디자인 디테일이 아닙니다. 본문을 직접 읽은 LLM이 본문 메타데이터만 본 LLM보다 정확하다는 RAG 정확도의 일반 원리이고, 분업 구조가 이를 자연스럽게 강제합니다. (시각 비교와 brand-spec 구성 디테일은 시리즈 3편에서 더 깊이 다룹니다.)

6. 일반화: 분업 패턴은 다른 시나리오에도 적용된다

이 작업의 본질은 "이미지 134개"가 아니라 **"긴 콘텐츠를 가공하는 일을 보조 에이전트에게 위임하면 메인 LLM 토큰이 거의 들지 않는다"**입니다. 같은 패턴이 적용되는 다른 시나리오들이 있습니다.

공통 원칙은 세 가지입니다.

1. 결정과 실행을 분리한다. 결정은 짧은 식별자만 다루고, 실행은 긴 콘텐츠를 다룬다.
2. 긴 콘텐츠는 디스크나 외부 LLM에 두고, 메인 LLM 컨텍스트를 거치지 않게 한다.
3. MCP 도구 결과는 자동으로 메인 LLM 컨텍스트에 들어가므로, MCP를 우회할 수 있는 경로(파일 경로, 외부 API, 서브 에이전트)가 있는지 먼저 확인한다.

세 번째 원칙은 의외로 중요합니다. MCP 도구는 LLM이 직접 호출할 수 있어 편하지만, 모든 응답이 컨텍스트에 들어옵니다. ghost_get_post(include_content=true)를 134번 호출하면 본문 134개가 모두 Claude로 들어옵니다. 이번 작업에서 우리는 본문이 이미 디스크에 있는 글은 MCP를 우회하고, 디스크에 없는 글만 MCP로 fetch한 뒤 곧바로 디스크에 저장해 다음부터는 디스크에서 처리했습니다.

7. 핵심 개념 정리

8. 베스트 프랙티스 체크리스트

작업을 시작하기 전:

• [ ] 작업이 "결정"과 "실행"으로 분리 가능한가? 분리 가능하면 분업 후보
• [ ] 실행 단계가 긴 콘텐츠(>1KB/건)를 매번 읽어야 하나? 그렇다면 메인 LLM 우회 필요
• [ ] 보조 에이전트(codex/local LLM)나 외부 batch API가 같은 작업을 처리 가능한가
• [ ] 결정 단계의 식별자(슬러그·ID·경로)가 충분히 짧은가
• [ ] 디스크에 이미 콘텐츠가 있는 케이스를 식별해 MCP를 우회하는가
• [ ] 동시성을 메인 LLM 밖에서 관리하는가 (bash 러너, 워크플로우 엔진 등)
• [ ] 보조 에이전트의 결과 보고가 짧고 일관된가 (성공 플래그 + 파일 경로 정도)

실행 중:

• [ ] 메인 LLM 컨텍스트에 본문/긴 콘텐츠가 새어 들어오지 않는지 주기적 확인
• [ ] 보조 에이전트의 stdin/stdout 분리 (< /dev/null, fd-3 패턴)
• [ ] 실패 케이스가 메인 LLM 컨텍스트를 오염시키지 않게 (fail만 기록, 본문 로그는 디스크)

9. FAQ

Q. Codex가 본문을 읽는 게 Claude보다 정확하다는 게 무슨 뜻인가요?

A. 더 똑똑하다는 뜻이 아니라, 본문을 직접 읽으면 메타데이터만 읽었을 때보다 결과가 정확하다는 RAG의 일반 원리입니다. Claude를 codex 자리에 두고 본문을 직접 읽게 해도 결과는 비슷할 겁니다. 다만 Claude에 본문을 읽히면 134개 본문이 메인 컨텍스트로 들어옵니다. 이 글의 핵심은 “codex가 더 낫다”가 아니라 “본문을 메인 LLM 컨텍스트 밖에 두는 게 낫다”입니다.

Q. 멀티 에이전트가 항상 좋은가요?

A. 아닙니다. 작업이 짧으면(예: 글 한 편) 분업의 인프라(스크립트, 디스크 경유, 동시성 관리) 비용이 더 클 수 있습니다. 분업은 반복 횟수가 많고 콘텐츠가 길 때 본전을 뽑습니다. 이번 케이스는 134번 × 5KB라 분명히 본전 이상이었습니다.

Q. Hook으로 자동화하면 안 되나요? ghost_push_local 후 PostToolUse hook이 이미지 생성을 자동 트리거하는 것처럼.

A. 가능하지만 두 가지 함정이 있습니다. 첫째, codex 한 호출이 1-3분이라 hook이 멈춰 있으면 Claude Code 응답이 그대로 막힙니다. 백그라운드 fire-and-forget으로 돌려야 합니다. 둘째, 자동 발동을 사용자가 끄고 싶을 때 토글이 어렵습니다. 슬래시 커맨드(/feature-image)를 명시적으로 트리거하는 게 디버깅과 통제 면에서 더 안전했습니다.

Q. 다른 도메인에 적용하려면?

A. 위 6번 섹션의 표가 출발점입니다. 적용 시 핵심 질문은 "결정(짧음)과 실행(긺)이 분리되는가, 그리고 실행을 맡길 보조 에이전트/도구가 있는가"입니다. 보조 에이전트가 없으면 batch API, 그것도 없으면 단순 bash 스크립트라도 됩니다. 결정과 실행을 같은 모델에 묶지 않는 것이 본질입니다.

Q. 토큰 절약이 진짜 55배인가요?

A. 추정치입니다. Claude Code 내부에서 정확한 토큰 측정은 어렵고(세션 누적값으로만 보임), 본문 토큰화 비율은 한글·코드 구성에 따라 변합니다. 다만 두 자릿수 배수 차이는 본문이 컨텍스트를 거치느냐 마느냐의 직접 결과라 방향성은 확실합니다.

Q. 결과 이미지 품질은 어땠나요?

A. 134개 중 실패 0건, 모든 이미지가 1672×941로 일관된 해상도, 같은 비주얼 시스템을 따르는 카드. 본문 기반 시각화는 글마다 다른 알고리즘·UI·메트릭을 표현해 시각적 일관성과 콘텐츠 정확성을 동시에 달성했습니다. 자세한 결과 비교는 시리즈 3편에서 다룹니다.

10. 참고 자료

• Claude Code 공식 문서 — Hooks
• OpenAI Codex CLI GitHub
• Ghost Admin API 문서
• Model Context Protocol (MCP) 명세

11. 다음 단계

이 글에서는 분업 아키텍처의 동기와 전체 그림을 다뤘습니다. 시리즈 후속 두 편에서는 각 책임의 구체적 구현을 깊이 풀어 봅니다.

시리즈 목차:

1. 134개 블로그 이미지를 0 Claude 토큰으로 — Claude×Codex 멀티에이전트 분업 패턴 ← 현재 글
2. Ghost MCP로 134개 글 일괄 메타 작업하기 — slug↔ID 매핑·페이지네이션·fd-3 stdin 패턴 (예정)
3. codex /imagen에 한글 헤드라인 시각화 맡기기 — brand-spec 락과 본문 기반 정확도 (예정)