リモート指示ファイルの欠落に気づきにくい理由
OpenCodeは、AGENTS.mdファイル、およびopencode.jsonやグローバル設定で指定されたリストからカスタム指示を読み込みます。そのリストには、通常のパス、グロブ（glob）、URLを指定でき、ドキュメントには「すべての指示ファイルがAGENTS.mdファイルと結合される」と記載されています。
ここで重要なのは「結合される」という点です。起動時に1つのマージされた指示セットが構築されますが、会話の中にはどのエントリが反映されたかを示すマークは一切ありません。正常に取得できたファイルと、タイムアウトしたファイルは、見た目上まったく同じセッションを作り出します。エージェントは指示に従っているように見えますが、単にすべての指示に従っているわけではないだけです。
これをローカルエントリの挙動と比較してみましょう。リスト内のパスは、ディスク上に存在するかしないかのどちらかであり、ディスクの検索に5秒もかかることはありません。グロブはファイルにマッチするか、まったくマッチしないかのどちらかです。これらの失敗は「恒常的」です。今日間違っていれば明日も間違っているため、一度見つけて修正すれば済む種類の問題です。
一方、リモートエントリは「断続的」に失敗します。オフィスでは機能しても、電車内では機能しません。自分には機能しても、低速なプロキシの背後にいる同僚には機能しません。指示が断続的に欠落することは、この問題の最悪のパターンです。なぜなら、エージェントがルールを無視したときに人が取る行動は、ルールが届いているかを確認することではなく、ルールを再提示することだからです。これは、エージェントが指示ファイルのルールをスキップしているように見えるケースの多くに潜む罠と同じです。
同じリストには、もう1つ、より目立たない問題があります。OpenCode自身のinstructionsフィールドの例には、.mdで終わる.cursor/rulesのグロブが含まれています。Cursorのプロジェクトルールは異なる拡張子を使用するため、そのように記述されたグロブは、Cursorルールでいっぱいのフォルダ内であっても何もマッチしません。そして、何もマッチしないことはエラーにはなりません。あるツールのドキュメントから動作する例を別のツールの設定にコピーした結果、設定は埋まっているように見えても、実際にはほとんど機能していないという状態に陥るのです。
よくある代替アプローチとその限界
すべてのプロジェクトで同じURLを指定し、それを「一元管理」と呼ぶ。 確かに一元管理ではあります。しかし、社内のすべてのセッションの起動パスにネットワーク依存関係が発生することになります。
タイムアウト時間を延ばす。 そのための設定オプションはドキュメントに記載されていません。5秒という時間は、調整可能なデフォルト値ではなく、仕様として明記されています。
フォールバックとして2つ目のURLを追加する。 2つのリモートエントリを指定することは、タイムアウトの機会が2回に増えるだけであり、フェイルオーバーにはなりません。ドキュメントに記載されている挙動では、一方を試してからもう一方を試すような処理は行われません。
取得失敗時にエラーが通知されると仮定する。 リモート指示ファイルが時間内に届かなかった場合に、致命的なエラーが発生したりセッションがブロックされたりする挙動は、ドキュメントには一切記載されていません。何も通知されない（サイレントにスキップされる）前提で対策を立てる必要があります。
共有ルールをすべてのプロジェクトのAGENTS.mdに複製する。 これは信頼性の高い方法であり、まさにリモート機能が回避しようとしているアプローチです。動作はしますが、1ヶ月も経たないうちに各コピーの内容にズレが生じます。
ファイル参照構文が解決してくれると期待する。 解決しません。ドキュメントには明示的に「OpenCodeはAGENTS.md内のファイル参照を自動的に解析しません」と書かれています。指示ファイルの中にパスを記述しても、そのファイルが読み込まれることはありません。サポートされているルートはinstructionsフィールドのみです。
解決策：コミットされたローカルコピーを信頼できる唯一の情報源とし、ネットワーク経由で更新する
ゴールは、すべてのセッションのクリティカルパスにネットワーク呼び出しを挟むことなく、共有ルールの信頼できるバージョンを1つ維持することです。つまり、OpenCodeが読み込むのはリポジトリ内のコピーであり、ネットワークはそのコピーを更新するためにのみ使用します。
ステップ 1: リモートエントリをコミット済みのローカルパスに置き換える
opencode.jsonで、URLエントリをリポジトリ内のパスに変更します。たとえば、共有ガイドを保持するdocsフォルダなどを指定し、instructions配列に通常のパスとして参照させます。そして、そのファイルをコミットします。
これにより依存関係が逆転します。OpenCodeはディスク上のファイルを読み込むようになり、ファイルが存在するかしないかの二択になるため、失敗モードが断続的なものから恒常的なものへと変わります。リポジトリをクローンした全員が、社内ホストにアクセスできるかどうかに関係なく、ルールを取得できるようになります。
リストを編集する際は、含まれているすべてのグロブを確認してください。拡張子が対象のツールが実際に書き出すものと一致していることを確認し（ここでCursorルールの例が間違っている部分です）、各グロブが現在少なくとも1つのファイルにマッチしていることを確認します。何もマッチしないグロブは、正常に動作しているエントリと区別がつきません。これこそが、排除すべき挙動です。
ステップ 2: 更新を起動時のサイドエフェクトではなく、可視化されたステップにする
次に、ローカルコピーの更新方法を決定します。最適な方法は、チームがすでにレビューしているプロセスに組み込むことです。たとえば、上流のガイドが変更されたときにプルリクエストを自動作成するスケジュールジョブや、依存関係の更新ルーティンの一部にする方法があります。
重要なのは、更新が「人の目に触れる」ことです。共有ガイドが変更されたとき、誰かがこのプロジェクトの文脈で差分（diff）をレビューする必要があります。中央リポジトリで意味を持つルールが、特定のサービスでは適切でない場合があるからです。起動時の自動取得ではレビューなしで新しいテキストが適用されてしまいますが、プルリクエストであれば、新しいテキストを確認した上で適用を判断できます。
また、履歴も残ります。半年後に「このルールはいつから適用されたのか」という疑問が生じた際、リポジトリのログから答えを得ることができます。これは、その都度取得されるリモートファイルでは不可能なことです。
ステップ 3: 結合された指示セットが期待通りであることを検証する
セッションを開始し、ルールが適用されていることを確認します。エージェントにルールを持っているか直接尋ねるのではなく、そのルールが適用される小さなタスクを与えて、出力がルールに従っているかを確認します。
曖昧さがなく、コストの低いタスクを選んでください。共有ガイドで特定のエラーハンドリングの形式が求められている場合は、エラーを返す小さな関数を作成させ、その形式を確認します。コメントの規約が求められている場合は、新しいファイルを作成させ、ヘッダーを確認します。
この検証は、変更後に一度行い、その後はローカルコピーが更新されるたびに行います。ルールを実際に適用させるテストこそが唯一の信頼できる確認方法です。なぜなら、指示セットはエントリごとのレポートなしで1つのボディにマージされるからです。これは、指示の適用範囲を特定のファイルに制限することを、想定に頼らず意図的に行うべき理由と同じです。
MemoryLakeでの設定方法
共有ガイドはある1つのツールのための設定にすぎません。しかし、そのルールの背景にある「なぜこのエラー形式なのか」「なぜこの境界なのか」という「理由（Reasoning）」こそが、すべてのツールやセッションで利用可能にしたい本質的な情報です。MemoryLakeは、リモート取得の成否に依存することなく、その理由を保存しておくための場所です。
エントリは、あなた自身の言葉で作成します。リモート指示ファイル、OpenCodeの設定、またはベンダーのストレージから何かが読み取られたり、書き込まれたり、削除されたりすることはありません。
ステップ 1: APIキーを作成する
サインインし、ダッシュボードからキーを生成します。このキーを使用することで、エージェントは中間ファイルの取得やタイムアウトの心配をすることなく、エントリを直接読み込むことができます。
ステップ 2: 最初の記憶（Memories）をアップロードする
共有ガイドが規定している決定事項を、1つのエントリにつき1つ、それぞれの理由とともに追加します。「呼び出し元が種類に応じて分岐処理を行えるよう、エラーは型定義された結果を返す」という記述は、どこでも通用します。一方で「エラーハンドリングガイドに従うこと」という記述は、そのガイドへのリンクが切れた瞬間に機能しなくなる単なるポインタにすぎません。
ステップ 3: AIとエージェントを接続する
エージェントの参照先をワークスペースに設定します。これにより、チームが使用するすべてのツールでその「理由」が共有され、ツール固有の指示ファイルは必要最小限の薄い内容に保つことができます。
実践において何が変わるか
最初の変化は、ネットワークの不調が「サイレントなルールの欠落」を引き起こさなくなることです。ディスクから読み込むということは、ルールが存在するか、あるいは「明らかに存在しない」かのどちらかであることを意味します。「明らかに存在しない」状態であれば、3週間後のコードレビューではなく、最初の実行時に気づくことができます。
2つ目の変化は、共有ガイドにレビューのステップが加わることです。中央のルールリポジトリにはルールが蓄積されていきます。起動時にそれらを取得するプロジェクトは、自分に関係のないルールも含め、すべての追加ルールを自動的に取り込んでしまいます。差分（diff）として届く更新であれば、内容を読んで確認することができます。
3つ目の変化は、指示リストの監査が可能になることです。すべてのエントリがチェック可能なパスまたはグロブになり、グロブの確認には数秒しかかかりません。リストからURLが排除されれば、「指示セットに何が含まれているか」という問いに対して明確な答えを出せるようになります。これこそが、指示ファイルを維持管理する価値を生む特性であり、ファイルの順序と優先順位を明示的に特定しておくべき理由でもあります。
もちろんコストもあり、それを率直に認めることが重要です。それは「ローカルコピーが古くなる可能性がある」ということです。その都度取得されるファイルは常に最新ですが、コミットされたファイルは最後の更新時点のものです。しかし、古いルールはファイル内で確認できますが、欠落したルールは確認できないため、このトレードオフは受け入れる価値があります。ただし、これは実際に更新が行われる場合に限られます。チームが更新を実行しないのであれば、不意を突かれる代わりに、自ら「古くなること」を選択したことになります。
このトレードオフは、ツールが他から指示をプルすることを提案するあらゆる場面で発生します。それは、リクエストに応じてエージェントがルールを生成する場合であれ、設定を新しいツールのフォーマットに書き換える移行作業であれ同様です。CursorからOpenCodeにプロジェクトを移行した経験がある方なら、誰もがこのことを実感するでしょう。
信頼できる指示リストのためのベストプラクティス
起動パスはローカルに保つ。 OpenCodeが最初のターンの前に読み込む必要のあるものは、すべてディスク上に配置すべきです。ネットワーク呼び出しはセッションの起動時ではなく、更新ジョブで行うべきです。
すべてのグロブを対象ツールの実際の拡張子と照合する。 This is a two-minute check that catches the single most common silent-nothing entry. Do not trust an example, including an official one.
リポジトリごとに1つの信頼できるコピーをコミットする。 共有チェックアウトへのシンボリックリンクや、プロジェクト外のパスは避けてください。新しくクローンした人がすぐにルールを取得できるようにします。
ルールについて尋ねるのではなく、テストする。 エージェントが「指示を持っています」と報告することは証拠になりません。そのルールが適用される小さなタスクを実行させることが唯一の証拠です。
ルールの理由はルールファイルの外の永続的な場所に保管する。 ツールが変わるとルールファイルは書き換えられます。ルールが存在する理由こそが、次の担当者がそれを維持するかどうかを判断するための材料になります。
ローカルコピーに日付を記載する。 ファイルの先頭に「最終更新日」を1行メモしておくだけで、「これは最新か」という疑問が、調査を要する問題から一目でわかる情報に変わります。
肥大化に注意する。 指示リストのすべてのエントリはリクエストに結合されます。エントリが蓄積されたリストは、ターンごとに肥大化するプレフィックスとなり、これは毎回送信されるデータによって発生するトークンコストと同じ計算上の問題を引き起こします。
結論
リモート指示ファイルは現実の問題を解決しますが、同時に特有の問題も引き起こします。OpenCodeはそれらを5秒のタイムアウトで取得し、届いたものをAGENTS.mdと結合しますが、エントリごとのレポートは提供しません。そのため、届かなかった指示ファイルは、届いたものとまったく同じように見えてしまいます。
リストの参照先をコミット済みのローカルコピーに設定し、更新を起動時のサイドエフェクトではなくレビューを伴うステップにし、ルールが適用されるタスクをエージェントに与えることでルールが有効であることを証明してください。自動的な最新性の維持は失われますが、代わりに「目に見える失敗モード」を手に入れることができます。
そして、ルールの背景にある理由は、特定のツールの設定ファイルに依存しない場所に保管してください。なぜなら、それこそが次の移行後にも必要となる部分だからです。これは、エージェント間で指示を移行した結果、ファイルの移動は簡単な部分にすぎなかったと気づいたチームが達する結論と同じです。