Skip to content

7단계 파이프라인 개요 ​

학습 후 할 수 있는 것 ​

  • 7단계 파이프라인의 전체 흐름과 각 단계의 역할을 이해합니다.
  • 각 단계의 입력, 출력, 종료 조건을 알게 됩니다.
  • 체크포인트 메커니즘이 어떻게 품질을 보장하는지 이해합니다.
  • Sisyphus 스케줄러가 Agent 실행을 어떻게 조율하는지 이해합니다.
  • 권한 행렬이 Agent의 권한을 어떻게 제한하는지 숙지합니다.
  • "새 세션에서 계속하기"를 사용하여 Token을 절약하는 방법을 익힙니다.

핵심 개념 ​

파이프라인이란 무엇인가요?

AI App Factory의 파이프라인은 제품 아이디어를 실제 실행 가능한 애플리케이션으로 단계별로 변환하는 자동화된 생산 라인입니다. 공장의 생산 라인과 마찬가지로, 원자재(제품 아이디어)가 7개의 공정(단계)을 거쳐 완제품(전체 애플리케이션)으로 만들어집니다.

각 공정은 전담 Agent가 담당하며, 각자 역할을 수행해 서로 간섭하지 않습니다.

단계Agent역할산출물
BootstrapBootstrap Agent제품 아이디어를 깊이 파악input/idea.md
PRDPRD Agent제품 요구사항 문서 생성artifacts/prd/prd.md
UIUI Agent인터페이스 및 프로토타입 설계artifacts/ui/ui.schema.yaml + 미리보기 페이지
TechTech Agent기술 아키텍처 설계artifacts/tech/tech.md + Prisma Schema
CodeCode Agent실행 가능한 코드 생성artifacts/backend/ + artifacts/client/
ValidationValidation Agent코드 품질 검증artifacts/validation/report.md
PreviewPreview Agent배포 가이드 생성artifacts/preview/README.md

주요 기능

  1. 체크포인트 메커니즘: 각 단계 완료 후 일시 중지하며, 사용자 확인 후 다음으로 진행합니다.
  2. 권한 격리: 각 Agent는 허가된 디렉터리만 읽고 쓸 수 있어 오염을 방지합니다.
  3. 실패 시 롤백 가능: 단계 실패 시 자동 재시도하며, 연속 실패 시 마지막 성공한 체크포인트로 롤백합니다.
  4. 컨텍스트 최적화: 새 세션에서 계속 실행하여 Token을 절약할 수 있습니다.

파이프라인 전체 개요 ​

mermaid
graph LR
    A[Bootstrap<br/>구조화된 제품 아이디어] -->|idea.md| B[PRD<br/>요구사항 문서 생성]
    B -->|prd.md| C[UI<br/>인터페이스 프로토타입 설계]
    C -->|ui.schema.yaml| D[Tech<br/>기술 아키텍처 설계]
    D -->|tech.md + schema.prisma| E[Code<br/>실행 가능한 코드 생성]
    E -->|backend + client| F[Validation<br/>코드 품질 검증]
    F -->|검증 보고서| G[Preview<br/>배포 가이드 생성]
    
    style A fill:#e0f2fe
    style B fill:#f0fdf4
    style C fill:#fef3c7
    style D fill:#ede9fe
    style E fill:#fce7f3
    style F fill:#dbeafe
    style G fill:#d1fae5

파이프라인 실행 규칙

실행 규칙

  1. 엄격한 순서: Bootstrap부터 순서대로 Preview까지 실행하며, 건너뛰거나 병렬로 실행할 수 없습니다.
  2. 단일 Agent 활성화: 동시에 하나의 Agent만 작업할 수 있습니다.
  3. 되돌릴 수 없음: 이미 확인된 산출물은 수정할 수 없으며, 해당 단계를 다시 실행해야 합니다.

주의: 이 규칙은 파이프라인의 실행 규칙이지 체크포인트 옵션 수가 아닙니다. 각 단계 완료 시 Sisyphus는 5개의 체크포인트 옵션을 제공합니다(아래 '체크포인트 메커니즘' 참조).

단계별 상세 ​

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

무엇을 하나요?

사용자가 제공한 자연어 제품 설명을 구조화된 문서로 변환하여 문제, 사용자, 가치, 가정을 깊이 파악합니다.

왜 중요한가요?

명확한 제품 정의는 전체 파이프라인의 기초입니다. 이 단계를 제대로 하지 않으면 이후 모든 단계가 방향을 잃게 됩니다.

입력과 출력

유형경로설명
입력사용자 자연어 설명예: "가계부 앱을 만들고 싶어요"
출력input/idea.md구조화된 제품 아이디어 문서

종료 조건

  • [ ] idea.md가 존재합니다.
  • [ ] 일관성 있는 제품 아이디어를 설명합니다.
  • [ ] Agent가 superpowers:brainstorm 스킬을 사용하여 깊이 파악했습니다.

필수 스킬 사용

반드시 superpowers:brainstorm 사용

Bootstrap 단계에서는 superpowers:brainstorm 스킬을 사용하여 깊이 파악해야 합니다. Agent가 이 스킬을 사용하지 않은 경우 산출물이 거부되며, 다시 실행하도록 요청합니다.

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

무엇을 하나요?

구조화된 제품 아이디어를 MVP 레벨의 제품 요구사항 문서로 변환하여 기능 범위, 비목표, 사용자 스토리를 명확히 합니다.

왜 중요한가요?

PRD는 설계와 개발을 위한 '계약'으로, '무엇을 할 것인가'와 '하지 않을 것인가'를 명확히 하여 범위 확장을 방지합니다.

입력과 출력

유형경로설명
입력input/idea.mdBootstrap 단계에서 출력된 구조화된 아이디어
출력artifacts/prd/prd.mdMVP 레벨 제품 요구사항 문서

종료 조건

  • [ ] PRD에 대상 사용자가 포함되어 있습니다.
  • [ ] PRD가 MVP 범위를 정의합니다.
  • [ ] PRD가 비목표를 나열합니다.
  • [ ] PRD에 기술 구현 세부 사항이 포함되지 않습니다.

주의: PRD에는 기술 세부 사항을 포함하지 않음

PRD는 '사용자가 필요로 하는 것'을 설명해야 하며, '어떻게 구현할 것인가'가 아닙니다. 기술 구현 세부 사항은 Tech와 Code 단계가 담당합니다.

단계 3: UI - 인터페이스 및 프로토타입 설계 ​

무엇을 하나요?

PRD를 바탕으로 UI 구조, 색상 계획을 설계하고 브라우저에서 미리 볼 수 있는 HTML 프로토타입을 생성합니다.

왜 중요한가요?

시각적 설계는 팀과 초기 사용자가 제품의 형태를 직관적으로 이해하게 하여 개발 재작업을 줄여줍니다.

입력과 출력

유형경로설명
입력artifacts/prd/prd.mdPRD 문서
출력artifacts/ui/ui.schema.yamlUI 구조 정의
출력artifacts/ui/preview.web/index.html미리 볼 수 있는 HTML 프로토타입

종료 조건

  • [ ] ui.schema.yaml이 존재합니다.
  • [ ] 페이지 수가 3개를 넘지 않습니다.
  • [ ] 미리보기 페이지를 브라우저에서 열 수 있습니다.
  • [ ] Agent가 ui-ux-pro-max 스킬을 사용했습니다.

필수 스킬 사용

반드시 ui-ux-pro-max 사용

UI 단계에서는 ui-ux-pro-max 스킬을 사용하여 전문적인 디자인 시스템을 생성해야 합니다. 이 스킬에는 67가지 스타일, 96가지 색상 팔레트, 100가지 업계 규칙이 포함되어 있습니다.

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

무엇을 하나요?

최소 기술 아키텍처와 데이터 모델을 설계하고, 기술 스택을 선택하며 API 엔드포인트를 정의합니다.

왜 중요한가요?

기술 아키텍처는 코드의 유지 관리성, 확장성, 성능을 결정합니다. 과도하게 설계하면 개발이 어렵고, 설계가 부족하면 요구사항을 지원할 수 없습니다.

입력과 출력

유형경로설명
입력artifacts/prd/prd.mdPRD 문서
출력artifacts/tech/tech.md기술 아키텍처 문서
출력artifacts/backend/prisma/schema.prismaPrisma 데이터 모델

종료 조건

  • [ ] 기술 스택이 명확하게 선언되었습니다.
  • [ ] 데이터 모델이 PRD와 일치합니다.
  • [ ] 조기 최적화나 과도한 설계가 수행되지 않았습니다.

기술 스택 기본 선택

  • 백엔드: Node.js + Express + Prisma
  • 데이터베이스: SQLite(개발) / PostgreSQL(프로덕션)
  • 프론트엔드: React Native + Expo

단계 5: Code - 실행 가능한 코드 생성 ​

무엇을 하나요?

UI Schema, Tech 설계, Prisma Schema를 바탕으로 전체 프론트엔드와 백엔드 코드, 테스트, 설정, 문서를 생성합니다.

왜 중요한가요?

이는 '아이디어에서 애플리케이션으로'의 핵심 단계로, 생성된 코드는 실행 가능하고 프로덕션 준비 상태여야 합니다.

입력과 출력

유형경로설명
입력artifacts/ui/ui.schema.yamlUI 구조 정의
입력artifacts/tech/tech.md기술 아키텍처 문서
입력artifacts/backend/prisma/schema.prisma데이터 모델
출력artifacts/backend/백엔드 코드(Express + Prisma)
출력artifacts/client/프론트엔드 코드(React Native)

종료 조건

  • [ ] 백엔드가 시작되며 심각한 오류가 없습니다.
  • [ ] 클라이언트를 렌더링하고 액세스할 수 있습니다.
  • [ ] 추가 인증이나 무관한 기능이 도입되지 않았습니다.

생성되는 내용

Code Agent는 다음을 생성합니다.

백엔드:

  • Express 서버 + 라우트
  • Prisma ORM + 데이터 모델
  • 단위 테스트 및 통합 테스트(Vitest)
  • API 문서(Swagger/OpenAPI)
  • 시드 데이터(prisma/seed.ts)
  • Docker 구성
  • 로깅 및 모니터링

프론트엔드:

  • React Native 페이지 및 컴포넌트
  • React Navigation 라우트
  • 단위 테스트(Jest + React Testing Library)
  • 환경 설정

인증 기능을 생성하지 않는 이유는 무엇인가요?

AI App Factory는 MVP에 집중하며, 기본적으로 인증, 권한 부여와 같은 복잡한 기능을 생성하지 않습니다. 이러한 기능은 후속 반복에서 추가할 수 있습니다.

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

무엇을 하나요?

생성된 코드가 의존성을 설치할 수 있는지, 유형 검사를 통과하는지, 코드 표준을 준수하는지 검증합니다.

왜 중요한가요?

코드를 실행하기 전에 문제를 발견하여 배포 후 오류가 발견되는 것을 방지하고 디버깅 시간을 절약합니다.

입력과 출력

유형경로설명
입력artifacts/backend/백엔드 코드
입력artifacts/client/프론트엔드 코드
출력artifacts/validation/report.md검증 보고서

종료 조건

  • [ ] 검증 보고서가 생성되었습니다.
  • [ ] 백엔드 의존성을 정상적으로 해석할 수 있습니다.
  • [ ] 프론트엔드 의존성을 정상적으로 해석할 수 있습니다.
  • [ ] TypeScript 컴파일에 심각한 오류가 없습니다.
  • [ ] Prisma schema 검증을 통과했습니다.

검증 내용

Validation Agent는 다음을 확인합니다.

  1. 의존성 해석: npm install이 성공하는지 확인
  2. 유형 검사: tsc --noEmit을 통과하는지 확인
  3. 코드 표준: policies/code-standards.md를 준수하는지 확인
  4. Prisma Schema: prisma validate를 통과하는지 확인
  5. 테스트 통과율: 테스트가 존재하고 실행 가능한지 확인

실패 처리

검증에 실패하면 Validation Agent는 상세한 오류 보고서를 생성하여 구체적인 문제와 수정 제안을 지적합니다.

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

무엇을 하나요?

모든 산출물을 요약하여 전체 실행 안내서, 배포 설정, 데모 절차 문서를 생성합니다.

왜 중요한가요?

이는 파이프라인의 마지막 단계로, 생성된 애플리케이션을 빠르게 실행하고 배포할 수 있게 합니다.

입력과 출력

유형경로설명
입력artifacts/backend/백엔드 코드
입력artifacts/client/프론트엔드 코드
출력artifacts/preview/README.md전체 실행 안내서
출력artifacts/preview/GETTING_STARTED.md빠른 시작 가이드

종료 조건

  • [ ] README에 설치 단계가 포함되어 있습니다.
  • [ ] README에 실행 명령어가 포함되어 있습니다.
  • [ ] README에 접근 주소와 데모 절차가 나열되어 있습니다.

생성되는 내용

Preview Agent는 다음을 생성합니다.

  • 로컬 실행 안내서(Web, iOS, Android)
  • Docker 배포 설정(docker-compose.yml)
  • CI/CD 설정 참조(GitHub Actions)
  • Git Hooks 설정 참조(Husky)
  • 데이터베이스 마이그레이션 가이드(SQLite → PostgreSQL)

체크포인트 메커니즘 ​

체크포인트란 무엇인가요?

각 단계 완료 후 파이프라인이 일시 중지되고, 생성된 산출물 목록을 보여주어 기대에 부합하는지 확인합니다. 부합하지 않으면 '재시도' 또는 '수정 후 다시 실행'을 선택할 수 있습니다.

체크포인트가 필요한 이유는 무엇인가요?

  • 오류 누적 방지: 초기 문제는 현재 단계에서 해결하지 않으면 이후 단계에서 오류가 확대됩니다.
  • 품질 보장: 각 단계에서 출력이 기대에 부합하는지 확인하여 사용 불가능한 코드를 생성하는 것을 방지합니다.
  • 유연한 제어: 모든 체크포인트에서 일시 중지, 재시도, 입력 수정을 할 수 있습니다.

체크포인트 옵션

각 단계 완료 시 Sisyphus 스케줄러는 다음 옵션을 보여줍니다.

┌──────┬──────────────────────────────────────────────────────┐
│ 옵션 │ 설명                                                  │
├──────┼──────────────────────────────────────────────────────┤
│  1   │ 다음 단계 계속(동일 세션)                              │
│      │ [다음 단계 이름] 단계를 계속 실행합니다.                │
├──────┼──────────────────────────────────────────────────────┤
│  2   │ 새 세션에서 계속 ⭐ 추천 옵션, Token 절약               │
│      │ 새 명령줄 창에서 다음을 실행합니다: factory continue    │
│      │ (새 Claude Code 창을 자동으로 시작하고 파이프라인 계속)  │
├──────┼──────────────────────────────────────────────────────┤
│  3   │ 현재 단계 다시 실행                                    │
│      │ [현재 단계 이름] 단계를 다시 실행합니다.                 │
├──────┼──────────────────────────────────────────────────────┤
│  4   │ 수정 후 다시 실행                                      │
│      │ [입력 파일]을 수정한 후 다시 실행합니다.                │
├──────┼──────────────────────────────────────────────────────┤
│  5   │ 파이프라인 일시 중지                                   │
│      │ 현재 진행 상황을 저장하고 나중에 계속합니다.             │
└──────┴──────────────────────────────────────────────────────┘

권장 사항

'새 세션에서 계속' 선택으로 Token 절약

각 단계 완료 후 '새 세션에서 계속'(옵션 2)을 선택하는 것을 권장합니다.

  1. 새 명령줄 창에서 factory continue를 실행합니다.
  2. 명령이 새 Claude Code 창을 자동으로 시작합니다.
  3. 각 단계가 깨끗한 컨텍스트를 독점적으로 사용하여 Token 누적을 방지합니다.

권한 행렬 ​

권한 격리가 필요한 이유는 무엇인가요?

Agent가 임의로 모든 디렉터리를 읽고 쓸 수 있다면 다음이 발생할 수 있습니다.

  • Bootstrap Agent가 완료된 PRD를 실수로 수정할 수 있습니다.
  • Code Agent가 UI 설계를 실수로 삭제할 수 있습니다.
  • Validation Agent가 백엔드 코드를 잘못 수정할 수 있습니다.

능력 경계 행렬

Sisyphus 스케줄러는 각 단계 실행 전후에 Agent 권한을 확인합니다.

Agent읽기 허용쓰기 허용
bootstrap없음input/
prdinput/artifacts/prd/
uiartifacts/prd/artifacts/ui/
techartifacts/prd/artifacts/tech/, artifacts/backend/prisma/
codeartifacts/ui/, artifacts/tech/, artifacts/backend/prisma/artifacts/backend/, artifacts/client/
validationartifacts/backend/, artifacts/client/artifacts/validation/
previewartifacts/backend/, artifacts/client/artifacts/preview/

권한 초과 처리

Agent가 권한 없는 디렉터리에 쓰면, Sisyphus 스케줄러는 파일을 artifacts/_untrusted/<stage-id>/로 이동하고, 파이프라인을 일시 중지한 후 보고합니다.

권한 초과 예시

PRD Agent가 artifacts/ui/ui.schema.yaml에 쓴다고 가정해 봅시다(이는 권한 범위가 아닙니다). 스케줄러는 다음을 수행합니다.

  1. 파일을 artifacts/_untrusted/prd/ui.schema.yaml로 이동합니다.
  2. 파이프라인을 일시 중지합니다.
  3. 다음과 같이 보고합니다: 권한 없는 쓰기가 감지되었습니다. 수동으로 처리해 주세요.

실패 처리 ​

무엇이 실패로 간주되나요?

  • 출력 파일이 누락되었습니다.
  • 산출물 내용이 exit_criteria를 충족하지 않습니다.
  • Agent가 권한 없는 디렉터리에 썼습니다.
  • 스크립트 오류 또는 입력을 읽을 수 없습니다.

기본 처리 전략

  1. 자동 재시도: 각 단계는 자동 재시도를 한 번 허용합니다.
  2. 실패 보관: 실패한 산출물을 artifacts/_failed/<stage-id>/로 이동합니다.
  3. 파이프라인 일시 중지: 연속 실패 2회 후 수동 개입을 기다립니다.
  4. 롤백 메커니즘: 가장 최근 성공한 체크포인트로 롤백하여 다시 실행합니다.

수동 개입 후 처리

연속 실패 2회 발생 시 다음을 수행할 수 있습니다.

  1. 입력 파일(예: input/idea.md) 수정
  2. Agent 프롬프트 조정
  3. 권한 문제 수정
  4. factory run [stage]를 실행하여 해당 단계부터 다시 시작

상태 관리 ​

상태 파일

파이프라인의 모든 상태는 .factory/state.json에 저장되며, 다음을 포함합니다.

json
{
  "version": 1,
  "status": "waiting_for_confirmation",
  "current_stage": "prd",
  "completed_stages": ["bootstrap"],
  "started_at": "2026-01-29T10:00:00Z",
  "last_updated": "2026-01-29T10:30:00Z"
}

상태 머신

상태의미트리거 조건
idle시작되지 않음factory run 대기 중
running실행 중단 Stage 시작
waiting_for_confirmation확인 대기 중단계 완료
paused일시 중지됨사용자가 일시 중지 선택
failed실패로 개입 필요연속 실패 또는 권한 초과 조작

Sisyphus 스케줄러만 상태를 업데이트할 권한이 있습니다.

문제 해결 팁 ​

일반적인 오류 1: Bootstrap 단계에서 brainstorm 스킬 미사용 ​

현상: Sisyphus가 input/idea.md를 거부하며 'superpowers:brainstorm 스킬 사용 감지 안 됨'을 표시합니다.

원인: Bootstrap Agent가 superpowers:brainstorm 스킬을 사용하여 제품 아이디어를 깊이 파악하지 않았습니다.

해결 방법: 산출물 확인 시 '현재 단계 다시 실행'을 선택하고, Agent가 명시적으로 superpowers:brainstorm 스킬을 사용하도록 요청합니다.

일반적인 오류 2: UI 단계에서 평범한 디자인 ​

현상: 생성된 UI 디자인이 획일적이며 모두 보라색 그라데이션, Inter 폰트입니다.

원인: UI Agent가 ui-ux-pro-max 스킬을 사용하지 않았습니다.

해결 방법: 산출물 확인 시 '현재 단계 다시 실행'을 선택하고, Agent가 명시적으로 ui-ux-pro-max 스킬을 사용하도록 요청하며, 명확한 미학적 방향(예: '사이버펑크', '미니멀리즘')을 지정합니다.

일반적인 오류 3: Code 단계에서 인증 기능 생성 ​

현상: 생성된 백엔드 코드에 JWT 인증, 사용자 로그인 등 복잡한 기능이 포함되어 있습니다.

원인: Code Agent가 MVP 범위를 초과했습니다.

해결 방법: PRD를 수정하여 '비목표'(예: '사용자 로그인 미지원', '다중 사용자 협업 미지원')를 명시하고 나열한 후 Code 단계를 다시 실행합니다.

일반적인 오류 4: Token 소모 과도 ​

현상: 파이프라인 후반부로 갈수록 Token 소모가 급증하고 AI 어시스턴트의 응답이 느려집니다.

원인: 동일 세션에서 여러 단계를 실행하여 컨텍스트가 계속 누적됩니다.

해결 방법: 항상 '새 세션에서 계속'(옵션 2)을 선택하여 각 단계가 깨끗한 컨텍스트를 독점적으로 사용하도록 합니다.

요약 ​

  • 파이프라인은 7단계로 구성됩니다: Bootstrap → PRD → UI → Tech → Code → Validation → Preview
  • 각 단계 완료 후 일시 중지하여 확인하며 출력이 기대에 부합하는지 보장합니다.
  • Sisyphus 스케줄러는 Agent 실행을 조율하고 상태 및 권한을 관리합니다.
  • 능력 경계 행렬은 Agent의 권한 초과를 방지하여 책임 분리를 보장합니다.
  • '새 세션에서 계속'을 선택하면 Token을 크게 절약할 수 있습니다.

다음 강좌 미리보기 ​

다음 강좌에서는 **Claude Code 통합 가이드**를 학습합니다.

다음을 배울 수 있습니다:

  • Claude Code 권한 구성 방법
  • 파이프라인 실행 방법
  • Claude Code 모범 사례

부록: 소스 코드 참조 ​

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

업데이트: 2026-01-29

기능파일 경로행 번호
파이프라인 정의pipeline.yaml1-111
스케줄러 핵심agents/orchestrator.checkpoint.md1-302
프로젝트 READMEREADME.md1-253

핵심 상수:

  • 파이프라인 모드: checkpoint(각 단계마다 확인 대기 체크포인트 모드)

핵심 Agent 정의:

  • Bootstrap Agent: superpowers:brainstorm 스킬 사용, input/idea.md 생성
  • PRD Agent: input/idea.md 읽기, artifacts/prd/prd.md 생성
  • UI Agent: ui-ux-pro-max 스킬 사용, artifacts/ui/ui.schema.yaml 및 미리보기 페이지 생성
  • Tech Agent: artifacts/tech/tech.md 및 artifacts/backend/prisma/schema.prisma 생성
  • Code Agent: UI, Tech, Schema를 기반으로 artifacts/backend/ 및 artifacts/client/ 생성
  • Validation Agent: 코드 품질 검증, artifacts/validation/report.md 생성
  • Preview Agent: artifacts/preview/README.md 생성