opt-deploy

name	opt-deploy
description	最適化モデルの運用設計。自動化・監視・フォールバックを定義する
user_invocable	true

Skill: opt-deploy（運用設計）

/opt-deploy [project_path] で実行。 改善提案が承認された後、実際に現場で継続運用するための設計を行う。

いつ使うか

• /opt-report で提案が承認された後
• 「これを毎日/毎週自動で回したい」と言われた時
• PoC から本番移行する時

---

Opus 4.7 ヒント

• TaskCreate でフェーズ分割: Phase 1（運用要件）→ Phase 2（自動化）→ Phase 3（監視）→ Phase 4（フォールバック）を タスクに分けて追跡。途中で承認を取りに戻る運用がしやすい
• 本番パイプラインの骨格は Plan サブエージェント: run_*.py の構造（データ取得 → 検証 → 最適化 → 検証 → 通知）は subagent_type=Plan で先に設計→主導で実装
• 拡張思考はフォールバック設計のみ: 「ソルバー落ち / データ欠損 / infeasible」の3障害パターンに対する代替手段は、運用継続性を決める。1回深く考える価値あり
• 監視ダッシュボードのモック化は背景: 図表生成や Streamlit 等は run_in_background=true で投げ、その間に検証ルール表を作成
• Docker 化前提: 本番環境で OR-Tools が入らない事故を避けるため、Dockerfile を scripts/ に同梱する設計を最初から組む

詳細は reference/opus47_collaboration.md。

---

Phase 1: 運用要件の整理

1.1 実行頻度と計算時間の制約

どれくらいの頻度で実行するか？
  ├── リアルタイム（数秒以内） → 軽量ヒューリスティクス or 事前計算テーブル
  ├── 日次（朝までに完了） → ソルバー + 十分な計算時間
  ├── 週次 → ソルバー + 長時間探索可能
  └── 月次/都度 → 人間が確認しながら実行

計算時間の上限:
  - バッチ: 実行開始から結果が必要な時刻まで
  - リアルタイム: レスポンスタイム要件
  → ソルバーの time_limit をこの制約に合わせる

1.2 入力データの取得方法

データはどこから来るか？
  ├── 手動アップロード（Excel/CSV） → バリデーション必須
  ├── DB/API から自動取得 → 接続設定とエラーハンドリング
  └── 複数ソース → ETL パイプラインの設計

データの鮮度:
  - マスタデータ: 変更頻度が低い → キャッシュ可能
  - トランザクションデータ: 毎回最新を取得

---

Phase 2: 自動化設計

2.1 実行パイプライン

推奨構成:

  1. データ取得 → 2. バリデーション → 3. 前処理 → 4. 最適化実行
  → 5. 結果検証 → 6. 出力/通知

各ステップの設計:

  Step 1: データ取得
    - ソース接続の設定
    - タイムアウトとリトライ

  Step 2: バリデーション（★最重要）
    □ 必須カラムが存在するか
    □ データ型は正しいか
    □ 値の範囲は妥当か（外れ値検出）
    □ 前回からの変化率は異常でないか（±30%を超えたら警告）
    □ レコード数は想定範囲内か

  Step 3: 前処理
    - data_preprocessing.md の定石を適用
    - 前処理結果のログ出力

  Step 4: 最適化実行
    - ソルバーの time_limit を運用要件に合わせて設定
    - メモリ使用量の監視

  Step 5: 結果検証（★重要）
    □ Feasibility チェック（全ハード制約を満たすか）
    □ スコアが前回より大幅に悪化していないか
    □ 異常な割当がないか（1人に極端に集中など）
    → 検証NGなら人間にエスカレーション

  Step 6: 出力/通知
    - 結果ファイルの出力（CSV/Excel/API）
    - 担当者への通知（メール/Slack）
    - 実行ログの保存

2.2 スケジューリング

# cron の例（毎朝5時に実行）
# 0 5 * * * cd /path/to/project && python run_optimization.py >> log/$(date +\%Y\%m\%d).log 2>&1

# Python スクリプトの骨格
def main():
    # 1. データ取得
    data = load_data()

    # 2. バリデーション
    issues = validate_data(data)
    if issues['critical']:
        notify_error(issues)
        return

    # 3. 前処理
    processed = preprocess(data)

    # 4. 最適化実行
    solution = optimize(processed, time_limit=300)

    # 5. 結果検証
    quality = verify_solution(solution, processed)
    if not quality['feasible']:
        notify_warning("Infeasible solution", quality)
        # フォールバック: 前回の解を使用
        solution = load_previous_solution()

    # 6. 出力
    export_solution(solution)
    notify_success(quality)

---

Phase 3: 監視と異常検知

3.1 監視すべき指標

■ 入力データの監視
  - レコード数の推移（急増/急減は異常）
  - 新しいカテゴリ値の出現（未知の従業員、新しい配送先）
  - 欠損率の変化

■ 最適化結果の監視
  - Feasibility（1回でもinfeasibleなら即アラート）
  - スコアの推移（トレンドの変化を検知）
  - 計算時間の推移（問題サイズの増大を早期検知）
  - 制約違反の内訳（新しい種類の違反が出たら警告）

■ 仮定の妥当性監視
  - 移動速度の仮定 vs 実績（乖離が大きくなっていないか）
  - 作業時間の仮定 vs 実績
  - 需要パターンの変化（季節変動、トレンド変化）
  → 仮定と実績の乖離が閾値を超えたらモデル見直しのアラート

3.2 モデル劣化の検知

以下のサインが出たらモデルの見直しが必要:

  □ スコアが徐々に悪化（入力が変化しているのにモデルが追従していない）
  □ 制約違反が増加傾向（新しい制約がデータに反映されていない）
  □ 現場から「最近の結果がおかしい」というフィードバック
  □ 仮定と実績の乖離が20%を超えた

対応:
  → /opt-assess で再アセスメント
  → 仮定の更新
  → 必要なら /opt-baseline からやり直し

---

Phase 4: フォールバック設計

4.1 障害時の代替手段

ソルバーが落ちた場合:
  1. リトライ（time_limit を短縮して再実行）
  2. 簡易ヒューリスティクスにフォールバック
  3. 前回の解をベースに微修正
  4. 人間が手動で作成（最終手段）

データが取得できない場合:
  1. リトライ（一定時間待って再取得）
  2. 前回のデータ + 差分推定で実行
  3. 人間に通知して手動データ入力を依頼

結果が infeasible の場合:
  1. 制約を緩和して再実行（ソフト化）
  2. 時間制限を延長して再実行
  3. 前回の feasible 解を使用
  4. 人間にエスカレーション

4.2 ロールバック手順

「今日の結果は使わず、昨日の結果に戻す」ができるように:
  - 過去N回分の結果を保持する
  - 結果ファイルにタイムスタンプとバージョンを付与
  - ロールバックコマンドを用意

---

Phase 5: 出力

バージョンフォルダ内に以下を保存する:

• reports/deploy_design.md（実行概要、パイプライン構成、バリデーションルール、監視指標、フォールバック手順、モデル見直しトリガー）
• scripts/run_*.py（本番パイプライン）

## 運用設計書

### 実行概要
- 実行頻度: [日次/週次/月次/都度]
- 計算時間制限: [X秒/X分]
- データソース: [手動/DB/API]
- 出力先: [CSV/Excel/DB/API]

### パイプライン構成
[Step 1-6 の具体的な設定]

### バリデーションルール
| チェック項目 | 閾値 | アクション |
|------------|------|----------|
| [レコード数] | [前回比±30%] | [警告] |
| [欠損率] | [5%以上] | [エラー] |
| ... | ... | ... |

### 監視指標
| 指標 | 正常範囲 | アラート条件 | 通知先 |
|------|---------|------------|--------|
| [Feasibility] | [常に1] | [0になったら] | [担当者] |
| [スコア] | [前回比±10%] | [20%以上悪化] | [担当者] |
| ... | ... | ... | ... |

### フォールバック手順
1. [障害パターン1]: [対応手順]
2. [障害パターン2]: [対応手順]

### モデル見直しトリガー
- [ ] スコアが3回連続で悪化
- [ ] 仮定と実績の乖離 > 20%
- [ ] 現場からのフィードバック
→ /opt-assess で再アセスメントを実施

### 次のステップ
1. [パイプラインの実装]
2. [テスト環境での動作確認]
3. [本番移行（段階的ロールアウト推奨）]

---

状態管理

読み込み

• バージョンフォルダ内の .opt_state.yaml の全セクション（assess, baseline, improve, report）を読み込む
• 最適化の全履歴を参照して運用設計に反映

書き込み

• 実行完了時にバージョンフォルダ内の .opt_state.yaml の deploy セクションを書き込む
• スキーマは reference/state_schema.md を参照

---

トラブルシューティング

本番環境で OR-Tools がインストールできない

対策:
  ├── Docker コンテナ化（Dockerfile に pip install ortools を含める）
  ├── PuLP + HiGHS に切り替え（より軽量、プロキシ環境でも通りやすい）
  ├── SWO+IFS に切り替え（Python 標準ライブラリのみで動作）
  └── API 化して別サーバーで実行（本番環境にソルバー不要）

計算時間が運用要件を超える

対策:
  ├── time_limit を運用要件に合わせて短縮（解の品質は多少犠牲）
  ├── warm start（前回の解を add_hint() で渡して収束を高速化）
  ├── 問題を分解して並列実行
  └── 夜間バッチで事前計算（リアルタイム要件がある場合）

現場が最適化結果を使ってくれない

対策:
  ├── 段階的導入: まず「参考」として提示、徐々に本番化
  ├── 現場の暗黙知を制約に反映（「この結果はおかしい」→ 新制約の発見）
  ├── 手動調整の余地を残す（100%自動化ではなく、人間が微修正できる出力形式）
  └── Before/After の数値で効果を可視化して信頼を構築