はじめに
最近、AIにコーディングを手伝ってもらう文脈で「ハーネス」という言葉を見かけるようになりました。専門用語っぽくて身構えてしまいますが、中身はとてもシンプルらしいです。
難しい記事を漁りましたが、頭の中で整理しきれなかったので、Claudeに教えてもらいつつまとめ上げました。
「毎回言うことが違う新人」と「一度教えたことはちゃんと守り続けてくれるベテラン」の違いは何か
これがハーネスの正体です。エンジニアでなくても、「誰かに仕事を教える」経験がある人なら、すぐにピンとくるでしょう。
ハーネスって、そもそも何？
ハーネス(harness)は、もともと馬に付ける「馬具」のことらしいです。手綱や引き具を付けることで、馬は好き勝手な方向には走れなくなりますが、その代わり、決められた方向に向かって全力を出し切ることができます。
馬がモデル、馬を制御するのがハーネス（および騎手？）
このようなものではないでしょうか？
AIも同じで、「何でも自由にやっていいよ」と丸投げするより、やっていいこと・やってほしい手順・思い出してほしい情報をあらかじめ整えておいたほうが、結果的に良い仕事をしてくれる、という考え方です。
ハーネスがないと何が起きるか
AIに「このルールを守ってね」とお願いするだけでは、前回話した内容を次の日にはきれいさっぱり忘れていたり、「これはやっちゃダメ」と一度注意してもまた同じことをしてしまったり、毎回プロジェクトの背景や決め事をゼロから説明し直す必要があったりします。
これは、新人に口頭だけで仕事を教えて、マニュアルも引き継ぎノートも作らないまま放置している状態に似ています。教えたその場ではできても、翌週には元通り、というやつです。
ハーネスを構成する5つの要素
ハーネスは、次の5つの仕組みの組み合わせでできています。それぞれ、職場でよくあるものに例えてみます。
| 要素 | 中身 | 職場でいうと |
|---|---|---|
| Rules(ルール) | プロジェクトごとの決め事・方針をまとめたファイル | 新人研修マニュアル・就業規則 |
| Skills(スキル) | よく使う定型作業の手順書。呼び出すと自動でその手順通りに動く | よく使う業務のレシピ・チェックリスト |
| Hooks(フック) | 「あることをしたら自動でこれをチェックする」という仕掛け | 提出前に自動で走る誤字チェック・承認フロー |
| Memory(メモリ) | セッションをまたいでも覚えておいてほしいことを保存しておく場所 | 引き継ぎノート・申し送り事項 |
| Feedback loops(フィードバックループ) | テストや検証を実行して、本当にうまくいったかを確認する仕組み | 検品・出荷前チェック |
どれか1つだけでは弱く、5つが組み合わさることで初めて「毎回安定して仕事ができる」状態になる、というのがポイントです。ルールだけあっても、それを覚えていて、実際に検証までしてくれる仕組みがなければ、結局は口約束と同じになってしまいます。
実例: 実際に目の前で起きたこと
最近、TFLiteを使って麻雀の点数計算アプリを作ってみるトライアルをしていたので、その中にハーネスを入れ込んでみました。
きっかけ
アプリの中で、カメラで撮った麻雀牌を自動認識する機能があるのですが、Claudeに「認識精度が良くない」と相談しました。Claudeが原因を調べたところ、アプリのコード自体にはバグが無く、AIの学習に使った写真が特定の牌のセット・特定の背景でしか撮られておらず、それ以外の牌だとうまく認識できないということが分かりました。ここまでの調査と、試してみた対策(効果は限定的だった)、今後考えられる選択肢を、そのまま会話の中で終わらせず、Claudeに「メモリ」として保存してもらいました。
こうしておくことで、次に別のタイミングで同じプロジェクトの相談をしたときに、Claudeが「その話、前に調べたやつですね。原因はこうでした」と答えてくれるようになり、試して効果が薄かった対策をもう一度提案するという無駄もなくなります。まさに「引き継ぎノート」そのものです。
ルールブックも作った
さらに、「このプロジェクトでは、完成済みのロジックを勝手に作り直さない」「実装が終わったら、テストが通っただけで満足せず、実際にアプリを起動して目で見て確認する」といった、このプロジェクト特有の決め事を、Claudeにルールファイル(CLAUDE.md)としてまとめてもらいました。
これを用意しておくと、次に同じプロジェクトについてClaudeに相談するとき（同じセッションでも、別のセッションでも）、毎回同じ説明をし直さなくても、Claudeが最初から同じ方針で動いてくれるようになります。
自動チェック(フック)も足りていなかった
ルールブックを作ったあと、「そういえばこのプロジェクト、フックが1つも設定されていない」ということに気づきました。ルールは「守ってほしいお願い」でしかなく、それを機械的に強制する仕組みがなければ、結局は「守られるかどうかは気分次第」になってしまいます。
そこで、「ファイルを編集したら、自動でコードを整形し、その場で簡単な文法チェックをする」というフックをClaudeに追加してもらいました。イメージとしては、書類を提出する前に、自動でフォーマットを整えて誤字脱字を軽くチェックしてくれる仕組みです。
面白かったのは、このフックを実際に動かして検証している最中に、「このプロジェクトの一部のファイルが、実は最新のツールの整形ルールとズレていた」ということが偶然見つかったことです。これは、フックという自動チェックの仕組みを用意して初めて表面化した問題でした。人間が毎回手作業でチェックしていたら、見過ごされ続けていたかもしれません。
これが、ハーネスの5要素の中でもフックが担う役割です。ルールを「言っただけ」で終わらせず、実際にその場でチェックし、直すところまで自動でやってくれます。新人研修でいうと、マニュアルを渡すだけでなく、提出物を毎回その場でチェックしてくれる先輩が付いているようなものです。
フィードバックループも足りていなかった
フックを整えたあと、もう一つ気づいたことがありました。「見た目のチェック(整形・簡単な文法チェック)はできても、本当に動くかを確認する仕組みがない」という点です。
このプロジェクトには103件のテスト(flutter test)がすでに用意されていたのですが、それをいつ実行するかが決まっていませんでした。Claudeが「テストを書きました」と言うだけでは、実際に毎回テストを実行して確認しているとは限りません。これはハーネスの5要素のうち、最後の「フィードバックループ」が抜けている状態です。
そこで、「会話の1ターンが終わるタイミングで、その間にDartのコードが変更されていたら、自動でテストを全部実行する」仕組みをClaudeに新設してもらいました。もしテストが失敗していたら、その内容を要約して通知するようにしています。
ポイントは、先ほどのフック(ファイルを保存するたびに毎回動く)と、役割をあえて分けたことです。
| タイミング | やること | たとえるなら | |
|---|---|---|---|
| フック(整形・文法チェック) | ファイルを1つ編集するたび | その場で素早く形式面をチェック | 誤字脱字チェック |
| フィードバックループ(テスト実行) | 一連の作業がひと区切りついたタイミング | 実際に動かして、本当に正しいか確認 | 出荷前の実機検品 |
誤字脱字チェックを、書類を1文字打つたびに毎回全ページ分やっていたら仕事になりません。逆に、出荷前の検品を誤字レベルの細かさでしか見ていなければ、動作不良を見逃します。チェックの粒度とタイミングを役割ごとに使い分けること、これもハーネスを設計するうえで大事な考え方です。
このフィードバックループを実際に用意して検証している最中にも、ちょっとしたハプニングがありました。検証用にわざとテストを失敗させるコードを書いてみたところ、狙った通りに失敗が検知され、失敗内容の要約が正しく通知されることを確認できました。「動くはずのものが、実際にちゃんと動くと確認できて初めて安心できる」というのは、人間の仕事の検品もAIの仕事の検品も、実は同じなのだと思います。
before / after
| ハーネスなし | ハーネスあり | |
|---|---|---|
| 同じ失敗を繰り返すか | 繰り返しやすい | 一度学んだことは記録に残る |
| 説明の手間 | 毎回ゼロから説明が必要 | 前提はすでに共有されている |
| 品質のブレ | 気分やその場の判断次第 | ルールと検証で一定水準を保てる |
| 「本当にできてるか」の確認 | 言った・言わないになりがち | テストや実機確認で裏付けが残る |
まとめ
ハーネスは、AIを「縛る」ための窮屈な仕組みではなく、AIが安定して良い仕事をし続けるための土台です。ルールはマニュアルにあたり、スキルは手順書、フックは自動チェック、メモリは引き継ぎノート、フィードバックループは検品体制にそれぞれ対応します。
この5つは、実はどれも「人に仕事を教えて、任せて、育てていく」ときに私たちが自然とやっていることと同じです。AIに対しても同じように、教えたことがちゃんと積み上がっていく仕組みを用意してあげること。それが「ハーネスを整える」ということなのだと思います。
（なるほどです、、claudeさん勉強になります）