# 設計意図・選定理由・思想（開発者向けフォローアップ）

本章は、非開発者向け手順書において採用・不採用とした技術的判断の背景および思想の記録（ADR / 備忘録）です。



## 1. なぜ WSL なのか（完全ではない隔離という妥協点）

* 選定理由: ターゲットがWindowsユーザーであり、ホストのレジストリやシステム領域、実環境をAI（およびその実行コード）に不用意に触らせたくないため。
* セキュリティの妥協: WSL内に閉じ込めることで影響範囲を限定できるが、完全なサンドボックスではない。本来であれば「物理的にPCを分け、専用のGoogle/Gmailアカウントを別途取得して作業させる」のが理想解である。しかしコストや運用の観点からそれが叶わない場合の、現実的でちょうど良い妥協点としてWSLを採用した。
* 仮想OSの利用について: 仮想OS（VM）を利用すれば、より厳密な隔離が可能だが、リソース消費や設定の複雑さから非開発者には敷居が高い。WSLはWindowsに統合された軽量なLinux環境であり、導入が容易で、かつ一定の隔離性を確保できる点でバランスが取れている。



## 2. なぜ Ubuntu なのか

* WSLで動くディストリビューションの中で最もWeb上の技術情報・トラブルシューティング情報が豊富であるため。非開発者が自力でエラーメッセージを検索した際、解決策にたどり着く確率が最も高い。



## 3. なぜ micro なのか（vi の不採用）

* `vi` のモーダル編集（ノーマル/インサート）、保存・終了コマンド（`:wq` / `:q!`）は非開発者にとって高すぎる壁であり、説明コストが合わない。
* [`micro`](https://micro-editor.github.io/) は直感的なキーボード操作が可能であり、`sudo apt install micro` だけで素直に入る。ただし、`Ctrl + S`（保存）や `Ctrl + Q`（終了）もターミナル操作に不慣れな層は引っかかりやすいため、手順書側での明記を徹底している。



## 4. なぜ [Windows Terminal](https://github.com/microsoft/terminal) なのか（`conhost` と `readline` の競合問題）

* 当初PowerShellの生コンソールで作業させていたが、TABキーによるパス補完が効かず、タイポによるエラーで脱落するリスクが判明した。
* 技術的真相:
  これはシェル（bash）側の設定不備ではなく、Windowsのターミナルエミュレータ（GUIレイヤー）とbashの相性問題である。PowerShellやcmdの標準ウィンドウでは、裏側で `conhost.exe` が「cooked mode」の行編集（履歴・TAB補完含む）を担当しており、入力をシェルに渡す前に横取りする。一方、Ubuntuのbash側も `readline` による補完機能を持っており、この二重の行編集レイヤーが競合することで、bash本来のTAB補完が正しく機能しなくなる（[Windows Console と Windows Terminal の関係](https://learn.microsoft.com/ja-jp/windows/terminal/)）。
  Windows Terminal は後継の OpenConsole を使用しており、従来の `conhost` のように行編集を横取りしない。そのため、bashの `readline` が本来のTAB補完を安定して実行できる。
* インストール方法に `winget` コマンドを用いず Microsoft Store を案内したのは、非開発者に黒い画面でのパッケージ管理コマンドを叩かせないためである。



## 5. なぜ [herdr](https://herdr.dev) なのか（そして任意にした理由）

* サーバー起動、エディタ、opencodeなどで多数の端末ウィンドウが開かれ、画面迷子になるのを防ぐ目的で採用を検討した。
* しかし、後述の `opencode pair`（Web UI）を主軸に据える構成に倒したことで、ターミナル作業自体が激減したため、必須要件から外し「任意」へ格下げした。



## 6. なぜ Codex app や Claude Desktop（GUIアプリ）ではないのか

* 安全性の懸念: [OpenAIのCodex app](https://openai.com/ja-JP/index/introducing-the-codex-app/) や [AnthropicのClaude Desktop](https://claude.com/ja/download) などの公式デスクトップアプリは極めて強力だが、Windowsのホスト環境全体へのアクセス権を握りやすく、ユーザー自身も「Windows全体をAIに触らせるのは怖い」と感じている。
* 課金の壁: 完全な無課金ユーザーを想定している。もし毎月のサブスクリプション費用を払えるのであれば、[opencode](https://opencode.ai)ではなくこれらの有名どころ（Codex appやClaude Desktop）を使うことを素直におすすめする。無課金で、かつ安全に隔離された環境で試行錯誤させるための現実解として、スタンドアロンでWeb UI（pair）まで内包する `opencode` を選定した。



## 7. opencode のコマンド変遷とセッション管理

* OpenCode V1系ではWeb UI起動に `opencode --web` が使用されていたが、V2系において `opencode pair` サブコマンドへと移行された。ワンタイムリンク（約5分で失効）と30日有効なセッションクッキーによる接続方式を採用している（参照：[opencode 公式サイト](https://opencode.ai) / [GitHub リポジトリ](https://github.com/anomalyco/opencode)）。
* セッションのハンドリング:
  TUIから `opencode pair` を立ち上げた際、セッションが自動継続されないケースがある。開発者であれば `--continue`（`-c`）や `--session <id>`（`-s`）でセッションを明示的に引き継げるが、非開発者にセッションIDの管理を強いるのは煩雑なため、手順書では「Web側で同じ依頼を再度入力する」運用で十分と割り切った。



## 8. ネットワーク設計：mirrored、WSL Settings、バインドの仕様

* WSL Settings（`wslsettings.exe`）の採用:
  WSL 2.3.24以降で同梱された設定GUIを用いることで、非開発者が [`.wslconfig`](https://learn.microsoft.com/ja-jp/windows/wsl/wsl-config) の構文エラーを起こすリスクを排除した。WSL Settingsは `.wslconfig` をリアルタイムに直接書き換えるため、競合を防ぐ目的でエディタとの同時編集を禁止事項として案内している。
* mirrored モードの採用（Windows 11 22H2以降必須）:
  NATモード（`localhostForwarding=true`）では、Windows側から `localhost` は引けても `127.0.0.1` へのバインドで不整合が起きやすく、サーバー起動時に `0.0.0.0` バインドが要求されるなどトラブルの温床になる。`networkingMode=mirrored` を採用することで、Linux側の `127.0.0.1` バインドがそのままWindowsホストに透過される（[公式リファレンス](https://learn.microsoft.com/ja-jp/windows/wsl/wsl-config#networking-settings)）。
* セキュリティトレードオフ:
  mirroredモードの副作用として、Windows側の `localhost` サービスもWSL内から透過的に見えてしまう。「WSL内のプロセスからホスト側サービスへの不要な到達経路ができる」というセキュリティ上の抜け穴であるため、非開発者向け手順の末尾にも警告を残している。



## 9. なぜ Git や [WSLg](https://github.com/microsoft/wslg) を非開発者に説明しないのか

* Git: GitとGitHubの区別がつかない段階で教えるのは不可能。モデルが気まぐれにファイルを全削除するリスクのみを口頭で伝え、「壊れたらWSLのUbuntuごと作り直せばよい」という割り切りで進める。このチュートリアルではGitの概念や使い方を説明せず、あくまでAIがファイルを生成・管理するためのツールとして扱うに留めた。Gitの理解は今後の学習課題（宿題）として位置づけている。
* WSLg: WSLgの機能自体をわざわざ無効化したいわけではない。しかし、Linux側のGUIウィンドウがWindows側に直接飛び出してくる挙動は、「いまどこで何が動いているのか」というメンタルモデルを混乱させる。説明の手間を省き、すべて「ブラウザ（HTTP）」を境界線として完結させる方針とした。



## 10. 将来の Node / npm（npx）要求への対応方針（[mise](https://mise.jdx.dev)）

AIが発展的な作業で `npx` やNodeランタイムを要求してきた場合、安易にUbuntuの `apt` で入れるとバージョンが古すぎて動かない問題に直面する。
個人の趣味的なapt運用を避け、必要になった段階で [`mise`（旧rtx）](https://github.com/jdx/mise) を導入し、`mise activate` でシェル環境を整える方針を推奨する（[インストール手順](https://mise.jdx.dev/installing-mise.html)）。



## 11. 公式ドキュメントへの固執

非公式な技術ブログやQiita等のまとめ記事は、執筆時点での疎通確認が取れていても、ツールやWSLのバージョンアップで動かなくなっているケースが極めて多い。特に変化の激しいWSL・AI領域においては、公式のインストール手順（curl等）を愚直になぞらせることが最も確実である。



## 12. モデルの選定について

モデル名は流動的であるため固定しない。無料枠のDeepSeek、GLM、Qwenなどを用途や時期に応じて `/models` から試行錯誤させる構成とした。



## 13. 「貧者のためのAI」——回答を得るためではなく、現実に接地して試行錯誤するbotとして

社会人と学生、あるいは潤沢な企業予算を使える開発者と無課金ユーザーの間には、AIとの付き合い方に決定的な経済的・環境的断絶がある。

富裕な環境であれば、毎月トークンやサブスクリプション（[Codex app](https://openai.com/ja-JP/index/introducing-the-codex-app/)や[Claude Desktop](https://claude.com/ja/download)など）に課金し、フル権限を与えた専用PC上で高度なエージェントを回せば済むかもしれない。しかし、手元にある1台のWindows PCで、無課金でAIの恩恵を受けようとする「貧者」には別の付き合い方が求められる。

目指すべきは、「ブラウザのチャット窓に質問して、綺麗なテキストの答えを貰って終わるAI」ではない。
それは現実から遊離した単なるQ&Aマシンに過ぎず、環境を加味せずに誤った回答を自信満々に返すリスクがある。

本当に必要なのは、現実の環境（ファイルシステム、HTTP通信、ローカルのブラウザ）に足をつけて接地（グラウンディング）し、手足を動かして試行錯誤してくれるbotとしてのAIである。
多少不格好であっても、WSLという隔離された小部屋を与え、そこで実際にファイルを生成させ、サーバーを立ち上げさせ、吐き出されたレポートをブラウザから人間が眺めてフィードバックを返す。

答えを一発で当てさせるのではなく、ホスト環境を安全に守った状態で、AIが環境を加味せずに誤った回答を自信満々に返すことを防ぎ、現実のツールを動かしながら自動試行錯誤を繰り返す。この「接地した状態での試行錯誤の場」を最小のコストとリスクで非開発者に手渡すことこそが、本構成の真の目的である。