모범 사례: 명확한 설명, 체크포인트 활용, 범위 제어 및 반복 기법

학습 완료 후 할 수 있는 것

이 강의를 완료하면 다음을 마스터하게 됩니다:

AI가 당신의 아이디어를 이해할 수 있도록 고품질 제품 설명을 작성하는 방법
각 단계의 출력 품질을 제어하기 위해 체크포인트 메커니즘을 활용하는 방법
비목표를 통해 범위 경계를 명확히 하여 프로젝트 확장을 방지하는 방법
단계별 반복을 통해 아이디어를 빠르게 검증하고 지속적으로 최적화하는 방법

현재의 어려움

다음과 같은 상황을 경험한 적이 있나요?

"분명히 설명했는데, 왜 원하는 것이 생성되지 않는가?"
"한 부분이 마음에 안 들면 뒤쪽이 모두 잘못되고, 수정하기가 고통스럽다"
"하다 보니 기능이 점점 많아져서 완전히 마무리할 수 없다"
"한 번에 모든 기능을 만들려고 했는데, 결과적으로 아무것도 만들지 못했다"

언제 이 기법을 사용할까

AI App Factory를 처음 사용하든 이미 몇 번 경험이 있든, 이러한 모범 사례는 다음을 도와줍니다:

출력 품질 향상: 생성된 애플리케이션이 기대에 더 부합하도록
수정 시간 절약: 오류 누적 방지, 초기 문제 발견
프로젝트 규모 제어: MVP에 집중하여 빠른 배달
개발 비용 절감: 단계별 검증으로 무효 투자 방지

🎒 시작 전 준비 사항

전제 조건

빠른 시작을 읽어 AI App Factory의 기본 개념 이해
7단계 파이프라인 개요를 읽어 전체 프로세스 이해
최소 한 번의 완전한 파이프라인 실행 완료(각 단계의 출력에 대한 직관적 이해)

핵심 아이디어

AI App Factory의 모범 사례는 4가지 핵심 원칙을 중심으로 합니다:

입력 품질이 출력 품질을 결정: 명확하고 상세한 제품 설명이 성공의 첫걸음
체크포인트는 품질 방어선: 각 단계 완료 후 신중히 확인하여 오류 누적 방지
MVP 집중: 비목표를 명확히 하여 범위를 제어하고 핵심 기능을 빠르게 배달
지속적인 반복: 핵심 아이디어를 먼저 검증한 후 점진적으로 기능 확장

이러한 원칙은 소스 코드와 실전 경험에서 추출한 것으로, 이를 따르면 개발 효율성이 수 배 향상될 수 있습니다.

따라 해보기

기법 1: 명확한 제품 설명 제공

왜 필요한가

AI가 당신의 아이디어를 이해할 때는 제공된 텍스트 정보만 의존할 수 있습니다. 설명이 더 명확할수록 생성된 결과물이 기대에 더 부합합니다.

어떻게 하는가

좋은 제품 설명에는 다음 요소가 포함됩니다:

목표 사용자: 누가 이 제품을 사용할 것인가?
핵심 문제: 사용자가 어떤 어려움을 겪고 있는가?
해결책: 제품이 이 어려움을 어떻게 해결하는가?
핵심 기능: 반드시 포함해야 할 기능은 무엇인가?
사용 시나리오: 사용자가 어떤 상황에서 사용하는가?
제약 조건: 어떤 제한이나 특별한 요구사항이 있는가?

비교 예시

❌ 부족한 설명	✅ 좋은 설명
피트니스 앱 만들기	운동 초보자를 위한 훈련 기록 앱으로, 운동 유형, 시간, 소모 칼로리 기록 및 이번 주 훈련 통계 조회 지원. 목표 사용자는 운동을 시작한 지 얼마 안 된 젊은이들이며, 핵심 기능은 빠른 기록과 진행 상황 확인이고, 소셜 공유나 유료 기능은 포함하지 않음
가계부 앱 만들기	젊은이들이 일일 지출을 빠르게 기록할 수 있는 모바일 가계부 앱으로, 주요 기능은 금액 기록, 분류 선택(식비, 교통, 오락, 기타), 이번 달 총 지출 및 분류 통계 조회. 오프라인 사용 지원, 데이터는 로컬에만 저장
작업 관리 도구 만들기	소규모 팀이 작업을 관리할 수 있는 간단한 도구로, 작업 생성, 멤버 할당, 마감일 설정, 작업 목록 조회 지원. 팀원 간 작업 상태 공유 가능. 복잡한 워크플로우나 권한 관리는 불필요

체크포인트 ✅

[ ] 설명에 목표 사용자가 명확히 되어 있음
[ ] 설명에 사용자가 겪는 핵심 문제가 설명되어 있음
[ ] 설명에 핵심 기능이 나열되어 있음(5개 이하)
[ ] 설명에 제약 조건이나 비목표가 포함되어 있음

기법 2: 체크포인트에서 신중히 확인

왜 필요한가

파이프라인의 각 단계 완료 후에는 체크포인트에서 일시 정지하여 확인을 기다립니다. 이는 품질 방어선으로, 초기에 문제를 발견하여 후속 단계로 오류가 전파되는 것을 방지합니다.

이 단계에서 문제를 발견하면 현재 단계만 재실행하면 됩니다. 마지막까지 기다렸다가 발견하면 여러 단계를 롤백해야 할 수 있어 많은 시간과 토큰이 낭비됩니다.

어떻게 하는가

각 체크포인트 확인 시 다음 내용을 검사:

Bootstrap 단계 체크포인트:

[ ] input/idea.md의 문제 정의가 정확함
[ ] 목표 사용자 페르소나가 명확하고 구체적임
[ ] 핵심 가치 제안이 명확함
[ ] 가정 조건이 합리적임

PRD 단계 체크포인트:

[ ] 사용자 스토리가 명확하고 수락 조건을 포함함
[ ] 기능 목록이 7개 이하(MVP 원칙)
[ ] 비목표(Non-Goals)가 명확히 나열됨
[ ] 기술 세부사항(React, API, 데이터베이스 등)이 포함되지 않음

UI 단계 체크포인트:

[ ] 페이지 구조가 합리적이고 3페이지 이하
[ ] 브라우저에서 프로토타입 미리보기 가능
[ ] 상호작용 흐름이 명확함
[ ] 미적 스타일이 뚜렷함(일반적인 AI 스타일 회피)

Tech 단계 체크포인트:

[ ] 기술 스택 선택이 합리적이고 MVP 원칙에 부합함
[ ] 데이터 모델 설계가 간단하고 테이블 수가 10개 이하
[ ] API 엔드포인트 목록이 완전함
[ ] 마이크로서비스, 캐싱 등 과도한 설계가 도입되지 않음

Code 단계 체크포인트:

[ ] 프론트엔드 및 백엔드 코드 구조가 완전함
[ ] 테스트 케이스가 포함됨
[ ] 명백한 any 타입이 없음
[ ] 실행 방법을 설명하는 README.md가 포함됨

Validation 단계 체크포인트:

[ ] 검증 보고서에 심각한 보안 문제가 없음
[ ] 테스트 커버리지 > 60%
[ ] 의존성 설치에 충돌이 없음
[ ] TypeScript 타입 검사가 통과함

Preview 단계 체크포인트:

[ ] README.md에 완전한 실행 설명이 포함됨
[ ] Docker 구성이 정상적으로 빌드됨
[ ] 로컬에서 프론트엔드 및 백엔드 서비스를 시작할 수 있음
[ ] 환경 변수 구성 설명이 포함됨

체크포인트 확인 프로세스

각 체크포인트에서 시스템은 다음 옵션을 제공합니다:

계속: 출력이 기대에 부합하면 다음 단계로 진행
재시도: 출력에 문제가 있으면 수정 의견을 제공하고 현재 단계를 재실행
일시 정지: 더 많은 정보가 필요하거나 아이디어를 조정하려면 파이프라인을 일시 정지

의사결정 원칙:

✅ 계속: 모든 검사 항목이 요구사항에 부합함
⚠️ 재시도: 작은 문제(형식, 누락, 세부사항)로 즉시 수정 가능
🛑 일시 정지: 중대한 문제(방향 오류, 범위 통제 불가, 수정 불가)로 재계획 필요

함정 경고

일반적인 오류

"빨리 완료하려고" 체크포인트 확인을 건너뛰지 마세요!

파이프라인이 "단계별 일시 정지 확인"으로 설계된 것은 문제를 적시에 발견하기 위함입니다. 습관적으로 "계속"을 클릭하면 마지막에 문제를 발견했을 때 다음이 필요할 수 있습니다:

여러 단계 롤백
대량의 작업 재실행
많은 토큰 낭비

기억하세요: 체크포인트 확인에 투입하는 시간은 롤백 후 재작업하는 시간 비용보다 훨씬 적습니다.

기법 3: 비목표를 활용한 범위 제어

왜 필요한가

비목표(Non-Goals)는 MVP 개발의 핵심 무기입니다. "무엇을 하지 않을 것인지"를 명확히 나열하면 범위 확장을 효과적으로 방지할 수 있습니다.

많은 프로젝트가 실패하는 근본 원인은 기능이 너무 적어서가 아니라 너무 많아서입니다. 각 새로운 기능은 복잡성, 개발 시간 및 유지보수 비용을 증가시킵니다. 경계를 명확히 하고 핵심 가치에 집중해야 빠르게 배달할 수 있습니다.

어떻게 하는가

Bootstrap 단계에서 비목표를 명확히 나열:

markdown

## 비목표(이 버전에서 하지 않을 기능)

1. 다중 사용자 협업 지원 안 함
2. 실시간 동기화 지원 안 함
3. 서드파티 서비스 통합 지원 안 함(결제, 지도 등)
4. 데이터 분석 또는 보고 기능 제공 안 함
5. 소셜 공유 기능 포함 안 함
6. 사용자 인증 또는 로그인 기능 불필요

PRD 단계에서 비목표를 독립적인 장으로 작성:

markdown

## 비목표(이 버전에서 명확히 하지 않음)

다음 기능은 가치가 있지만 이번 MVP 범위에 포함되지 않음:

| 기능 | 이유 | 향후 계획 |
| --- | --- | --- |
| 다중 사용자 협업 | 개인 사용자에 집중 | v2.0 고려 |
| 실시간 동기화 | 기술 복잡성 증가 | 사용자 피드백이 강력하면 고려 |
| 결제 통합 | 핵심 가치 아님 | v1.5 고려 |
| 데이터 분석 | MVP에 불필요 | v2.0 고려 |

비목표 판단 기준

비목표로 설정해야 하는지 판단하는 방법:

❌ 이 기능이 핵심 아이디어 검증에 필수적이지 않음 → 비목표로 설정
❌ 이 기능이 기술 복잡성을 크게 증가시킴 → 비목표로 설정
❌ 이 기능이 수동 방식으로 대체 가능함 → 비목표로 설정
✅ 이 기능이 제품 존재 이유임 → 반드시 포함

함정 경고

범위 확장 함정

일반적인 범위 확장 신호:

"어차피 간단하니까, 겸사겸사 하나 추가하자..."
"경쟁사에 이 기능이 있으니 우리도..."
"사용자가 필요할 수도 있으니 미리 만들자..."
"이 기능이 재미있어서 제품 하이라이트가 될 수 있을 것 같아..."

이러한 생각이 들 때 자신에게 세 가지 질문:

이 기능이 핵심 아이디어 검증에 도움이 되는가?
이 기능을 하지 않으면 제품을 사용할 수 없는가?
이 기능을 추가하면 배달 시간이 지연되는가?

답이 "필요 없음", "사용 가능", "지연됨"이라면 과감히 비목표로 설정하세요.

기법 4: 단계별 반복, 빠른 검증

왜 필요한가

MVP(최소可行 제품)의 핵심 개념은 아이디어를 빠르게 검증하는 것이지, 한 번에 완벽하게 만드는 것이 아닙니다.

반복 개발을 통해 다음을 할 수 있습니다:

초기에 사용자 피드백 얻기
방향을 적시에 조정
매몰 비용 감소
개발 동력 유지

어떻게 하는가

반복 개발 단계:

1라운드: 핵심 기능 검증

AI App Factory를 사용하여 1차 버전 애플리케이션 생성
가장 핵심적인 3-5개 기능만 포함
빠르게 실행 및 테스트
실제 사용자에게 프로토타입을 보여주고 피드백 수집

2라운드: 피드백 기반 최적화

사용자 피드백에 따라 우선순위가 가장 높은 개선점 결정
input/idea.md 또는 artifacts/prd/prd.md 수정
factory run <stage>를 사용하여 해당 단계부터 재실행
새 버전 생성 및 테스트

3라운드: 기능 확장

핵심 목표 달성 여부 평가
2-3개의 높은 가치 기능 선택
파이프라인을 통해 생성 및 통합
지속적인 반복으로 점진적 개선

반복 실전 예시

시나리오: 작업 관리 애플리케이션을 만들고 싶음

1라운드 MVP:

핵심 기능: 작업 생성, 목록 조회, 완료 표시
비목표: 멤버 관리, 권한 제어, 알림
배달 시간: 1일

2라운드 최적화(피드백 기반):

사용자 피드백: 작업에 태그를 추가하고 싶음
PRD 수정하여 "태그 분류" 기능 추가
UI 단계부터 파이프라인 재실행
배달 시간: 반나절

3라운드 확장(검증 성공 후):

멤버 관리 기능 추가
마감일 알림 추가
작업 댓글 기능 추가
배달 시간: 2일

체크포인트 ✅

각 반복 전에 확인:

[ ] 새로운 기능이 핵심 목표와 일치하는가
[ ] 새로운 기능에 사용자 요구가 뒷받침되는가
[ ] 새로운 기능이 복잡성을 크게 증가시키지 않는가
[ ] 명확한 수락 기준이 있는가

고급 기법

기법 5: 세션 분리로 토큰 절약

왜 필요한가

장시간 파이프라인 실행은 컨텍스트가 누적되어 많은 토큰을 소모합니다. 세션 분리 실행을 통해 각 단계가 깨끗한 컨텍스트를 독점적으로 사용하여 사용 비용을 크게 절감할 수 있습니다.

어떻게 하는가

각 체크포인트에서 "새 세션으로 계속" 선택:

bash

# 새 명령줄 창에서 실행
factory continue

시스템이 자동으로:

.factory/state.json을 읽어 상태 복원
새 Claude Code 창 시작
다음 실행할 단계부터 계속
해당 단계에 필요한 입력 파일만 로드

비교:

방식	장점	단점
동일 세션 계속	간단하고 창 전환 불필요	컨텍스트 누적, 토큰 소모 큼
새 세션 계속	단계별 깨끗한 컨텍스트 독점, 토큰 절약	창 전환 필요

권장 방법

대형 프로젝트나 토큰 예산이 제한된 경우 "새 세션으로 계속"을 강력히 권장합니다.

자세한 설명은 컨텍스트 최적화 튜토리얼을 참조하세요.

기법 6: 실패 처리 및 재시도

왜 필요한가

파이프라인 실행 중 입력 부족, 권한 문제, 코드 오류 등으로 인해 실패가 발생할 수 있습니다. 실패를 처리하는 방법을 이해하면 진행 상황을 더 빨리 복구할 수 있습니다.

어떻게 하는가

실패 처리 모범 사례(failure.policy.md:267-274 참조):

조기 실패: 문제를 가능한 한 빨리 발견하여 후속 단계에서 시간 낭비 방지
상세 로그: 문제 해결을 위해 충분한 컨텍스트 정보 기록
원자적 작업: 각 단계의 출력은 원자적이어야 하며 롤백이 용이함
증거 보존: 재시도 전 실패 결과물을 보관하여 비교 분석에 활용
점진적 재시도: 재시도 시 단순 반복이 아닌 더 구체적인 지침 제공

일반적인 실패 시나리오:

실패 유형	증상	처리 방안
출력 누락	`input/idea.md`가 존재하지 않음	재시도, 쓰기 경로 확인
범위 확장	기능 수 > 7개	재시도, MVP로 간소화 요구
기술 오류	TypeScript 컴파일 실패	타입 정의 확인, 재시도
권한 문제	에이전트가 인증되지 않은 디렉토리에 쓰기	능력 경계 매트릭스 확인

실패 복구 체크리스트:

[ ] 실패 원인이 명확해짐
[ ] 수정 방안이 실행됨
[ ] 관련 구성이 업데이트됨
[ ] 실패한 단계부터 다시 시작

실패는 정상입니다

실패를 두려워하지 마세요! AI App Factory는 완벽한 실패 처리 메커니즘을 설계했습니다:

각 단계는 자동 재시도를 한 번 허용
실패 결과물은 자동으로 artifacts/_failed/에 보관
가장 최근의 성공한 체크포인트로 롤백 가능

실패를 만나면 침착하게 원인을 분석하고 실패 전략에 따라 처리하세요.

강의 요약

이 강의에서는 AI App Factory의 6가지 모범 사례를 소개했습니다:

명확한 제품 설명: 목표 사용자, 핵심 문제, 핵심 기능 및 제약 조건을 상세히 설명
체크포인트 신중 확인: 각 단계 완료 후 출력 품질을 검사하여 오류 누적 방지
비목표 활용한 범위 제어: 하지 않을 기능을 명확히 나열하여 범위 확장 방지
단계별 반복: 핵심 아이디어를 먼저 검증한 후 사용자 피드백을 기반으로 점진적 확장
세션 분리로 토큰 절약: 각 체크포인트에서 새 세션을 만들어 사용 비용 절감
실패 올바르게 처리: 실패 처리 메커니즘을 활용하여 빠른 진행 상황 복구

이러한 모범 사례를 따르면 AI App Factory 사용 경험이 더 원활해지고, 생성된 애플리케이션 품질이 더 높아지며, 개발 효율성이 수 배 향상될 수 있습니다.

다음 강의 예고

다음 강의에서는 **CLI 명령어 참조**를 학습합니다.
배울 내용:
factory init 명령어의 모든 매개변수와 옵션
factory run 명령어가 지정된 단계에서 시작하는 방법
factory continue 명령어가 새 세션을 만들어 계속하는 방법
factory status 및 factory list가 프로젝트 정보를 조회하는 방법
factory reset이 프로젝트 상태를 재설정하는 방법

부록: 소스 코드 참조

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

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

기능	파일 경로	줄 번호
제품 설명 기법	`README.md`	186-210
체크포인트 메커니즘	`agents/orchestrator.checkpoint.md`	98-112
비목표 제어	`README.md`	199-203
실패 처리 전략	`policies/failure.policy.md`	267-274
컨텍스트 격리	`policies/context-isolation.md`	10-42
코드 표준	`policies/code-standards.md`	전문

핵심 상수:

MAX_RETRY_COUNT = 1: 각 단계에서 기본적으로 자동 재시도를 한 번 허용

핵심 규칙:

Must Have 기능 수 ≤ 7개(MVP 원칙)
페이지 수 ≤ 3페이지(UI 단계)
데이터 모델 수 ≤ 10개(Tech 단계)
테스트 커버리지 > 60%(Validation 단계)

모범 사례: 명확한 설명, 체크포인트 활용, 범위 제어 및 반복 기법 ​

학습 완료 후 할 수 있는 것 ​

현재의 어려움 ​

언제 이 기법을 사용할까 ​

🎒 시작 전 준비 사항 ​

핵심 아이디어 ​

따라 해보기 ​

기법 1: 명확한 제품 설명 제공 ​

왜 필요한가 ​

어떻게 하는가 ​

비교 예시 ​

체크포인트 ✅ ​

기법 2: 체크포인트에서 신중히 확인 ​

왜 필요한가 ​

어떻게 하는가 ​

체크포인트 확인 프로세스 ​

함정 경고 ​

기법 3: 비목표를 활용한 범위 제어 ​

왜 필요한가 ​

어떻게 하는가 ​

비목표 판단 기준 ​

함정 경고 ​

기법 4: 단계별 반복, 빠른 검증 ​

왜 필요한가 ​

어떻게 하는가 ​

반복 실전 예시 ​

체크포인트 ✅ ​

고급 기법 ​

기법 5: 세션 분리로 토큰 절약 ​

왜 필요한가 ​

어떻게 하는가 ​

기법 6: 실패 처리 및 재시도 ​

왜 필요한가 ​

어떻게 하는가 ​

강의 요약 ​

다음 강의 예고 ​

부록: 소스 코드 참조 ​

모범 사례: 명확한 설명, 체크포인트 활용, 범위 제어 및 반복 기법

학습 완료 후 할 수 있는 것

현재의 어려움

언제 이 기법을 사용할까

🎒 시작 전 준비 사항

핵심 아이디어

따라 해보기

기법 1: 명확한 제품 설명 제공

왜 필요한가

어떻게 하는가

비교 예시

체크포인트 ✅

기법 2: 체크포인트에서 신중히 확인

왜 필요한가

어떻게 하는가

체크포인트 확인 프로세스

함정 경고

기법 3: 비목표를 활용한 범위 제어

왜 필요한가

어떻게 하는가

비목표 판단 기준

함정 경고

기법 4: 단계별 반복, 빠른 검증

왜 필요한가

어떻게 하는가

반복 실전 예시

체크포인트 ✅

고급 기법

기법 5: 세션 분리로 토큰 절약

왜 필요한가

어떻게 하는가

기법 6: 실패 처리 및 재시도

왜 필요한가

어떻게 하는가

강의 요약

다음 강의 예고

부록: 소스 코드 참조