Codexのハーネスとは？AGENTS.md・Skills・サブエージェント・Hooksの4点セットを解説

なぜハーネスが必要か — AIは確率で動く

単発の依頼でうまくいっても、AI（大規模言語モデル）は確率で動くため、業務で毎日使い続けると次のような症状が必ず出てきます。

• 同じ頼み方なのに、日によって成果物の形が違う
• 会話が長くなると、序盤に伝えたルールを忘れる
• 参照してほしい資料を、参照したりしなかったりする
• 守ってほしい禁止事項を、たまにすり抜ける

そこで必要になるのが、指示・手順・役割分担・強制ルールをあらかじめ仕組みとして固定しておく枠組み＝ハーネスです。AIエージェントを馬にたとえるなら、ハーネスは馬の力を安全に引き出す「馬具」にあたります。

「AIに何をどう渡すか」という原則論はコンテキストエンジニアリングの12原則で解説しています。本記事はその設計をCodexで毎回安定して実行するための道具立て、つまり実装側の話です。

Codexの4つのハーネス — 全体像

Codexには、ハーネスにあたる仕組みが4つ用意されています。それぞれ役割と発動のタイミングが違い、どれか1つで全部をまかなうものではありません。

4つにはそれぞれ深掘り記事があります。AGENTS.mdの書き方、Skillsの作り方、サブエージェントと並列実行、Hooksの設定方法。本記事は4つをどう組み合わせ、どの順で整備するかという全体像に絞ります。

使い分けの軸は2つ — 「いつ読まれるか」と「AIの判断が入るか」

4つの仕組みは、2つの軸で整理すると迷いません。1つ目はいつ読まれるか。AGENTS.mdは毎回、Skillsは必要なときだけ読まれます。毎回読むものに手順の詳細まで書くと、AIが一度に扱える情報量を圧迫します。

2つ目の軸がAIの判断が入るかです。AGENTS.md・Skills・サブエージェントは、最終的にAIが「従う・使う」を判断する、いわばお願いの仕組み。対してHooksだけは、指定イベントで例外なく毎回走る強制の仕組みです。

この2軸から、設計の原則がそのまま導けます。方針は毎回読むAGENTS.mdへ、手順は必要時だけのSkillsへ、確実に守らせたいことだけHooksへ。それぞれの中身を順に見ていきます。

① AGENTS.md — 毎回説明し直していた前提を書き留める「憲法」

AGENTS.mdは、Codexが仕事を始めるときに毎回読み込む指示ファイルです。プロジェクトの目的、フォルダ構成、判断基準、禁止事項——毎回口頭で説明し直していた前提を書いておくと、どのセッションも同じ土台から始まります。

置き場所は階層構造になっており、グローバル（~/.codex/AGENTS.md）から作業フォルダの直下まで順に読み込まれ、手元に近いものほど強く効きます。全プロジェクト共通の好みはグローバルへ、案件ごとのルールはフォルダ側へ、が基本の分担です。

最初から立派なものを書く必要はありません。「同じ指摘を2回したら1行追記」で育てるのがコツです。書き方はCodexのAGENTS.md入門、グローバル階層とアプリの「カスタム指示」欄の関係はカスタム指示の正体をご覧ください。

② Skills — 繰り返す手順を資産にする「業務マニュアル」

Skillsは、特定タスクの手順書・テンプレートをフォルダにまとめ、必要なときだけ読み込ませる仕組みです。「週次レポート作成」「請求書チェック」のような繰り返し作業をスキル化すると、呼び出すだけで毎回同じ品質で実行されます。

AGENTS.mdとの違いは読み込みタイミングです。AGENTS.mdは毎回読む憲法、Skillsは必要時だけ読むマニュアル。この分担により、AIが一度に処理する情報量を節約しながら、手順の詳細さは保てます。

必須ファイルはSKILL.md 1枚だけで、Codex自身に「今やった手順をスキル化して」と頼めば雛形が作れます。フォルダ構成と書き方の手順はCodexのSkillsの作り方で解説しています。

③ サブエージェント — 文脈を分けて任せる「専門の同僚」

サブエージェントは、調査・レビューなどの作業をメインとは別の文脈で動く担当者に任せ、結果だけを受け取る仕組みです。大量の資料を読む作業を任せても、メインの会話には結論しか戻らないため、本体の文脈を汚しません。

運用のコツは1エージェント＝1つの役割に絞ることです。「なんでもレビューして」と1体に頼むと、どの観点も浅くなります。事実確認の担当、公開可否の担当——評価軸が増えたら体を増やすのが正解で、1体を賢くしようとしないことです。

頼み方と担当の定義方法はCodexのサブエージェントと並列実行で解説しています。定義ファイルだけTOML形式である理由と、権限の観点でレビューすべき理由はSubagentだけ.tomlである理由をどうぞ。

④ Hooks — AIの判断を挟まず必ず走る「自動処理」

Hooksは、Codexの実行ループの決まったタイミング（コマンド実行の前後、セッション開始時など）に自分のスクリプトを必ず走らせる仕組みです。前の3つと違い、AIの判断が入りません。「今回は不要」と判断されて飛ばされることがないのが決定的な違いです。

だからこそ、確実に守らせたい禁止事項や、毎回必ず残したい記録はHooksに置きます。AGENTS.mdへの記載は「お願い」であり、100%の遵守は保証されないためです。当社でも、機密ファイルへのアクセス遮断のような譲れないルールは、この層で機械的に止めています。

設定はhooks.jsonというファイルに書きますが、Codex自身に書かせれば非エンジニアでも設定できます。イベントの種類・置き場所・頼み方の実例はCodexのHooksで解説しています。

どこから整備するか — 推奨の順序

4つを最初から全部そろえる必要はありません。当社の研修では、次の順で「運用しながら育てる」ことをおすすめしています。

1. 1AGENTS.mdから始める — 毎回説明し直している前提・ルールを書き出すだけで、体感が大きく変わる
2. 2同じ作業を2回頼んだらSkills化する — 「今やった手順をスキル化して」と伝えるだけで雛形ができる
3. 3作業が複雑になったらサブエージェントで分業する — まずはレビュー役を1体切り出すところから
4. 4確実に守らせたいことが明確になったらHooksで強制する — お願いで守られなかったルールを機械化する

この順序には意味があります。「毎回言っていること」「守られなかったこと」は、運用してみて初めて見えるからです。最初から完璧なハーネスを設計しようとせず、使いながら1つずつ仕組みへ昇格させていくのが、遠回りに見えて最短です。

ハーネスを整えても、渡す材料が悪ければ精度は出ない

ハーネスは「AIの走らせ方」の仕組みです。もう1つの車輪が「AIに渡す材料（コンテキスト）」の質で、こちらが悪ければ、どれだけ仕組みを整えても精度は頭打ちになります。

材料の置き方——資料を2階建てのフォルダに整理し、索引を作って必要な箇所だけ読ませる方法はCodexのコンテキスト管理で、材料の集め方・貯め方はコンテキストの集め方で解説しています。

ハーネス＝走らせ方の仕組み、コンテキスト＝渡す材料。この2つを分けて考えると、「精度が出ない」ときに直すべきが仕組みなのか材料なのか、原因の切り分けが速くなります。

Claude Codeとの対応関係 — 考え方は共通

ハーネスの考え方はツールをまたいで共通で、Claude Codeにもほぼ1対1で対応する仕組みがあります。片方で覚えた設計は、もう片方にそのまま持ち込めます。

Claude Code側の4点セットの整理はClaude Codeのハーネスとはで解説しています。両ツールに共通する使いこなしの道筋はCodexとClaude Code共通の6ステップもあわせてどうぞ。

当社のCodex研修・導入伴走支援では、この4つのハーネスの構築を、貴社の実業務を題材にその場で行います。「自社のどのルールを、どの仕組みに置くか」まで一緒に決めるのが、ツール操作の説明で終わらせない当社の研修の軸です。