Phantomをはじめよう

このガイドでは、Phantomのインストールから高度な使用方法まで、知っておくべきすべてを網羅します。

クイックスタート

5分でPhantomを動かしてみましょう：

# グローバルインストール
npm install -g @aku11i/phantom

# Gitリポジトリに移動
cd your-git-repo

# 最初のphantomを作成
phantom create my-feature

# phantomで作業開始
phantom shell my-feature

インストール

Homebrewインストール（推奨）

# Homebrewを使用（macOS/Linux）
brew install aku11i/tap/phantom

# インストール確認
phantom --version

代替方法：グローバルインストール

# npmを使用
npm install -g @aku11i/phantom

# pnpmを使用
pnpm add -g @aku11i/phantom

# インストール確認
phantom --version

要件

Node.js: v22.0.0以上
Git: worktreeサポート付きモダンバージョン（2.5.0+）
パッケージマネージャー: npmまたはpnpm

コアコンセプト

Git Worktreeとは？

Git worktreeは、単一のGitリポジトリに複数の作業ディレクトリを接続できる機能です。各worktreeには独自の作業ディレクトリがあり、異なるブランチをチェックアウトできます。

メインリポジトリ (.git)
├── main worktree（デフォルト）
├── feature-a worktree
├── bugfix-b worktree
└── review-c worktree

Phantomとは？

「phantom」は、Git worktreeに対するPhantomのユーザーフレンドリーな用語です。以下のような作業を行える隔離された作業ディレクトリを表します：

特定の機能やバグ修正の作業
プルリクエストのレビュー
異なるバージョンのテスト
複数の開発サーバーの実行

Phantomの保存場所

デフォルトでは、phantomは以下に保存されます：

デフォルト: .git/phantom/worktrees/<phantom-name>
カスタム: phantom.config.jsonで設定可能

基本的な使用法

Phantomの作成

# 現在のブランチからphantomを作成
phantom create my-feature

# 特定のブランチからphantomを作成
phantom create bugfix-123 origin/production

# 既存ブランチにアタッチ
phantom attach review-pr origin/feature/new-ui

Phantomでの作業

# すべてのphantomをリスト表示
phantom list

# phantom内でコマンドを実行
phantom exec my-feature npm test
phantom exec my-feature "npm install && npm run build"

# インタラクティブシェルに入る
phantom shell my-feature

# phantomの場所を取得
phantom where my-feature

# phantomを削除
phantom delete my-feature

GitHub統合

# GitHub PRやissueを直接チェックアウト
phantom github checkout 123

# 以下のような名前でphantomが作成されます：
# - pulls/123（PRの場合）
# - issues/456（issueの場合）

AI統合

# AIアシスタント用MCPサーバーを起動
phantom mcp start

# AIアシスタント（Claude Desktop、Cursor）ができること：
# - phantomの作成と管理
# - phantom内でのコマンド実行
# - 開発ワークフローとの統合

コマンドリファレンス

コマンド	説明	例
`create`	新しいphantomを作成	`phantom create <name> [branch]`
`attach`	既存ブランチにアタッチ	`phantom attach <name> <branch>`
`delete`	phantomを削除	`phantom delete <name>`
`list`	すべてのphantomをリスト	`phantom list`
`exec`	phantom内でコマンド実行	`phantom exec <name> <command>`
`shell`	phantomシェルに入る	`phantom shell <name>`
`where`	phantomのパスを取得	`phantom where <name>`
`github checkout`	PR/issueをチェックアウト	`phantom github checkout <number>`
`mcp start`	MCPサーバーを起動	`phantom mcp start`

実用例

機能開発

# 新機能用のphantomを作成
phantom create new-dashboard

# phantomに入って開発開始
phantom shell new-dashboard

# phantom内で：
git checkout -b feature/dashboard
npm install
npm run dev
# 変更、テスト、コミット...
exit

# メインリポジトリで他の作業を継続

コードレビュー

# GitHub PRを直接レビュー
phantom github checkout 42

# または手動でレビュー用phantomを作成
phantom create review-pr-42 origin/feature/new-api

# テストとコードチェック
phantom exec review-pr-42 npm test
phantom exec review-pr-42 npm run lint

# インタラクティブレビュー
phantom shell review-pr-42

並列開発

# 複数の機能を同時に作業
phantom create feature-a
phantom create feature-b
phantom create feature-c

# 並列でテスト実行
phantom exec feature-a npm test &
phantom exec feature-b npm test &
phantom exec feature-c npm test &
wait

# 複数の開発サーバーを実行
phantom exec frontend "npm run dev -- --port 3001" &
phantom exec backend "npm run dev -- --port 3002" &
phantom exec mobile "npm run dev -- --port 3003" &

ホットフィックスワークフロー

# プロダクションからphantomを作成
phantom create hotfix origin/production

# 修正とテスト
phantom exec hotfix "git checkout -b hotfix/security-patch"
phantom exec hotfix "npm test"

# phantomからデプロイ
phantom exec hotfix "npm run deploy"

# クリーンアップ
phantom delete hotfix

開発環境のセットアップ

Phantom自体への貢献

Phantom自体に貢献したい場合：

# リポジトリをフォークしてクローン
git clone https://github.com/YOUR_USERNAME/phantom.git
cd phantom

# 依存関係をインストール（pnpmが必要）
pnpm install

# ソースから実行
pnpm phantom

# テスト実行
pnpm test

# コミット前に
pnpm ready  # lint、typecheck、testを実行

プロジェクト構造

phantom/
├── packages/           # Monorepoパッケージ
│   ├── cli/           # CLIインターフェース
│   ├── core/          # コアビジネスロジック
│   ├── git/           # Git操作
│   ├── github/        # GitHub統合
│   ├── mcp/           # MCPサーバー
│   ├── process/       # プロセスユーティリティ
│   └── shared/        # 共有ユーティリティ
├── package.json       # ルート設定
├── pnpm-workspace.yaml # ワークスペース設定
└── pnpm-lock.yaml     # 依存関係ロックファイル

設定

基本設定

リポジトリルートにphantom.config.jsonを作成：

{
  "worktreesDirectory": "../phantom-worktrees",
  "postCreate": {
    "copyFiles": [".env", ".env.local"],
    "commands": ["npm install", "npm run build"]
  },
  "preDelete": {
    "commands": ["docker-compose down"]
  }
}

設定オプション

worktreesDirectory: phantomのカスタム保存場所
postCreate.copyFiles: 新しいphantomにコピーするファイル
postCreate.commands: phantom作成後に実行するコマンド
preDelete.commands: phantom削除前に実行するコマンド

ベストプラクティス

命名規則

# 良いphantom名
phantom create feature-user-auth
phantom create bugfix-memory-leak
phantom create review-pr-123
phantom create experiment-new-api

# 汎用的な名前は避ける
phantom create test     # 汎用的すぎる
phantom create temp     # 説明的でない

Phantomの衛生管理

定期的なクリーンアップ: 完了したphantomを削除
頻繁なコミット: コミットされていない作業を残さない
ブランチを使用: phantom内でフィーチャーブランチを作成
目的を文書化: 明確で説明的な命名を使用

Gitワークフローとの統合

# フィーチャーブランチワークフロー
phantom create feature-xyz
phantom shell feature-xyz
git checkout -b feature/xyz
# ... 開発、テスト、コミット
git push origin feature/xyz
exit
phantom delete feature-xyz

# レビューワークフロー
phantom github checkout 123  # PR #123をチェックアウト
phantom exec pulls/123 "npm test && npm run lint"
phantom shell pulls/123      # インタラクティブレビュー

トラブルシューティング

よくある問題

インストールの問題

# Node.jsバージョンチェック（v22+が必要）
node --version

# 必要に応じて再インストール
npm uninstall -g @aku11i/phantom
npm install -g @aku11i/phantom

# インストール確認
phantom --version

Phantom作成に失敗

Gitリポジトリにいることを確認: git status
ブランチが存在することを確認: git branch -a
worktreeサポートを確認: git worktree list

権限エラー

phantomディレクトリの書き込み権限を確認
ディスク容量を確認: df -h
設定でカスタムディレクトリを試す: "worktreesDirectory": "/path/with/permissions"

GitHub統合の問題

# GitHub CLIをインストールして認証
brew install gh  # またはプラットフォーム固有のコマンド
gh auth login

# 認証確認
gh auth status

# リポジトリアクセスをテスト
gh repo view

ヘルプの取得

ドキュメント: 詳細なガイドは他のwikiページを確認
Issue: バグはGitHub Issuesで報告
CLIヘルプ: phantom --helpまたはphantom <command> --helpを実行

次のステップ

基本を理解したら：

統合機能を探索: PRワークフローのGitHub統合をチェック
AIアシスタント: 強化された開発のためにAI統合をセットアップ
高度な設定: 設定ガイドで詳細を学習
アーキテクチャ: アーキテクチャでシステムを理解

シンプルな使用例から始めて、phantomワークフローに慣れてきたら徐々により高度な機能を取り入れていきましょう！