ハーネスのテストと検証 - drift 検出・CI バリデーション

約5分

Codex ハーネスの同期漏れや設定 drift をローカルと CI で検出したい開発者

AGENTS.md、config.toml、Rules、Skills、Hooks の役割を理解していること

ハーネスの drift は、期待する設定と実際に Codex が読み込む状態がずれることです。シムリンク切れ、日英ページの差、古いアダプター、広すぎる権限などは、通常の単体テストだけでは見つかりません。

検証を四層に分ける

層	検証例
構文	TOML、JSON、frontmatter が解析できる
参照	AGENTS.md、Skills、内部リンクの参照先が存在する
方針	build 承認、秘密情報禁止、i18n が守られている
動作	Codex が Skill や Hook を実際に発見できる

一つの巨大スクリプトにせず、失敗理由が分かる小さな検証を組み合わせます。

npm run harness:sync
npm run harness:check
node scripts/ensure-slugs.js
node scripts/verify-links.js

shared/ を更新した場合は、先にアダプターを同期します。harness:check は安全規約や生成物の整合性、slug とリンクのスクリプトはコンテンツ構造を確認します。

意図的に壊れた参照を作るテストも有効です。検証が失敗することを確認したら、必ず元へ戻し、正常状態でも通ることを確認します。

通常の構文・リンク検証は、秘密情報を必要としないスクリプトとして CI で実行します。Codex 自体にレビューや反復タスクを実行させる場合は openai/codex-action@v1 を利用できます。

Codex GitHub Action では、次を明示します。

CI 上の Codex は広い権限を持つ可能性があります。contents: read から始め、必要な権限だけを追加します。

ハーネス変更は、ファイルが存在するだけでは完了ではありません。同期、構文、リンク、ローカル実行、CI のうち、変更範囲に必要な検証が通り、未実行項目が明記されている状態を完了とします。

最後に Plugin Marketplace 公開で、再利用可能なハーネス資産の配布方法を扱います。

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]

クイズ