Factory 프로젝트 초기화: 처음부터 3분 설정

이 과정을 마치면 할 수 있는 것들

임의의 빈 디렉터리에서 Factory 프로젝트 초기화
생성된 .factory/ 디렉터리 구조 이해
프로젝트 파라미터 설정(기술 스택, UI 선호도, MVP 제약조건)
AI 어시스턴트 자동 시작 및 파이프라인 시작

현재 겪고 있는 문제

AI App Factory를 사용해보고 싶지만 어디서부터 시작해야 할지 모르나요? 빈 폴더를 보면서 어떤 파일을 만들어야 할지 고민하고 있나요? 아니면 이미 코드가 있어서 바로 사용할 수 있을지 확실하지 않나요? 걱정하지 마세요, factory init 명령어가 모든 것을 해결해 드립니다.

이 기능을 사용하는 경우

처음으로 AI App Factory를 사용할 때
새로운 제품 아이디어를 시작할 때
깔끔한 Factory 프로젝트 환경이 필요할 때

🎒 시작 전 준비

사전 점검

시작하기 전에 확인하세요:

✅ 설치 및 설정 완료
✅ AI 어시스턴트 설치 완료(Claude Code 또는 OpenCode)
✅ 빈 디렉터리 또는 Git/편집기 설정만 포함된 디렉터리가 있음

핵심 개념

factory init 명령어의 핵심은 **자체 포함(self-contained)**입니다:

모든 필수 파일(agents, skills, policies, pipeline.yaml)을 프로젝트의 .factory/ 디렉터리에 복사
프로젝트 설정 파일(config.yaml 및 state.json) 생성
Claude Code 권한 설정(.claude/settings.local.json)
필수 플러그인 자동 설치(superpowers, ui-ux-pro-max)
AI 어시스턴트 시작 및 파이프라인 시작

이렇게 하면 각 Factory 프로젝트가 실행에 필요한 모든 것을 포함하며, 전역 설치에 의존하지 않습니다.

왜 자체 포함인가요?

자체 포함 설계의 장점:

버전 격리: 다른 프로젝트에서 다른 버전의 Factory 설정을 사용할 수 있음
이식성: .factory/ 디렉터리를 Git에 직접 커밋하여 팀원들이 재사용 가능
보안: 권한 설정이 프로젝트 디렉터리 내에서만 적용되며 다른 프로젝트에 영향을 주지 않음

함께 해보기

1단계: 프로젝트 디렉터리로 이동

이유: 생성된 앱을 저장할 깔끔한 작업 디렉터리가 필요합니다.

bash

# 새 디렉터리 생성
mkdir my-app && cd my-app

# 또는 기존 빈 디렉터리로 이동
cd /path/to/your/project

다음과 같아야 합니다: 디렉터리가 비어 있거나, .git/, .gitignore, README.md 등 허용된 파일만 포함되어 있습니다.

2단계: 초기화 명령어 실행

이유: factory init는 .factory/ 디렉터리를 생성하고 모든 필수 파일을 복사합니다.

bash

factory init

다음과 같아야 합니다:

Agent Factory - Project Initialization

✓ Factory project initialized!

Project structure created:
  .factory/
    agents/
    skills/
    templates/
    policies/
    pipeline.yaml
    config.yaml
    state.json

Checking and installing required Claude plugins...
Installing superpowers plugin... ✓
Installing ui-ux-pro-max-skill plugin... ✓
Plugins installed!

Starting Claude Code...
✓ Claude Code is starting...
  (Please wait for window to open)

3단계: 선택적 매개변수로 사용자 정의(선택사항)

이유: 명확한 기술 스택 선호도가 있는 경우 초기화 시 지정할 수 있습니다.

bash

factory init --name "나의 가계부 앱" --description "젊은 사람들을 위한 일일 지출 기록 도구"

이러한 매개변수는 config.yaml에 기록되며, 후속 코드 생성에 영향을 미칩니다.

4단계: 생성된 디렉터리 구조 확인

이유: 모든 파일이 올바르게 생성되었는지 확인합니다.

bash

ls -la

다음과 같아야 합니다:

.claude/              # Claude Code 설정 디렉터리
  └── settings.local.json   # 권한 설정

.factory/            # Factory 핵심 디렉터리
  ├── agents/          # Agent 정의 파일
  ├── skills/          # 스킬 모듈
  ├── templates/       # 설정 템플릿
  ├── policies/        # 정책 및 규칙
  ├── pipeline.yaml    # 파이프라인 정의
  ├── config.yaml      # 프로젝트 설정
  └── state.json      # 파이프라인 상태

점검점 ✅

다음 파일이 모두 생성되었는지 확인하세요:

[ ] .factory/pipeline.yaml 존재
[ ] .factory/config.yaml 존재
[ ] .factory/state.json 존재
[ ] .claude/settings.local.json 존재
[ ] .factory/agents/ 디렉터리에 7개의 .agent.md 파일 포함
[ ] .factory/skills/ 디렉터리에 6개의 스킬 모듈 포함
[ ] .factory/policies/ 디렉터리에 7개의 정책 문서 포함

생성된 파일 상세 설명

config.yaml: 프로젝트 설정

config.yaml에는 프로젝트의 기본 정보와 파이프라인 상태가 포함됩니다:

yaml

project:
  name: my-app                  # 프로젝트 이름
  description: ""                # 프로젝트 설명
  created_at: "2026-01-30T00:00:00.000Z"  # 생성 시간
  updated_at: "2026-01-30T00:00:00.000Z"  # 업데이트 시간

pipeline:
  current_stage: null           # 현재 실행 단계
  completed_stages: []          # 완료된 단계 목록
  last_checkpoint: null         # 마지막 체크포인트

settings:
  auto_save: true               # 자동 저장
  backup_on_error: true        # 오류 시 백업

설정 수정

factory init 후에 직접 config.yaml을 편집할 수 있으며, 파이프라인 실행 시 자동으로 적용됩니다. 다시 초기화할 필요가 없습니다.

state.json: 파이프라인 상태

state.json은 파이프라인의 실행 진행률을 기록합니다:

json

{
  "version": 1,
  "status": "idle",
  "current_stage": null,
  "completed_stages": [],
  "started_at": null,
  "last_updated": "2026-01-30T00:00:00.000Z"
}

status: 현재 상태(초기화 시 idle, 실행 시 running, waiting_for_confirmation, paused, failed로 동적으로 전환)
current_stage: 현재 실행 중인 단계
completed_stages: 완료된 단계 목록

상태 설명

파이프라인은 상태 머신으로 실행되며, 초기화 시 상태는 idle입니다. 다른 상태 값은 파이프라인 실행 중에 동적으로 설정됩니다:

idle: 시작 대기 중
running: 특정 단계 실행 중
waiting_for_confirmation: 수동 확인 대기 중(계속, 재시도, 일시중지)
paused: 수동으로 일시중지됨
failed: 실패 감지, 수동 개입 필요

수동으로 편집하지 마세요

state.json은 파이프라인에 의해 자동으로 유지 관리되며, 수동으로 편집하면 상태 불일치가 발생할 수 있습니다. 재설정이 필요한 경우 factory reset 명령어를 사용하세요.

pipeline.yaml: 파이프라인 정의

7개 단계의 실행 순서와 종속성을 정의합니다:

yaml

stages:
  - id: bootstrap
    description: 프로젝트 아이디어 초기화
    agent: agents/bootstrap.agent.md
    inputs: []
    outputs: [input/idea.md]

  - id: prd
    description: 제품 요구사항 문서 생성
    agent: agents/prd.agent.md
    inputs: [input/idea.md]
    outputs: [artifacts/prd/prd.md]

  # ... 다른 단계

파이프라인 순서

파이프라인은 순서대로 엄격하게 실행되며 건너뛸 수 없습니다. 각 단계가 완료되면 확인을 위해 일시중지됩니다.

.claude/settings.local.json: 권한 설정

자동으로 생성된 Claude Code 권한 설정에는 다음이 포함됩니다:

파일 작업 권한: 프로젝트 디렉터리에 대한 Read/Write/Glob/Edit
Bash 명령어 권한: git, npm, npx, docker 등
스킬 권한: superpowers, ui-ux-pro-max 등 필수 스킬
WebFetch 권한: 특정 도메인(GitHub, NPM 등)에 대한 접근 허용

보안

권한 설정은 현재 프로젝트 디렉터리에만 적용되며 시스템의 다른 위치에 영향을 주지 않습니다. 이는 Factory의 보안 설계 중 하나입니다.

주의 사항

디렉터리 비어있지 않음 오류

오류 메시지:

Cannot initialize: directory is not empty.
Factory init requires an empty directory or one with only git/config files.

원인: 호환되지 않는 파일 또는 디렉터리(예: artifacts/, input/ 등)가 존재함

해결 방법:

충돌 파일 정리:
bash
```
rm -rf artifacts/ input/
```

또는 새 디렉터리 사용:

bash

mkdir my-app-new && cd my-app-new
factory init

이미 Factory 프로젝트

오류 메시지:

This directory is already a Factory project:
  Name: my-app
  Created: 2026-01-29T13:00:00.000Z

To reset project, use: factory reset

원인: .factory/ 디렉터리가 이미 존재함

해결 방법:

bash

# 프로젝트 상태 재설정(산출물 유지)
factory reset

# 또는 완전히 다시 초기화(모든 내용 삭제)
rm -rf .factory/
factory init

Claude Code 미설치

오류 메시지:

Claude CLI not found - skipping plugin installation
Install Claude Code to enable plugins: https://claude.ai/code

원인: Claude Code CLI가 설치되지 않음

해결 방법:

Claude Code 설치: https://claude.ai/code
또는 수동으로 파이프라인 실행(빠른 시작 참조)

플러그인 설치 실패

오류 메시지:

Installing superpowers plugin... (failed)
Note: superpowers plugin installation failed
The bootstrap stage may prompt you to install it manually

원인: 네트워크 문제 또는 Claude Code 구성 문제

해결 방법:

경고를 무시하고 계속 사용하세요. Bootstrap 단계에서 수동으로 플러그인을 설치하라는 메시지가 표시됩니다.

이 과정 요약

이 과정에서 배운 내용:

✅ factory init 명령어로 Factory 프로젝트 초기화
✅ 생성된 .factory/ 디렉터리 구조 이해
✅ config.yaml의 설정 항목 이해
✅ state.json의 상태 관리 이해
✅ .claude/settings.local.json의 권한 설정 이해

초기화가 완료되면 프로젝트가 파이프라인 실행을 준비합니다. 다음 단계에서 파이프라인 개요를 학습하여 아이디어에서 앱으로 이어지는 전체 프로세스를 이해해 보세요.

다음 과정 미리보기

다음 과정에서는 **파이프라인 개요**를 학습합니다.
배우게 될 내용:
7개 단계의 순서와 종속성
각 단계의 입력 및 출력
체크포인트 메커니즘이 품질을 보장하는 방법
실패 처리 및 재시도 전략

부록: 소스 코드 참조

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

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

기능	파일 경로	행번호
init 메인 로직	`cli/commands/init.js`	220-456
디렉터리 안전 점검	`cli/commands/init.js`	32-53
설정 생성	`cli/commands/init.js`	58-76
Claude 권한 설정	`cli/utils/claude-settings.js`	41-248
파이프라인 정의	`pipeline.yaml`	7-111
프로젝트 설정 템플릿	`config.yaml`	1-102

핵심 함수:

isFactoryProject(): 디렉터리가 이미 Factory 프로젝트인지 확인(22-26행)
isDirectorySafeToInit(): 디렉터리가 안전하게 초기화할 수 있는지 확인(32-53행)
generateConfig(): 프로젝트 설정 생성(58-76행)
generateClaudeSettings(): Claude Code 권한 설정 생성(256-275행)

Factory 프로젝트 초기화: 처음부터 3분 설정 ​

이 과정을 마치면 할 수 있는 것들 ​

현재 겪고 있는 문제 ​

이 기능을 사용하는 경우 ​

🎒 시작 전 준비 ​

핵심 개념 ​

함께 해보기 ​

1단계: 프로젝트 디렉터리로 이동 ​

2단계: 초기화 명령어 실행 ​

3단계: 선택적 매개변수로 사용자 정의(선택사항) ​

4단계: 생성된 디렉터리 구조 확인 ​

점검점 ✅ ​

생성된 파일 상세 설명 ​

config.yaml: 프로젝트 설정 ​

state.json: 파이프라인 상태 ​

pipeline.yaml: 파이프라인 정의 ​

.claude/settings.local.json: 권한 설정 ​

주의 사항 ​

디렉터리 비어있지 않음 오류 ​

이미 Factory 프로젝트 ​

Claude Code 미설치 ​

플러그인 설치 실패 ​

이 과정 요약 ​

다음 과정 미리보기 ​

부록: 소스 코드 참조 ​

Factory 프로젝트 초기화: 처음부터 3분 설정

이 과정을 마치면 할 수 있는 것들

현재 겪고 있는 문제

이 기능을 사용하는 경우

🎒 시작 전 준비

핵심 개념

함께 해보기

1단계: 프로젝트 디렉터리로 이동

2단계: 초기화 명령어 실행

3단계: 선택적 매개변수로 사용자 정의(선택사항)

4단계: 생성된 디렉터리 구조 확인

점검점 ✅

생성된 파일 상세 설명

config.yaml: 프로젝트 설정

state.json: 파이프라인 상태

pipeline.yaml: 파이프라인 정의

.claude/settings.local.json: 권한 설정

주의 사항

디렉터리 비어있지 않음 오류

이미 Factory 프로젝트

Claude Code 미설치

플러그인 설치 실패

이 과정 요약

다음 과정 미리보기

부록: 소스 코드 참조