docs(gemini): PLAN50 gemini の Vertex AI 強制をやめる設計

[takemi-ohama]

概要

containers/base/Dockerfile が .bashrc へ書き込む alias が、全コンテナで GOOGLE_GENAI_USE_VERTEXAI=true を無条件に強制しています。Vertex AI を使わないプロジェクトでも Vertex 経路へ倒れるため、これをやめる設計です。実装は含めません。

利用者からの報告（with-ai-dev で gemini の Vertex 経由が使えない → OAuth へ切り替えたい）が発端です。

関連 Issue

なし（利用者からの直接の報告。この PR で issue は閉じません）

変更点

• issues/PLAN50_gemini-vertex-alias.md を追加（要求仕様 + 設計）

調査で確定したこと

確認事項	結果
GOOGLE_GENAI_USE_VERTEXAI の設定箇所	alias 1 か所のみ（containers/base/Dockerfile:207）。どの projects/*/env にも、secrets/global.env.age のキーにも無い
Vertex に必要な GOOGLE_CLOUD_PROJECT の出所	secrets/global.env.age（値は nyle の GCP プロジェクト）
プロジェクトを空にしているもの	with-ai-dev と project-trygroup-prd の 2 件
devbase env set のスコープ指定	--project / -p のみ。指定なしが共通スコープ（-g は存在しない）

alias は「Vertex を使う」と決め打つ一方、Vertex に不可欠なプロジェクトはグローバルの機密が供給しています。プロジェクトを空にした環境では前提が崩れます。

主な設計判断

認証方式は起動定義で推論せず、環境変数で明示的に選びます。 GOOGLE_CLOUD_PROJECT は gcloud・BigQuery など GCP 全般が共有するプロジェクト指定であって、gemini の認証方式の opt-in ではありません。これを判定に使うと、OAuth を選んだ利用者が BigQuery などの目的で同じ変数を設定した瞬間、意図せず Vertex へ倒れます。起動定義は GOOGLE_GENAI_USE_VERTEXAI を一切設定せず、環境を素通しします。

alias のままにし、"$@" を落とします。 条件分岐を持たないためシェル関数にする必要はありません。alias は展開時に引数が末尾へ付くので、定義側の "$@" は不要です。現行の "$@" は alias の引数ではなくシェルの位置パラメータに展開されており、意図した働きをしていません。全 6 定義（claude / claudb / gemini / codex / kiro / agy）から落とします。

起動定義を containers/base/ai-cli-aliases.sh へ出します。 インラインの echo >> ~/.bashrc はテストできません。tmux.conf と同じく COPY する資産にすれば、tests/containers/ の既存方式（shell を直接 source する）で振る舞いを固定できます。この移動自体は振る舞いを変えないので、コミットを分けます。

共通機密を認証方式の既定の置き場にします。 GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION と同じ層に置きます。3 つは揃って初めて Vertex が成立するため、別々の層に散らすと片方だけを変えたときに壊れます。

移行が要ります

この変更だけでは、いま Vertex を使っている環境が OAuth 側へ倒れます。 起動定義が補っていた値を環境の側へ移す必要があります。

対象	何をするか
共通（Vertex を既定にする）	devbase env set GOOGLE_GENAI_USE_VERTEXAI=true
with-ai-dev / project-trygroup-prd	projects/<name>/env へ GOOGLE_GENAI_USE_VERTEXAI= を書いて共通の値を打ち消す（GOOGLE_CLOUD_PROJECT= と同じやり方）

共通機密は利用者の環境にあり、リポジトリの差分では移せません。手順として計画に書き、実施状況を完了報告に残します（AC12）。

動作確認

設計だけの PR のためコード変更はありません。設計の裏付けとして次を実行しています。

• grep -rn GOOGLE_GENAI_USE_VERTEXAI containers/ lib/ bin/ で設定箇所が alias 1 か所だけであることを確認
• secrets/global.env.age を復号してキー一覧に GOOGLE_GENAI_USE_VERTEXAI が無いこと、GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION があることを確認
• 全 projects/*/env を走査し、プロジェクトを空にしている 2 件を特定
• 稼働中の with-ai-dev コンテナで .bashrc の alias と gcloud auth list（ohama.takemi@withjp.inc）を確認
• ./bin/devbase env set --help で移行コマンドのスコープ指定を確認
• ローカルで ./bin/devbase --help が正常に動作する（コード変更なしのため未実施）
• CI が green である

補足

この修正はベースイメージの再ビルドとコンテナ再作成で初めて効きます。 稼働中のコンテナには反映されません。

レビューでは特に次を見ていただきたいです。

1. 移行を要求する設計（決定 1）。推論を残して移行を避ける案と比べ、認証方式が 1 か所で読み取れる状態と引き換えに 1 度の手順を払う判断が妥当か
2. 共通機密を置き場にする判断（決定 4）。GOOGLE_CLOUD_PROJECT と同じ層へ揃える読みでよいか
3. 受け入れ条件 AC1〜AC12 で、alias 群の移動と "$@" の除去による退行を止めるのに足りているか

[takemi-ohama]

🤖 cross-review | round 1 | gemini | APPROVE

設計内容に論理的な破綻や既存仕様との矛盾は見られません。

• 「GOOGLE_CLOUD_PROJECT が非空なら Vertex」という判定は、Vertex AI の必須要件と一致しており妥当です。
• ${VAR+x} での判定は、ユーザーによる明示的な無効化（空文字での上書きなど）を正しく尊重できるため安全な設計です。
• 提示されている AC1〜AC10 は想定される環境変数の組み合わせと既存定義の互換性を十分に網羅しています。

修正提案はありません。

[takemi-ohama]

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

認証方式の判定を GOOGLE_CLOUD_PROJECT から分離し、Vertex を明示的に opt-in する設計へ変更してください。

[takemi-ohama]

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

移行手順に実行不能なコマンドがあり、検証手順にも新しい認証方式と矛盾する記述が残っています。

[takemi-ohama]

🤖 cross-review | round 2 | gemini | REQUEST_CHANGES

移行手順に記載されている devbase env set コマンドのフラグに誤りがあるため修正を提案します。

[takemi-ohama]

🤖 cross-review | round 3 | codex | REQUEST_CHANGES

PR 本文の「主な設計判断」が、現在の計画と正反対の旧仕様（GOOGLE_CLOUD_PROJECT の有無による推論とシェル関数化）を記載したままです。実装判断とレビューを誤らせるため、本文を GOOGLE_GENAI_USE_VERTEXAI の環境設定をそのまま使うこと、alias を維持して "$@" を除くこと、既存 Vertex 利用者には移行が必要なことに更新してください。

[takemi-ohama]

🤖 cross-review | round 3 | gemini | REQUEST_CHANGES

PR 本文 (Description) と PLAN50_gemini-vertex-alias.md の内容に致命的な矛盾があります。PR 本文の「主な設計判断」では以下の旧仕様（または没案）が記載されたままになっています。

• GOOGLE_CLOUD_PROJECT の有無で推論する
• alias ではなくシェル関数にする
• ${VAR+x} で設定済みを判定する

これらはすべて PLAN50 内の「決定 1 (推論せず環境変数で明示的に選ぶ)」「決定 2 (alias のままにし、"$@" を落とす)」で明確に否定・変更されています。今後の実装や運用での判断を誤らせる原因となるため、PR 本文を現在の PLAN50 の内容に正しく更新してください。

[takemi-ohama]

🤖 cross-review | round 4 | codex | APPROVE

修正が必要な問題は見つかりませんでした。

[takemi-ohama]

🤖 cross-review | round 4 | gemini | APPROVE

内容を確認しました。設計・移行手順・テスト方針について修正の必要な点はありません。