コードが読めないから、AIの品質管理を仕組み【ハーネス】で解決した

「直す」から「最初から良いものを出す」へ

前回、AIの出力をブラッシュアップするプロンプトの話を書きました。「30点です。100点にするには？」「隠してることない？」「ベストプラクティスを教えて」。この3つで出力はかなり引き上げられるようになった。

でもこれは「作った後に直す」話です。

プロジェクトが増えるほど、毎回同じやりとりを繰り返す余裕がなくなってきた。そもそも、最初からできる限り品質の良いものが出てくれば、ブラッシュアップの回数は減る。

そこから構築しているのが、ハーネスという仕組みです。

ハーネスって何？

ハーネスは元々「馬具」や「安全帯」の意味です。暴れる馬を制御したり、高所での落下を防いだりする装置。

AIの世界では、AIの出力を制御・検証する全体の枠組みを指します。Anthropicの公式ドキュメントに「エージェント・ハーネス設計」という考え方があって、それを自分の環境に導入しました。

一言でいうと、「AIの作業手順を仕組み化して、品質を管理する枠組み」です。

ハーネスの構造

ハーネスは3つの要素で構成されていますが、並列ではなく入れ子構造です。

Skills（部品）

Skillsは、AIの作業を手順化した部品です。「設計のときはこう動け」「品質チェックのときはこう動け」というルールを書いたファイル。

自分の環境では、こういう順番でSkillsが動きます：

brainstorming → 何を作るか設計する writing-plans → どう作るか計画を書く subagent実装 → 計画に沿ってコードを書く harness-evaluator → 別のAIが採点する quality-gates → lint・型チェック・テストを通す

人間の開発チームでいうと、PM→設計→開発→QA→最終チェック。この役割分担をAIでやっています。

エージェント（実行者）

各Skillを実際に動かすのが、個別のAI（エージェント）です。

ここで重要なのが**「生成するAIと評価するAIを分ける」**こと。

同じAIにコードを書かせて「これ合ってる？」と聞くと、だいたい「はい、問題ありません」と返してきます。自分で作ったものを自分で採点したら甘くなる。これを「自画自賛バイアス」と呼んでいて、長いタスクほど品質が落ちる原因でした。

だからEvaluator（採点者）は完全に別のコンテキストで動かしています。コードを書いたAIの経緯を知らないので、忖度なしで採点する。

UI系のタスクでは、Playwrightで実際の画面のスクリーンショットを撮ってEvaluatorに渡します。「型チェックは通ったけど画面は崩壊してる」を防ぐためです。

Sprint Contract（合格基準）

ハーネスの中で一番効いているのが、実はAIの数じゃなくてこれ。「何ができたら完了か」を最初に決める合格基準書です。

×「きれいなUIにして」

○ 「WCAG AA準拠、余白16px以上、モバイルで横スクロールなし」

測定可能な基準を先に書いて渡すだけで、AIの出力が安定します。後で書きますが、エラーログで一番多いのが「仕様ミス」で166件。曖昧な指示がエラーの最大の原因でした。Sprint Contractはそれを潰すための仕組みです。

Level 0/1/2 — 全部にフルは要らなかった

最初は全タスクにフルハーネス（3エージェント+Sprint Contract）を使っていました。品質は上がったけど、設定変更1つにフル体制は明らかにやりすぎだった。

今はタスクの複雑さで3段階に分けています。

判断はシンプルで：

10分で終わる？ → Level 0 手順が予測できる？ → Level 1 ミスったらヤバい？ → Level 2

Level 0で済むものにLevel 2を使っていた無駄がかなりあったので、これだけでコストと時間がだいぶ減りました。

エラーログ494件の実態

ハーネスを作る過程で、AIが犯したエラーを自動記録する仕組み（self-error-log）を入れています。A自身が原因と対策を1行で記録するログです。

1ヶ月ちょっとで494件溜まりました。内訳がこちら。

1位がspec（仕様ミス）の166件。 AIが最も苦手なのは「技術」じゃなくて「こっちの意図を正しく汲むこと」でした。

だからSprint Contractで「意図」を測定可能な基準に変換しておく。ハーネスの各パーツは、全部このエラーログから逆算して作っています。

494件→5件：仕組みの効果

ハーネスを本格的に運用し始めてから、エラーの推移が明らかに変わりました。

3月27日：66件（ピーク） 3月28日：16件 3月29日：36件 3月30日：33件 3月31日：20件 4月1日 ：20件 4月3日 ： 2件 4月4日 ： 3件

3月27日のピーク（66件/日）から、4月は3日間で合計5件まで減りました。

もちろんプロジェクトの作業量にもよるので単純比較はできないけど、同じように開発を続けていてこの減り方は、仕組みが効いていると感じています。

まとめ

コードが読めない自分がAIで開発を続けるために作った仕組みが、ハーネスです。

• Skillsで作業手順を部品化する

• エージェントで生成と評価を分離する

• Sprint Contractで合格基準を先に決める

• Level 0/1/2で複雑さに応じて使い分ける

コードが読めなくても、仕組みは作れます。というか、コードが読めないからこそ仕組みで品質を担保するしかない。

494件のエラーは、この仕組みを作るための授業料でした。