wf-planning-fusion-optimizer

Workfront Planning + Fusion シナリオオプティマイザー

これは何をするものですか

Workfront Planning（Maestro）コネクターを使用する Fusion シナリオのエクスポート済みブループリント（.json）を 1 つ以上受け取り、シナリオのパフォーマンスを低下させている要因（実行時間、消費オペレーション数、API 呼び出し量（レート制限 429 の原因））を優先順位付きで読み取り専用のレポートとして提示します。結果の報告のみを行い、ブループリントは変更しません。また、稼働中のワークスペースへのアクセスも不要です。

目的はレート制限への対処にとどまりません。Fusion ではモジュールの実行ごとにオペレーションが発生し、オペレーションは実行時間とクォータを消費し、ループのネストによってその数が増加します。そのため、同じ構造上の修正で、通常は速度、コスト、レート制限の余裕をまとめて改善できます。レート制限の 429 は、同じ根本的な非効率さが表れる症状の 1 つです。

対象範囲：Workfront Planning のみ

このレビューツールは、Workfront Planning コネクター（workfront-maestro モジュール）を理解します。Fusion 全般を対象とするオプティマイザーではありません。ブループリントに Planning モジュールがない場合（たとえば Salesforce から Slack へのシナリオ）、アナライザーはそれを検出し、見つかったコネクターを列挙した明確な「適用対象外」の結果を返します。対象外のシナリオに無理に適用しないでください。ユーザーには Planning 専用であることを伝え、希望する場合は、このスキルとは別に Fusion 全般に関するアドバイスを提供してください。

使用するタイミング

Workfront Planning の Fusion シナリオが対象で、速度、実行時間、タイムアウト、オペレーション／クォータ、コスト、信頼性、API 制限が懸念されている場合は、「最適化」や「429」と明言されていなくても、必ず使用してください。レプリケーション、同期、移行のシナリオでは階層をたどり、呼び出しが多岐にわたるため、特に効果がありますが、あらゆる Planning シナリオに適用できます。

実行方法

1. エクスポート済みのブループリントファイル（Fusion シナリオのブループリントエクスポート、.json）を取得します。 複数のファイルをまとめてレビューできます。

2. 次を実行します。

   python scripts/analyze_blueprint.py <blueprint.json> [<blueprint2.json> ...]
   

   測定データを確認するため、リクエストごとの呼び出しエクスポート（Resource、Method、Status Code 列と、任意の Duration 列を含む CSV）を指定する場合は、次を実行します。

   python scripts/analyze_blueprint.py <blueprint.json> --callmix <calls.csv>
   

   機械可読な結果を出力するには、--json を追加します。

3. Markdown レポートを成果物として提示し、結果に表示された順（影響が大きいものから）に指摘事項を並べます。スクリプトが出力していない数値を作り出さないでください。

指摘事項の説明方法

すべての説明の軸として、次のモデルを使います。呼び出し量とオペレーション数は、各モジュールが実行される回数にモジュール数を掛けたものであり、反復の深さがその倍率になります。 シナリオの先頭での GET は低コストですが、複数のループの奥深くで実行される GET は高コストです。各指摘事項が何を改善するのか（呼び出し数、オペレーション数、実行時間、信頼性、スループット）を明示してください。このため、レポートでは各指摘事項に「改善対象：」の項目を付けています。

早い段階で 1 点明確に伝えてください。一括読み取り用のエンドポイントはありません。 読み取りに使えるのは検索と単一 GET のみで、一括処理があるのは書き込みだけです。そのため、上限を引き上げたり書き込みを一括処理したりしても、読み取り中心のシナリオは改善されません。改善するには、読み取り回数を減らし、より広範なデータを読み取る必要があります。この理由から、読み取りに関する指摘事項（F1、F2、F3）を最初に説明してください。

指摘事項コード、その根拠、推奨される修正方法については、references/findings.md を参照してください。コードの詳細な説明が必要な場合はそちらを確認してください。各指摘事項には、レポートに 1 行の推奨事項がすでに記載されています。

任意：接続された Workfront Planning MCP で情報を補完する

静的アナライザーは基本機能であり、接続は不要です。ただし、セッションに Workfront Planning MCP が接続されている場合（Planning を利用しているお客様の大半は接続しています）、推奨事項を一般論ではなく、そのインスタンスに合わせた内容にできます。ブループリント内の不透明な ID（Rt69e105...、F6a2010...）を実際のレコードタイプ名やフィールド名に変換し、さらに重要な点として、読み取り集約に関する各指摘が実際に実現可能かどうかを、稼働中のスキーマで確認できます。具体的には、子レコードタイプが親へのフィルター可能な参照を持つこと、およびレコードごとの GET が取得するフィールドが、検索結果にルックアップとしてすでに含まれていることを確認します。これが、サンプルを貼り付けてもらわずに済ませるために必要な確認です。

python scripts/analyze_blueprint.py <blueprint.json> --ids を実行して、ブループリントが参照するレコードタイプ ID とフィールド ID を一覧表示し、Planning MCP を通じて解決します。完全なワークフローと重要な注意点（MCP が検証するのはスキーマと実現可能性であり、Fusion コネクターの出力のネスト構造ではありません）は、references/mcp-enrichment.md に記載されています。Planning MCP を利用できる場合は、これを読んでください。この手順は読み取り専用です。MCP が接続されていない場合はスキップしてください。静的レポートだけでも役立ちます。

注意すべき点

• これはエクスポートの構造に基づくヒューリスティックなレビューであり、実稼働環境での測定ではありません。その旨を伝えてください。
• 参照 ID とレコードタイプ ID はワークスペースのインスタンスごとに異なります。具体的な修正内容は、お客様の稼働中のスキーマに照らして確認する必要があります。
• 代表的な実行を変更前と変更後に測定し、本番反映前にサンドボックスで検証することを推奨してください。
• 改善率を約束しないでください。コストが発生している箇所を示し、実際の変更前後の測定で数値を出してください。
• Sleep によるスロットリング（P1）は、読み取り経路を削減してから、順を追って取り除く必要があります。そうしないと、バーストが悪化する可能性があります。単に「削除してください」と伝えるのではなく、この順序を説明してください。
• --callmix を指定した場合、比率は通常サンプリング値です。割合として扱ってください。