Codex ハーネス構築 - 設定・ルール・スキルの全体像

約5分

Codex の基本操作を理解し、個人またはチームのリポジトリで安全かつ再現可能な開発フローを設計したい方

Codex CLI・IDE 拡張・Codex app のいずれかを利用できること
Git とリポジトリの基本構造を理解していること

Codex を継続的に使うには、毎回長い指示を書くのではなく、リポジトリの規約、権限、再利用可能な手順、検証方法をファイルとして管理する必要があります。Codex ハーネスは、Codex が作業前に読む情報と、作業中に使える機能、作業後に通す検証を一つの運用体系にまとめたものです。

Codex レベルでは、この領域を Level 6: Harness Builder と定義しています。先に手を動かしたい場合は、Level 6 実践で最小構成を作ってから、このセクションで各要素を詳しく設計します。

Codex ハーネスとは

Codex ハーネスは、主に次の三層で構成します。

project-root/
├── AGENTS.md              # エントリーポイントと作業契約
├── shared/                # チーム共通のルール・スキル・ワークフロー
├── .agents/skills/        # Codex が発見するリポジトリスキル
└── .codex/                # Codex 固有の設定・ルール・フック・エージェント
    ├── config.toml
    ├── rules/
    ├── hooks.json
    └── agents/

AGENTS.md は「何を守るか」、shared/ は「詳しい手順をどこで管理するか」、.codex/ と .agents/ は「Codex がどのように機能を読み込むか」を担当します。重要な規約は Git 管理し、個人の認証情報やローカル状態はリポジトリへ含めません。

このセクションのロードマップ

順序	ページ	学ぶ内容
1	AGENTS.md 階層設計	グローバル、プロジェクト、サブディレクトリの指示連鎖
2	config.toml 設計	モデル、承認、サンドボックス、プロファイルの設定
3	Rules ファイル設計	サンドボックス外コマンドの許可・確認・禁止
4	Commands と Workflows	対話コマンド、定型プロンプト、非対話実行の使い分け
5	Skills 設計パターン	`SKILL.md` と progressive disclosure
6	Subagents 設計	専門エージェントの分担と並列実行
7	Hooks 実装	ライフサイクルイベントでの決定的な自動化
8	MCP・Plugins 統合	外部ツール、Apps、MCP サーバーとの接続
9	Memories 設計	セッションを越える補助記憶と永続ルールの分離
10	テストと検証	drift 検出、リンク検証、CI での再現性確認
11	Plugin Marketplace 公開	スキルや連携を配布可能なプラグインにまとめる方法

設計の基本原則

必須ルールはメモリに置かない: AGENTS.md または Git 管理された文書を正とします。
権限は最小化する: 読み取りだけで済む作業に書き込み権限を与えません。
説明と強制を分ける: 方針は Markdown、機械的に防げる制約は Rules・Hooks・CI に置きます。
共通資産とアダプターを分ける: 複数エージェントで共有する内容を shared/ に置き、.codex/ は Codex 固有の読み込み層として扱います。
変更後に検証する: ハーネスは設定ファイルの集合なので、同期漏れや壊れた参照を自動検出します。

このリポジトリ自体が実装例です。AGENTS.md から shared/rules/ を読み、.codex/agents/ は shared/agents/ から生成されます。まず AGENTS.md 階層設計から読み進めてください。

AGENTS.md 階層設計 - グローバル・プロジェクト・サブディレクトリ

Level 10 実践: 複数エージェントの運用基盤を設計する