AIにコーディングを頼むとき、一番消耗する事のひとつは「複雑な分岐や状態遷移をプロンプトで伝える時間」ではないでしょうか。
「タイトルからフィールドに遷移して、NPCに話しかけると会話イベントが起動する。ただしポーズ中はすべての入力を遮断して、会話が終わった時に特定フラグが立っていたらエンディングへ……」
こうした仕様を自然言語の長文でAIに渡すと、高い確率で次のような事態に陥ります。
- ポーズから復帰した瞬間にプレイヤーの入力ロックが外れなくなる
- フラグ判定の順番が狂い、イベントが永久ループする
- エッジケース（ゲームオーバー時のリトライ先など）がきれいさっぱり忘れ去られる
修正プロンプトを投げれば投げるほどコードはツギハギのスパゲッティになり、結局自分で最初から書いたほうが早かった――そんな経験がある方も多いはずです。
この問題の本質は、AIの知能不足ではなく**「テキストという1次元の表現で、状態遷移という多次元のネットワークを伝えようとしている無理」**にあります。
今回は、自作の思考整理WebツールiOrgを使って、この「仕様伝達の摩擦」をゼロにするアプローチを紹介します。
人間は「図」で発想し、AIは「構造化データ」を好む
思考を整理するとき、私たちは頭の中で
「画面Aから画面Bへ矢印が伸びて、条件Cで分岐する」
という空間的な配置を思い描いています。
しかし、一般的なマインドマップや作図ツールは「人に見せるための清書用」に作られているため、
ツール上で描いた構造をそのままAIに渡すことができません。
エクスポートしても画像になるか、余計なスタイル記号が詰まった巨大なJSONが出力されるだけです。
そこで、私が開発している iOrg では、最初から以下の2点をコアに据えています。
- アウトライン（木構造）と2次元ダイアグラム（maxGraph）の完全双方向同期
- AIが最もトークン効率よく解釈できる「余計な記号を排したクリーンなYAML」の出力
そして先日リリースした v0.1.1 で、この思想を決定づける 「ワンクリックYAMLコピーボタン」 を実装しました。画面上でノードを繋ぎ、ボタンを1回押すだけで、クリップボードにAI専用の仕様書が格納されます。
実践：2Dアドベンチャーの「シーン＆ステート管理」を描く
実際に作成したサンプルボードがこちらです。
（見やすくするため、一部加工しています。）
左のアウトラインツリーで全体のライフサイクルを分類しつつ、中央のキャンバス上で画面遷移とループ構造を配置しています。
- メイン動線（水平フロー）:
[Boot] 初期化➔[Title] タイトル➔[Field] フィールド探索➔[Dialogue] 会話➔[Branch] 判定➔[Ending] クリア - サブループ（垂直フロー）:
[Field]の上下に[Pause]と[GameOver]を配置し、復帰・リトライの直交接続線を引く
各ノードの「ノート」欄には、感覚的な説明や曖昧な長文テキストではなく、判定式やシグナル名をそのままメモしておくのがコツです。
[Field]: メインループ。プレイヤー移動受付。NPC接触時にon_npc_interacted発行。[Branch]:GameManager.flags.is_quest_cleared == trueを評価。[Pause]:process_mode = PROCESS_MODE_WHEN_PAUSED。ツリー一時停止。
ワンクリックでコピーし、普段使いの「ChatGPT」に渡してみる
ボードが描けたら、画面上の「YAMLコピー」ボタンを押します。一瞬で構造化されたYAMLがクリップボードに入ります。
(※以下は可読性を優先し、UUIDなどの内部IDを省略した抜粋・要約イメージです。完全なデータは記事末尾のリンクに掲載しています)
Application:
name: iOrg
url: https://iorg.shin-jo.net/
version: 0.1.1
rootBoard:
name: 2Dアドベンチャー_シーン＆ステート管理
shapes:
- label: "[Field] フィールド探索"
note: "メインループ。移動・探索入力受付。NPC接触監視。"
- label: "[Dialogue] 会話・イベント"
note: "入力ロック。会話終了時にフラグ更新。"
- label: "[Branch] 進行・クリア判定"
note: "is_quest_cleared の真偽値を評価。"
lines:
- source: "[Field]"
target: "[Dialogue]"
label: "NPC接触"
- source: "[Dialogue]"
target: "[Branch]"
label: "会話終了"
- source: "[Branch]"
target: "[Ending]"
label: "クリア達成 (True)"このYAMLを添えて、AIにこうプロンプトを投げます。
プロンプト例:
「上記のYAMLで定義されたシーン遷移と状態管理仕様に基づき、Godot 4で動作するステートマシン（enum Stateとシグナルによる遷移制御）のGDScriptコードを書いてください。」
高度なエージェントAIでなくても、ChatGPT（生成AI）で一発で決まる
ここで強調しておきたいのは、Antigravityのような自律エージェント型AIをわざわざ立ち上げる必要すらないという点です。
今回のような単一スクリプトやステートマシンの生成であれば、ブラウザで開いている普段使いのChatGPT（GPT-4o等）やClaudeのような「対話型生成AI」で十分に、しかも一発で正確なコードが出力されます。
なぜMarkdown記法（箇条書き）ではなく、iOrgのYAMLなのか？
「自然言語が曖昧なら、Markdownの箇条書きやインデントで仕様書を書けばいいのでは？」と思われるかもしれません。しかし、画面遷移や状態管理のような**ネットワーク構造（グラフ）**を扱おうとすると、Markdown記法には明確な限界が現れます。
| 比較項目 | 自然言語（長文プロンプト） | Markdown記法（箇条書き・リスト） | iOrg（図解 ➔ クリーンYAML） |
|---|---|---|---|
| 表現できる構造 | 1次元（直線的なテキスト） | 木構造（上から下への階層） | グラフ構造（網目・巡回・多対多） |
| 画面遷移・ループの表現 | 前後関係が曖昧になりやすい | ポーズやリトライ等のループで破綻 | 矢印（source / target）で完全定義 |
| 属性・シグナルの紐づけ | 本文に埋もれてAIが見落とす | インデントが深くなり人間もAIも混乱 | 各ノードの note や tags に分離 |
| AIの解釈精度（コード品質） | ❌ ハルシネーション・指示漏れ多発 | △ 直線フローなら動くがループで脱線 | ⭕ 決定論的に一発で正確なコード出力 |
| 作成・修正の手間 | 書くのは楽だがデバッグで激しく消耗 | テキストでの階層修正が苦痛 | キャンバス上で直感配置＆ワンクリック |
Markdownの箇条書きは「上から下への一本道」や「単純な階層関係」を整理するには適していますが、「フィールドからポーズ画面へ行き、再開で戻り、あるいはタイトルへ遷移する」といった網目状の双方向ループをテキストのインデントだけで表現しようとすると、人間にとってもAIにとっても急激に認知負荷が高まります。
一方、iOrgが出力するYAMLでは、以下の理由によりAIの出力結果が劇的に安定します。
- シグナルと遷移の抜けがゼロになる:
接続線（lines）がsourceとtargetで厳密に定義されているため、AIが「AからBへ行くルート」を見落としません。 - フラグの更新タイミングが正確に反映される:
[Dialogue]➔[Branch]➔[Ending]の順序が固定されているため、会話が終わる前にクリア判定が走るようなバグが混入しません。 - 無駄な往復（プロンプトの修正ラリー）が消える:
前提条件と構造が1枚のYAMLに凝縮されているため、AIが推測で変な実装を付け足すことなく、意図通りの設計が一撃で手に入ります。
まとめ：道具を使い、AIへの指示出しを「構造化」する
個人開発において、自分の時間は最も貴重なリソースです。AIとの不毛なプロンプト往復で夜中までデバッグを繰り返すのは、あまりにも勿体ない。
頭の中にあるアイデアを、直感的に図として並べる。
整った構造をワンクリックでYAMLとして取り出し、AIの文脈として流し込む。
この一連のパイプラインができるだけで、AI開発のストレスは劇的に減り、本来集中すべき「面白い仕組みを作ること」に時間を使えるようになります。
今回紹介したサンプルデータは、以下のリンクからコピーしてすぐにお使いいただけます。
- 完全版サンプルデータ: [Sample]2Dアドベンチャー_シーン＆ステート管理.yaml
- ツール本体: iOrg (Webブラウザ版)
完全ローカル動作のため、会員登録もログインも不要です。ブラウザを開いてすぐに触れます。
果たしてこのファイルから、生成AIがどのようなコードを生成するのか？
ぜひ、あなたの目で確かめてください。
そして、ご自身のプロジェクトの設計にぜひ活用してみてください！！
コメント