AIの「できました」を信じない。Codexで試したハーネスエンジニアリング

こんにちは。

AIに何かを作らせるとき、裏でAIが何をしているか、気にしたことはないでしょうか。私が気になっていたことは2つあります。

・AIの「できました」という報告が、何を根拠にしているのか。本当にできているのか、わからない
・作ってくれるのはいいけれど、どういう基準でものづくりを進めているのかが、いまいちピンとこない

そこで、Codexで個人のAI開発を進めるための開発キットを作りました。このキットでは、AIそのものではなく「AIの周り」に仕組みを足して、この2つに対処しました。

・基準：AIが守ることと進め方を、指示書・要件書・スキルに書いて先に渡す
・根拠：AIがやったことを証跡と記録に残し、報告をそこで確かめる

この記事では、「ハーネスエンジニアリング」の考え方と、キットの4つの工夫、作ってみてわかった注意点を紹介します。

■ ハーネスエンジニアリングとは

「ハーネスエンジニアリング」は、OpenAIが2026年2月のブログ記事のタイトルで使った言葉です。考え方の説明でいちばんしっくりきたのは、AWSのKiroハンズオンの開催報告にある整理でした。

この報告では、エージェントを「モデル」と「ハーネス」の組み合わせとして説明しています。ハーネスは、モデルの周りで入力やツール呼び出し、検証を制御する仕組みです。

ハーネスには、ツールの提供元が作る「エージェントハーネス」と、利用者が作る「ユーザーハーネス」があります。ユーザーハーネスの例は、Steering（指示書）・スキル・Hooksなどです。このキットで工夫したのは、ユーザーハーネスのほうです。

●なぜハーネスが必要なのか

同じ報告では、LLM（大規模言語モデル）の性質として次の3つを挙げています。

・確率的に動く
・生成はしても、自分で検証はしない
・会話の状態を持たない

そのため、「与えた制約を守らない」「検証していないのに『完成しました』と報告する」「進捗を見失って途中で止まる」といったずれが起きます。導入で書いた私の2つの悩みも、このずれから来ていました。

●2つの軸で整理する

報告では、ハーネスを2つの軸で整理しています。

・事前に与えるもの（フィードフォワード）か、結果から直すもの（フィードバック）か
・毎回同じ結果になるもの（テストや静的解析など）か、そうでないもの（指示書に書いた規約など）か

このキットに当てはめると、次のようになります。

・フィードフォワード：指示書・要件書・スキルで、守ることと進め方を先に渡す
・フィードバック：テストの証跡と記録で、報告が正しいかを確かめる
・毎回同じ結果になるチェック：テストのやり直しと、hooksによる実行前の検査

指示書に書いた規約は、毎回同じように守られるとは限りません。そこで、大事なところは毎回同じ結果になるチェックでも支えるようにしました。

報告には「一回作っておしまいってことはほぼない」という言葉もあります。ハーネスは、動かしてうまくいかなかった点を直しながら育てるものです。このキットでも、作業の最後にAIが改善案を出し、人が採否を決める流れを入れました。

■ キットで目指したのは「人が決めて、AIが進める」形

キットの目的は、人が作りたいものと完成条件を決め、AIが質問・提案・開発・検証を進めることです。人がやるのは、依頼とAIの質問への回答、要件書の承認、完成品の確認の3つです。

最初の依頼は短い文で構いません。足りない点はAIが質問し、案を出します。開発まで依頼して要件書を承認すると、止まる条件に当たらない限り、人の承認を待たずに完成まで進みます。

■ 全体像は「指示書・スキル・hooks・記録」の4層

キットは、AIを次の4つの層で支えています。

・指示書（AGENTS.md）：AIが何を守るかを書く
・スキル：工程ごとにどう進めるかを書く
・hooks：禁止された操作を実行前に止める
・記録：AIがやったことを、あとから確かめられるようにする

■ 工夫1：「承認」と「開発の依頼」を分ける

キットでは、要件書の承認と開発の依頼を別のものとして扱います。READMEには、次の一文を入れました。

依頼範囲が「要件定義のみ」なら、AIは資料を納品して終わります。範囲がわからないときは、確かめるまで開発しません。

毎回の確認を省きたいときは、「このセッションは全部承認。以後の確認は不要」と伝える一括承認も使えます。ただし、秘密情報の保護やレビュー・テストなどのルールは外れません。

■ 工夫2：工程ごとにスキルを分け、AIの担当に任せる

要件の整理、設計、レビュー、ふり返りなど、工程ごとに8つのスキルを用意しました。

開発が始まると、メインのAIは進行を管理する「まとめ役」に回ります。設計（調査を含む）・実装・レビュー・テストは、サブエージェント（メインから作業を任される別のAI）の4つの担当に任せます。

■ 工夫3：報告を信じず、記録で確かめる

この工夫は、キットでいちばん大事にしたものです。指示書には、次の一文を入れています。

まとめ役は、担当の報告文ではなく記録で判断します。テストやビルドは、出力と終了コードを証跡に残す形で実行させ、共通ルールに次のように書きました。

報告と記録が食い違ったときは、担当に差し戻します。

納品の前には、まとめ役が自分でテストを実行し直します。納品に進めるのは、結果がテスト担当の報告と一致したときだけです。

テストそのものは、初回のテストの後にレビュー担当が1回だけ見直します。見るのは、テストが受け入れ条件を本当に確かめているかです。

●止まる条件を決めておく

自動で進むのをやめて、人に相談する条件も決めました。

・差し戻しの回数が3を超えた
・報告と記録の食い違いが3を超えた
・担当が「要件では決められない」と差し戻した
・承認済み要件の変更が必要になった
・アプリのフォルダの外のファイル削除など、取り消せない操作が必要になった

●最後にキットの改善案を出させる

人が完成品を最終承認すると、AIが記録をもとに作業をふり返り、キットへの改善案を多くても5件出します。改善案は自動では反映せず、採否は人が決めます。

■ 工夫4：hooksで危ない操作を実行前に止める

hooksは、作業の開始時やツールを使う前などに、決めたチェックを自動で走らせる仕組みです。キットでは、リモート接続や秘密情報のファイルへのアクセスなどを、実行前に検査して拒否します。

ただし、設定ファイルを置くだけでは動きません。Codexで、hookを実行してよいと認める「信頼登録」が必要です。

hooksですべての禁止操作を止められるわけではありません。そのため禁止事項は、指示書のルールとしても守らせています。

■ 作ってみてわかった限界と注意点

・hooksは補助のガードです。ネットワークの隔離やOSのアクセス制御の代わりにはなりません
・1つのフォルダでは、Codexのセッションを1つだけ動かします。複数動かすと、ふり返りのトークン集計が混ざります
・ルールは増やしすぎないようにします。ルールが増えるほど、すべての担当の負担が増えるためです

■ まとめ

・エージェントは「モデル」と「ハーネス」の組み合わせ。キットでは、利用者が作るハーネスを工夫しました
・キットでは、指示書・スキル・hooks・記録の4層でAIを支えました
・中でも大事にしたのは、AIの報告を信じず、証跡と再実行で確かめることです

注意点として、hooksは信頼登録をしないと動きません。

自分の環境に取り入れるなら、まずは「テスト結果を証跡に残すこと」か「hooksによる実行前の検査」のどちらか1つから始めるのがおすすめです。AIに任せる範囲を少しずつ広げたい方の参考になればうれしいです。

■ 参考リンク

OpenAI「Harness engineering: leveraging Codex in an agent-first world」
▶ https://openai.com/index/harness-engineering/

Codex公式ドキュメント（AGENTS.md）
▶ https://learn.chatgpt.com/docs/agent-configuration/agents-md

Codex公式ドキュメント（Skills）
▶ https://learn.chatgpt.com/docs/build-skills

Codex公式ドキュメント（hooks）
▶ https://learn.chatgpt.com/docs/hooks

Codex公式ドキュメント（サブエージェント）
▶ https://learn.chatgpt.com/docs/agent-configuration/subagents

AWS「【資料公開 & 開催報告】Kiro ハンズオン「手を動かして実感する、Kiro が変える開発体験」」
▶ https://aws.amazon.com/jp/blogs/news/kiro-handson-20260924-report/