コンテキストを失わずに Codex から OpenHands へ移行する方法 (2026)

どちらのツールも検出プロセスを正確にドキュメント化しているため、並べて読めばその違いは一目瞭然です。

Codex は、作業を開始する前にすべてを1つの順序付けられたチェーンに組み立てます：

"Codex は起動時に指示チェーンを構築します（実行ごとに1回。TUIでは通常、起動されたセッションごとに1回を意味します）。"

検出はグローバル（Codex のホームディレクトリ）から始まり、そこでは「AGENTS.override.md が存在すればそれを読み込み、存在しなければ AGENTS.md を読み込み」、「このレベルで最初の空でないファイルのみを使用」します。その後、プロジェクト内を探索します：

"プロジェクトのルート（通常は Git のルート）から開始し、Codex は現在の作業ディレクトリまで下っていきます。"

そのパスに沿った各ディレクトリで、AGENTS.override.md、次に AGENTS.md、さらに project_doc_fallback_filenames で設定されたフォールバック名をチェックし、「1つのディレクトリにつき最大1つのファイルを含め」ます。マージは連結によって行われます。「Codex はルートから順にファイルを連結し、空行で結合します。現在のディレクトリに近いファイルほど、結合されたプロンプトの後方に表示されるため、以前のガイダンスを上書きします。」

And there is a hard ceiling: Codex "stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)."

そして、厳格な上限が存在します。Codex は「結合されたサイズが project_doc_max_bytes（デフォルトは 32 KiB）で定義された制限に達すると、ファイルの追加を停止」します。

OpenHands はこれとは真逆の前提からスタートします。ルートの AGENTS.md は常にオン（常時有効）ですが、それ以外のものは関連性が発生するまで意図的に保留されます。ドキュメントでは、その仕組みが表で説明されています。リポジトリルートの AGENTS.md は「初期システムプロンプトに全コンテンツが含まれる」ことを意味し、.agents/skills/<skill-name>/SKILL.md にある Agent Skill は「名前と説明が最初に提示され、関連性がある場合にエージェントが完全なスキルを呼び出す」ことを意味します。

それに続くガイダンスは、Codex から移行するすべての人にとって最も重要な一文です：

"リポジトリ全体の短い規約には AGENTS.md を使用してください。一部のタスクでのみ必要となる特化した知識には SKILL.md を使用してください。"

そして、それに付随する警告がこちらです：

"常時有効なコンテンツは、最初から会話のコンテキストを占有します。AGENTS.md は簡潔に保ち、長い指示や専門的な指示はオンデマンドのスキルやリファレンスに移動してください。"

つまり、ルールのコンテンツはそのまま移行できますが、ルールの構造は移行できません。Codex では、ディレクトリをネストさせることが条件分岐の仕組みそのものでした。専門的な作業の近くにファイルを配置することで、連結されたプロンプトの後方に配置されるようになっていました。しかし OpenHands では、ネストは仕組みではありません。その仕組みは、スキルの説明、宣言されたトリガー、または宣言されたパスパターンです。

Codex のチェーンを1つの OpenHands の AGENTS.md にフラット化することは、近道ではありません。それは、移行先のドキュメントが「やってはいけない」と明記しているまさにその行為です。

ステップ 1: 各部分が実際に適用される頻度でチェーンを分割する

Codex の指示チェーンをルートから順にたどり、すべてのブロックを次の3つのグループのいずれかに分類します。

常に、どこでも当てはまるもの。 テストコマンド、パッケージマネージャー、「自動生成されたファイルは絶対に編集しない」というルール、リポジトリ全体で適用される命名規則など。これが新しいルートの AGENTS.md になり、短く抑える必要があります。現在のルート AGENTS.md が 32 KiB の上限に向けて肥大化してしまっている場合、このタイミングで、そのうちのどれだけが本当に普遍的なルールだったのかを見極めましょう。

特定の領域でのみ当てはまるもの。 決済サービス、フロントエンド、またはマイグレーションフォルダに適用されるために、ネストされた AGENTS.md に配置されていたすべてのもの。これらは paths 宣言を持つスキルになります。OpenHands はこれを、単なる推奨ではなく決定論的なルールとしてドキュメント化しています。paths は「ファイルをパス起動ルールに変換します。このルールはモデルには提示されず、一致するファイルが読み取り、編集、または作成されたときに、会話ごとに1回注入されます。」

このグループこそ、移行によってメリットが得られる部分です。Codex では、ネストされたファイルは「そのディレクトリ内またはその配下でセッションを開始したから」適用されていました。つまり、スコープの設定は「自分がどこに立っているか」の副作用に過ぎませんでした。一方、paths パターンは、セッションがどこで開始されたかに関係なく、エージェントが実際に一致するファイルに触れたときに適用されます。これは、表現したかったことをより正確に実現する方法です。

特定のタスクでのみ当てはまるもの。 リリースチェックリスト、インシデントのランブック、データパイプラインの接続方法に関する長い説明など。これらは、名前と説明を持つ通常のスキルになります。これらは呼び出されるまでコストがほとんどかからないため、必要なだけ長くすることができます。これは、連結チェーンとバイト制限という制約の下で作業していたときとは正反対です。スキルに移行する際に留意すべき注意点が1つあります。agent skills are not memory（エージェントのスキルはメモリではない）ということです。スキルはエージェントが呼び出せる手順であり、チームが決定した事項の記録ではありません。

言及しておく価値のある4つ目のグループがあります。それは、ファイルではなく特定のフレーズによってトリガーされるガイダンスです。OpenHands もこれをサポートしています。triggers は「ユーザーメッセージにキーワードやコマンドが現れたときにスキルを注入」し、そのスキルはモデルによる呼び出しにも引き続き利用可能です。ファイルが両方を宣言している場合、ドキュメントには「paths が優先される」と明記されています。

ステップ 2: 逆方向を向いているファイル名の前提を修正する

2つの詳細な仕様が落とし穴になりますが、それらは正反対の方向を指しています。

Codex では、標準外の指示ファイル名を登録する必要があります。ドキュメントには、project_doc_fallback_filenames リストにないファイル名は「指示の検出において無視される」と記載されています。もしリポジトリに Codex が読み込む CLAUDE.md が存在していたなら、それは誰かがそのリストに追加したからです。

OpenHands はデフォルトでその逆を行います。「OpenHands は CLAUDE.md や GEMINI.md もモデル固有のリポジトリコンテキストとして認識します。」登録は不要です。つまり、これまで無視していた（あるいは Codex のフォールバックリストから意図的に除外していた）CLAUDE.md が、移行した瞬間から有効になってしまいます。最初の実行前に確認しておきましょう。

もう1つの詳細は AGENTS.override.md です。Codex はこれを2つの場所で使用します。グローバル（AGENTS.md に完全に優先する）と、ディレクトリごと（最初にチェックされる）です。これは一時的なローカルの挙動を定義するのに便利なエスケープハッチです。OpenHands のスキルに関するドキュメントには、このようなオーバーライド用のファイル名についての記載がないため、ツリー内にある AGENTS.override.md は、移行先では読み込まれないファイルになります。そのコンテンツをルートの AGENTS.md に含めるべきか、スコープ付きのスキルにするべきか、あるいは不要にするべきかをファイルごとに判断してください。

レガシーファイルに関するもう1つの注意点として、OpenHands のドキュメントには「トリガーのないレガシーな .md スキルは常に完全にロードされる」とあり、意図を明確にするためにその場合は AGENTS.md を優先することを推奨しています。バラバラの Markdown ファイル群を移植する場合は、この一文を念頭に置いて計画を立ててください。トリガーのない素の .md スキルは常時有効なコンテンツのように動作するため、移行しようとしていた元の状態に逆戻りしてしまいます。指示ファイルがもともと CLAUDE.md として作成されたものである場合は、converting a CLAUDE.md into an AGENTS.md で、名前とコンテンツの違いについて詳しく解説しています。

上記の内容はすべて再構築の作業であり、基盤となるロードモデルが変更されるたびに、同じような作業を繰り返すことになります。Codex はバイト数制限のある連結を使用し、OpenHands は段階的な開示を使用します。次のツールはまた別の方法を使用するでしょう。

これらすべてを乗り越えて生き残るのは、「なぜその規約が存在するのか」「何を却下したのか」「そもそもなぜそのルールが追加されるに至ったのか」という「理由（推論）」です。これは指示ファイルにはうまく収まりません。なぜなら、指示ファイルはコマンドのリストであり、どちらのプラットフォームでも短く保つべきだからです。

MemoryLake は、このレイヤーを両方のランタイムの外部に保持し、MCP または API を介して、要求してきたエージェントに提供します。Codex は独自のローカルメモリを保持し、OpenHands はスキルカタログをそのまま維持できます。

ステップ 1: API キーを作成する

ファイルを分割し始める前に、キーを生成して約30秒で最初のリクエストを実行しましょう。

ステップ 2: 最初のメモリをアップロードする

ステップ1で各ブロックを分類しながら、「なぜこれがここにあるのか」を問い続けてください。その答え（決定事項、却下した代替案、その背後にある制約）を書き留めていきます。ドキュメントやその他のファイルも同じ場所に保存します。

ステップ 3: AI とエージェントを接続する

Claude、Codex、OpenClaw、OpenHands に MCP または API 経由でアクセス権を付与します。意思決定レイヤーに問い合わせができるエージェントは、常時有効なファイルに根拠をインラインで記述する必要がなくなります。これにより、両ベンダーが推奨するように、ルートの AGENTS.md を極限まで短く保つことができます。

最初の変化は、32 KiB に関する議論が終わることです。Codex の上限に達したチームには、ドキュメントに記載されている2つの選択肢（制限を引き上げるか、ネストされたディレクトリに分割するか）があり、どちらも予算を管理する方法でした。OpenHands 側では、予算の問題が変化します。ルートファイルを短くすべきなのは、バイト数の上限があるからではなく、常時有効なコンテンツが最初のメッセージからコンテキストを圧迫するからです。オンデマンドで照会される意思決定レイヤーを導入することで、理由を失うことなくファイルを短く保つことができます。

2つ目の変化は、スコープ設定がよりシャープになることです。paths パターンは、「このファイルは決済ディレクトリにある」というよりも強力な宣言であり、セッションが開始された場所ではなく、エージェントが実際に触れたファイルに対して実行されます。

3つ目の変化は、移行の重複期間中に現れます。ほとんどのチームは数週間、両方を並行して実行します。2つのロードモデルを持つ2つの指示ツリーは、一方のエージェントが他方のエージェントなら行わないような行動をとるまで、誰も気づかない形で乖離していきます。共有された1つの意思決定レイヤーがあれば、ファイルのレイアウトが異なっていても、その理由は同一に保たれます。

コピーする前にルートファイルのサイズを測定する。 Codex チェーンがバイト数の上限に達していた場合、そのうちのどれだけが本当に普遍的なルールだったのかを自問してみてください。ほとんどの場合、答えは「思っているよりも少ない」です。

ディレクトリのネストを宣言されたパターンに変換する。 OpenHands で Codex のディレクトリレイアウトをそのまま再現して、同じ挙動を期待しないでください。ネストは一方のスコープ設定メカニズムであり、paths 宣言は他方のスコープ設定メカニズムです。

最初の実行前に CLAUDE.md と GEMINI.md を監査する。 これらは登録が必要な状態から、自動的に認識されるようになります。これは通常歓迎すべきことですが、時に予期せぬ挙動を引き起こすことがあります。

すべてのスキルに、それがいつ適用されるかを示す説明を付ける。 検出プロセスでは、名前と説明のみが提示されます。スキルが何をするかだけを説明し、いつ使うべきかを説明していない場合、適切なタイミングで呼び出されません。

常時有効なファイルに理由（推論）を記述しない。 両ベンダーとも、ファイルを簡潔に保つよう指示しています。根拠は、すべてのメッセージでロードされるブロックではなく、エージェントが照会するストアに配置すべきです。

長いセッションでは要約が行われることを想定する。 OpenHands は、履歴が設定されたサイズを超えると、最近のメッセージをそのまま維持しつつ、古いコンテンツを要約するコンテキストコンデンサー（context condenser）を搭載しています。これは長い会話を管理するための合理的な方法ですが、会話を記録の保存場所として扱ってはいけない良い理由でもあります。

Codex と OpenHands は同じ名前のファイルを読み込みますが、その扱い方はほぼ真逆です。Codex は、プロジェクトのルートから作業ディレクトリまで、1ディレクトリにつき1つのファイルをバイト数の上限に達するまで順序正しく連結します。OpenHands はルートファイルを完全にロードし、それ以外のすべては説明、キーワードトリガー、またはパスパターンの背後に保持します。

この違いこそが移行の本質です。コンテンツはそのまま移植できますが、構造は「短い常時有効なファイル」と「無制限のオンデマンドの詳細」を活かすロードモデルに合わせて再構築する必要があります。その過程で、正反対の方向を指す2つのファイル名に関する驚きと、ドキュメント化された同等機能のない1つのエスケープハッチ（AGENTS.override.md）に直面することになります。

各部分が適用される頻度でチェーンを分割し、ネストを宣言されたパターンに変換し、どちらのランタイムにも依存しない場所に理由を保持しましょう。そうすれば、次のロードモデルが登場したときには、考古学のプロジェクトではなく、単なる再構築の作業で済むようになります。