마지막 업데이트 2026-07-22
기획자는 요구사항만 작성 → 번역기가 관련 파일·패턴·가드 조건을 자동 주입 → AI가 프로젝트에 맞는 코드 생성.
기획자가 모르는 암묵적 제약(쿨다운, cleanup, 소켓 서버 수정 등)을 번역 단계에서 표면화한다.
기획자가 AI를 활용해 PR을 올리는 케이스가 증가하면서 두 가지 문제가 반복됐다.
기획자는 happy path만 기술한다. AI도 요청에 없으면 구현하지 않는다.
예: 아동 알림 프리셋 — 발송 후 15초간 표시되는 알림인데, 그 사이에 다른 알림을 계속 보낼 수 있는 쿨다운 부재 버그 발생.
AI는 기존 훅/패턴을 모르고 새로 만든다. 소켓 이벤트를 상수 없이 문자열로 하드코딩하거나, 서버 핸들러를 빠뜨리거나, 타이머 cleanup을 누락한다.
기획자 요구사항 → 번역기 → 컨텍스트가 풍부한 개발 프롬프트 → AI 구현.
번역기가 코드베이스를 실제로 탐색해서 관련 파일·기존 패턴·가드 조건을 자동으로 주입한다.
Claude Code에서 아래와 같이 호출한다.
/po-translator [요구사항 텍스트]
프리셋 버튼 누르면 핑퐁이가 해당 문구를 말하게 해줘. 15초간 표시되고 사라지는 알림이야.
| 추가 항목 | 내용 |
|---|---|
| 관련 파일 | 코드베이스를 직접 grep해서 수정해야 할 파일 목록과 역할 설명 주입 |
| 기존 패턴 | 유사 기능의 실제 코드 스니펫 — "이 패턴을 따라 구현할 것" 형태로 제공 |
| 컨벤션 규칙 | 소켓 상수 위치, 파일 구조, 타이머 관리 방식 등 PPI 프로젝트 규칙 |
| 가드 조건 | 요구사항 유형별로 자동 감지된 중복 방지·cleanup·상태 초기화 체크리스트 |
| 수정 금지 영역 | 건드리면 안 되는 핵심 파일 명시 |
번역기는 세 블록으로 출력한다.
요구사항 유형에 따라 자동 생성된 구체적 질문 목록.
예: "이미 알림 표시 중(15초 이내)에 버튼을 다시 누르면 A) 무시 B) 타이머 연장 C) 내용 교체 중 어느 것인가요?"
기획자 AI PR에 특화된 리뷰 항목.
일반 리뷰(로직·타입) + 기획자 AI 추가 항목(가드 조건 구현 여부, 기존 패턴 재사용 여부, 소켓 서버 핸들러 수정 여부 등)
요구사항 유형을 분석해 아래 기준으로 가드 조건을 자동 주입한다.
| 요구사항 유형 | 자동 주입되는 가드 조건 |
|---|---|
| 버튼 → 이벤트 발송 | 중복 발송 방지, 쿨다운, 발송 중 버튼 비활성화 |
| 타이머/시간 관련 | 컴포넌트 언마운트 시 clearTimeout cleanup, 재실행 시 기존 타이머 제거 |
| 상태 표시/UI 변경 | 초기화 시점 명시, 다른 상태와 충돌 여부 확인 |
| 소켓 이벤트 추가 | 서버 핸들러 수정 필요, constants.ts 상수 등록, 재연결 시 재등록 여부 |
| 목록/데이터 조회 | 로딩 상태, 빈 목록 처리, 에러 상태 |
| 파일/미디어 처리 | 실패 처리, 용량 제한, 포맷 검증 |
기획자 입력 "프리셋 버튼 누르면 핑퐁이가 해당 문구를 말하게 해줘. 15초간 표시되고 사라지는 알림이야."
→ AI가 버튼 클릭 → 이벤트 발송까지만 구현.
→ 15초 표시 중 버튼 재클릭 시 중복 발송 버그 발생.
번역기가 use-guest-page-session.ts:225의 showAmbientNoiseAlert() 패턴을 탐색해서 자동 주입:
disabled={ambientAlertVisible} 처리 필요 명시clearTimeout cleanup 가드 조건 자동 추가기획자 입력 "수업 중 게스트 네트워크가 불안정하면 진행자 화면에 경고 배지를 표시해줘. 네트워크가 회복되면 배지는 자동으로 사라져야 해."
→ AI가 새로운 네트워크 감지 로직 + 소켓 이벤트 + 배지 컴포넌트를 처음부터 구현.
→ 이미 존재하는 GUEST_NETWORK_ALERT 이벤트 및 guestNetworkAlertLevel 상태와 중복 구현 발생.
코드베이스 탐색 결과 기능이 이미 완성되어 있었음:
constants.ts:327 — GUEST_NETWORK_ALERT 소켓 이벤트 이미 존재use-monitor-session.ts:129 — guestNetworkAlertLevel: "warning" | "critical" | null 상태 이미 존재monitor-media-display.tsx:271 — warning(amber 배지) / critical(빨간 오버레이) UI 이미 존재monitoring-handlers.ts:371 — 서버 발송 로직 이미 존재→ 번역기가 "구현 전 테스트 먼저" + "카드뷰/포커스뷰 누락 여부 확인" 질문 생성.
→ 중복 구현 방지. 실제 필요한 작업(카드뷰 prop 추가)만 최소 범위로 진행.
번역 시 항상 포함되는 PPI 프로젝트 고유 지식이다.
constants.ts에 추가하지 않고 문자열 하드코딩use-session-manager, use-resource-cache 등)clearTimeout cleanup 누락isLowPerformanceDevice)apps/web/hooks/use-session-manager.ts — OpenAI 세션 핵심apps/socket/src/sfu-socket/signalingHandler.ts — SFU 시그널링apps/web/lib/fetch-resumable.ts — 리소스 다운로드 핵심apps/web/server.js — 커스텀 Next.js 서버packages/shared/src/utils/constants.ts — 이벤트 상수 정의 apps/socket/src/sfu-socket/handlers/ — 서버 핸들러 apps/web/hooks/ 또는 entities/ — 클라이언트 핸들러