빠른 시작: 아이디어에서 앱까지

학습 완료 후 달성할 수 있는 것

이 수업을 완료하면 다음을 할 수 있습니다:

• AI App Factory가 아이디어를 실행 가능한 앱으로 빠르게 변환하는 방법 이해
• 첫 번째 Factory 프로젝트 초기화 완료
• 7단계를 따라 첫 번째 MVP 앱 생성을 위한 파이프라인 시작

현재 겪고 있는 문제

"제품 아이디어는 있지만, 어디서 시작해야 할지 모르겠다"

다음 상황에 직면한 적이 있나요:

• 제품 아이디어는 있지만, 실행 가능한 요구사항으로 어떻게 분해해야 할지 모름
• 프론트엔드, 백엔드, 데이터베이스, 테스트, 배포… 각 항목마다 시간을 투자해야 함
• 아이디어를 빠르게 검증하고 싶지만, 개발 환경 설정만 며칠이 걸림
• 코드를 작성한 후에야 요구사항을 잘못 이해했다는 것을 알게 되고 다시 시작해야 함

AI App Factory는 바로 이러한 문제를 해결하기 위해 만들어졌습니다.

언제 이 방법을 사용해야 할까요

AI App Factory는 다음 시나리오에 적합합니다:

• ✅ 제품 아이디어 빠른 검증: 이 아이디어가 실현 가능한지 시도해보고 싶을 때
• ✅ 스타트업 프로젝트의 0-1 단계: 빠르게 데모 가능한 프로토타입을 제공해야 할 때
• ✅ 내부 도구 및 관리 시스템: 복잡한 권한이 필요 없고, 단순하고 실용적이면 될 때
• ✅ 풀스택 개발 모범 사례 학습: AI가 프로덕션 수준 코드를 생성하는 방법을 보고 싶을 때

다음 시나리오에는 적합하지 않습니다:

• ❌ 복잡한 엔터프라이즈 시스템: 멀티테넌트, 권한 시스템, 높은 동시성
• ❌ 고도로 커스터마이징된 UI 필요: 독특한 디자인 시스템이 있는 프로젝트
• ❌ 매우 높은 실시간 요구 사항: 게임, 비디오 통화 등

🎯 핵심 개념

AI App Factory는 체크포인트 기반의 지능형 앱 생성 시스템으로, 다중 에이전트 협업 파이프라인을 통해 제품 아이디어를 프론트엔드/백엔드 코드, 테스트, 문서가 포함된 완전한 실행 가능한 앱으로 자동 변환합니다.

세 가지 핵심 가치:

1. 엔드투엔드 자동화

아이디어에서 코드까지 완전히 자동화:

• 입력: 제품 아이디어를 한 문장으로 설명
• 출력: 완전한 프론트엔드 및 백엔드 애플리케이션 (Express + Prisma + React Native)
• 중간 과정: 요구사항 분석, UI 디자인, 기술 아키텍처, 코드 생성 자동 완료

2. 체크포인트 메커니즘

각 단계가 완료된 후 일시정지하고 확인을 기다림:

• ✅ 오류 누적 방지, 각 단계가 기대에 부합하는지 확인
• ✅ 언제든지 방향 조정 가능, 끝에서야 잘못된 방향임을 발견하는 것을 방지
• ✅ 실패 시 자동 롤백, 잘못된 코드에 시간을 낭비하지 않음

3. 프로덕션 준비 완료

장난감 코드가 아니라, 즉시 배포 가능한 프로덕션 수준 앱 생성:

• ✅ 완전한 프론트엔드 및 백엔드 코드
• ✅ 단위 테스트 및 통합 테스트 (60% 이상 커버리지)
• ✅ API 문서 (Swagger/OpenAPI)
• ✅ 데이터베이스 시드 데이터
• ✅ Docker 배포 구성
• ✅ CI/CD 파이프라인 (GitHub Actions)
• ✅ 오류 처리 및 로그 모니터링
• ✅ 성능 최적화 및 보안 검사

7단계 파이프라인:

Bootstrap → PRD → UI → Tech → Code → Validation → Preview
   ↓          ↓    ↓     ↓      ↓         ↓          ↓
구조화   제품   UI   기술    코드      검증      배포
아이디어    요구  디자인  아키텍처   생성      품질      가이드

🎒 시작 전 준비

필수 도구

1. Node.js >= 16.0.0

# Node.js 버전 확인
node --version

설치되지 않았거나 버전이 낮다면 nodejs.org에서 다운로드하여 설치하세요.

2. AI 프로그래밍 어시스턴트 (필수) ⚠️ 중요

AI App Factory의 에이전트 정의 및 스킬 파일은 Markdown 형식의 AI 명령이므로, AI 어시스턴트를 통해 해석하고 실행해야 합니다. 사람이 직접 이러한 파이프라인을 실행할 수 없습니다.

다음 도구 중 하나를 사용하는 것이 좋습니다:

• Claude Code (https://claude.ai/code) - 추천 ⭐
• OpenCode 또는 에이전트 모드를 지원하는 다른 AI 어시스턴트

왜 AI 어시스턴트를 사용해야 할까요?

이 프로젝트의 핵심은 AI 에이전트 시스템으로, 각 단계에서 AI 어시스턴트가 필요합니다:

• .agent.md 파일을 읽어 자신의 작업 이해
• 해당 스킬 파일을 로드하여 지식 습득
• 지침을 엄격히 따라 코드와 문서 생성

사람이 이 과정을 대체할 수 없습니다. 메모장으로 Python 코드를 실행할 수 없는 것과 같습니다.

3. CLI 도구 전역 설치

npm install -g agent-app-factory

설치 확인:

factory --version

버전 번호가 출력되어야 합니다.

제품 아이디어 준비

5분을 들여 제품 아이디어를 작성하세요. 자세한 설명일수록 예상에 부합하는 앱이 생성됩니다.

좋은 설명 예시:

✅ 피트니스 초보자가 운동을 기록하는 데 도움을 주는 앱, 운동 유형(러닝, 수영, 체육관), 지속 시간, 소모 칼로리 기록을 지원하고, 이번 주 운동 통계를 볼 수 있습니다. 협업은 필요하지 않고, 데이터 분석도 하지 않으며, 개인 기록에 초점을 맞춥니다.

나쁜 설명 예시:

❌ 피트니스 앱을 만들어라.

따라해보세요

1단계: 프로젝트 디렉토리 생성

원하는 위치에 빈 디렉토리를 생성하세요:

mkdir my-first-app && cd my-first-app

2단계: Factory 프로젝트 초기화

초기화 명령을 실행하세요:

factory init

왜 필요한가 이 명령은 .factory/ 디렉토리를 생성하고 모든 필수 에이전트, 스킬, 정책 파일을 복사하여, 현재 디렉토리를 Factory 프로젝트로 만듭니다.

다음을 볼 수 있어야 합니다:

✓ .factory/ 디렉토리 생성 완료
✓ agents/, skills/, policies/, pipeline.yaml 복사 완료
✓ 구성 파일 생성 완료: config.yaml, state.json
✓ Claude Code 권한 구성 생성 완료: .claude/settings.local.json
✓ 필수 플러그인 설치 시도 (superpowers, ui-ux-pro-max)

오류 메시지가 표시되면 다음을 확인하세요:

• 디렉토리가 비어 있는지 (또는 구성 파일만 포함하는지)
• Node.js 버전이 16.0.0 이상인지
• agent-app-factory가 전역으로 설치되었는지

디렉토리 구조

초기화 후 디렉토리 구조는 다음과 같아야 합니다:

my-first-app/
├── .factory/
│   ├── agents/              # 에이전트 정의 파일
│   ├── skills/              # 재사용 가능한 지식 모듈
│   ├── policies/            # 정책 및 규범
│   ├── pipeline.yaml         # 파이프라인 정의
│   ├── config.yaml          # 프로젝트 구성
│   └── state.json           # 파이프라인 상태
└── .claude/
    └── settings.local.json  # Claude Code 권한 구성

3단계: 파이프라인 시작

AI 어시스턴트에서 (Claude Code 추천), 다음 명령을 실행하세요:

pipeline.yaml과 agents/orchestrator.checkpoint.md를 읽고,
파이프라인을 시작하여 이 제품 아이디어를 실행 가능한 앱으로 변환해 주세요:

[제품 아이디어를 붙여넣으세요]

왜 필요한가 이 명령은 Sisyphus 스케줄러가 파이프라인을 시작하여, Bootstrap 단계부터 아이디어를 단계별로 코드로 변환합니다.

다음을 볼 수 있어야 합니다:

AI 어시스턴트가 다음을 수행합니다:

1. pipeline.yaml과 orchestrator.checkpoint.md 읽기
2. 현재 상태 표시 (idle → running)
3. Bootstrap 에이전트 시작, 제품 아이디어 구조화 시작

4단계: 7단계 따라가기

시스템은 다음 7단계로 실행하며, 각 단계가 완료된 후 일시정지하고 확인을 요청합니다:

단계 1: Bootstrap - 제품 아이디어 구조화

입력: 제품 설명 출력: input/idea.md (구조화된 제품 문서)

확인 내용:

• 문제 정의: 어떤 문제를 해결합니까?
• 타겟 사용자: 누가 이 문제를 겪습니까?
• 핵심 가치: 이 제품이 필요한 이유는 무엇입니까?
• 핵심 가정: 당신의 가정은 무엇입니까?

다음을 볼 수 있어야 합니다:

AI 어시스턴트가 다음을 묻습니다:

✓ Bootstrap 단계 완료
생성된 문서: input/idea.md

확인하세요:
1. 다음 단계 계속
2. 현재 단계 재시도 (수정 제안 제공)
3. 파이프라인 일시정지

input/idea.md를 주의 깊게 읽고, 맞지 않는 부분이 있다면 "재시도"를 선택하고 수정 제안을 제공하세요.

단계 2: PRD - 제품 요구사항 문서 생성

입력: input/idea.md출력: artifacts/prd/prd.md

확인 내용:

• 사용자 스토리: 사용자가 이 제품을 어떻게 사용할까요?
• 기능 목록: 어떤 핵심 기능을 구현해야 할까요?
• 비목표: 명확히 하지 않을 것 (범위 확장 방지)

단계 3: UI - UI 구조 및 프로토타입 디자인

입력: artifacts/prd/prd.md출력: artifacts/ui/ui.schema.yaml + 미리보기 가능한 HTML 프로토타입

확인 내용:

• 페이지 구조: 어떤 페이지가 있나요?
• 상호작용 흐름: 사용자가 어떻게 조작하나요?
• 비주얼 디자인: 색상 구성, 폰트, 레이아웃

특징: ui-ux-pro-max 디자인 시스템 통합 (67가지 스타일, 96가지 색상 팔레트, 100개의 업계 규칙)

단계 4: Tech - 기술 아키텍처 설계

입력: artifacts/prd/prd.md출력: artifacts/tech/tech.md + artifacts/backend/prisma/schema.prisma

확인 내용:

• 기술 스택: 어떤 기술을 사용합니까?
• 데이터 모델: 어떤 테이블이 있나요? 필드는 무엇입니까?
• API 디자인: 어떤 API 엔드포인트가 있나요?

단계 5: Code - 완전한 코드 생성

입력: UI 스키마 + 기술 디자인 + Prisma 스키마 출력: artifacts/backend/ + artifacts/client/

확인 내용:

• 백엔드 코드: Express + Prisma + TypeScript
• 프론트엔드 코드: React Native + TypeScript
• 테스트: Vitest (백엔드) + Jest (프론트엔드)
• 구성 파일: package.json, tsconfig.json 등

단계 6: Validation - 코드 품질 검증

입력: 생성된 코드 출력: artifacts/validation/report.md

확인 내용:

• 의존성 설치: npm install이 성공했나요?
• 타입 검사: TypeScript 컴파일이 통과했나요?
• Prisma 검증: 데이터베이스 스키마가 올바른가요?

단계 7: Preview - 배포 가이드 생성

입력: 완전한 코드 출력: artifacts/preview/README.md + GETTING_STARTED.md

확인 내용:

• 로컬 실행 안내: 로컬에서 프론트엔드 및 백엔드를 어떻게 시작하나요?
• Docker 배포: Docker로 어떻게 배포하나요?
• CI/CD 구성: GitHub Actions를 어떻게 구성하나요?

체크포인트 ✅

모든 7단계를 완료한 후 다음을 볼 수 있어야 합니다:

✓ 모든 파이프라인 단계 완료
최종 산출물:
- artifacts/prd/prd.md (제품 요구사항 문서)
- artifacts/ui/ui.schema.yaml (UI 디자인)
- artifacts/tech/tech.md (기술 아키텍처)
- artifacts/backend/ (백엔드 코드)
- artifacts/client/ (프론트엔드 코드)
- artifacts/validation/report.md (검증 보고서)
- artifacts/preview/GETTING_STARTED.md (실행 가이드)

다음 단계: artifacts/preview/GETTING_STARTED.md를 확인하여 앱 실행 시작

축하합니다! 첫 번째 AI 생성 앱이 완성되었습니다.

5단계: 생성된 앱 실행

생성된 가이드에 따라 앱을 실행하세요:

# 백엔드
cd artifacts/backend
npm install
npm run dev

# 새 터미널 창을 열고, 프론트엔드 실행
cd artifacts/client
npm install
npm run web  # 웹 버전
# 또는
npm run ios      # iOS 시뮬레이터
# 또는
npm run android  # Android 시뮬레이터

다음을 볼 수 있어야 합니다:

• 백엔드가 http://localhost:3000에서 실행됨
• 프론트엔드가 http://localhost:8081 (웹 버전)에서 실행되거나 시뮬레이터에서 열림

문제 해결 가이드

❌ 오류 1: 디렉토리가 비어 있지 않음

오류 메시지:

✗ 디렉토리가 비어 있지 않습니다. 정리 후 다시 시도하세요

원인: 초기화 시 디렉토리에 이미 파일이 있음

해결 방법:

# 방법 1: 디렉토리 정리 (숨겨진 구성 파일만 유지)
ls -a    # 모든 파일 확인
rm -rf !(.*)

# 방법 2: 새 디렉토리 생성
mkdir new-app && cd new-app
factory init

❌ 오류 2: AI 어시스턴트가 명령을 이해하지 못함

오류 현상: AI 어시스턴트가 "에이전트 정의를 찾을 수 없음" 오류를 보고함

원인: Factory 프로젝트 디렉토리에서 실행되지 않음

해결 방법:

# .factory/ 디렉토리를 포함한 프로젝트 루트 디렉토리에 있는지 확인
ls -la  # .factory/가 보여야 함
pwd     # 현재 디렉토리 확인

❌ 오류 3: Claude CLI가 설치되지 않음

오류 메시지:

✗ Claude CLI가 설치되지 않았습니다. https://claude.ai/code에서 다운로드하세요

해결 방법:

https://claude.ai/code에서 Claude Code CLI를 다운로드하여 설치하세요.

이 수업 요약

이 수업에서 다음을 배웠습니다:

• AI App Factory의 핵심 가치: 엔드투엔드 자동화 + 체크포인트 메커니즘 + 프로덕션 준비 완료
• 7단계 파이프라인: Bootstrap → PRD → UI → Tech → Code → Validation → Preview
• 프로젝트 초기화 방법: factory init 명령
• 파이프라인 시작 방법: AI 어시스턴트에서 명령 실행
• 파이프라인 따라가기 방법: 각 단계 완료 후 확인하여 출력이 기대에 부합하는지 확인

핵심 요점:

• AI 어시스턴트와 함께 사용해야 함 (Claude Code 추천)
• 명확하고 상세한 제품 설명 제공
• 각 체크포인트에서 주의 깊게 확인하여 오류 누적 방지
• 생성된 코드는 프로덕션 수준이며 바로 사용 가능

다음 수업 예고

다음 수업에서는 **설치 및 설정**을 학습합니다.

배우게 될 내용:

• Agent Factory CLI를 전역으로 설치하는 방법
• AI 어시스턴트 (Claude Code / OpenCode)를 구성하는 방법
• 필수 플러그인 (superpowers, ui-ux-pro-max)을 설치하는 방법

---

부록: 소스 코드 참조

클릭하여 소스 코드 위치 확인

업데이트 날짜: 2026-01-29

기능	파일 경로	행号
CLI 엔트리 포인트	cli/bin/factory.js	1-123
init 명령 구현	cli/commands/init.js	-
run 명령 구현	cli/commands/run.js	-
continue 명령 구현	cli/commands/continue.js	-
파이프라인 정의	pipeline.yaml	-
스케줄러 정의	agents/orchestrator.checkpoint.md	-

핵심 구성:

• pipeline.yaml: 7단계 파이프라인 순서와 각 단계의 입력/출력을 정의
• .factory/state.json: 파이프라인 실행 상태를 유지 (idle/running/waiting_for_confirmation/paused/failed)

핵심 프로세스:

• factory init → .factory/ 디렉토리 생성, 에이전트/스킬/정책 파일 복사
• factory run → state.json 읽기, AI 어시스턴트 유형 감지, 어시스턴트 명령 생성
• factory continue → Claude Code 권한 구성 재생성, 새 세션 시작하여 실행 계속