game-start

AlterLab GameForge -- プロジェクト導入ワークフロー

すべてのゲームプロジェクトには始まりがありますが、その始まり方はさまざまです。意欲だけを胸に、何もないフォルダーを前にしているかもしれません。分厚いデザインドキュメントはあるものの、コードは一行も書いていないかもしれません。あるいは、誰かが6か月前に着手したコードベースに加わるところかもしれません。このワークフローは、現在の状況を把握し、すでに完了している手順に時間をかけずに作業を進められるようにします。

基本理念は、プロジェクトの現状に合わせることです。現在の状態を診断し、不足を補い、次に取るべき意味のある行動を示します。Hollow Knightはゲームジャムのスケッチから始まりました。Stardew Valleyは学習演習から始まりました。UndertaleはEarthBoundに触発されたデモから始まりました。どれも教科書にある「正しい」始め方には従っていません。しかし、それぞれに、散漫な意欲が体系的な実行へと変わる瞬間がありました。このワークフローは、その瞬間をつくります。

目的とトリガー

次の場合に、このワークフローを使用します。

• 開発者が「新しいゲームを始めたい」または「プロジェクトのセットアップを手伝ってほしい」と言ったとき
• 既存のプロジェクトに参加した人が、状況を把握する必要があるとき
• チームが現在のプロジェクト構造の健全性を確認したいとき
• 個人開発者が散在するファイルを整理し、本番開発に適した構成にしたいとき
• ゲーム開発に関して、誰かが「そもそも何から始めればいいの？」と尋ねたとき

解決できる問題：

• 新規プロジェクト開始時の分析麻痺
• 規模が大きくなるにつれて管理不能になる、整理されていないファイル構成
• 後々の混乱を招くドキュメントの不足
• 技術的負債を初日から生み出す、基礎的な意思決定の先送り
• 新しいチームメンバーが、各種ファイルの場所を把握するのに何日も費やすこと

重要なルール

1. 既存の作業を上書きしないでください。 プロジェクトにすでにファイル、構成、ドキュメントがある場合は、 それらを保持してください。再編成を提案し、明示的な確認なしに削除してはいけません。

2. 提案する前に状況を把握してください。 推奨事項を示す前に、必ずプロジェクトの状態を確認します。 プロジェクトが空だと決めつけてはいけません。既存のプロジェクトが整理されているとも決めつけてはいけません。

3. 確認が取れるまでは、エンジンを特定しないでください。 プロジェクトファイルからエンジンを検出できない場合は、尋ねてください。 推測してはいけません。エンジンを誤って想定すると、膨大な時間が無駄になります。

4. ドキュメントは必須です。 すべてのプロジェクトに最低限必要なのは、コンセプトドキュメント、技術アーキテクチャのメモ、タスク管理システムです。これらは単なる事務作業ではありません。将来の自分が切実に必要とする記憶です。ConcernedApeは、Stardew Valleyの開発期間を通じて、個人開発でありながらデザインドキュメントを更新し続けました。そのドキュメントが、4年間の作業を通じて方向性がぶれるのを防ぎました。

5. 最初の1分から、スコープを正直に見極めてください。 200時間かかるプロジェクトを説明しながら、週末が3回しかないと言う人がいたら、すぐに指摘してください。思いやりを持って、しかしすぐに伝えます。完成まで「あと少し」のまま2年間が過ぎたプロジェクトは、放棄されたインディーゲームの墓場にあふれています。

6. 共有標準を参照してください。 構造に関するすべての判断は、docs/collaboration-protocol.mdに記載された規約に沿う必要があります。デザイン用語はすべて、 docs/game-design-theory.mdに従ってください。

プロジェクトの検出（自動入力）

これらの値は、スキルの内容が Claude に届く前に、シェルの前処理によって自動的に挿入されます。これにより、状態の検出を思い込みではなく、リアルタイムのプロジェクトデータに基づいて開始できます。

• エンジン：!ls project.godot *.unity *.uproject 2>/dev/null | head -1 || echo "No engine project file detected"
• Git の状態：!git log --oneline -5 2>/dev/null || echo "No git history"
• ソースファイル数：!find . -name "*.gd" -o -name "*.cs" -o -name "*.cpp" -o -name "*.h" -o -name "*.rs" -o -name "*.js" 2>/dev/null | wc -l
• 既存のドキュメント：!ls -1 docs/ 2>/dev/null || echo "No docs directory"
• デザインディレクトリ：!ls -1 design/ 2>/dev/null || echo "No design directory"
• テストディレクトリ：!ls -1 tests/ 2>/dev/null || echo "No tests directory"
• ビルド設定：!ls Makefile CMakeLists.txt SConstruct *.sln package.json Cargo.toml 2>/dev/null | head -3 || echo "No build config detected"
• プロジェクトの経過期間：!git log --reverse --format="%ar" 2>/dev/null | head -1 || echo "Unknown — no git history"
• アクティブなコントリビューター：!git shortlog -sn --no-merges 2>/dev/null | head -5 || echo "Unknown — no git history"
• TODO/FIXME の数：!grep -r "TODO\|FIXME\|HACK\|XXX" src/ 2>/dev/null | wc -l || echo "0"

以下のステップ 0 を短縮するため、この自動入力データを使用してください。エンジンの欄に検出されたプロジェクトファイルが表示されている場合は、エンジン検出の質問を省略してください。ソースファイル数がゼロの場合は、状態 1（空のプロジェクト）です。ソースファイル数がゼロではないものの、ドキュメントディレクトリが空の場合、プロジェクトにはドキュメントの不足があると考えられます。Git 履歴の経過期間とコントリビューター数は、個人開発プロジェクトとチームプロジェクトの判別に役立ち、推奨するワークフローの複雑さに影響します。

ワークフロー

ステップ 0：プロジェクトの状態検出

推奨を行う前に、以下のシグナルを確認して現在の状態を評価してください。上記の自動入力データと照合してください。すでに回答されている項目も多くあります。

STATE DETECTION MATRIX
---------------------------------------------------------------
Signal                          | Indicates
---------------------------------------------------------------
No files / empty directory      | State 1: Empty Project
Design docs but no source code  | State 2: Concept Exists
Source code + design docs       | State 3: In-Progress
Mature codebase + CI + tests    | State 4: Existing Project
---------------------------------------------------------------

Engine Detection Signals:
- project.godot, *.gd, *.tscn        --> Godot Engine
- *.unity, *.cs, ProjectSettings/     --> Unity
- *.uproject, *.cpp + UE macros       --> Unreal Engine
- package.json + Phaser/PixiJS        --> Web-based engine
- Cargo.toml + Bevy/macroquad         --> Rust-based engine
- No recognizable engine files        --> Ask the user

検出を実行して結果を報告し、適切な状態別ハンドラーに進んでください。

---

状態 1：空のプロジェクト

白紙の状態です。多くの個人開発者や小規模チームがここから始めます。

ステップ 1.1 -- エンジンを選択します（まだ決めていない場合）：

• エンジンへの偏愛ではなく、トレードオフを率直に提示します
• 2D ピクセルアートの場合：Godot は軽量でプロトタイピングが速く、Cassette Beasts や Dome Keeper が商用品質のゲームをリリースできることを証明しています
• アセットストアが必要な 3D の場合：Unity は最も幅広いエコシステムと、最も豊富な学習リソースを備えています
• AAA 品質のビジュアルの場合：Unreal はそれを実現できますが、より高性能なハードウェアと専門知識が必要です
• Web 配信の場合：Phaser、PixiJS、または PlayCanvas
• 最適なエンジンとは、チームがすでに使い慣れているものです。プロジェクト途中でのエンジンの切り替えは、不適切なエンジン選びよりも多くのゲームを頓挫させます
• 選択後、適切なエンジン専門スキルに案内してください

ステップ 1.2 -- コンセプトを定義します（必要に応じて game-brainstorm に案内します）：

• 最低限、仮タイトル、ジャンル、プラットフォーム、コアメカニクス、ターゲット層を記録します
• ユーザーがすでにコンセプトを持っている場合は、構造化された形式で記録します
• ユーザーにコンセプトがない場合は、続行する前に game-brainstorm に案内します

ステップ 1.3 -- 初期のファイル構造を作成します：

以下は、一般的な開始時の推奨構成です。使用するエンジンに合わせて調整してください。

project-root/
  design/
    gdd/                  -- Game Design Document and sub-documents
    narrative/            -- Story outlines, dialogue scripts, lore bibles
    levels/               -- Level layouts, progression maps, zone designs
    balance/              -- Economy spreadsheets, difficulty curves, tuning tables
  docs/
    architecture/         -- Technical architecture decisions and diagrams
    api/                  -- Internal API documentation for game systems
  src/
    core/                 -- Engine initialization, main loop, global managers
    gameplay/             -- Player mechanics, enemy behaviors, interaction systems
    ai/                   -- NPC behavior trees, pathfinding, decision-making
    ui/                   -- Menus, HUD, in-game UI components
    tools/                -- Editor extensions, debug tools, dev utilities
  assets/
    art/                  -- Sprites, textures, models, animations
    audio/                -- Music tracks, sound effects, ambient loops
    vfx/                  -- Particle systems, shader effects, post-processing
    shaders/              -- Custom shader files
    data/                 -- JSON/XML config files, localization strings, data tables
  tests/
    unit/                 -- Isolated component tests
    integration/          -- System interaction tests
    playtest/             -- Playtest session logs and feedback forms
  production/
    sprints/              -- Sprint plans, retrospectives, velocity charts
    milestones/           -- Milestone definitions and completion criteria
  prototypes/             -- Throwaway prototypes (never promote to production code)

エンジン別の代替構成：

• Godot プロジェクト： 標準的な Godot のレイアウトを適用します：scripts/、scenes/、resources/、addons/。design/、docs/、production/ ディレクトリは、project.godot と並ぶプロジェクトルートに配置します。
• Unity プロジェクト： Assets/Scripts/、Assets/Prefabs/、Assets/Scenes/。design/、docs/、production/ ディレクトリは、Assets/ と並ぶプロジェクトルートに配置します。
• Unreal プロジェクト： Source/、Content/、Config/。design/、docs/、production/ ディレクトリは、プロジェクトルートに配置します。 この構成は推奨事項であり、必須ではありません。GameForge フックは、一般的な複数の場所（src/、scripts/、Scripts/、Source/、Assets/Scripts/、lib/）にあるソースコードを検出します。プロジェクトにすでに構成がある場合は、そのまま維持し、適切な場所に design/、docs/、production/ のオーバーレイを追加してください。

Step 1.4 -- スタータードキュメントを作成します：

• 最小限のゲームコンセプトドキュメントを作成します（templates/game-concept.md を参照）
• エンジン選定の理由を記載した技術アーキテクチャノートを作成します
• 直近の次のステップを記載した TODO.md を作成します
• 選択したエンジンに適した基本的な .gitignore を設定します

Step 1.5 -- 次のステップを提案します：

• コンセプトの内容が薄い場合は、game-brainstorm を実行して具体化します
• 3～5 個のデザインピラーを定義します（方法については docs/game-design-theory.md を参照）
• コアメカニクスをテストするため、最初の使い捨てプロトタイプを作成します
• 規模を見積もり、game-sprint-plan を使って最初のスプリントを計画します

---

状態 2：コンセプトあり（ドキュメントのみ、コードなし）

ユーザーはゲームについて考えていますが、まだ開発を始めていません。

Step 2.1 -- 既存のドキュメントを確認します：

• すべてのデザインドキュメントを読み、完成度を評価します
• 必須の GDD セクション 8 項目に照らして確認します（docs/game-design-theory.md を参照）
• 明確に定義されている項目と、不足がある項目を特定します

Step 2.2 -- ギャップ分析：

• 不足しているセクションを指摘します：コアループの定義、ピラーステートメント、規模の見積もり、 技術要件、アートスタイルの参考資料、オーディオの方向性、UI ワイヤーフレーム、進行システム
• 各ギャップを「重大」（開発の妨げとなる）、「重要」（後々混乱を招く）、 または「あれば望ましい」（仕上げに関する項目）に分類します

Step 2.3 -- 構造の評価：

• ドキュメントは標準的な構成に整理されていますか。それとも分散していますか？
• 分散している場合は、design/ の階層構造への再編成を提案します
• ドキュメント間に矛盾がないか確認します

Step 2.4 -- 次のアクションを提案します：

• まず重大な不足を補います（通常はコアループと技術アーキテクチャです）
• 詳細なデザインドキュメントのレビューには game-design-review を案内します
• 存在しない場合は、状態 1 の Step 1.3 に従ってファイル構造を作成します
• コーディングを始める適切なタイミングを特定します（通常は、コアループが定義され、 1 つのピラーメカニクスが十分に仕様化された後です）

---

状態 3：開発中（コードとドキュメントあり）

開発が進行中です。プロジェクトの健全性を評価し、優先事項を提案します。

Step 3.1 -- コードベースのスキャン：

• ソースファイル数を数え、プロジェクトの規模を見積もります
• 主な言語とエンジンを特定します
• テストファイルの有無を確認します（テストがまったく行われていないか）
• 設定ファイル、ビルドスクリプト、CI の設定を探します
• コードベース内の TODO、FIXME、HACK をスキャンし、件数を報告します

Step 3.2 -- ドキュメントの網羅性：

• GDD はありますか。完成度はどの程度ですか？
• 技術ドキュメントはありますか？
• 複雑なシステムにインラインコードコメントはありますか？
• 新しいコントリビューターが作業を始めるのに役立つ README はありますか？

Step 3.3 -- 構造の健全性：

• ファイル構造は論理的に整理されていますか？
• 分割が必要な巨大なゴッドファイルはありますか？
• ゲームプレイロジックとエンジン固有のコードは分離されていますか？
• アセットは整理されていますか。それともフラットなディレクトリにまとめて配置されていますか？

Step 3.4 -- 優先度に基づく提案：

• 影響度に応じて調査結果を順位付けします。次に最も問題を引き起こしそうなものは何ですか？
• 構造に問題がある場合は、具体的なリファクタリング対象を提案します
• 来月の作業時間を節約できるドキュメント作成タスクを提案します
• テストが行われていない場合は、最も重要なシステムから始めることを提案します

---

状態 4：既存プロジェクト（成熟したコードベース）

十分に確立されたプロジェクトです。目的は形だけの承認ではなく、率直な監査です。

Step 4.1 -- アーキテクチャの監査：

• 高レベルのアーキテクチャを把握します。どのようなシステムがあり、どのように通信していますか？
• 依存関係の方向を確認します。循環依存はありますか？
• 状態管理パターンを評価します。明確なステートマシンですか、それともブール値が乱立した状態ですか？
• データパイプラインを評価します。ゲームプレイの値はデータ駆動ですか、それともハードコードされていますか？ ステップ 4.2 -- ドキュメントの監査：
• ドキュメントの網羅率を 0～100％で評価します。システムのうち、何％にドキュメントがありますか？
• ドキュメントの鮮度を確認します。最新の内容ですか、それとも 6 か月前のゲームについて書かれていますか？
• ドキュメントがないシステムのうち、最も危険なものを特定します（複雑さが最も高く、ドキュメントが最も少ないもの）。

ステップ 4.3 -- 技術的な健全性の確認：

• テストカバレッジを評価します。何がテストされ、何がテストされていませんか？
• パフォーマンスを調査します。ホットパスに明らかな懸念点はありませんか？
• 依存関係を監査します。古いパッケージやセキュリティ上の問題はありませんか？
• ビルドの健全性を確認します。プロジェクトは問題なくビルドできますか？無視されている警告はありませんか？

ステップ 4.4 -- 推奨事項：

• 労力と効果に基づいて整理した、優先順位付きのアクションリストを作成します。
• リスクに焦点を当てます。本番環境のインシデントを最も引き起こしやすいものは何ですか？
• プロセスの改善（CI、テスト、コードレビューの実践）を提案します。
• 次の主要機能に着手する前に対処すべき技術的負債を特定します。

出力形式

このワークフローでは、次の構成の Project State Report を生成します。

# Project State Report
**Project:** [name]
**Date:** [date]
**Detected State:** [Empty / Concept / In-Progress / Existing]
**Engine:** [detected or user-specified]

## Current State Assessment
[Summary of what was found]

## Completed Items
- [What is already in good shape]

## Gaps & Issues
| Item | Severity | Category | Recommended Action |
|------|----------|----------|-------------------|
| ...  | Critical | Docs     | ...               |

## File Structure
[Current structure vs. recommended structure, with specific changes needed]

## Recommended Next Steps
1. [Highest priority action]
2. [Second priority]
3. [Third priority]

## Suggested Workflow Sequence
- [ ] [First workflow to run, e.g., game-brainstorm]
- [ ] [Second workflow, e.g., game-design-review]
- [ ] [Third workflow, e.g., game-sprint-plan]

品質基準

プロジェクトのオンボーディングが成功したといえるのは、以下のすべてを満たした場合です。

• 検出された状態が実情を正確に反映している（誤った前提がない）。
• すべての重大なギャップが特定され、具体的な推奨アクションが示されている。
• ファイル構成が作成済みであるか、再編成計画が提示されている。
• ユーザーが次に何をすべきかを正確に把握でき、曖昧さがない。
• エンジン固有のガイダンスが、実際に使用されているエンジンに合っている。
• 推奨されるワークフローの手順が論理的で、実行可能である。
• 次のステップにかかる時間の見積もりが、楽観的ではなく誠実である。
• レポートが一般的な定型文ではなく、このプロジェクトに即した内容である。

使用例

1. 「初めてゲームを作りたいです。」 空のプロジェクトを検出し、エンジンの希望とコンセプトについて質問します。ディレクトリ構成全体を作成し、スターター文書を用意して、game-brainstorm に案内します。

2. 「GDD はありますが、まだコーディングを始めていません。次は何をすればよいですか？」 State 2 を検出し、GDD の完全性を確認してギャップを特定します。コードを書く前に重要なセクションを埋めることを推奨し、プロトタイピングを始めるタイミングを提案します。

3. 「退職したチームメイトからこのプロジェクトを引き継ぎました。内容を理解するのを手伝ってください。」 State 4 を検出し、アーキテクチャ全体を監査してシステムをマッピングし、ドキュメントのない領域を特定して、新しい開発者向けの案内ガイドを作成します。

4. 「プロトタイプがありますが、まとまりがなくなってきました。再構成すべきでしょうか？」 State 3 を検出し、コードベースの構造上の問題を調査して、TODO と FIXME の数を集計し、テストカバレッジを評価して、具体的なリファクタリングの優先順位を提案します。

5. 「2D ローグライク用の新しい Godot プロジェクトをセットアップしてください。」 エンジンとジャンルがわかっている空のプロジェクトを検出し、Godot 固有の規約に沿ってディレクトリ構成を作成します。ローグライクに関連するセクションを含むコンセプト文書のひな形を生成し、セットアップのガイダンスを提供する Godot エンジンのスペシャリストに案内します。