배포 가이드 생성: Preview 단계 완벽 가이드

학습 완료 후 할 수 있는 것

이 강의를 완료하면 다음을 수행할 수 있습니다:

Preview Agent가 생성된 애플리케이션을 위한 실행 가이드를 작성하는 방법 이해
Docker 배포 설정 생성 방법 습득
Expo EAS 빌드 설정의 역할 이해
MVP를 위한 간단한 데모 프로세스 설계 방법 학습
CI/CD 및 Git Hooks 설정의 모범 사례 이해

현재 직면한 문제

코드가 생성되고 검증을 통과했습니다. 팀이나 고객에게 MVP를 빠르게 보여주고 싶지만 다음을 알지 못합니다:

어떤 종류의 실행 문서를 작성해야 할까요?
다른 사람이 어떻게 빠르게 애플리케이션을 시작하고 실행할 수 있게 할까요?
데모 시 어떤 기능을 보여야 하고, 어떤 함정을 피해야 할까요?
프로덕션 환경은 어떻게 배포해야 할까요? Docker인가 클라우드 플랫폼인가?
지속적인 통합과 코드 품질 게이트는 어떻게 설정할까요?

Preview 단계는 이러한 문제를 해결하기 위한 것입니다—완전한 실행 설명서와 배포 설정을 자동으로 생성합니다.

언제 이 기술을 사용할까

Preview 단계는 파이프라인의 7번째 단계이자 마지막 단계로, Validation 단계 직후에 실행됩니다.

일반적인 사용 시나리오:

시나리오	설명
MVP 데모	팀이나 고객에게 애플리케이션을 보여줘야 하며, 상세한 실행 가이드가 필요함
팀 협업	새로운 팀원이 프로젝트에 참여하여 개발 환경을 빠르게 시작해야 함
프로덕션 배포	애플리케이션을 출시할 준비가 되었으며, Docker 설정과 CI/CD 파이프라인이 필요함
모바일 앱 출시	Expo EAS를 구성하여 App Store와 Google Play에 제출할 준비가 필요함

적용되지 않는 시나리오:

코드만 보고 실행하지 않는 경우 (Preview 단계는 필수입니다)
코드가 Validation 단계를 통과하지 못한 경우 (먼저 문제를 수정한 후 Preview 실행)

🎒 시작 전 준비

전제 조건

이 강의는 다음을 완료했다고 가정합니다:

Validation 단계 완료: artifacts/validation/report.md가 존재하고 검증을 통과해야 함
애플리케이션 아키텍처 이해: 백엔드와 프론트엔드의 기술 스택, 데이터 모델 및 API 엔드포인트를 명확히 알아야 함
기본 개념 숙지: Docker, CI/CD, Git Hooks의 기본 개념을 이해해야 함

이해해야 할 개념:

Docker란 무엇인가?

Docker는 애플리케이션과 그 의존성을 이식 가능한 컨테이너로 패키징하는 컨테이너화 플랫폼입니다.

핵심 장점:

환경 일관성: 개발, 테스트, 프로덕션 환경이 완전히 동일하여 "내 컴퓨터에서는 되는데" 문제 방지
빠른 배포: 단일 명령으로 전체 애플리케이션 스택 시작 가능
리소스 격리: 컨테이너 간 상호 영향 없음, 보안성 향상

기본 개념:

Dockerfile → 이미지 (Image) → 컨테이너 (Container)

CI/CD란 무엇인가?

CI/CD(지속적 통합/지속적 배포)는 자동화된 소프트웨어 개발 관행입니다.

CI (Continuous Integration):

매번 커밋 시 자동으로 테스트와 검사 실행
코드 문제를 조기에 발견
코드 품질 향상

CD (Continuous Deployment):

애플리케이션 자동 빌드 및 배포
새로운 기능을 프로덕션에 빠르게 제공
수동 작업 오류 감소

GitHub Actions는 GitHub에서 제공하는 CI/CD 플랫폼으로, .github/workflows/*.yml 파일을 통해 자동화된 워크플로우를 정의합니다.

Git Hooks란 무엇인가?

Git Hooks는 Git 작업의 특정 시점에 자동으로 실행되는 스크립트입니다.

일반적인 Hooks:

pre-commit: 커밋 전 코드 검사 및 포맷팅 실행
commit-msg: 커밋 메시지 형식 검증
pre-push: 푸시 전 전체 테스트 실행

Husky는 Hooks 설정과 유지 관리를 단순화하는 인기 있는 Git Hooks 관리 도구입니다.

핵심 개념

Preview 단계의 핵심은 애플리케이션을 위한 완전한 사용 및 배포 문서 준비이며, "로컬 우선, 투명한 위험" 원칙을 따릅니다.

사고 프레임워크

Preview Agent는 다음 사고 프레임워크를 따릅니다:

원칙	설명
로컬 우선	기본적인 개발 환경을 가진 누구나 로컬에서 시작할 수 있도록 보장
배포 준비 완료	프로덕션 환경 배포에 필요한 모든 설정 파일 제공
사용자 스토리	핵심 가치를 보여주는 간단한 데모 프로세스 설계
투명한 위험	현재 버전에 존재하는 제한 사항이나 알려진 문제를 능동적으로 나열

출력 파일 구조

Preview Agent는 두 가지 유형의 파일을 생성합니다:

필수 파일 (모든 프로젝트에 필요):

파일	설명	위치
`README.md`	주 실행 설명 문서	`artifacts/preview/README.md`
`Dockerfile`	백엔드 Docker 설정	`artifacts/backend/Dockerfile`
`docker-compose.yml`	개발 환경 Docker Compose	`artifacts/backend/docker-compose.yml`
`.env.production.example`	프로덕션 환경 변수 템플릿	`artifacts/backend/.env.production.example`
`eas.json`	Expo EAS 빌드 설정	`artifacts/client/eas.json`

권장 파일 (프로덕션 환경에 필요):

파일	설명	위치
`DEPLOYMENT.md`	상세 배포 가이드	`artifacts/preview/DEPLOYMENT.md`
`docker-compose.production.yml`	프로덕션 환경 Docker Compose	프로젝트 루트 디렉토리

README 문서 구조

artifacts/preview/README.md는 다음 섹션을 포함해야 합니다:

markdown

# [프로젝트 이름]

## 빠른 시작

### 환경 요구사항
- Node.js >= 18
- npm >= 9
- [기타 의존성]

### 백엔드 시작
[의존성 설치, 환경 설정, 데이터베이스 초기화, 서비스 시작]

### 프론트엔드 시작
[의존성 설치, 환경 설정, 개발 서버 시작]

### 설치 검증
[테스트 명령, 상태 확인]

---

## 데모 프로세스

### 준비 작업
### 데모 단계
### 데모 주의사항

---

## 알려진 문제와 제한사항

### 기능 제한
### 기술 부채
### 데모 시 피해야 할 작업

---

## 자주 묻는 질문

Preview Agent의 워크플로우

Preview Agent는 생성된 애플리케이션을 위한 실행 가이드와 배포 설정을 작성하는 AI Agent입니다. 워크플로우는 다음과 같습니다:

입력 파일

Preview Agent는 다음 파일만 읽을 수 있습니다:

파일	설명	위치
백엔드 코드	검증된 백엔드 애플리케이션	`artifacts/backend/`
프론트엔드 코드	검증된 프론트엔드 애플리케이션	`artifacts/client/`

출력 파일

Preview Agent는 다음 파일을 생성해야 합니다:

파일	설명	위치
`README.md`	주 실행 설명 문서	`artifacts/preview/README.md`
`Dockerfile`	백엔드 Docker 설정	`artifacts/backend/Dockerfile`
`docker-compose.yml`	개발 환경 Docker Compose	`artifacts/backend/docker-compose.yml`
`.env.production.example`	프로덕션 환경 변수 템플릿	`artifacts/backend/.env.production.example`
`eas.json`	Expo EAS 빌드 설정	`artifacts/client/eas.json`

실행 단계

코드 탐색: 백엔드와 프론트엔드 디렉토리 분석하여 의존성 설치 및 시작 명령 확인
README 작성: skills/preview/skill.md의 지침에 따라 명확한 설치 및 실행 가이드 작성
Docker 설정 생성: Dockerfile 및 docker-compose.yml 생성
EAS 설정: Expo EAS 빌드 설정 구성 (모바일 앱)
데모 프로세스 준비: 간단한 데모 시나리오 설명 설계
알려진 문제 나열: 현재 버전에 존재하는 결함이나 제한 사항 능동적으로 나열

따라하기: Preview 단계 실행

1단계: Validation 단계 완료 확인

이유

Preview Agent는 artifacts/backend/와 artifacts/client/를 읽어야 하므로, 코드가 검증을 통과하지 않으면 Preview 단계에서 생성된 문서가 부정확할 수 있습니다.

작업

bash

# 검증 보고서 확인
cat artifacts/validation/report.md

확인해야 할 내용: 검증 보고서에 백엔드와 프론트엔드의 모든 검사가 통과되어야 함

✅ Backend Dependencies: OK
✅ Backend Type Check: OK
✅ Prisma Schema: OK
✅ Frontend Dependencies: OK
✅ Frontend Type Check: OK

2단계: Preview 단계 실행

이유

AI 어시스턴트를 사용하여 Preview Agent를 실행하고, 실행 가이드와 배포 설정을 자동으로 생성합니다.

작업

bash

# Claude Code를 사용하여 preview 단계 실행
factory run preview

확인해야 할 내용:

✓ 현재 단계: preview
✓ 백엔드 코드 로드: artifacts/backend/
✓ 프론트엔드 코드 로드: artifacts/client/
✓ Preview Agent 시작

Preview Agent가 실행 가이드와 배포 설정을 생성하는 중...

[AI 어시스턴트가 다음 작업을 수행합니다]
1. 백엔드와 프론트엔드의 프로젝트 구조 분석
2. README.md 생성 (설치, 실행, 데모 프로세스)
3. Dockerfile 및 docker-compose.yml 생성
4. Expo EAS 빌드 파일 구성
5. 프로덕션 환경 변수 템플릿 준비
6. 알려진 문제와 제한 사항 나열

Agent 완료 대기 중...

3단계: 생성된 README 확인

이유

README가 완전한지 확인하고, 설치 단계와 실행 명령이 명확한지 검증합니다.

작업

bash

# 실행 가이드 확인
cat artifacts/preview/README.md

확인해야 할 내용: 다음 섹션이 포함된 완전한 실행 가이드

markdown

# AI 레스토랑 추천 도우미

## 빠른 시작

### 환경 요구사항

- Node.js >= 18
- npm >= 9
- Docker (선택사항, 컨테이너화 배포용)

### 백엔드 시작

```bash
# 백엔드 디렉토리로 이동
cd artifacts/backend

# 의존성 설치
npm install

# 환경 변수 설정
cp .env.example .env
# .env를 편집하여 필요한 설정 입력

# 데이터베이스 초기화
npx prisma migrate dev

# (선택사항) 시드 데이터 채우기
npm run db:seed

# 개발 서버 시작
npm run dev

백엔드 실행 주소: http://localhost:3000 상태 확인: http://localhost:3000/health API 문서: http://localhost:3000/api-docs

프론트엔드 시작

bash

# 프론트엔드 디렉토리로 이동
cd artifacts/client

# 의존성 설치
npm install

# 환경 변수 설정
cp .env.example .env
# API_URL을 백엔드 주소로 편집

# 개발 서버 시작
npm start

iOS 시뮬레이터: i 키 누르기
Android 시뮬레이터: a 키 누르기
웹 브라우저: w 키 누르기

설치 검증

다음 명령을 실행하여 설치가 성공했는지 확인:

bash

# 백엔드 테스트
cd artifacts/backend && npm test

# 프론트엔드 테스트
cd artifacts/client && npm test

# API 상태 확인
curl http://localhost:3000/health

데모 프로세스

준비 작업

백엔드와 프론트엔드가 모두 시작되었는지 확인
데모 데이터 초기화 또는 재설정 (선택사항)

데모 단계

시나리오 소개 (30초)
- 목표 사용자 소개: 새로운 레스토랑을 시도하고 싶은 사용자
- 핵심 문제 소개: 선택의 어려움, 무엇을 먹을지 모름
기능 데모 (3-5분)
- 단계 1: 사용자가 선호도 입력 (요리 종류, 맛, 예산)
- 단계 2: AI가 선호도 기반으로 레스토랑 추천
- 단계 3: 사용자가 추천 결과를 보고 선택
기술 하이라이트 (선택사항, 1분)
- 실시간 AI 추천 (OpenAI API 호출)
- 모바일 반응형 디자인
- 로컬 데이터베이스 영속화

데모 주의사항

네트워크 연결이 정상인지 확인 (AI 추천은 API 호출 필요)
너무 길거나 모호한 선호도 입력 피하기 (추천이 부정확할 수 있음)
데모 중 데이터베이스 수정 피하기 (데모 효과에 영향을 줄 수 있음)

알려진 문제와 제한사항

기능 제한

[ ] 사용자 등록 및 로그인은 아직 지원되지 않음
[ ] 즐겨찾기 및 기록은 아직 지원되지 않음
[ ] AI 추천은 텍스트 입력만 지원, 음성이나 이미지는 아직 지원되지 않음

기술 부채

[ ] 프론트엔드 오류 처리가 충분하지 않음
[ ] 백엔드 로그 기록 최적화 필요
[ ] 데이터베이스 인덱스가 최적화되지 않음 (소량 데이터에는 영향 없음)

데모 시 피해야 할 작업

계정 등록 또는 로그인 시도 - 데모가 중단될 수 있음
특수 문자나 초과 길이의 텍스트 입력 - 오류를 유발할 수 있음
빠른 연속 요청 - API 속도 제한을 트리거할 수 있음

자주 묻는 질문

Q: 포트가 이미 사용 중이면 어떻게 하나요?

A: .env의 PORT 변수를 수정하거나, 해당 포트를 사용 중인 프로세스를 먼저 종료하세요.

Q: 데이터베이스 연결에 실패하면 어떻게 하나요?

A: .env의 DATABASE_URL 설정이 올바른지 확인하고, 데이터베이스가 시작되었는지 확인하세요.

Q: AI 추천이 응답하지 않으면 어떻게 하나요?

A: .env의 OPENAI_API_KEY가 유효한지, 네트워크 연결이 정상인지 확인하세요.


### 4단계: 생성된 Docker 설정 확인

**이유**

Docker 설정이 올바른지 확인하여 컨테이너를 원활하게 빌드하고 실행할 수 있도록 합니다.

**작업**

```bash
# Dockerfile 확인
cat artifacts/backend/Dockerfile

# docker-compose.yml 확인
cat artifacts/backend/docker-compose.yml

확인해야 할 내용: Docker 모범 사례를 따르는 설정 파일

Dockerfile 예시:

dockerfile

# 기본 이미지
FROM node:20-alpine AS builder

WORKDIR /app

# 의존성 파일 복사
COPY package*.json ./
COPY prisma ./prisma/

# 의존성 설치
RUN npm ci --only=production

# Prisma Client 생성
RUN npx prisma generate

# 소스 코드 복사
COPY . .

# 빌드
RUN npm run build

# 프로덕션 이미지
FROM node:20-alpine AS production

WORKDIR /app

# 프로덕션 의존성 설치
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/prisma ./prisma
COPY --from=builder /app/package*.json ./

# 포트 노출
EXPOSE 3000

# 상태 확인
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# 시작 명령
CMD ["npm", "start"]

docker-compose.yml 예시:

yaml

version: '3.8'

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=file:./dev.db
    volumes:
      - .:/app
      - /app/node_modules
    command: npm run dev
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3

5단계: EAS 설정 확인

이유

Expo EAS 설정이 올바른지 확인하여 모바일 애플리케이션을 원활하게 빌드하고 출시할 수 있도록 합니다.

작업

bash

# EAS 설정 확인
cat artifacts/client/eas.json

확인해야 할 내용: development, preview, production 세 가지 환경 설정이 포함되어 있어야 함

json

{
  "cli": {
    "version": ">= 5.0.0"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "env": {
        "EXPO_PUBLIC_API_URL": "http://localhost:3000"
      }
    },
    "preview": {
      "distribution": "internal",
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api-staging.your-domain.com"
      }
    },
    "production": {
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api.your-domain.com"
      }
    }
  },
  "submit": {
    "production": {}
  }
}

6단계: 종료 조건 검증

이유

Sisyphus는 Preview Agent가 종료 조건을 충족하는지 검증하며, 충족하지 않으면 재실행을 요구합니다.

체크리스트

검사 항목	설명	통과/실패
README에 설치 단계 포함	백엔드와 프론트엔드에 필요한 의존성 설치 명령을 명확히 나열	[ ]
README에 실행 명령 포함	백엔드와 프론트엔드를 시작하는 명령을 각각 제공	[ ]
README에 접근 주소와 데모 프로세스 나열	데모 시 접근해야 할 주소와 포트 설명	[ ]
Docker 설정이 정상적으로 빌드 가능	Dockerfile과 docker-compose.yml에 구문 오류 없음	[ ]
프로덕션 환경 변수 템플릿이 완전함	.env.production.example에 모든 필수 설정 포함	[ ]

실패한 경우:

bash

# Preview 단계 재실행
factory run preview

체크포인트 ✅

완료했는지 확인:

[ ] Preview 단계가 성공적으로 실행됨
[ ] artifacts/preview/README.md 파일이 존재하고 내용이 완전함
[ ] artifacts/backend/Dockerfile 파일이 존재하고 빌드 가능함
[ ] artifacts/backend/docker-compose.yml 파일이 존재함
[ ] artifacts/backend/.env.production.example 파일이 존재함
[ ] artifacts/client/eas.json 파일이 존재함 (모바일 앱)
[ ] README에 명확한 설치 단계와 실행 명령이 포함됨
[ ] README에 데모 프로세스와 알려진 문제가 포함됨

함정 경고

⚠️ 함정 1: 의존성 설치 단계 무시

문제: README에 "서비스 시작"만 작성하고 의존성 설치 방법을 설명하지 않음

증상: 새로운 팀원이 README를 따라 npm run dev를 실행하면 "모듈을 찾을 수 없음" 오류 발생

해결: Preview Agent는 "README에 설치 단계가 포함되어야 함"을 제약으로 설정하여 각 단계에 명확한 명령이 있도록 보장

올바른 예시:

bash

# ❌ 잘못됨 - 설치 단계 누락
npm run dev

# ✅ 올바름 - 완전한 단계 포함
npm install
npm run dev

⚠️ 함정 2: Docker 설정에 latest 태그 사용

문제: Dockerfile에서 FROM node:latest 또는 FROM node:alpine 사용

증상: 매번 빌드 시 다른 버전의 Node.js를 사용할 수 있어 환경 불일치 발생

해결: Preview Agent는 "Docker 이미지 태그로 latest를 NEVER 사용하고, 구체적인 버전 번호를 사용해야 함"을 제약으로 설정

올바른 예시:

dockerfile

# ❌ 잘못됨 - latest 사용
FROM node:latest

# ❌ 잘못됨 - 구체적인 버전 미지정
FROM node:alpine

# ✅ 올바름 - 구체적인 버전 사용
FROM node:20-alpine

⚠️ 함정 3: 환경 변수 하드코딩

문제: Docker 설정이나 EAS 설정에 민감한 정보(비밀번호, API 키 등)를 하드코딩

증상: 민감한 정보가 코드 저장소에 유출되어 보안 위험 발생

해결: Preview Agent는 "배포 설정에 민감한 정보를 NEVER 하드코딩"을 제약으로 설정하고, 환경 변수 템플릿 사용

올바른 예시:

yaml

# ❌ 잘못됨 - 데이터베이스 비밀번호 하드코딩
DATABASE_URL=postgresql://user:password123@host:5432/database

# ✅ 올바름 - 환경 변수 사용
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:5432/${DB_NAME}

⚠️ 함정 4: 알려진 문제 숨기기

문제: README에 알려진 문제와 제한 사항을 나열하지 않고 제품 능력을 과장

증상: 데모 시 예상치 못한 문제 발생으로 당황하고 신뢰도 하락

해결: Preview Agent는 "기능을 과장하거나 결함을 숨기지 NEVER 말 것"을 제약으로 설정하고, 현재 버전에 존재하는 문제를 능동적으로 나열

올바른 예시:

markdown

## 알려진 문제와 제한사항

### 기능 제한
- [ ] 사용자 등록 및 로그인은 아직 지원되지 않음
- [ ] AI 추천이 부정확할 수 있음 (OpenAI API 반환 결과에 따라 다름)

⚠️ 함정 5: 데모 프로세스가 너무 복잡함

문제: 데모 프로세스에 10개 이상의 단계가 포함되어 10분 이상 소요

증상: 데모 진행자가 단계를 기억하지 못하고, 관객이 인내심을 잃음

해결: Preview Agent는 "데모 프로세스는 3-5분 이내, 단계는 5개 이하로 제한"을 제약으로 설정

올바른 예시:

markdown

### 데모 단계

1. **시나리오 소개** (30초)
   - 목표 사용자와 핵심 문제 소개

2. **기능 데모** (3-5분)
   - 단계 1: 사용자가 선호도 입력
   - 단계 2: AI가 선호도 기반으로 추천
   - 단계 3: 사용자가 결과 확인

3. **기술 하이라이트** (선택사항, 1분)
   - 실시간 AI 추천
   - 모바일 반응형 디자인

CI/CD 설정 템플릿

Preview Agent는 templates/cicd-github-actions.md를 참조하여 CI/CD 설정을 생성할 수 있습니다:

백엔드 CI 파이프라인

yaml

name: Backend CI

on:
  push:
    branches: [main, develop]
    paths:
      - 'backend/**'
      - '.github/workflows/backend-ci.yml'
  pull_request:
    branches: [main, develop]
    paths:
      - 'backend/**'

jobs:
  test:
    name: Test & Lint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.x
          cache: 'npm'
          cache-dependency-path: backend/package-lock.json

      - name: Install dependencies
        working-directory: backend
        run: npm ci

      - name: Run linter
        working-directory: backend
        run: npm run lint

      - name: Run type check
        working-directory: backend
        run: npx tsc --noEmit

      - name: Validate Prisma schema
        working-directory: backend
        run: npx prisma validate

      - name: Generate Prisma Client
        working-directory: backend
        run: npx prisma generate

      - name: Run tests
        working-directory: backend
        run: npm test

프론트엔드 CI 파이프라인

yaml

name: Frontend CI

on:
  push:
    branches: [main, develop]
    paths:
      - 'client/**'
      - '.github/workflows/frontend-ci.yml'
  pull_request:
    branches: [main, develop]
    paths:
      - 'client/**'

jobs:
  test:
    name: Test & Lint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.x
          cache: 'npm'
          cache-dependency-path: client/package-lock.json

      - name: Install dependencies
        working-directory: client
        run: npm ci

      - name: Run linter
        working-directory: client
        run: npm run lint

      - name: Run type check
        working-directory: client
        run: npx tsc --noEmit

      - name: Run tests
        working-directory: client
        run: npm test -- --coverage

Git Hooks 설정 템플릿

Preview Agent는 templates/git-hooks-husky.md를 참조하여 Git Hooks 설정을 생성할 수 있습니다:

pre-commit Hook

커밋 전 코드 검사 및 포맷팅을 실행합니다.

bash

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

echo "🔍 pre-commit 검사 실행 중..."

# lint-staged 실행
npx lint-staged

# TypeScript 타입 검사
echo "📝 타입 검사 중..."
npm run type-check

echo "✅ pre-commit 검사 통과!"

commit-msg Hook

커밋 메시지 형식을 검증합니다.

bash

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

echo "📋 커밋 메시지 검증 중..."

npx --no -- commitlint --edit "$1"

echo "✅ 커밋 메시지가 유효합니다!"

강의 요약

Preview 단계는 파이프라인의 마지막 단계로, 생성된 애플리케이션을 위한 완전한 사용 및 배포 문서를 준비하는 역할을 합니다. 자동으로 생성되는 내용:

실행 가이드: 명확한 설치 단계, 시작 명령 및 데모 프로세스
Docker 설정: Dockerfile 및 docker-compose.yml, 컨테이너화 배포 지원
EAS 설정: Expo EAS 빌드 설정, 모바일 앱 출시 지원
CI/CD 설정: GitHub Actions 파이프라인, 지속적 통합 및 배포 지원
Git Hooks: Husky 설정, 커밋 전 검사 지원

핵심 원칙:

로컬 우선: 기본적인 개발 환경을 가진 누구나 로컬에서 시작할 수 있도록 보장
배포 준비 완료: 프로덕션 환경 배포에 필요한 모든 설정 파일 제공
사용자 스토리: 핵심 가치를 보여주는 간단한 데모 프로세스 설계
투명한 위험: 현재 버전에 존재하는 제한 사항이나 알려진 문제를 능동적으로 나열

Preview 단계를 완료하면 다음을 얻게 됩니다:

✅ 완전한 실행 가이드 (README.md)
✅ Docker 컨테이너화 설정 (Dockerfile, docker-compose.yml)
✅ 프로덕션 환경 변수 템플릿 (.env.production.example)
✅ Expo EAS 빌드 설정 (eas.json)
✅ 선택사항: 상세 배포 가이드 (DEPLOYMENT.md)

다음 강의 예고

축하합니다! AI App Factory의 모든 7개 단계를 완료했습니다.
파이프라인의 조정 메커니즘에 대해 더 깊이 알고 싶다면 **Sisyphus 오케스트레이터 상세 설명**을 학습할 수 있습니다.
학습할 내용:
오케스트레이터가 파이프라인 실행을 조정하는 방법
권한 검사 및 권한 초과 처리 메커니즘
실패 처리 및 롤백 전략
컨텍스트 최적화 및 Token 절약 팁

부록: 소스 코드 참조

클릭하여 소스 코드 위치 보기

업데이트 시간: 2026-01-29

기능	파일 경로	라인 번호
Preview Agent 정의	`source/hyz1992/agent-app-factory/agents/preview.agent.md`	1-33
Preview 스킬 가이드	`source/hyz1992/agent-app-factory/skills/preview/skill.md`	1-583
Pipeline 설정	`source/hyz1992/agent-app-factory/pipeline.yaml`	98-111
CI/CD 설정 템플릿	`source/hyz1992/agent-app-factory/templates/cicd-github-actions.md`	1-617
Git Hooks 설정 템플릿	`source/hyz1992/agent-app-factory/templates/git-hooks-husky.md`	1-530

핵심 제약:

로컬 우선: 기본적인 개발 환경을 가진 누구나 로컬에서 시작할 수 있도록 보장
배포 준비 완료: 프로덕션 환경 배포에 필요한 모든 설정 파일 제공
투명한 위험: 현재 버전에 존재하는 제한 사항이나 알려진 문제를 능동적으로 나열

생성해야 하는 파일:

artifacts/preview/README.md - 주 실행 설명 문서
artifacts/backend/Dockerfile - 백엔드 Docker 설정
artifacts/backend/docker-compose.yml - 개발 환경 Docker Compose
artifacts/backend/.env.production.example - 프로덕션 환경 변수 템플릿
artifacts/client/eas.json - Expo EAS 빌드 설정

하지 말 것 (NEVER):

NEVER 의존성 설치나 설정 단계를 무시하면 실행이나 배포가 실패할 가능성이 높음
NEVER 애플리케이션과 관련 없는 추가 설명이나 마케팅 언어 제공
NEVER 제품 능력을 과장하거나 결함이나 제한을 숨김
NEVER 배포 설정에 민감한 정보(비밀번호, API 키 등)를 하드코딩
NEVER 상태 확인 설정을 무시—프로덕션 환경 모니터링에 필수적임
NEVER 데이터베이스 마이그레이션 설명을 건너뜀—출시의 핵심 단계임
NEVER Docker 이미지 태그로 latest 사용—구체적인 버전 번호를 사용해야 함
NEVER 프로덕션 환경에서 SQLite 사용—PostgreSQL로 마이그레이션해야 함

배포 가이드 생성: Preview 단계 완벽 가이드 ​

학습 완료 후 할 수 있는 것 ​

현재 직면한 문제 ​

언제 이 기술을 사용할까 ​

🎒 시작 전 준비 ​

핵심 개념 ​

사고 프레임워크 ​

출력 파일 구조 ​

README 문서 구조 ​

Preview Agent의 워크플로우 ​

입력 파일 ​

출력 파일 ​

실행 단계 ​

따라하기: Preview 단계 실행 ​

1단계: Validation 단계 완료 확인 ​

2단계: Preview 단계 실행 ​

3단계: 생성된 README 확인 ​

프론트엔드 시작 ​

설치 검증 ​

데모 프로세스 ​

준비 작업 ​

데모 단계 ​

데모 주의사항 ​

알려진 문제와 제한사항 ​

기능 제한 ​

기술 부채 ​

데모 시 피해야 할 작업 ​

자주 묻는 질문 ​

Q: 포트가 이미 사용 중이면 어떻게 하나요? ​

Q: 데이터베이스 연결에 실패하면 어떻게 하나요? ​

Q: AI 추천이 응답하지 않으면 어떻게 하나요? ​

5단계: EAS 설정 확인 ​

6단계: 종료 조건 검증 ​

체크포인트 ✅ ​

함정 경고 ​

⚠️ 함정 1: 의존성 설치 단계 무시 ​

⚠️ 함정 2: Docker 설정에 latest 태그 사용 ​

⚠️ 함정 3: 환경 변수 하드코딩 ​

⚠️ 함정 4: 알려진 문제 숨기기 ​

⚠️ 함정 5: 데모 프로세스가 너무 복잡함 ​

CI/CD 설정 템플릿 ​

백엔드 CI 파이프라인 ​

프론트엔드 CI 파이프라인 ​

Git Hooks 설정 템플릿 ​

pre-commit Hook ​

commit-msg Hook ​

강의 요약 ​

다음 강의 예고 ​

부록: 소스 코드 참조 ​

배포 가이드 생성: Preview 단계 완벽 가이드

학습 완료 후 할 수 있는 것

현재 직면한 문제

언제 이 기술을 사용할까

🎒 시작 전 준비

핵심 개념

사고 프레임워크

출력 파일 구조

README 문서 구조

Preview Agent의 워크플로우

입력 파일

출력 파일

실행 단계

따라하기: Preview 단계 실행

1단계: Validation 단계 완료 확인

2단계: Preview 단계 실행

3단계: 생성된 README 확인

프론트엔드 시작

설치 검증

데모 프로세스

준비 작업

데모 단계

데모 주의사항

알려진 문제와 제한사항

기능 제한

기술 부채

데모 시 피해야 할 작업

자주 묻는 질문

Q: 포트가 이미 사용 중이면 어떻게 하나요?

Q: 데이터베이스 연결에 실패하면 어떻게 하나요?

Q: AI 추천이 응답하지 않으면 어떻게 하나요?

5단계: EAS 설정 확인

6단계: 종료 조건 검증

체크포인트 ✅

함정 경고

⚠️ 함정 1: 의존성 설치 단계 무시

⚠️ 함정 2: Docker 설정에 latest 태그 사용

⚠️ 함정 3: 환경 변수 하드코딩

⚠️ 함정 4: 알려진 문제 숨기기

⚠️ 함정 5: 데모 프로세스가 너무 복잡함

CI/CD 설정 템플릿

백엔드 CI 파이프라인

프론트엔드 CI 파이프라인

Git Hooks 설정 템플릿

pre-commit Hook

commit-msg Hook

강의 요약

다음 강의 예고

부록: 소스 코드 참조