ハーネスエンジニアリングを「核と殻」で捉え直す¶

— 生成を信頼できるシステムへ変換する、検査・探索・証跡・削除のループ

対象 / ポイント

対象: AIコーディングのハーネス（rules / hooks / verification など）を設計・導入する立場の読者。Claude Code や Codex などエージェント運用の経験があると読みやすい。

ポイント:

ハーネスの本質は単なる品質ゲートではなく、安価になった生成を信頼できるシステムへ変換するループである。
「仕様化できる核」と「仕様化できない殻」を分けると、どこを自動ゲートで閉じ、どこを判断に残すかが見える。
正解は仕様駆動でも探索駆動でもなく、自分の情報状態にハーネスの形を合わせることである。

核と殻、および検査・証跡化・探索・削除のループからなるハーネスエンジニアリングの全体像 — ハーネスエンジニアリングの全体像。図中のAIハーネスは、モデル外で設計する運用制御レイヤーを指す。発見された欠陥は殻から核へ昇格する。

ハーネスは何のために存在するのか¶

ルール集やプロンプト集ではなく、なぜ「ハーネス」が要るのか。

ある開発者がAIコーディングエージェントに「このバグを直して」と頼む。エージェントはコードを修正し、テストを流し、通ったと報告する。だが仕様書の更新は忘れ、関連ドキュメントも古いまま残る。コードは増え、確認すべき差分は人間のレビュー帯域を超えていく。

この記事の問いは明確だ。AIコーディングのハーネスは、何を保証し、何を人間の判断に残すべきなのか。

本稿でいうハーネスとは、AIに渡すプロンプトやルール集だけを指すものではない。 AIが何を読めるか、何を編集できるか、どのタイミングでテスト・静的解析・セキュリティスキャンを走らせるか。さらに、何を証跡として残すか、不要になった生成物をどう消すかまで含めた、モデル外の運用制御レイヤーである。本稿では、その制御レイヤーを設計・運用する領域をハーネスエンジニアリングとして扱う。

実装例として、Claude Code などのエージェント運用を skills・hooks・rules・MCP設定・セキュリティスキャンで包む ECC のような OSS の試みもある¹。ただし本稿で重要なのは、特定ツールの構成要素ではなく、 AIの生成・編集・実行・検証・証跡化を、モデル外の仕組みで囲う考え方である。

AIが書いたコードを人間がすべてホワイトボックスとして把握し続けられるなら、ハーネスの重要性は相対的に下がる。だが現実には、生成スループットは人間のレビュー帯域をすぐに超える。だからこそ、失われたレビューの網羅性を、人間の努力ではなく、検査・権限制御・証跡化・削除の仕組みで補う必要がある。

核と殻 ― 仕様化できる部分と、できない部分¶

100個の仕様をすべてガードレールで通したら、品質は保証されるのか。

決済アプリケーションを例にする。「残高がマイナスにならない」「同じリクエストIDで二重課金しない（冪等性）」「ログにPIIを出さない」——これらは温度計を刺すように測れる。検査が通れば、その契約に書かれた性質については、人間の主観レビューに頼らず機械的に合否を判定できる。ここでは「誰が書いたか」を信用する必要すらない。

一方で「このチェックアウトUIはユーザーに使いやすいか」「未知の攻撃にどこまで耐えられるか」は、単一の温度計では測れない。 UXテストや脅威モデリングのような部分的なセンサーはあっても、合否を一意に決める計器はない。テストはバグの存在を示せても、不在は証明できない²。

この2つを分けると、ハーネスの効き方が見える。

核：仕様化でき、契約に書いた性質については検査で機械的に合否を出せる領域（台帳の不変条件、型付きインターフェース、適合性テスト）。
殻：有限のルールに還元しきれない領域（使いやすさ、意図との一致、未知の脅威への耐性）。

契約に書き漏れた性質は、保証の外に残って殻に落ちる。核では、実装差分の逐行レビューを縮小できる。ただし仕様そのものの妥当性、リスク受容、本番反映の承認といった判断は残る。殻では、その判断がさらに大きく残る。設計の腕は、核をどこまで広げ、殻をどこまで小さくできるかにかかっている。

決定性と正しさは別の軸¶

「同じ入力で同じ出力」は品質の保証になるのか。

ならない。同じ間違った答えを100回返す関数は、完全に決定的だが無価値である。決定性が効くのは監査・デバッグ・信頼であって、品質とは直交する。

品質を担保する中心は、生成器の決定性ではなく、契約の明確さと検査可能性である。 I/O・型・不変条件・権限制約・禁止事項が十分に具体化されていれば、どの生成器が作った差分でも、ゲートを通じて契約の範囲では正しさを判定できる。逆に契約が曖昧なら、生成器をいくら決定的にしても穴は残る。

したがって「確率的な生成は信用できない」という直感は、少し的を外している。信用すべきでないのは確率的生成そのものではなく、検査可能な契約を持たないまま生成物を受け入れる運用である。核では生成のブレをゲートで吸収し、殻では人間の判断と現実からのフィードバックを当てる。

レビューはゲートではなくセンサーである¶

良いガードレールを作れば、レビューは要らなくなるのか。

核の逐行レビューは縮小できる。だが殻では、なくならない。少なくとも殻において、レビューは単なる合否ゲートではなく、仕様の欠陥を検知するセンサーである。理由は、仕様への適合は検証できても、仕様そのものの妥当性は仕様だけでは検証できないからである。

たとえば「3タップで決済完了」と仕様化し、ゲートを通したとする。だが実際にはOTP入力でSMSが遅く、フォールバックが無いせいでユーザーが離脱する。この事実は仕様書を眺めても出てこない。プロダクトを動かし、現実のユーザーに当てて初めて分かる。

つまりアウトプットのレビューは、仕様の欠陥を検知するセンサーである。修正が仕様側に着地するとしても、欠陥を検知するには、仕様書の内側だけで閉じず、実際のアウトプットや利用状況を観測する必要がある。そしてこのセンサーは捨てるための一時しのぎではなく、核を育てるループの起点になる。

アウトプットを現実にぶつける → 仕様の欠陥が表面化する → その欠陥を回帰テストやルールに昇格させる → 次回は同じ点を自動で弾ける → 核が広がり、殻が縮む。

未知の攻撃や潜在的なユーザー嗜好のように、事前には仕様化できない性質も残る。ここでのレビューは過渡的なものではなく、恒久的に必要になる。

仕様駆動は正義ではない ― 探索と活用¶

仕様を先に固めるのが、つねに正しいのか。

正しくない。仕様先行と探索（POC）駆動は、核と殻をプロセスに適用した2つのモードにすぎない。

決済アプリケーションの台帳不変条件は、作る前に書ける。ここは仕様先行が効く（核）。一方、どのチェックアウトUIが刺さるかは、作る前に完全には書けない³。

ここでは複数案を安く作って比較する探索が効く。たとえば30個のUIを試作し、同じタスク完了テストと簡易なユーザーテストを当てて、勝ち筋のある案を選ぶ。数が30であることが本質ではない。生成コストが下がり、探索幅を広げられること自体が本質である（殻）。 POCは、製品発見のレベルで現実をセンサーにしている。

ハーネスの形は、探索から活用へ進むほど変わる。試作段階に必要なのは、正しさのゲートではない。

封じ込め：30個のPOCは偽の決済サンドボックスで動き、本物のカードやPIIに触れず、自動で破棄される。
測定の一貫性：同じタスク完了テストとアンケートを全試作に当て、比較を公平にする。
多様性の確保：30個が同じ局所最適のバリエーションに収束しないよう、探索空間を散らす。

勝者を選び肉付けに入ってはじめて、冪等性・台帳不変条件・PCI DSS・PIIといった核のガードレールが乗る。早期に後期のハーネスを当てれば速度を殺し、後期に早期のままなら、金を動かすコードを無防備に出荷してしまう。

いわゆる vibe coding、つまり細かな仕様を先に固めず、AIとの対話と直感で素早く形にする開発スタイルは、早期ハーネスを最小化して速度に振った形である。捨てる試作には合うが、本番にそのまま乗せるには危うい。

探索のコストが下がると、次にボトルネックになるのは生成ではなく廃棄である。探索から活用へ移るときに必要なのは、勝者を選ぶことだけではない。敗者を消すことである。

AIは安く大量に試作を作れるが、その副作用として、使われない関数・重複したアダプタ・古いfeature flag・過剰なfallbackを残しやすい。したがってハーネスには、生成を促す仕組みだけでなく、不要になった生成物を削除する圧力も含める必要がある。 dead code や unused dependency を検出するスキャンと、cleanup のゲートがそれにあたる。

ハーネスは情報状態に合わせて形を変える¶

結局、ハーネスとは何なのか。

ハーネスは「仕様を強制する仕組み」ではない。安価になった生成を、信頼できるシステムへ安全に変換するループであり、その形は自分の情報状態を追って変わる。

仕様化できる核ではガードレールが強制し、逐行レビューは縮む。仕様化できない殻では安く安全に探索し、現実をセンサーにして、見つかったものを核へ昇格させる。仕様駆動とPOC駆動はその両端で、ゾーンごとに選ぶ。そしてシステムは成熟とともに殻から核へ移っていく。

冒頭で触れた証跡化も、このループの一部である。人間がすべての差分を読めないなら、せめてAIが何を読み、何を変更し、何を実行し、何を未確認のまま残したかを記録する。これは監査ログというより、レビュー不能な大量差分を、レビュー可能な変更台帳（Change Ledger）へ圧縮する仕組みである。コード変更に対して仕様・テスト・ドキュメントが同期しているかをCIで点検する仕掛けも、同じ系譜にある。

「仕様駆動が正義か」への答えは No である。正義は仕様駆動そのものではなく、情報状態にハーネスの形を合わせることにある。議論の重心は「品質ゲートをどう作るか」から、「探索と活用をどう管理するか」へ移る。

領域	例	ハーネスの形	人間の役割
核	冪等性、型、DB制約、PCI DSS / PIIログ禁止	test / typecheck / 静的解析 / policy gate	仕様とリスクの承認
殻	UX、未知の攻撃、ユーザー嗜好	POC、観測、レビュー、実験	判断・発見・仕様化
殻→核	発見済みバグ、再発パターン	regression test / rule / hook / CI	欠陥を検査可能な形に変換
探索後	不採用POC、重複実装	dead code scan / cleanup gate	残す・消すの判断
証跡化	読んだファイル、変更理由、実行した検査、未確認事項	Change Ledger / audit log / PR template / CI summary	差分全体ではなく、判断に必要な情報を確認

まとめ¶

ハーネスエンジニアリングを「品質ゲート」とだけ呼ぶと、探索の設計と廃棄の設計が見えなくなる。核では検査可能な契約を増やし、殻では現実からのフィードバックを安全に受ける。どちらか一方では足りない。

大事なのは、生成の量を増やすことではない。生成されたものを、どの時点で検査し、どの欠陥を核へ昇格させ、どの試作を消すかである。AIコーディングの運用品質は、その循環を設計できるかで決まる。