English | 日本語

このガイドでは、Phantomで使用される重要な概念と用語について説明します。

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

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

1. 並行開発: 複数のブランチで同時に作業
2. コンテキストの保持: WIPをstashやコミットする必要なし
3. 高速な切り替え: タスク間の即座のコンテキストスイッチ
4. 分離: 1つのworktreeの変更は他に影響しない
5. 共有リポジトリ: すべてのworktreeは同じGit履歴を共有

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

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

graph LR
    A[Phantomを作成] --> B[Phantomで作業]
    B --> C[変更をコミット]
    C --> D[リモートにプッシュ]
    D --> E[Phantomを削除]
    
    B --> F[コマンドを実行]
    B --> G[シェルに入る]
    
    style A fill:#9f9,stroke:#333
    style E fill:#f99,stroke:#333

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

• macOS/Linux: /tmp/phantom/<repo-name>/<phantom-name>
• カスタム: 環境変数で設定可能（将来の機能）

ソース: src/core/paths.ts#L19-L26

新しいphantom（Git worktree）を作成：

phantom create <name> [branch]

• name: phantomのユニークな識別子
• branch: phantomのベースとなるオプションのブランチ
  • 省略した場合、現在のブランチを使用
  • ローカルまたはリモートブランチ可能

phantomとその作業ディレクトリを削除：

phantom delete <name>

• worktreeのみを削除し、ブランチは削除しない
• ディスクスペースをクリーンアップ
• コミットされていない変更がある場合は削除できない

現在のリポジトリ内のすべてのphantomを表示：

phantom list

表示内容：

• Phantom名
• 関連するブランチ
• ファイルシステムパス

phantom内でコマンドを実行：

phantom exec <name> <command>

• phantomの作業ディレクトリで実行
• 現在の環境を継承
• コマンドの終了コードを返す

phantom内でインタラクティブシェルを開く：

phantom shell <name>

• phantomディレクトリに変更
• ユーザーのデフォルトシェルを開始
• 完全なインタラクティブ環境

phantomのファイルシステムパスを取得：

phantom where <name>

• 絶対パスを返す
• スクリプティングに便利
• 他のツールと一緒に使用可能

ソース: src/core/types/result.ts

Phantomは関数型エラーハンドリングパターンを使用：

type Result<T, E = Error> = 
  | { ok: true; value: T }
  | { ok: false; error: E }

利点：

• 明示的なエラーハンドリング
• 型安全なエラー伝播
• 予期しない例外なし
• 明確な成功/失敗パス

1. CLIレイヤー: ユーザーインターフェースとコマンド解析
2. コアレイヤー: ビジネスロジックと操作
3. Gitレイヤー: Gitコマンド実行
4. システムレイヤー: ファイルシステムとプロセス管理

各モジュールには単一の責任があります：

• worktree/: Phantomライフサイクル管理
• git/: Git操作ラッパー
• process/: コマンド実行
• paths/: パス解決と管理

1. 検証エラー: 無効なphantom名または引数
2. Gitエラー: Git操作の失敗
3. システムエラー: ファイルシステムまたは権限の問題
4. プロセスエラー: コマンド実行の失敗

• Phantomはステートレス - 必要に応じて再作成可能
• Git操作はアトミック
• 失敗した操作はリポジトリの状態を破損しない

説明的で一貫性のある名前を使用：

# 良い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 create foo      # 意味がない

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

# フィーチャー用のphantomを作成
phantom create feature-xyz

# phantomで作業
phantom shell feature-xyz
git checkout -b feature/xyz
# ... 変更を加える ...
git commit -m "Add feature XYZ"
git push origin feature/xyz
exit

# PRマージ後にクリーンアップ
phantom delete feature-xyz

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

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

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

# クリーンアップ
phantom delete hotfix

複数のphantomで同時にコマンドを実行：

# バックグラウンド実行
phantom exec feat-a "npm test" &
phantom exec feat-b "npm test" &
wait

# 並列ビルド
for p in $(phantom list | tail -n +2 | cut -f1); do
    phantom exec "$p" "npm run build" &
done
wait

#!/bin/bash
# すべてのphantomをテストするスクリプト

phantom list | tail -n +2 | while read name branch path; do
    echo "Testing phantom: $name"
    if phantom exec "$name" "npm test"; then
        echo "✓ $name passed"
    else
        echo "✗ $name failed"
    fi
done

各phantomは分離されています：

• 個別のnode_modules
• 独立したビルド成果物
• 分離されたGitインデックス
• 個別のブランチ状態

これにより以下が可能になります：

• 異なる依存関係バージョンのテスト
• 複数の開発サーバーの実行
• 並列CI/CDパイプライン
• 安全な実験

# 複数のNodeバージョンに対してテスト
phantom create test-node-20
phantom create test-node-22

phantom exec test-node-20 "nvm use 20 && npm test"
phantom exec test-node-22 "nvm use 22 && npm test"

# AIコーディング用の隔離環境を作成
phantom create ai-session-1
phantom create ai-session-2

# 各AIエージェントは独立して作業
# 並列セッション間での競合なし

# 複数のPRを同時にレビュー
for pr in 123 124 125; do
    phantom create "review-pr-$pr" "origin/pr/$pr"
done

# 各PRをチェック
phantom exec review-pr-123 "npm run lint"
phantom shell review-pr-124  # インタラクティブレビュー

Phantomは以下によりGit worktree管理を簡素化します：

1. 直感的なコマンドの提供
2. 複雑なGit操作の抽象化
3. 並列ワークフローの有効化
4. リポジトリの整合性の維持
5. モダンな開発プラクティスのサポート

これらのコアコンセプトを理解することで、開発生産性を向上させるためにPhantomを効果的に活用できます。