設計思想
強い Web の推論能力と、実際の開発マシンをつなぐ。
役割： 概要は herdr-mcp とは何かを説明し、アーキテクチャはシステムがどう動くかを説明します。本章が答えるのはなぜこれらの設計原則を選んだのかだけです。
多くの AI コーディング製品は、もう一つの Coding Agent を作るところから始めます。herdr-mcp は別の観察から始めます。Web モデルはすでに推論が得意であり、ローカル開発環境はすでに実行が得意である。足りないのは、その間にある信頼できて観測可能な接続です。
本章は、インストール手順、コンポーネント構成、エコシステム比較を意図的に繰り返しません。今後の設計判断が守るべき原則を記録します。
Web AI とローカル coding Agent は得意分野が違う#
ローカルの coding Agent は、リポジトリ、ターミナル、実行中のプロセスを自然に見られます。Web AI のセッションは、強い推論、モデル選択、長いコンテキスト、そして別のデバイスから続けられる力を提供します。
herdr-mcp はこれらの強みを組み合わせます。
Web AI
+ ローカルのファイル / Git / Shell
+ Herdr の永続 workspace
+ ローカル Agent の dispatch
+ ブラウザの連続性
= 遠隔から観測できるコーディング作業環境
ターミナル UI や別の Agent runtime を作り直すのではありません。Web AI に欠けている手と目を与えます。
原則 1：計画は Web モデルに残す#
高レベルの目標、分解、トレードオフ、検証は Web モデルが所有します。
ローカル Agent は独立した worker として扱うほうが適しています。
- 焦点を絞った問題を調査する。
- 境界の明確な機能を実装する。
- 二度目のレビューを行う。
- 長い推論タスクを実行する。
Web の planner は、すべての git status を実行したり、すべてのファイルを読んだりするために Agent を必要としません。翻訳層が少ないほど、レイテンシが減り、判断が明確になります。
原則 2：決定的な作業は直接行う#
問いかけてください。「この操作は本当にもう一つの推論プロセスを必要とするか？」
| 作業 | 既定のツール |
|---|---|
| ファイルの読み取り / 検索 | herdr_fs_* |
| Git の事実 | herdr_git |
| 正確な変更 | herdr_fs_patch/edit/write |
| ビルド / テストコマンド | herdr_exec* |
| runtime の観測 | herdr_inspect / herdr_since |
| 独立した調査 | herdr_prompt |
これによりワークフローは、経験のあるエンジニアがツールを使う姿に近づきます。
原則 3：実行時の真実は Herdr に属する#
会話履歴は意図を記述します。Herdr は実際に動いているものを記述します。
長いタスク、再起動、引き継ぎの後で正しい行為は、live な workspace を観測することです。古いテキストが今もマシンを説明していると仮定してはいけません。
workspace、ペイン、cwd、Agent の状態、イベントが真実の情報源です。
原則 4：MCP の面は焦点を絞る#
Herdr には多数のネイティブ Socket API メソッドがあります。すべてのメソッドを MCP ツールとして公開するとコンテキストを消費し、ツール選択が難しくなります。
herdr-mcp は簡潔な公開契約を保ちます。よく使う操作には専用ツールがあり、高度なネイティブ能力は動的な discovery から到達できます。
原則 5：長いタスクは不在に耐えるべき#
連続性の価値は、無制限の自動化ではありません。何時間も画面を見続ける必要を取り除くことです。
目標を定義する
↓
Web AI が作業する
↓
必要なら長いタスクを dispatch する
↓
コンピュータを離れる
↓
Agent が完了を報告する
↓
ブラウザの連続性が会話を再開する
自動化は連続性を提供し、権限と検証は明示的なままです。
原則 6：不確実な書き込みは慎重に扱う#
分散システムでは、「成功応答がない」ことは「何も起きていない」ことを意味しません。
ネットワークタイムアウトが現れたとき、プロンプト、デプロイ、コミットはすでに起きているかもしれません。したがって mutation の扱いは、盲目的な再試行ではなく、観測、冪等性、delivery state に依拠します。
原則 7：明確な境界がセキュリティを生む#
herdr-mcp は shell アクセスがサンドボックスであるふりをしません。shell の実行を許可することは、ワークステーションのユーザー権限でコマンドを許可することを意味します。
システムは境界を明示します。
- managed Git roots
- readonly モード
- write roots
- OAuth identity
- ワークステーション identity
- ローカルの信頼された IPC
推奨ワークフロー#
Observe → Understand → Act → Verify → Delegate when useful → Re-observe
信頼できる AI 開発ワークフローは、変更の後で常に現在の事実へ戻ります。
このアプローチが価値を持つとき#
- 自分のリポジトリにアクセスできる Web ChatGPT を使いたい。
- タスクが何時間も続き、複数の Agent やターミナルを巻き込む。
- 頻繁にコンピュータを移動する。
- Agent を観測し、方向を修正したい。
- マシンを公開せずに、安定した遠隔の入口がほしい。
ターミナルの前に座ったままの小さなローカル編集なら、ローカルの coding Agent で十分かもしれません。タスクが長く、分散し、協調的になるほど、herdr-mcp の価値は高まります。