ハーネスエンジニアリングを調べたメモ（OpenAI記事・Claude Code・汎用CLI）

by yasuna

6 min read

AIエージェント ハーネスエンジニアリング Claude Code Codex 個人開発

この記事はAIエージェントと一緒に執筆しています

こんにちは！yasunaです！

ハーネスエンジニアリングに興味を持ったのは、人間が随時「見張って」直す運用だけでは続かないと感じたからです。ドキュメントが古くなって入力の質が落ちたり、ルールを細かく説明しないとエージェントが安定しなかったりと、負担の正体を言語化したかったです。加えて、OpenAI の Harness Engineering（日本語）で、制約やコンテキスト、時間で荒れるものまで含めて設計する話が整理されており、自分の違和感と重なりました。Claude Code 上で「skills だけで足りるのか」「Codex でも同じ検査を回したい」という話も重なり、調べ始めました。

まず OpenAI — Harness Engineering（日本語） を読んでみた

エージェントの力を「どう制御して、どう運用に回すか」を、プロダクト開発の話として正面から切ってある感じがして、かなり刺さりました。見張り役のプロンプトを増やす話ではなく、コンテキスト・制約・時間で劣化するものまで含めて設計する、という全体像が、こちら側のモヤモヤと言語につながりました。

「馬とハーネス」の比喩も含めて、賢さを足す前にレールを敷く、というメッセージがはっきりしていて、読んだあとに「だから自分の環境ではこういう症状が出るのか」と腑に落ちました。感動に近いものでした。

いまの肌感（X に書いたことの背景）

最近、次のような気づきをつぶやいていました。どれもこの記事の三本柱と噛み合います。

  • 「AI 見張り番」的なことばかりやってないと上手く動かないのは、ハーネス設計が良くないのでは、という感覚 — 常に人間が止めて直す前提だと、スケールしませんし疲れます。見張りではなく、先に失敗させない構造が欲しいです。
  • ドキュメントも陳腐化してコンテキストが荒れてくるし、そういう整備も定期実行で回す必要がある — 「細かい AI エージェントの動き方の指導をしないといけない」と気づくほど、運用ルールが増えていきます。エントロピー管理を後回しにすると、コンテキストエンジニアリングだけでは追いつきません。
  • AI が荒れたコードを書いているかどうか、少しずつ分かるようになってきた — だからこそ、ハーネスエンジニアリングを極めたいです。見張りの勘より、再現性のある制約と検証に寄せていきたいです。

そこで私は、Claude Code 上で「ハーネスエンジニアリングって何？」「skills だけで足りる？」「Codex でも同じやり方にしたい」といった話をしながら、一次ソースと周辺記事を当たった記録でもあります。結論から言うと、skills は“手順書”で、本丸は制約・検証・観測を回すインフラ（＋必要なら CLI）、という整理になりました。

何を調べたか

  • OpenAI の Harness Engineering（英語） / 日本語 を起点に、AI エージェントを安全かつ自律的に運ぶための設計について整理しました。
  • 自動取得ツールから公式ページを読もうとしたところ、403 でブロックされ、代わりに Web 検索と、解説・再構成されている記事（例: Martin Fowler — Harness Engineering、各種ニュース・ガイド）を参照しました。公式本文の逐語引用はしていないので、詳細はブラウザで直接読むのが確実です。

ハーネスエンジニアリングのイメージ（比喩）

「エージェント＝馬」なら、ハーネス（馬具）は、力を暴走させずに目的の方向へ導くための仕組み全体、という説明がよく出てきます。ポイントは「賢さを足す」より先に、探索空間を狭めて失敗コストを下げることです。

よく挙がる三本柱

調べた範囲で、説明の軸になりやすいのは次の三つでした。

  1. コンテキストエンジニアリング
    必要な情報（アーキテクチャ、AGENTS.md / CLAUDE.md、CI の結果、直近の diff など）を、必要なタイミングで取りにいけるようにします。

  2. アーキテクチャ上の制約
    レイヤー依存、lint、pre-commit、構造テストなどで、エージェントがやってよいことの外枠を機械的に決めます。

  3. エントロピー管理
    時間とともに荒れるドキュメント・パターン違反・複雑度などを、定期的に検出して掃除する（人でもバックグラウンドジョブでもよい）ことです。

「制約があると遅くなるのでは？」に対しては、逆に 解像度が上がってトークンと手戻りが減る、という話題（例として、特定プロダクトでハーネス改善だけでスコアが大きく伸びた、といった記述）も紹介されていました。

自律 × 安全を現実に落とすときの型

  • 多層の検証ループ: 依頼 →（ループ検知など）→ 推論の前後でのチェック → CI → 人のレビュー、のように、一箇所に賭けない形です。
  • レベル分け: 個人なら CLAUDE.md ＋フック＋テスト、チームなら共有ルール＋ CI、組織なら観測・ミドルウェア・定期掃除、のように段階を踏む、という整理がしやすいです。

Claude Code だと skills だけで足りる？

skills も役に立ちますが、全部を skills に詰め込むのは非推奨、という整理がしっくりきました。

  • hooks 等で機械的に強制したいもの（lint、テスト、禁止パターン）
    → 人間の注意に頼らず 失敗させます。
  • 判断が要る検証（設計の整合、仕様との一致、アーキテクチャレビュー）
    → skills は手順と観点のパッケージとして使います。

さらに Codex のような別環境まで含めて汎用にしたい場合、会話用のスキルにロジックを埋め込むより、リポジトリ内の Python CLI（またはシェル）に「検査の実体」を置き、各エージェント側の設定には「そのコマンドを実行し、結果を解釈する」と書く形にする方が、単一の真実（single source of truth）になります。

自分用メモ：実装の方向性（調査ログより）

  • 設定の単一ソース: 例として harness.yaml のような YAML に制約・コンテキスト・ループ設定をまとめます。
  • クリーンアーキテクチャ寄り: ドメインとポート（制約チェック、エントロピー計測、観測の永続化など）を分け、SQLite にメトリクスを溜める発想です。
  • 「黄金の原則」: 技術的 lint とは別に、共有ユーティリティ優先・推測ベースのデータアクセス禁止など、設計方針を機械ルール化する、という話題（Codex チームの公開事例の説明として紹介されているもの）を、設定に golden_rules として分けて持つ、という設計案です。
  • ツールチェーン: uv で venv、pytest でテスト、Windows では /tmp が無いので 一時ディレクトリは OS に合わせる、などです。

参考リンク（調査時に辿ったもの）

まとめ

ハーネスエンジニアリングは、「AI を賢くする」というより 失敗しにくいレールと検証を先に敷く設計だと理解しました。Claude Code なら skills・hooks・プロジェクト文書がそのレールになりやすく、Codex など別のエージェントと併用するなら CLI に検査を寄せてアダプタで呼ぶと汎用性が出る、というのが今回の調査の落としどころです。

日本語の公式記事で全体像を掴んでから読むと、後半のメモ（三本柱・skills と hooks の分担など）が自分ごととして繋がりやすかったです。見張りからハーネスへを、実際のリポジトリで少しずつ試していきたいです。

なお、このあたりの整理をコードに落とし込む ハーネスエンジニアリング用のリポジトリをいま作成中です。公開できたらまた書きますので、お楽しみにしていてください。