awesome-gpt-image-2 딥다이브
— 프롬프트 모음집이 “제품”이 되기까지

1프로젝트 한줄 요약

awesome-gpt-image-2는 OpenAI의 이미지 모델 GPT-Image-2로 좋은 그림을 뽑아낸 사례 532개를 모아 놓고, 그 사례들에서 반복되는 뼈대를 22개의 재사용 템플릿으로 정리한 저장소입니다.

여기까지는 흔한 awesome 목록입니다. 이 저장소가 다른 지점은 그다음입니다 — 마크다운으로 적어 둔 사례들이 빌드할 때마다 cases.json이라는 데이터 파일로 변환되고, 그 한 벌의 데이터가 웹사이트와 AI 에이전트용 스킬 양쪽에 동시에 공급됩니다.

그리고 하나 더 — 그 웹사이트는 취미 페이지가 아니라 로그인·크레딧·결제가 붙은 실제 상용 서비스이고, 그 서버 코드가 MIT 라이선스로 같은 저장소에 공개돼 있습니다. 공부 대상으로서 이 저장소의 진짜 값어치는 프롬프트가 아니라 여기에 있습니다.

2왜 주목받는가

① 모델 출시 직후의 공백을 메웠다

새 이미지 모델이 나오면 항상 같은 문제가 생깁니다. 모델은 좋아졌는데 무슨 말을 어떻게 적어야 그 성능이 나오는지 아무도 모릅니다. 이 저장소는 커뮤니티에 흩어진 성공 사례를 모아 그 공백을 메웠고, 2026년 4월 25일 생성 이후 4개월 만에 별 1.5만 개를 받았습니다.

② 사례를 모으는 데서 멈추지 않고 ‘구조’를 뽑아냈다

사례 532개를 그냥 나열하면 쓸모가 떨어집니다. 이 저장소는 사례들에서 반복되는 뼈대를 12개 카테고리 × 22개 템플릿으로 압축했습니다. 각 템플릿에는 언제 쓰는지(useWhen), 지켜야 할 것(guidance), 흔히 망하는 지점(pitfalls)이 영어·중국어 양쪽으로 붙어 있습니다.

특히 “망하는 지점”을 명시한 게 실무적입니다. 예를 들어 UI 스크린샷 템플릿의 주의사항은 이렇습니다 — 플랫폼 이름을 뭉뚱그리지 말 것, 화면에 들어갈 글자의 가독성과 플랫폼 고유 요소를 조건으로 못 박을 것.

③ 같은 데이터로 에이전트 스킬까지 만들어 3중 배포

이 저장소의 스킬 gpt-image-2-style-library는 세 가지 경로로 설치됩니다. 하나의 소스에서 세 채널로 나가는 구조 자체가 배울 만합니다.

④ 상용 서비스의 “돈 받는 코드”가 통째로 열려 있다

이게 공부 자료로서 가장 희소한 부분입니다. 결제·크레딧·환불처럼 실수하면 바로 돈 문제가 되는 코드는 보통 비공개입니다. 그런데 여기엔 Stripe 결제, 알리페이 결제, 크레딧 차감/환불, 관리자 대시보드, 유료 커뮤니티 QR 발급까지 실제로 돈이 오가는 흐름 전체가 마이그레이션 SQL과 함께 공개돼 있습니다.

⑤ 그런데 — 솔직하게 짚어야 할 것

경쟁 자료와 비교하면

3기술 스택 전체 지도

프론트엔드

백엔드 (서버리스 함수)

데이터베이스 · 인증

결제 · 외부 연동

인프라 · CI

• Vercel — 정적 사이트 + 서버리스 함수 한 벌 배포. cleanUrls와 rewrite 4개로 /community 경로 처리
• GitHub Actions — gpt-image-2-style-library-v* 태그를 밀면 스킬 패키지를 GitHub Packages에 자동 배포
• 빌드 훅 — predev/prebuild에서 데이터 생성 스크립트를 강제 실행. 사람이 잊어도 데이터가 낡지 않음

4아키텍처 심화 분석

전체 그림

설계 ① 마크다운을 데이터베이스로 쓴다

사례 데이터는 DB에도, JSON 원본에도 없습니다. 사람이 읽기 좋은 마크다운 문서에만 있고, 빌드할 때 정규식으로 파싱해 JSON을 만들어 냅니다.

// scripts/generate-site-data.mjs — 마크다운에서 사례를 뜯어내는 부분
// 1) 케이스 경계는 HTML 앵커로 자른다
const chunks = text.split(/<a name="case-(\d+)"><\/a>/g);

// 2) 프롬프트는 "**提示词：**" 다음의 코드펜스 안
const match = normalized.match(/\*\*提示词：\*\*[\s\S]*?```(?:text)?\n([\s\S]*?)```/);

// 3) 카테고리가 비면 제목·본문 키워드로 추론 (규칙 12개)
['UI & Interfaces', ['ui','app','interface','dashboard','截图']],
['Charts & Infographics', ['infographic','diagram','图谱','信息图']],
// ... 매칭이 하나도 없으면 'Other Use Cases'로 떨어뜨림

설계 ② 빌드를 실패시키는 검증 게이트

마크다운 파싱은 깨지기 쉽습니다. 그래서 스킬 생성 스크립트에는 조건을 어기면 빌드를 멈추는 검사들이 박혀 있습니다.

// scripts/generate-style-skill.mjs
function assertUnique(items, field, label) {   // ① id 중복 금지
  if (seen.has(value)) throw new Error(`${label} has duplicate ${field}`);
}

// ② 템플릿이 가리키는 앵커가 templates.md에 실제로 있는지
const templateAnchors = new Set([...templateText.matchAll(/<a name="([^"]+)"><\/a>/g)]);

// ③ 커버 이미지 파일이 디스크에 실재하는지
function localImagePath(src) { return join(root, 'data', ...); }

// ④ 금지된 문체("不是…而是" 대비 구문)가 섞이면 실패
function assertNoPattern(text, label) { ... }

설계 ③ 크레딧을 안전하게 깎는 ‘예약 → 확정 → 해제’ 3단계

이 저장소에서 가장 값진 코드입니다. 문제 상황은 이렇습니다 — 돈(크레딧)은 먼저 깎아야 하는데, 이미지 생성은 실패할 수 있습니다. 먼저 깎으면 실패 시 손해고, 나중에 깎으면 무한 생성이 가능해집니다.

핵심은 차감과 환불을 애플리케이션 코드가 아니라 데이터베이스 함수 안에서 처리한다는 점입니다. 서버가 중간에 죽어도 크레딧이 반쪽만 깎이는 상태가 생기지 않습니다.

-- supabase/migrations/202605090001_user_credits.sql
create or replace function public.reserve_generation_usage(...)
language plpgsql
security definer              -- 함수 소유자 권한으로 실행
set search_path = public      -- 검색 경로 고정 = 함수 가로채기 방지
as $$
begin
  select * into v_profile from public.profiles
   where id = p_user_id for update;   -- ★ 행 잠금: 동시 요청 직렬화
  ...

설계 ④ 권한을 “주지 않는” 방식의 보안

-- 같은 파일 끝부분. 순서가 중요하다: 먼저 회수, 그다음 딱 하나만 허용
revoke execute on function public.reserve_generation_usage(...)
  from public, anon, authenticated;     -- 로그인한 사용자조차 못 부름

grant execute on function public.reserve_generation_usage(...)
  to service_role;                       -- 서버만 부를 수 있음

브라우저가 들고 있는 열쇠(anon key)로는 크레딧 함수를 호출할 방법이 아예 없습니다. 서버 전용 열쇠(SUPABASE_SERVICE_ROLE_KEY)는 Vercel 환경변수에만 두고 브라우저 코드에 절대 넣지 않습니다.

설계 ⑤ 로컬 개발용 Vercel 흉내내기

Vercel Functions는 클라우드에서만 도는 게 원칙이라 로컬 개발이 번거롭습니다. 이 저장소는 Vite 플러그인 100줄로 그걸 흉내 냅니다.

// scripts/vite-local-api.mjs
export function localVercelApi() {
  return {
    name: 'local-vercel-community-api',
    apply: 'serve',                  // 개발 서버에서만 동작
    configureServer(server) {
      server.middlewares.use(async (req, res, next) => {
        // Vercel이 넣어주는 것들을 손으로 채워 넣는다
        req.query = Object.fromEntries(requestUrl.searchParams.entries());
        attachVercelResponseHelpers(res);   // res.status().json() 흉내
        const module = await routeLoader();
        await module.default(req, res);      // 실제 핸들러를 그대로 실행
      });
    }
  };
}

포인트는 핸들러 코드를 하나도 고치지 않는다는 것입니다. 부족한 건 Vercel이 얹어주는 req.query와 res.status().json()뿐이라, 그 둘만 채워 주면 같은 파일이 로컬에서도 돕니다.

5디렉토리 구조 해부

6학습 포인트

① 결제·크레딧 시스템 설계 난이도 높음 · 가치 최상

배울 것: 예약-확정-해제 3단계, FOR UPDATE 행 잠금, 보상 트랜잭션, 거래 원장(credit_transactions) 분리.

왜 귀한가: 이런 코드는 대개 회사 안에만 있습니다. 잔액 하나로 두 번 결제되는 사고, 실패했는데 돈만 빠지는 사고는 전부 이 설계를 대충 해서 생깁니다.

실습 아이디어: reserve_generation_usage를 직접 psql에 붙여넣고, 서로 다른 두 세션에서 동시에 호출해 보세요. FOR UPDATE를 지웠을 때와 남겼을 때 잔액이 어떻게 달라지는지가 바로 눈에 보입니다.

② 문서를 데이터로 쓰는 빌드 파이프라인 난이도 중간 · 응용범위 넓음

배울 것: 마크다운 정규식 파싱, 키워드 기반 분류 추론, 그리고 깨지면 빌드를 세우는 검증.

어디에 쓰나: 사내 위키를 검색 API로, 블로그 글을 뉴스레터 데이터로, 회의록을 대시보드로 — 원본이 문서이고 소비처가 여럿일 때 같은 패턴이 그대로 먹힙니다.

실습 아이디어: 자기 블로그의 마크다운 글을 파싱해 posts.json을 만드는 스크립트를 써 보세요. 그다음 assertUnique처럼 슬러그 중복이면 빌드 실패를 추가해 보면 게이트의 감각이 옵니다.

③ 하나의 소스를 여러 채널로 배포하기 난이도 중간

배울 것: data/style-library.json 하나에서 웹 UI·스킬 레퍼런스·npm 패키지가 파생되는 구조. GitHub Actions에서 태그로 배포를 거는 방법.

핵심 통찰: 스킬을 “따로 관리하는 문서”로 두면 반드시 사이트와 어긋납니다. 생성물로 만들어 두면 어긋날 수가 없습니다 — 이 저장소가 references/style-library.md를 손으로 쓰지 않는 이유입니다.

④ 에이전트 스킬 작성법 난이도 낮음

SKILL.md가 짧고 좋은 예입니다. 배울 지점 세 가지 —

• 기억보다 파일을 믿으라고 명시: “템플릿 이름·카테고리가 중요할 땐 기억 대신 레퍼런스를 읽어라”
• 애매하면 되묻게 함: 후보가 여럿이면 2~3개를 이유와 함께 제시하고 사용자에게 고르게 함
• 출력 형태를 고정: 복사 가능한 프롬프트를 맨 먼저, 제약(글자·비율·레이아웃)은 구체적으로

⑤ 프레임워크 없이 서버리스 API 짜기 난이도 낮음~중간

Express도 NestJS도 없습니다. export default async function handler(req, res)와 _lib/ 공용 모듈만으로 34개 엔드포인트가 굴러갑니다. 프레임워크가 실제로 무엇을 대신해 주고 있었는지(라우팅·바디 파싱·에러 처리) 손으로 확인해 볼 수 있는 크기입니다.

⑥ 프롬프트 엔지니어링 그 자체 난이도 낮음

템플릿 문서가 알려주는 핵심은 “예쁜 형용사”가 아니라 고정해야 할 축입니다.

7하드웨어 / 시스템 요구사항

단계별로 무엇까지 되나

8직접 해볼 수 있는 실습 과제

npx skills add freestylefly/awesome-gpt-image-2 \
  --skill gpt-image-2-style-library --agent claude-code --global --yes --copy

9관련 기술 심화 학습 로드맵

1주차 · 파이프라인과 데이터 생성

2주차 · Postgres와 트랜잭션

3주차 · 서버리스와 결제

4주차 · 에이전트 스킬과 배포

10핵심 키워드 사전

프롬프트 · 에이전트

빌드 · 파이프라인

데이터베이스 · 백엔드

프론트엔드 · 배포

11참고 링크

저장소

• freestylefly/awesome-gpt-image-2 — 본체 (MIT)
• docs/templates.md — 22개 산업용 템플릿 + 함정 안내 (중국어)
• docs/gallery.md — 카테고리별 사례 색인
• user_credits.sql — 크레딧 예약·확정·해제 3함수. 이 저장소의 정수
• api/generate-image.js — 위 함수를 부르는 애플리케이션 쪽 코드
• generate-site-data.mjs — 마크다운 → JSON 파이프라인
• SKILL.md — 에이전트 스킬 본문 (짧고 좋은 예)
• gpt-image2.canghe.ai — 이 코드로 돌아가는 실제 서비스

배경 지식

• PostgreSQL — Explicit Locking — FOR UPDATE의 공식 설명
• Supabase — Row Level Security
• Supabase — Database Functions — SECURITY DEFINER 주의사항 포함
• Vercel Functions 문서 — api/ 파일 규약과 _lib 관행
• Vite — Env Variables and Modes — VITE_ 접두사 규칙
• Stripe — Webhooks — 서명 검증과 재전송 처리
• Node.js — 내장 테스트 러너 — 이 저장소가 Jest 대신 쓰는 것
• Claude Code — Skills 문서 — SKILL.md 규약

현재 상태 (2026-08-25 확인)