同じAIモデルを使っているのに、チャット画面とエージェントツールでは出てくる結果がまるで違う。そんな経験はないでしょうか。
その差を生んでいるのが「ハーネス」です。AIの実力は、モデルの賢さだけでなく、モデルをどう動かすかで大きく変わります。
ハーネスとは何か
ハーネスは、もともと馬具のことです。馬の力を、荷車を引くという仕事に変える道具です。
AIでも同じで、モデルが「馬の力」、ハーネスが「その力を仕事に変える仕組み」にあたります。モデルが考え、ハーネスがファイルを読ませ、コマンドを実行させ、結果をモデルに返します。
ハーネスの構成要素：新人エンジニアに例えると
ハーネスの要素は、AIを「配属されたばかりの優秀な新人」と考えると整理しやすくなります。地頭（モデル）は良くても、資料も権限も渡さなければ仕事になりません。
| 要素 | 新人に例えると | 役割 |
|---|---|---|
| 指示ファイル（CLAUDE.md、AGENTS.mdなど） | 毎朝読むオンボーディング資料 | プロジェクトの前提や規約を、毎回必ず伝える |
| Skills | 棚に並んだ業務マニュアル | 手順書や補助スクリプトをまとめておき、関係する作業のときだけ読み込ませる |
| Tools | PCと社内システムのアカウント | ファイルの読み書き、コマンド実行、検索など、手を動かす手段 |
| MCP | 他部署や取引先との窓口 | 外部のサービスやデータにつなぐ共通規格 |
| Agents（サブエージェント） | 専門チームへの依頼 | 調査やレビューなどを別のAIに任せ、結果だけ受け取る |
| Hooks | 必ず通るチェック工程 | ファイル編集後のフォーマットなど、決まった処理をAIの判断に関係なく必ず実行する |
| 権限設定 | 決裁権限 | 自動でやってよいことと、人の承認が必要なことを分ける |
チャット画面のAIは、このうちごく一部しか持っていません。だから同じモデルでも、できることに差が出るのです。
迷いやすい使い分け
- 毎回必要な前提 → 指示ファイル。ただし書きすぎると、毎回読む量が増えて重くなります。
- ときどき必要な手順（PDFの作り方、レビューの観点など） → Skills。必要なときだけ読まれるので、たくさん用意しても邪魔になりにくいです。
- 作業を丸ごと任せたい（広い範囲の調査など） → Agents。メインの会話に途中経過が溜まらず、話がこじれにくくなります。
- 絶対に毎回やらせたい（フォーマット、テスト実行） → Hooks。AIに「やってね」と頼むのではなく、仕組みで強制します。
一言でまとめると、指示ファイルは「常識」、Skillsは「マニュアル」、Agentsは「同僚」、Hooksは「ルール」です。
具体例で見るハーネス
指示ファイルの例
プロジェクトの直下に置く指示ファイルには、たとえばこんなことを書きます（架空のプロジェクトの例です）。
# このプロジェクトについて
- 社内の勤怠管理システム。バックエンドはTypeScript、DBはPostgreSQL。
# 規約
- テストは tests/ に、対象ファイルと同じ名前で置く（例：date.ts → date.test.ts）
- 日付の処理は必ず src/utils/date.ts の関数を使う。直接 Date を計算しない。
# やってはいけないこと
- migrations/ 配下のファイルは編集しない。変更が必要なら報告すること。
- テストを通すために、テスト側の期待値を書き換えない。
新人に「うちのチームではこうしてね」と最初に伝える内容と同じです。これがあるだけで、毎回の指示がぐっと短くなります。
Skillsの例
Skillsは、手順書をフォルダにまとめておく仕組みです。たとえば「単体テストの書き方」というSkillなら、こんな構成になります。
skills/
unit-test/
SKILL.md ← いつ使うか、どう書くかの手順
template.ts ← テストのひな形
SKILL.md の先頭には「単体テストを書くときに使う」といった説明を書いておきます。AIはその説明を見て、テストを書く作業のときだけ中身を読み込みます。普段の会話では読まれないので、手順書をたくさん用意しても邪魔になりません。
Hooksの例
Hooksは、「ファイルを編集したら必ずフォーマッタを実行する」「作業を終える前に必ずテストを実行する」といった処理を仕組みとして登録するものです。
指示ファイルに「編集後はフォーマットしてね」と書いても、AIが忘れることはあります。Hooksなら、AIの判断に関係なく必ず実行されます。設定の書き方はツールごとに違うので、使っているツールの公式ドキュメントを確認してください。
自分で整えられるハーネス
ハーネスはツールを作る人だけのものではありません。使う側でも、次の順番で整えていけます。
- 指示ファイルに規約を書く。 コーディング規約やテストの書き方、やってはいけないことを書いておきます。「シニアエンジニアの観点で」と毎回打たなくても、前提が伝わるようになります。
- 仕様書をMarkdown化してリポジトリに置く。 WordやExcelより、AIが読みやすいinputになります。
- 単体テストを整備する。 テストがあれば、AIが自分の変更の正しさを自分で確かめられます。
- 権限の線引きをする。 自動でやってよいことと、必ず確認を挟むことを決めておきます。
- 同じ指摘を3回したら、仕組みにする。 指示ファイルに書くか、Skillにするか、Hooksにするかを考えます。
地味な作業に見えますが、ここを整えるほどAIは頼れる作業者になります。
よくある失敗
指示ファイルに何でも書いて、巨大にする
気づいたことを全部書き足していくと、指示ファイルはすぐに長くなります。毎回すべて読まれるので、重くなるうえに大事なルールが埋もれます。たまにしか使わない手順は、Skillsに移しましょう。
古い指示が残って、矛盾する
規約が変わったのに指示ファイルを直し忘れると、AIは古いルールに従います。指示ファイルもコードと同じく、変更があったら更新するものと考えましょう。
権限を広げすぎる
承認が面倒で、何でも自動で許可すると、思わぬ操作をされたときに止められません。削除や外部への送信など、取り返しのつかない操作は確認を残しておきましょう。
ツールや連携を増やしすぎる
MCPで外部サービスをたくさんつなぐと便利そうに見えます。ただ、使える道具が多すぎると、AIが選択に迷うこともあります。まずは本当に使うものだけにしましょう。
まとめ
「AIの精度がいまいち」と感じたら、モデルを変える前にハーネスを見直してみてください。
仕様書のMarkdown化や単体テストの整備は、実はAIのためのハーネス整備でもあります。人間にとって読みやすく、確かめやすい環境は、AIにとっても働きやすい環境です。
この記事は Zenn にも投稿しています。