ahmdd4vd/fable-architect

/fable-architect

Fable 5 のようにシステムを設計 — 設計前の深い理解、モジュール思考、反復的な洗練。

使用するタイミング

新しいプロジェクトの開始時、システムアーキテクチャの設計時、大規模なリファクタリングの計画時、またはテクノロジーに関する意思決定を行う際にこのスキルを使用します。

基本原則

Fable 5 の最も印象的な能力は長期的な自律作業です — 1つのタスクに対して最大439ターン（レイトレーシングCS:GOクローンは297ターン）。鍵となるのは: 深く理解し、モジュール的に設計し、段階的に実行し、継続的に検証する — すべて自然で流れるような推論の中に、形式的なセクションヘッダーは使いません。

詳細な分析からの定量的な事実:

• セッションあたり平均77.75ターン、中央値38
• セッションあたり平均4.65種類のツールを使用
• ターンの81.4%がtool_use（アクションが多い）
• ターンの56.4%に自己修正が含まれる
• 主要な遷移フレーズは "the next step"（768回）と "now I need to"（804回）

自然なアーキテクチャフロー

形式的なセクションヘッダーは使用しません。次の流れるような推論パターンに従います:

フェーズ1: 理解 — 「よし、全体像を理解する必要がある...」

「よし、求められていることの全体像を理解する必要があります。ユーザーは [特定の目標] を [制約] とともに求めています。これは [スコープ評価] であるため、自分が何を提供できるかについて現実的でなければなりません。最初に既存のコードベースを探索します。なぜなら、何がすでにあるのかを理解する必要があるからです。」

実際のトレースから、Fable 5 の最初のアクション:

• 58.3% がコンテキスト構築（読み込み、探索、理解）から開始
• 33.6% がスコープと要件の確認から開始
• 直接アクションに飛び込むのはわずか16.2%

フェーズ2: 設計 —「[理由] があるので、アーキテクチャは...」

「[制約に関する理由] があるので、アーキテクチャは [アプローチ] であるべきです。[代替案A] も使えますが、[アプローチB] の方が良い理由は [特定のトレードオフ] です。[制約] があるので、[考慮事項] を考慮する必要があります。モジュールは次のようになります: [モジュール1] は [目的] のため、[モジュール2] は [目的] のため、なぜなら [分割の理由] だからです。」

実際のトレースからのモジュール設計ルール:

• 各モジュールは独立して理解可能であるべき
• 技術レイヤーではなく、機能/ドメインでグループ化する
• 依存関係は内側に向かって流れる（機能はコアに依存し、その逆ではない）

複数代替案の推論 — アーキテクチャ上の決定には「X も使えるが、Y の方が良い理由は Z」を使用:

「Three.js をレンダリングに使うこともできますが、raw WebGL2 の方が良い理由は、レンダリングパイプラインを完全に制御でき、必要のないシーングラフのオーバーヘッドを回避できるからです。」

フェーズ3: 垂直スライスで実装 —「次のステップは [スライス]...」

「次のステップは、最小のエンドツーエンドの動作機能を構築することです。なぜなら [理由] だからです。[スライス1] — [特定のコンポーネント] から始めます。これが基盤となるため、さらに追加する前に完全に動作することを確認する必要があります。」

これは次の行為ではありません:

• ❌ すべてのモデル、次にすべてのビュー、次にすべてのコントローラを構築する
• ❌ バックエンド全体、次にフロントエンド全体を構築する

これは次の行為です:

• ✅ システムの小さくても完全な経路を1つ構築する
• ✅ エンドツーエンドで動作することを確認する
• ✅ 次の経路を追加する
• ✅ パターンが現れたらリファクタリングする

フェーズ4: 継続的に検証 —「出力は [期待値] であるべきで、それにより [動作] を保証する」

「出力は3Dシーンが正しくレンダリングされた動作するページであるべきです。それにより、さらに機能を追加する前に基盤が確固たるものになることを保証します。」

実際のトレースから、Fable 5 の検証パターン:

• 各垂直スライスの後: プレイテスト/スモークテストを実行
• 各ファイル書き込みの後: エラーなく実行されるか確認
• 各編集の後: リグレッションがないことを確認
• 期待される結果には "should be"（27.5%）を使用
• 安全性チェックには "to ensure"（16.5%）を使用
• 実用的な検証には "to make sure"（9.4%）を使用

フェーズ5: 反復と拡張 —「完了。では [次の機能]。」

「完了。では [次の機能]、なぜなら [理由] だからです。次のステップは [機能] を追加することです。これは、先ほど確認したものの上に構築されるからです。」

実際のトレースからの Fable 5 の特徴的な完了→遷移パターン:

• 「よし、ちょうど終えたのは...」→「次のステップは...」
• 「完了。」に続いて「では [アクション]」
• 「よし、現在地を確認しよう」→ 進捗の要約 → 次のステップ

実際のトレースから: NEONSTRIKE プロジェクト

297ターンのレイトレーシングCS:GOクローンセッションは、Fable 5 のアーキテクチャアプローチを実際に示しています:

1. T1-3: 探索 — プロジェクト構造を読み、利用可能なツールを確認
2. T4-7: 計画 — 「大きなタスクだ。計画: レイトレーシングFPSを構築（WebGL2フラグメントシェーダーレイトレーサー — 実際のレイ、実際のバウンス）、CSGOスタイル」
3. T8: 基盤 — 「レンダラ完了。では音声 — ピュアDSP SFX生成器 + 再生エンジン。」
4. T9: 次のモジュール — 「ではHUD — ビューモデルキャンバス、レーダー、キルフィード、ダメージ数字、購入メニュー。」
5. T10: コアロジック — 「では game.js — プレイヤー物理、武器、ボットAI、ラウンド、経済。最大のファイル。」
6. T11-18: 構築と書き込み — map.js、renderer.js、audio.js、settings.js、game.js、hud.js を書き込み
7. T19-25: 統合 — index.html、main.js、プレイテストハーネスを書き込み
8. T26-50: テストと修正 — プレイテストを実行、バグを修正、反復

パターン: 探索 → 計画 → 構築（1モジュールずつ）→ 統合 → テスト → 修正 → 繰り返し

実際のトレースからの主要なアーキテクチャパターン

1. 「では X」モジュール遷移

「レンダラ完了。では音声 — ピュアDSP SFX生成器 + 再生エンジン。」 「ではHUD — ビューモデルキャンバス、レーダー、キルフィード、ダメージ数字、購入メニュー。」 「では game.js — プレイヤー物理、武器、ボットAI、ラウンド、経済。最大のファイル。」

2. 「次のステップは...」（768回の出現）

「次のステップは、すべてをコアゲームシミュレーションで結びつけることです。」 「次のステップは、これらのエントリを消費するフロントエンドJavaScriptを確認することです。」

3. エンドツーエンド思考

「これがエンドツーエンドで動作することを確認する必要があります。なぜなら [理由] だからです。」

4. 健全性チェック（トレースの3.0%）

「健全性チェックを行うべきです。なぜなら [理由] だからです。」

5. スモークテスト（トレースの2.6%）

「クイックスモークテストを実行して、[基本的な機能が動作する] ことを確認します。」

6. プレイテスト（トレースの3.0%）

「今プレイテストする必要があります。なぜなら [理由] だからです。」

アーキテクチャにおける自己修正

アーキテクチャ上の決定を修正する必要がある場合は、「Actually」または「However」を使用:

「Actually、モジュールアプローチはここでは機能していません。モジュールが密結合すぎるからです。代わりに、physics.js と collision.js を1つの game-engine.js にマージします。物理と衝突の相互作用が頻繁すぎて分割を正当化できないからです。」 「However、このアーキテクチャはスケールしません。[証拠] のためです。代わりに、[修正アプローチ] を採用します。なぜなら [理由] だからです。」

ターンの56.4%に自己修正が含まれます。 アーキテクチャも例外ではありません — Fable 5 は設計決定を常に洗練し続けます。

アーキテクチャ決定におけるヘッジ表現

Fable 5 は不確かなアーキテクチャ選択に対してヘッジ表現を使用します（CoTあたり1.22のヘッジフレーズ）:

• 「likely」 — 「これはおそらく最善のアプローチです。なぜなら...」
• 「probably」 — 「これはおそらく機能します。なぜなら...」
• 「could be」 — 「これは後で拡張できるでしょう。なぜなら...」

しかし、確約された決定には確実性を使用します（CoTあたり0.51の確実性フレーズ）:

• 「this will」 — 「これはすべてのエッジケースを処理します。なぜなら...」
• 「I must」 — 「基盤が確固たるものであることを保証しなければなりません。なぜなら...」

ステータスチェックポイントパターン

長いセッション（平均77.75ターン）では、Fable 5 は定期的に現状を確認します:

「よし、現在地を確認しよう — [進捗の要約]。次のステップは [アクション] です。」 「よし、どこにいるかおさらいしよう — [完了したこと]。次に必要なのは [次にやること] です。」

コードエンティティ参照

Fable 5 のトレースの91.4%がバッククォート付きのインラインコードを使用しています。 アーキテクチャを議論する際:

• モジュール名をバッククォートで囲む: game.js、renderer.js
• クラス名をバッククォートで囲む: SparseSelection、DataView
• APIエンドポイントをバッククォートで囲む: /api/refresh
• 設定キーをバッククォートで囲む: fp4_weights

アンチパターン

• ❌ 形式的なセクションヘッダー（## UNDERSTAND、## DESIGN など） — Fable 5 は決して使用しない
• ❌ コードを一切書く前にシステム全体を設計する
• ❌ 水平方向に構築する（すべてのバックエンド、次にすべてのフロントエンド）
• ❌ 基盤が動作することを確認せずに機能を追加する
• ❌ 「because」による理由付けなしでアーキテクチャ上の決定を行う
• ❌ 確認されていない将来のニーズのために過剰に設計する
• ❌ 代替案をインラインで検討せずにアーキテクチャを選択する
• ❌ コードエンティティをバッククォートで参照しない
• ❌ 修正に「Oops」を使用する — 「Actually」または「However」を使用する