一つの Video Agent イテレーションがハーネス手法に育つまで

2026-05-18review#ai-engineering#agent#thoughts

少し前、特定の映像スタイルに向けた video agent を改善していた。

タスクは「動画を生成できるようにする」という漠然としたものではなく、あるクラスのスタイルを安定して出させることだった。参照ブランドの Instagram / Reel の視覚言語を踏まえ、別のブランドやプロダクトに置き換える。構図・照明・色調・カメラワークのリズムは保ちつつ、参照ブランドのロゴ・パッケージ・文字を最終画面に持ち込まない。

このタスクは判断を誤りやすい。

単発の出力だけ見れば「悪くない」か「似ていない」で終わる。しかし数ラウンド回すと、問題は記述しにくくなる。あるバージョンは安定したがスタイルが平板になった。あるバージョンは参照動画に近づいたがプロダクトの識別が悪化した。妥当に見えた修正が、次のラウンドで元々良かった case を壊した。

最初から方法論を作るつもりはなかった。

毎ラウンドの結果を記録して、開発ミーティングで生成品質のすり合わせをしたかっただけだ。今回何を変えたのか、どの case が良くなり、どの case が退行し、次はどこを直すべきか。

後になって分かった。本当に最適化すべきなのは特定の prompt でも、どこかのコードでもなく、agent イテレーション全体のフィードバックシステムだった。

過程の記録：「効果のすり合わせ」から始まった

第一歩は素朴だ。coding agent にテストを回すたび、結果を飛書ドキュメントへ同期させた。

これらのドキュメントは論文式の記録でも、外部読者向けのレポートでもない。開発協働の中の効果ボードに近い。

一方のドキュメントは横方向の比較を担う。同じ一群の case が、異なるバージョン・異なる戦略・異なる生成経路でそれぞれ何を出したか。要点は表の見た目ではなく、ミーティングで全員が同じ行を指して「この case は良くなった、これは退行した」と言えることだ。

もう一方は縦方向の展開を担う。一つの case を、ユーザー入力から、素材収集・スタイル分析・プロダクト分析・素材編成・prompt 生成・ツール呼び出し・出力結果まで広げる。agent の中間生成物を開いて見せることで、問題が最終成果物の上にだけ落ちなくなる。

二種類の記録が解いているのは同じ問題だ：agent に、前のラウンドで何が起きたかを会話の記憶だけで理解させない。

video agent の失敗は、「仕上がりが良くない」だけでは済まないことが多い。素材段階で参照を取り違えたのかもしれないし、プロダクト分析段階で本物の SKU を取れていなかったのかもしれないし、prompt 段階で「構図を参照する」が「参照プロダクトを複製する」に化けたのかもしれない。

trace がなければ、coding agent は平気で render の層だけを直す。

図 1：同じ動画 case 群を複数ラウンドで比較する効果マトリクス

共有コンテキスト：飛書ドキュメントが外部記憶になる

数ラウンド回すと、ドキュメントの役割が変わった。

もはや効果ボードではなく、coding agent・sub agent・私が共に働く界面になった。

coding agent はテスト結果を書き込む。sub agent はドキュメント上で独立レビューをする。私はその横に人間の判断を添える。「このバージョンは参照スタイルに近いが、プロダクトの主体が弱くなった」「これは bad case ではない、このスタイルが本来残すべき粗さだ」「この修正方向は違う、全体をテンプレ的な広告映像へ引っ張ってしまう」。

このとき飛書ドキュメントは三つの役割を担っていた。

Shared Context：全参加者が同じ case 群・同じラウンドの出力・同じコメント群を囲んで働く。

External Memory：判断をラウンドをまたいで保存し、一つの会話ウィンドウに依存しない。

Review Surface：コメントは具体的な段落・表・結果に直接ぶら下がり、漠然とした「効果が悪い」に留まらない。

この一歩で、harness への理解がより具体的になった。

harness はテストを走らせるスクリプトだけではない。agent のワークフローにとっては、agent が読める履歴、再利用できる事例、レビューされうる出力、そしてレビュー結果を次のラウンドの修正へ運び戻す経路までを含む。

図 2：一つの video agent case の phase trace 展開

独立レビュー：sub agent はより客観的だが、客観的真理ではない

その後、sub agent によるレビューを加えた。

価値は独立したコンテキストにある。

workflow を変えたばかりの coding agent は、自分のパッチに沿って結果を解釈しがちだ。強めの product constraint を足した直後なら、「プロダクトがはっきりした」を進歩と読みやすい。だが私が本当に気にしているのは、プロダクトがはっきりした代わりに、参照ブランドのあの無造作な感じが消えたことかもしれない。

sub agent は別のコンテキストから入ってくる。見えるのはテストドキュメントと出力結果とレビュー要件だけ。さっきの修正ラウンドに参加していないから、coding agent が気づいていない副作用を指摘しやすい。

ただし sub agent を神格化してはいけない。

sub agent も依然として主観的なレビュアーだ。より明瞭で、より完全で、より商業的な出力へ寄るかもしれないし、そのスタイルが本来残すべきノイズを欠陥と判定するかもしれない。だから最終裁定者ではなく、コンテキストを隔離された AI reviewer である。

後で人間による較正が要る理由も、sub agent 自身のレビュー prompt をイテレーションする必要がある理由も、ここにある。

三層レビュー：固定スクリプト、AI、人間

ここまで来たとき、以前読んだ harness engineering 関連の記事を思い出した。

引っかかっていたのは特定の用語ではなく、一つの判断だ。信頼できる agent レビューは、一種類のシグナルだけでは成り立たない。

覚えていた主張はこうだ。harness の中のレビューは少なくとも三種類が一緒に働く必要がある：固定スクリプト、AI review、人間の review。

これは私がやっていたことにちょうど重なった。

固定スクリプトは議論の余地がないハードルールを担う。ファイルが生成されたか、動画リンクへアクセスできるか、長さが目標範囲か、出力に明白に禁止された字幕・ウォーターマーク・ブランド文字が出ていないか。

AI review は高スループットの意味判断を担う。スタイルは参照に近いか、プロダクトが誤って置き換えられていないか、カメラのリズムが明らかに外れていないか、このバージョンは前のバージョンから何が退行したか。

人間の review は方向とトレードオフを担う。ある「粗さ」は失敗なのか、それともこのスタイルが本来必要とする質感なのか。あるルールを次のラウンドへ入れるのか、それとも今回の case の観察に留めるのか。

図 3：固定スクリプト・AI review・人間の較正で組む三層レビュー

このとき気づいた。私は coding agent に「もう数ラウンド直させて」いたのではない。

小さな harness を組んでやっていたのだ。case を走らせ、trace を保存し、レビューを発起し、コメントを読み、コードを直し、また次のラウンドの case へ戻る。

Judge Calibration：AI レビュアーもイテレーションの対象

sub agent の判断は有用だが、信頼できると決めてかかってはいけない。

映像スタイルのタスクでは、AI reviewer は特定の方向へ安定して寄りやすい。より明瞭、より完全、より広告らしく、よりノイズが少なく。普通の品質評価ならこれらの好みは長所かもしれないが、ある種のスタイル適合タスクでは、むしろシステムを逸らせる。

だから sub agent も、イテレーションが必要なコンポーネントとして扱い始めた。

人間のコメントは見落としの補完だけでなく、judge の方向を較正している：

どのスタイル特徴を欠陥と誤判定しているか？
どの次元では判断が比較的安定しているか？
明瞭さ・プロダクトの画面占有・商業感を過剰に報酬していないか？
レビュー prompt に「ローファイの質感を残す」のような制約を足すべきか？

これが Judge Calibration だ。

最初から precision・recall・agreement の完全な指標が揃っている必要はない。だが考え方はすでにそこにある。AI reviewer の出力も抜き取り検査され、重みを下げられ、修正されるべきで、そのまま coding agent の修正根拠に入ってはいけない。

境界知識：コメントから条件へ

最初のループの問題はすぐに現れた。

飛書のコメントは人間には役立つが、coding agent にはまだ緩すぎる。

例えば私が「これは広告映像っぽくなった」と書くと、人間はその裏に、過剰なライティング、プロダクトの置き撮り感、安定しすぎたカメラ、綺麗すぎる仕上げが含まれうると分かる。だが coding agent はそのうちの一点だけを掴んで、「プロダクトの明瞭度を下げる」に変換するかもしれない。

これが自然言語のコメントとコード修正の間の grounding gap だ。

そこで既存の harness の実践に沿って、「境界を蓄積する」ロジックで問題を整理し始めた。

境界とは「これは駄目」の一言ではなく、条件付きの判断だ：

Instagram の無造作な感じを残すことが目標のとき、綺麗すぎる studio lighting は出力を広告スタジオ撮影へ押しやる。
参照素材に映っているのがソースブランドのプロダクトのとき、抽出してよいのは構図・光・粒子・色彩だけで、ターゲット prompt にソースプロダクトの形状を複製させてはならない。
プロダクト画像の分析が十分に本物の SKU を得ていないとき、render を続けると架空のプロダクトを生成しかねない。このときは fail fast を選ぶ。
プロダクト認識を強めるために主体を大きくしすぎると、style transfer は product hero packshot に退化する。

これが後に整理した方法論で言う Boundary Knowledge だ。

その働きは、bad case を「あの出力はひどかった」から「この条件のクラスで失敗する」へ格上げすることにある。coding agent が読むのはもう感情的なコメントではなく、ルールにずっと近い修正根拠だ。

構造化された境界：Agent 間の意味損失を減らす

自然言語の境界を蓄積するだけでは、まだ損失がある。

同じ「プロダクトがシーンにねじ込まれている」の一文が、画面占有が大きすぎる意味かもしれず、照明が合っていない意味かもしれず、プロダクトと人物の動作が無関係という意味かもしれない。人間は文脈で補えるが、coding agent が毎回正しく補うとは限らない。

だから境界は徐々に構造化する。

より堅牢な boundary は少なくともこれらを含むべきだ：

category：問題はスタイルか、プロダクト認識か、素材選択か、prompt 制約か、カメラのリズムか、安全ルールか。
condition：問題はどの条件で現れるか。
failure：どの目標を傷つけたか。
evidence：どの case と紐づくか。
severity：必修か、観察項目か。
confidence：この判断は人間からか、sub agent からか、両者一致か。

これは執筆を表に変えるためではない。

coding agent の当て推量を減らすためだ。とくに agent 同士がドキュメントで情報を渡し合うとき、構造化フィールドは「君が言っているのは別の問題だと思っていた」の確率を下げる。

図 4：bad case と good case をそれぞれ boundary と exemplar に沈殿させる

二つのシグナル：boundaries だけの蓄積は効果がいまいち

最初は harness の考えに沿って、主に boundaries を蓄積していた。

方向は正しいが、効果はいまいちだった。

理由は単純だ。bad case しかなければ、システムはどこへ行ってはいけないかだけを知り、どこを残す価値があるかを知らない。

どの bad case も agent に「あれをするな」と告げる。プロダクトを小さくしすぎるな、ロゴを漏らすな、画面を散らかすな、カットを跳ねさせるな。ルールが積み上がるほど、出力は安全なテンプレートに似ていく。

だが映像スタイルは「壊れていない」だけでは足りない。

いくつかのものは、まさにリスクがもたらす。手持ちの揺れ、偶然の構図、わずかな露出オーバー、素材の中のあまり商業的でない生活の空気、カット切り替えの不揃いなリズム。

だからフィードバックを双方向で体系的なものにしようと考え始めた。

一方は boundaries。「どの条件で壊れるか」を記録する。

もう一方は exemplars。「何を残すべきか」を記録する。

例えば、あるバージョンはプロダクトを最大限には見せていないが、参照ブランドの画面のトーンを守っている。ある case は少しノイズがあるが、全体として最も本物の Instagram post に近い。ある prompt 構造は綺麗ではないが、AI デフォルトのスタジオ撮影感を減らしている。

これが Good Case のリプレイだ。

good case の役割はシステムの優秀さの証明ではなく、coding agent への正の参照だ。次のラウンドで問題を直すとき、これらを一緒に直してしまうな。

Golden Set：一つ直して一つ壊すのを防ぐ

二つのシグナルをさらに進めると、自然に Golden Set へ行き着く。

いくつかの good case が人間に確認済みなら、次のラウンドの修正はそれらを壊してはならない。さもなければ agent は最新のコメントに過学習する。

私が「プロダクトの主体が弱い」とコメントした直後、次のラウンドで全 case のプロダクトが画面中央へ押し出されるかもしれない。「参照スタイルが弱い」とコメントした直後、ソースブランドの要素が巻き返してくるかもしれない。

Golden Set の役割は、coding agent にまず証明させることだ。このラウンドの修正は、すでに成立していた挙動を壊していない。

初日から完全な自動化は要らない。

最小バージョンは泥臭くていい。人間確認済みの case を一群固定してリプレイし、鍵となる次元が下がっていないかを比べる。workflow が安定したら Regression Gate に格上げする。合格率が閾値を超えて下がったら、このラウンドの修正はそのままでは通さない。

これが後の方法論ドキュメントに書いた Golden Set + Regression Gate だ。

図 5：Golden Set と Regression Gate が修正による退行を防ぐ

Active Probing：偶然問題にぶつかるのをやめ、能動的に境界を探す

初期のテストはランダムな case か自然な case が中心だった。

これでも問題は見つかるが、効率が悪い。多くの失敗は運が向かないと現れない。

例えばある境界は「短いトランジションは常に駄目」ではなく、「遅いテンポの語りでは短いトランジションが駄目で、速いテンポの音楽なら許容できる」かもしれない。ランダムな case だけでは、この線は長いこと見えてこない。

だから後の方法論では、これを Active Boundary Probing へ拡張した。

Probe Agent の仕事は普通の case 生成ではなく、既存の boundary の近傍にテストを構築することだ：

既知の bad case のパラメータ付近を微調整し、本当の臨界点を探す。
二つの境界条件を掛け合わせ、新しい失敗が現れるかを見る。
judge の確信度が低い case を狙って生成し、未知の領域を炙り出す。

この部分は当時完全に実践したモジュールではなく、「ランダム case は効率が悪い」という問題から押し出された次の一歩だ。

Convergence：ループを無限の継ぎ当てにしない

後になってようやくはっきりした問題がもう一つある。いつ止めるべきか？

agent イテレーションは無限の継ぎ当てになりやすい。どのラウンドも何かしら問題を見つけられ、どのラウンドも何かしら直せる。だが直し続けることは、良くなり続けることを意味しない。

だから方法論には収束シグナルの一式が要る。

シグナルは単純でいい：

Golden Set は安定しているか。
新しい bad case の数は減っているか。
新規 boundary はまだ急増しているか。
各ラウンドの fix の後、元の bad case が改善した割合は十分に高いか。
sub agent と人間の判断の一致は安定しているか。

この部分を「当時すでに完全なダッシュボードがあった」とは書きたくない。

正確に言えばこうだ。実践がまず「感覚では止まれない」という問題を露呈させ、方法論が後からそれを Convergence Metrics へ拡張した。

手法の進化：一つの実践から一組のエンジニアリングモジュールへ

この手法は最初から設計されたものではない。

こう育った：

まず video agent の各ラウンドの生成結果を記録し、開発ミーティングでの効果のすり合わせに使った。
記録ドキュメントが shared context になり、外部記憶とレビュー界面の役割を担い始めた。
sub agent を加え、独立コンテキストで AI review をさせた。
sub agent にも主観的な偏りがあると分かり、人間の review が judge calibration になった。
既存の harness の考えに沿って bad case と boundaries を蓄積した。
負のフィードバックだけでは効果がいまいちだと分かり、good case と exemplars を加えた。
修正が元々良かった case を壊すと分かり、Golden Set と Regression Gate が必要になった。
ランダム case の探索は効率が悪いと分かり、Active Probing へ進んだ。
ループに停止条件が要ると分かり、Convergence Metrics を補った。

これは新しい名前を付けることより重要だ。

名前は要らなくても、このモジュール群は残すべきだ：Trace、Shared Context、AI Review、Human Calibration、Boundary Store、Exemplar Store、Golden Set、Regression Gate、Active Probing、Judge Calibration、Convergence Metrics。

これらが共同で解いているのは一つの問題だ：各ラウンドの実践が生んだ経験を、本当に次のラウンドの修正へ届けるにはどうするか。

最小の再利用可能バージョン

この流れを最小まで圧縮するなら、六つのモジュールを残す。

Case Trace

毎ラウンドの結果は振り返れなければならない。少なくとも case・バージョン・入力・出力リンク・鍵となる中間生成物・tool calls が見えること。video agent なら最終動画だけでは足りず、素材分析・manifest・render prompt まで見えるのが望ましい。

Shared Review Doc

コメントは具体的な結果にぶら下げる。チャットで「このバージョンは駄目」とだけ言わず、具体的な case・具体的な段階・具体的な出力の横にコメントを置く。

Isolated AI Review

修正に参加していない sub agent にレビューさせる。最終決定は担わないが、coding agent が見落としがちな副作用を見つける役を担う。

Human Calibration

人間のコメントは方向・審美・トレードオフを担い、同時に sub agent のレビュー偏差を較正する。

Boundary / Exemplar Store

confirmed bad case は boundary へ、confirmed good case は exemplar へ。前者は agent にどの条件で壊れるかを教え、後者は次のラウンドで直し消してはいけないものを教える。

Golden Set / Regression Gate

毎ラウンドの修正後、人間確認済みの良い case を一群リプレイする。まず退行しないことを保証し、それから新しい問題を探索する。

この最小バージョンだけで、agent イテレーションの脱線の多くは解決できる。

Active Probing、指標化した Judge Calibration、Convergence Metrics は、次段階の強化パーツとして接続すればいい。

鍵となる takeaway

共有ドキュメントはただのログではなく、agent イテレーションにおける shared context・external memory・review surface である。
sub agent review の価値はコンテキストの隔離にあるが、それでも人間の較正と自身のイテレーションが要る。
boundaries の蓄積だけでは足りない。exemplars と Golden Set を同時に保存しなければ、agent は直すほど保守的になる。
実践から育った harness の本質はフィードバックシステムの設計であって、coding agent に感覚で何ラウンドか余計に走らせることではない。

参考

実践中に明確に思い出し、照合した記事：

後で agent とこの方法論を議論しながら補った理論的参照：