ハーネスエンジニアリング入門

1. まず1枚の絵：エンジンと車体

NVIDIAのジェンスン・フアンCEOは2026年5月、エージェントは言語モデルの上で直接動くのではなく、その手前に挟まる「安全に管理されたソフトウェア層」の上で動くと説明した。この層が担うのは、考えて道具を使う手順の繰り返し、外部システムの呼び出し、モデルの使い分け、記憶と文脈の管理、そして暴走の停止や行動の記録。

2. なぜ今、大事なのか

• モデルの差が縮まった：どの会社のAIも、一定以上に賢い。差がつくのは「どう仕事につなぐか」の側になった。
• 人間の統制は、機械の速度に間に合わない：人の担当者なら、権限・承認・監査で管理できた。AIは人間よりずっと速く複数のシステムを動かすので、別の設計が要る。
• 失敗の多くはモデルではなくハーネス側にある：権限が広すぎた、資料が古かった、止める条件がなかった。「もっと賢いAIにすれば解決する」とは限らない。

3. ハーネスの6つの部品

4. mdファイル：ハーネスの本体は「文章」

Claude Code のハーネスは、プログラムではなく、人が読める普通の文章ファイル（Markdown＝「.md」）で作る部分が大きい。AIは会話のたびに「白紙」から始まるので、前回の学びと、守ってほしいルールを持ち越す手段は、mdファイルしかない。ここを理解すると、プログラムが書けなくても、AIの振る舞いを設計できる。

4-1　3種類のmdファイルと、それぞれの役割

4-2　置き場所＝効く範囲

• 上書きではなく、連結される：見つかったすべての CLAUDE.md が、文脈に並べて読み込まれる。広い範囲のものが先、作業フォルダに近いものが後。食い違うときは、近いほうが優先されやすい。
• どこで開いたかで、読まれるものが決まる：案件のフォルダで開けば、その案件の CLAUDE.md とメモリが載る。全案件に効かせたいことは、全体用に昇格させる。

4-3　行数・サイズの限界（2026年10月時点・公式の数字）

行数の限界は「機械的に切られる線」ではなく、「長いほど守られにくい」という目安（CLAUDE.md）と、「それ以降は読まれない」という線（メモリの目次）の2種類がある。長い文章の中ほどが見落とされやすいことは、研究でも知られている（→ ①）。

4-4　使い方の原則

• 書くタイミング：「同じ間違いを2度された」「前回と同じ訂正を、また入力した」「新しく来た人にも同じ説明が要る」。毎回説明し直していることを、文章にする。
• 書くこと：毎回必要な事実（ルール、置き場所、言葉づかい、「必ずこうする」）。書かないこと：複数の手順（→ スキルへ）、一部の場所でしか要らないこと（→ サブフォルダやパス指定へ）、ファイルを見れば分かること（古くなって嘘になる）。
• 確かめられる具体さで書く：「ちゃんと書いて」は守りようがない。次のように、守れたかが分かる書き方にする。

• 見出しと箇条書きで整理する：長い文章より、構造のあるほうが、AIも読みやすい。
• 食い違う指示を残さない：矛盾があると、AIはどちらかを適当に選ぶ。追記を重ねたら、定期的に読み直して、古い指示や矛盾を消す。点検は、Claudeに頼めばよい（「CLAUDE.md を点検して。古い指示・存在しないファイルへの言及・食い違いを、一覧で報告して。直す前に、私に確認して」）。Claude Code には、同じ点検をする機能（/doctor prompt-audit）もある（新しいバージョンのみ）。
• 人間向けのメモは、コメントで書ける：行頭のHTMLコメント（<!-- ... -->）は、AIに読み込まれず、文脈を使わない。
• 会話の中だけで伝えた指示は、消える：長い会話を要約（コンパクト）したとき、案件の直下の CLAUDE.md は読み直されて残るが、会話の中で言っただけの指示は失われる。残したいことは、ファイルに書く。
• 他のAIツールとの共用：他のツールが使う指示書（AGENTS.md）がある場合、CLAUDE.md が無いときだけ読まれる。両方使うなら、CLAUDE.md の中から取り込む。

4-5　長くなったときの直し方（優先順位）

4-6　確認のしかた：コマンドより、Claudeへの頼み方

ターミナルが苦手でも大丈夫。やりたいことを、そのままClaudeに頼めばよい。コマンド（右の列）は、慣れた人向けの参考で、デスクトップアプリでは、使えないものもある。

5. 部品を、もう一段くわしく

① 指示書：短く、判断を書く

• 毎回読み込まれるので、長いほど損をする（目安は200行以内。くわしくは上の「4. mdファイル」）。コストがかかるうえ、肝心のルールが埋もれる（長い文章の真ん中は、見落とされやすいことが研究で知られている）。
• 書くこと：目的／置き場所／やってはいけないこと／言葉づかい／「ここを見れば分かる」という場所。書かないこと：フォルダ一覧の丸写しなど、ファイルを見れば分かること（すぐ古くなって嘘になる）。
• 置き場所＝効く範囲：全員共通のルールは全体用に、案件ごとのルールは案件のフォルダに。詳しい規則は別ファイルに置き、指示書にはそこへの案内だけ書く（真実源を1か所にする）。
• 矛盾する指示を同居させない：「記録を必ず残す」と「メモは書かない」が両方あると、AIは迷う。
• 一律の禁止より、判断の軸：Anthropicは2026年7月、最新のモデルは「周囲に合わせて」と判断を渡すほうが、細かい一律ルールで縛るより良く働く、と整理している。
• 秘密（パスワード・鍵）は絶対に書かない。指示書はコピーされ、チャットにも読み込まれる。

② スキル：必要なときだけ呼ぶ手順書

• 指示書は「常に読まれる」、スキルは「呼んだときだけ読まれる」。手順は、指示書ではなくスキルに入れると、軽く保てる（段階的に開く、という考え方）。
• スキルの中身は、F1の手順書の5項目（出来上がり・材料・手順・人が確認するところ・例外と目安）。
• 置き場所で効く範囲が決まる。どのフォルダからでも使うなら全体用、その案件だけなら案件のフォルダ。

③ 権限：必要な分だけ、渡す

鍵は仕事に必要な最小限だけ渡す。「念のため全部」は事故のもと。

④ 関所：ルールを「どこに置くか」はリスクで決める

ここが一番大事。指示書に「やらないでね」と書くだけでは足りない。AIは確率で動くので、ルールを「ほぼ」守るが、「必ず」ではない。長い文章の中で忘れる、外から紛れ込んだ文章に上書きされる、解釈を間違える、という理由がある。

⑤ 記憶：4種類を使い分ける

プリンストン大学の研究者が提案した整理（CoALA）では、AIエージェントの記憶は4種類。

• 経験は「蒸留」して残す：生のやりとり全部ではなく、教訓だけを残す（例：45分の会話ではなく、「作業を始める前に、必ず対象の環境を確認する」の1行）。
• 忘れる仕組みも要る：状況が変われば、古い教訓は捨てる。何を捨てるかが、使い勝手の質を決める。
• 記憶は、置き場所で効く範囲が決まる：案件ごとの記憶は、その案件を開いたときだけ載る。全部の案件に効かせたいことは、全体用の指示書へ昇格させる。

⑥ 点検：1回で終わらせず、回し続ける

• 点検は、未解決を翌週に持ち越す：指摘して終わりにせず、台帳（簡単なメモでよい）に残して、「先週の指摘は直ったか」を次の点検で確かめる。
• AIが直して、AIが確認して、人が見ない、という並びは避ける。自動で直した箇所は、次の点検で再検証する。
• 点検は、「新しく長持ちするものを作る」仕事ではなく、「調べて報告する」仕事に向く。

6. 「採点表」を持つ（評価）

動かして終わりではなく、「良い仕事」の基準を数字にして、測る。Microsoftのサティア・ナデラCEOは2026年6月、企業の「自分たちのAI」を、基盤モデル＋ハーネス＋自社専用の採点表（private eval）と説明した。一般的なAIの賢さの比較ではなく、自社の仕事で、何を価値とし、何を許されない失敗とするかを決めるもの。

モデルを乗り換えても、この採点表で良い結果が出続けるなら、主導権は自社にある。特定のAIに依存しないと成果が出ないなら、主導権は提供会社側にある。事故になる種類は、測って減点するより、④の関所で止める。

7. 事故から生まれたルール（講師の実例）

ハーネスは机上で考えるより、小さな事故を1つずつルールに変えていくと強くなる。

8. 作り方の手順

小さく始める1週間

9. AIに仕事を任せる前の10の確認

10. よくある失敗

関連資料

• F1 業務の棚卸しと仕組み化 … 手順書の書き方（スキルの材料）
• E1 はじめてのAIエージェント：フォルダ構成と管理 … セットで使う。置き場所と進め方、最初の30分の手順
• E4 Gitの導入と設定 … 変更履歴という「保存の金庫」。ターミナルなしで進められる
• E5 SupabaseとCloudflare … 作ったものの置き場所。RLSと無料枠
• E6 APIキー（秘密）の扱い … .env に頼らず、Vault に置く
• E7 VPSサーバー … 自分のサーバーに、Webアプリを設置するとき
• E3 ローカルLLMと「情報を外に出さない」設計
• C3 事例：この資料ライブラリの自動化・スキル化 … ハーネスの実物
• D1 信号機ルール