Factory プロジェクトを初期化：ゼロから始める 3 分のセットアップ

学んだらできること

任意の空ディレクトリで Factory プロジェクトを初期化する
生成される .factory/ ディレクトリ構造を理解する
プロジェクトパラメータ（技術スタック、UI 偏好、MVP 制約）を設定する
AI アシスタントを自動起動してパイプラインを開始する

今の悩み

AI App Factory を試してみたいけど、どこから始めればいいかわからない？空っぽのフォルダを見て、何を作ればいいかわからない？あるいは既にコードがあるけど、そのまま使えるか不安？心配いりません、factory init コマンドがすべて解決します。

いつ使うか

初めて AI App Factory を使用するとき
新しい製品のアイデアを始めるとき
クリーンな Factory プロジェクト環境が必要なとき

🎒 始める前の準備

事前確認

開始する前に、以下を確認してください：

✅ インストールと設定を完了している
✅ AI アシスタント（Claude Code または OpenCode）をインストールしている
✅ 空ディレクトリ、または Git/エディタ設定のみを含むディレクトリがある

コアコンセプト

factory init コマンドの核心は自己完結：

必要なすべてのファイル（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 など
Skills 権限：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 がインストールされていない

プラグインインストール失敗

まとめ

次回の予告

付録：ソースコード参照