설치 및 설정

학습 후 달성할 수 있는 것

✅ Agent App Factory CLI 도구를 설치하고 설치를 확인합니다 ✅ Claude Code 또는 OpenCode를 AI 실행 엔진으로 설정합니다 ✅ 파이프라인 실행에 필요한 필수 플러그인을 설치합니다 ✅ 프로젝트 초기화를 완료하고 첫 번째 Factory 프로젝트를 시작합니다

현재 겪고 계신 문제

AI App Factory를 사용하여 아이디어를 앱으로 만들고 싶지만, 어떤 도구를 설치하고 어떤 환경을 설정해야 할지 모릅니다. 설치를 완료했더라도 필수 플러그인을 놓쳐서 파이프라인 실행 중간에 오류가 발생할까 봐 걱정됩니다.

언제 이 방법을 사용해야 하나요

처음으로 AI App Factory를 사용하거나, 새로운 컴퓨터에서 개발 환경을 다시 구축할 때 먼저 설치 및 설정을 완료한 다음 앱 생성을 시작하세요.

🎒 시작 전 준비

사전 요구사항

설치를 시작하기 전에 다음을 확인하세요:

• Node.js 버전 >= 16.0.0 - CLI 도구의 최소 요구사항입니다
• npm 또는 yarn - 전역 패키지 설치에 사용합니다
• AI 어시스턴트 - Claude Code 또는 OpenCode (Claude Code 권장)

Node.js 버전 확인:

node --version

버전이 16.0.0 미만인 경우 Node.js 공식 웹사이트에서 최신 LTS 버전을 다운로드하여 설치하세요.

핵심 개념

AI App Factory 설치는 3가지 핵심 부분으로 구성됩니다:

1. CLI 도구 - 명령줄 인터페이스를 제공하고 프로젝트 상태를 관리합니다
2. AI 어시스턴트 - 파이프라인을 실행하는 "뇌"로서 Agent 지시사항을 해석합니다
3. 필수 플러그인 - AI 기능을 향상시키는 확장 패키지 (Bootstrap 브레인스토밍, UI 디자인 시스템)

설치 프로세스: CLI 설치 → AI 어시스턴트 설정 → 프로젝트 초기화 (자동 플러그인 설치)

함께 따라하기

1단계: CLI 도구 설치

Agent App Factory CLI를 전역으로 설치하여 모든 디렉토리에서 factory 명령어를 사용할 수 있도록 합니다.

npm install -g agent-app-factory

예상 결과: 설치 성공 메시지

added 1 package in Xs

설치 확인:

factory --version

예상 결과: 버전 번호 출력

1.0.0

버전 번호가 표시되지 않는 경우 설치가 성공했는지 확인하세요:

which factory  # macOS/Linux
where factory  # Windows

설치 실패?

권한 문제가 발생하는 경우 (macOS/Linux), 다음을 시도하세요:

sudo npm install -g agent-app-factory

또는 전역 설치 없이 npx 사용 (권장하지 않음, 사용할 때마다 다운로드 필요):

npx agent-app-factory init

2단계: AI 어시스턴트 설치

AI App Factory는 AI 어시스턴트와 함께 사용해야 합니다. Agent 정의와 Skill 파일은 Markdown 형식의 AI 지시사항이므로 AI가 해석하고 실행해야 합니다.

옵션 A: Claude Code (권장)

Claude Code는 Anthropic의 공식 AI 프로그래밍 어시스턴트로, AI App Factory와 완벽하게 통합되어 있습니다.

설치 방법:

1. Claude Code 공식 웹사이트 방문
2. 플랫폼에 맞는 애플리케이션 다운로드 및 설치
3. 설치 완료 후 명령어 사용 가능 여부 확인:

claude --version

예상 결과: 버전 번호 출력

Claude Code 1.x.x

옵션 B: OpenCode

OpenCode는 Agent 모드를 지원하는 또 다른 AI 프로그래밍 어시스턴트입니다.

설치 방법:

1. OpenCode 공식 웹사이트 방문
2. 플랫폼에 맞는 애플리케이션 다운로드 및 설치
3. 명령줄 도구가 없는 경우 수동으로 다운로드하여 다음 위치에 설치:

• Windows: %LOCALAPPDATA%\Programs\OpenCode\
• macOS: /Applications/OpenCode.app/
• Linux: /usr/bin/opencode 또는 /usr/local/bin/opencode

왜 Claude Code를 권장하나요?

• 공식 지원, AI App Factory의 권한 시스템과 가장 잘 통합됩니다
• 플러그인 설치 자동화, factory init이 필수 플러그인을 자동으로 구성합니다
• 더 나은 컨텍스트 관리로 Token 절약

3단계: 첫 번째 Factory 프로젝트 초기화

이제 깨끗한 팩토리가 생겼으니 첫 번째 프로젝트를 초기화해 보겠습니다.

프로젝트 디렉토리 생성:

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

Factory 프로젝트 초기화:

factory init

예상 결과:

Agent Factory - Project Initialization

✓ Factory project initialized!

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

✓ Plugins installed!

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

체크포인트 ✅: 다음 파일이 생성되었는지 확인하세요

ls -la .factory/

예상 결과:

agents/
skills/
policies/
templates/
pipeline.yaml
config.yaml
state.json

동시에 Claude Code 창이 자동으로 열립니다.

디렉토리는 비어 있어야 합니다

factory init은 빈 디렉토리 또는 .git, README.md 등의 구성 파일만 포함된 디렉토리에서만 실행할 수 있습니다.

디렉토리에 다른 파일이 있는 경우 오류가 표시됩니다:

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

4단계: 자동으로 설치된 플러그인

factory init은 두 가지 필수 플러그인을 자동으로 설치하려고 시도합니다:

1. superpowers - Bootstrap 단계의 브레인스토밍 스킬
2. ui-ux-pro-max-skill - UI 단계의 디자인 시스템 (67가지 스타일, 96가지 색상 팔레트, 100개의 업계 규칙)

자동 설치가 실패하면 경고가 표시됩니다:

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

플러그인 설치 실패 시 대처 방법

초기화 시 플러그인 설치가 실패한 경우 나중에 Claude Code에서 수동으로 설치할 수 있습니다:

1. Claude Code에서 다음을 입력:

   /install superpowers
   /install ui-ux-pro-max-skill

2. 또는 플러그인 마켓에서 수동으로 설치

5단계: AI 어시스턴트 권한 확인

factory init은 필요한 권한을 구성하는 .claude/settings.local.json 파일을 자동으로 생성합니다.

권한 구성 확인:

cat .claude/settings.local.json

예상 결과 (간소화된 버전):

{
  "allowedCommands": [
    "read",
    "write",
    "glob",
    "bash"
  ],
  "allowedPaths": [
    ".factory/**",
    "input/**",
    "artifacts/**"
  ]
}

이 권한은 AI 어시스턴트가 다음을 수행할 수 있도록 합니다:

• Agent 정의와 Skill 파일 읽기
• artifacts/ 디렉토리에 결과물 쓰기
• 필요한 스크립트 및 테스트 실행

--dangerously-skip-permissions를 사용하지 마세요

AI App Factory가 생성한 권한 구성은 이미 충분히 안전합니다. Claude Code에서 --dangerously-skip-permissions를 사용하지 마세요. 이는 보안을 낮추고 권한 초과 작업을 초래할 수 있습니다.

일반적인 문제 해결

❌ Node.js 버전이 너무 낮음

오류: npm install -g agent-app-factory 설치 실패 또는 실행 시 오류 발생

원인: Node.js 버전이 16.0.0 미만

해결: Node.js를 최신 LTS 버전으로 업그레이드

# nvm 사용하여 업그레이드 (권장)
nvm install --lts
nvm use --lts

❌ Claude Code가 올바르게 설치되지 않음

오류: factory init 실행 후 "Claude CLI not found" 메시지 표시

원인: Claude Code가 PATH에 올바르게 추가되지 않음

해결: Claude Code를 다시 설치하거나 실행 파일 경로를 수동으로 환경 변수에 추가

• Windows: Claude Code 설치 디렉토리를 PATH에 추가
• macOS/Linux: /usr/local/bin/에 claude 실행 파일이 있는지 확인

❌ 디렉토리가 비어 있지 않음

오류: factory init에서 "directory is not empty" 메시지 표시

원인: 디렉토리에 이미 다른 파일이 있음 (.git, README.md 등의 구성 파일 제외)

해결: 새로운 빈 디렉토리에서 초기화하거나 기존 디렉토리 정리

# 디렉토리의 비구성 파일 삭제
rm -rf * !(.git) !(README.md)

❌ 플러그인 설치 실패

오류: factory init에서 플러그인 설치 실패 경고 표시

원인: 네트워크 문제 또는 Claude Code 플러그인 마켓이 일시적으로 사용 불가

해결: Claude Code에서 수동으로 플러그인을 설치하거나 나중에 파이프라인 실행 시 프롬프트에 따라 설치

/install superpowers
/install ui-ux-pro-max-skill

이 단원 요약

이 단원에서는 AI App Factory의 전체 설치 및 설정을 완료했습니다:

1. ✅ CLI 도구 - npm install -g agent-app-factory로 전역 설치
2. ✅ AI 어시스턴트 - Claude Code 또는 OpenCode, Claude Code 권장
3. ✅ 프로젝트 초기화 - factory init으로 .factory/ 디렉토리 생성 및 자동 구성
4. ✅ 필수 플러그인 - superpowers 및 ui-ux-pro-max-skill (자동 또는 수동 설치)
5. ✅ 권한 구성 - Claude Code 권한 파일 자동 생성

이제 실행 가능한 Factory 프로젝트가 있고, Claude Code 창이 열려 파이프라인을 실행할 준비가 되었습니다.

다음 단원 미리보기

다음 단원에서는 **Factory 프로젝트 초기화**에 대해 학습합니다.

학습할 내용:

• factory init으로 생성된 디렉토리 구조 이해
• .factory/ 디렉토리의 각 파일 용도 이해
• 프로젝트 구성 수정 방법 마스터
• 프로젝트 상태 확인 방법 학습

첫 번째 앱 생성을 시작할 준비가 되셨나요? 계속 진행하세요!

---

부록: 소스 코드 참조

소스 코드 위치 보기

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

기능	파일 경로	행 번호
CLI 진입점	cli/bin/factory.js	1-123
초기화 명령	cli/commands/init.js	1-457
Node.js 요구사항	package.json	41
Claude Code 시작	cli/commands/init.js	119-147
OpenCode 시작	cli/commands/init.js	152-215
플러그인 설치 확인	cli/commands/init.js	360-392
권한 구성 생성	cli/utils/claude-settings.js	1-275

핵심 상수:

• NODE_VERSION_MIN = "16.0.0": 최소 Node.js 버전 요구사항 (package.json:41)

핵심 함수:

• getFactoryRoot(): Factory 설치 루트 디렉토리 가져오기 (factory.js:22-52)
• init(): Factory 프로젝트 초기화 (init.js:220-456)
• launchClaudeCode(): Claude Code 시작 (init.js:119-147)
• launchOpenCode(): OpenCode 시작 (init.js:152-215)
• generateClaudeSettings(): Claude Code 권한 구성 생성