Replicate 이미지 생성 스킬 — MVP 완성부터 코드 리뷰까지

## 배경

Claude Code에서 자연어로 이미지를 생성하는 스킬을 만들고 싶었다. "사이버펑크 도시 야경" 같은 한국어 프롬프트를 입력하면, 영어로 번역하고 Replicate API를 호출해서 로컬에 저장하는 전체 파이프라인.

## 과정

### Phase 1: 작동하는 스킬 만들기 (3/27)

첫 커밋은 직관적이었다:

- 한국어 프롬프트 → 영어 번역 → flux-2-pro API 호출 → {timestamp}_{slug}.webp로 저장

- $ARGUMENTS 치환으로 사용자 입력을 동적 주입

- Prefer: wait 헤더로 동기 호출 (polling 없이 ~20초 대기)

작동은 했지만 Claude Code 공식 스킬 문법을 제대로 따르지 않았다.

### Phase 2: 공식 문법 맞추기 (3/27)

공식 스킬 문서를 다시 읽고 수정:

- allowed-tools: Bash(curl ), Bash(mkdir ) — 정확한 문법

- disable-model-invocation: true 추가 — API 비용 보호

- models-reference.md 작성 — 30+ 모델의 가격/용도별 분류

그런데 disable-model-invocation을 켜니 사용성이 너무 떨어졌다. 결국 모델 레퍼런스에 비용 정보를 충분히 제공하고, 자동 호출을 다시 허용했다.

레슨: 제약보다 정보 공개가 낫다. 사용자가 비용을 알면 스스로 판단할 수 있다.

### Phase 3: autoresearch로 자체 최적화 (3/28)

하네스에 있는 autoresearch 스킬로 replicate-media 스킬을 평가했다. 75% → 100%로 개선:

- slug 생성 규칙이 모호했음 → 영어 프롬프트에서 핵심 단어 추출 규칙 + 예시 3개 추가

- --dir, --model, --count 플래그 동작이 미정의 → 각각 명확히 문서화

- 사용자가 비용을 모름 → 모델별 예상 비용 표시 추가

레슨: 자기 도구로 자기 도구를 개선하라. 메타 도구가 있으면 적극 활용해야 한다.

### Phase 4: 코드 리뷰 반영 (3/30)

PR 리뷰에서 CRITICAL 1건, HIGH 1건을 포함해 8개 이슈가 나왔다.

#### CRITICAL: API 토큰 프로세스 노출

curl -H "Authorization: Bearer $TOKEN"이 ps aux에서 토큰을 노출한다.

```bash

# Before (위험)

curl -H "Authorization: Bearer $REPLICATE_API_TOKEN" ...

# After (안전)

curl --config <(echo "header = \"Authorization: Bearer $REPLICATE_API_TOKEN\"") ...

```

레슨: 셸 명령의 인자는 프로세스 목록에서 보인다. --config나 stdin으로 민감 정보를 전달해야 한다.

#### HIGH: Replicate API 필드 불일치

"version": "black-forest-labs/flux-2-pro"는 잘못된 사용. version은 sha256 해시를 요구한다.

```bash

# Before (422 에러)

POST /v1/predictions

{"version": "black-forest-labs/flux-2-pro", ...}

# After (정상)

POST /v1/models/black-forest-labs/flux-2-pro/predictions

{"input": {...}}

```

레슨: API 문서를 꼼꼼히 읽자. 작동하는 것 같아도 잘못된 필드를 쓰고 있을 수 있다.

#### 모델 레퍼런스 → 탐색 가이드 전환

리뷰 과정에서 models-reference.md에 하드코딩된 30+ 모델 중 openai/gpt-image-1.5가 존재하지 않는 모델이었다 (올바른 ID: openai/gpt-image-1). AI가 생성한 모델 목록에 할루시네이션이 섞여 있었던 것.

이걸 계기로 정적 모델 목록(70줄)을 [Replicate Explore](https://replicate.com/explore) 탐색 가이드(30줄)로 전환했다. 원천 소스를 직접 탐색하는 게 하드코딩보다 정확하다.

레슨: AI가 생성한 참조 데이터는 반드시 검증하라. 그리고 정적 목록보다 원천 소스 링크가 낫다.

## 결과

- PR #13 머지, Issue #1 클로즈

- replicate-media 스킬 Phase 1 완성

- 8건 코드 리뷰 이슈 모두 해결

## 레슨런 요약

1. 제약보다 정보 공개 — disable-model-invocation 대신 비용 정보를 제공하면 사용자가 판단한다

2. 메타 도구 활용 — autoresearch로 스킬 자체를 개선하면 피드백 루프가 빨라진다

3. 셸 보안 — curl Authorization 헤더는 --config로 전달해야 프로세스 목록에 노출되지 않는다

4. API 문서 정독 — 작동하는 것과 올바른 것은 다르다 (version vs model 필드)

5. AI 산출물 검증 — 모델 목록 같은 참조 데이터에 할루시네이션이 섞일 수 있다

6. 원천 소스 > 하드코딩 — 정적 목록은 금방 구식이 된다. 탐색 안내가 더 정확하다