開発環境のセットアップ

English | 日本語

このガイドでは、Phantomに貢献するための開発環境のセットアップ方法を説明します。

前提条件

必要なソフトウェア

• Node.js v22.0.0以上

  • バージョン確認: node --version
  • nodejs.orgからインストール、またはnvmなどのバージョンマネージャーを使用

• pnpm v10.8.1以上（推奨）

  • インストール: npm install -g pnpm
  • またはcorepackを使用: corepack enable pnpm

• Git（worktreeサポート付き）

  • バージョン確認: git --version
  • WorktreeサポートにはGit 2.5.0以上が必要

オプションのツール

• Visual Studio Code - TypeScriptサポート付きの推奨IDE
• GitHub CLI - PRとissue管理を簡単にするため

リポジトリのセットアップ

1. フォークとクローン

# まずGitHubでリポジトリをフォークしてから:
git clone https://github.com/YOUR_USERNAME/phantom.git
cd phantom

2. 依存関係のインストール

# pnpmを使用（推奨）
pnpm install

# またはnpmを使用
npm install

3. インストールの確認

# ソースからCLIを実行
pnpm start

# テストを実行
pnpm test

# すべての品質チェックを実行
pnpm ready

開発ワークフロー

利用可能なスクリプト

ソース: package.json#L12-L20

スクリプト	説明	コマンド
start	ソースからCLIを実行	pnpm start
build	プロジェクトをビルド	pnpm build
test	ユニットテストを実行	pnpm test
lint	コード品質をチェック	pnpm lint
fix	コードの問題を自動修正	pnpm fix
typecheck	TypeScriptの型をチェック	pnpm typecheck
ready	すべてのチェックを実行	pnpm ready

コミット前に

コードが品質基準を満たしていることを確認するため、必ず以下のコマンドを実行してください：

pnpm ready

これは以下を実行します：

1. コードフォーマットと自動修正（pnpm fix）
2. TypeScript型チェック（pnpm typecheck）
3. ユニットテスト（pnpm test）

IDEのセットアップ

Visual Studio Code

プロジェクトにはVS Code設定が含まれています。推奨拡張機能をインストールしてください：

1. TypeScript - 組み込みのTypeScriptサポート
2. Biome - リンティングとフォーマット用

TypeScript設定

ソース: tsconfig.json

プロジェクトで使用：

• TypeScript 5.8+（ネイティブプレビュー機能付き）
• ES2023ターゲット（ESモジュール）
• 厳密な型チェックが有効
• Node.jsモジュール解決

プロジェクト構造

phantom/
├── src/                    # ソースコード
│   ├── bin/               # エントリーポイント
│   ├── cli/               # CLIレイヤー
│   │   ├── handlers/      # コマンドハンドラー
│   │   └── output.ts      # 出力フォーマット
│   └── core/              # ビジネスロジック
│       ├── worktree/      # Worktree操作
│       ├── git/           # Git操作
│       └── process/       # プロセスユーティリティ
├── dist/                  # ビルド出力（git-ignored）
├── package.json           # プロジェクト設定
├── tsconfig.json         # TypeScript設定
├── biome.json           # コード品質設定
└── build.ts             # ビルドスクリプト

開発ガイドライン

コードスタイル

ソース: biome.json

• フォーマッター: 特定のルールを持つBiome
  • インデントスタイル: タブ
  • クォートスタイル: ダブルクォート
  • セミコロン: 常に使用
• リンター: いくつかのカスタマイズを加えた推奨ルール
• コードコメントなし - 自己文書化されたコードを書く

アーキテクチャの原則

ソース: CLAUDE.md#L26-L31

• 単一責任: 各モジュールには明確な目的が1つ
• 関心の分離: CLIとコアロジックは分離されている
• テスト可能性: コアモジュールはフレームワークに依存しない
• 重複なし: 共通操作は集約されている

トラブルシューティング

よくある問題

1. Node.jsバージョンエラー

   • Node.js v22+があることを確認
   • nvmを使用してNodeバージョンを管理

2. pnpmが見つからない

   • グローバルにインストール: npm install -g pnpm
   • またはcorepackを有効化: corepack enable pnpm

3. TypeScriptエラー

   • pnpm typecheckを実行して詳細なエラーを確認
   • IDEがプロジェクトのTypeScriptバージョンを使用していることを確認

4. テストの失敗

   • pnpm testを実行して失敗したテストを確認
   • Node.js v22+を使用していることを確認

次のステップ

• クイックスタートガイドを読んで基本的な使用方法を理解する
• アーキテクチャ概要を確認してシステム設計を理解する
• コアコンセプトで用語と概念を確認する

コントリビューション

1. フィーチャーブランチを作成
2. 変更を加える
3. pnpm readyを実行して品質を確保
4. プルリクエストを送信

すべてのコントリビューションは以下を満たす必要があります：

• 英語で書かれていること
• 既存のコードパターンに従うこと
• 新機能にはテストを含むこと
• すべての品質チェックに合格すること