AIハーネス入門 — AIに安全に良い仕事をさせる環境づくり

AI(Claude Code など)と開発するとき、成果の質を決めるのは「AIへの頼み方」よりも、AIが働く環境をどれだけ整えたかです。この環境一式をハーネス(harness)と呼びます。

このシリーズは、実際に運用されているプロジェクト(MulmoClaude など)の設定を題材に、ハーネスの主要な部品を具体的な設定サンプルつきで解説します。

ハーネスってなに？

ハーネス(harness)は、もともと馬具 — 馬に着ける手綱や引き具のことです。馬の力を殺さずに、進む方向と速度を人が制御するための道具です。

AI開発の文脈では、AIが安全に・良い仕事をできるように、人間が整えておく「ルールと道具の一式」を指します。AIの能力はそのままに、暴走や脱線だけを防ぐ、という発想です。

なぜ必要？ — 「口頭の注意」は毎回忘れられる

AIとの会話で「テスト書いてね」「any 使わないでね」と注意しても、その効果はその会話の中だけです。次のセッションの AI は何も覚えていません。人間の新人なら一度言えば覚えますが、AI は毎朝記憶を失った状態で出社してくる新人のようなものです。

だから、注意を環境に埋め込みます。

口頭の注意(毎回忘れられる) ハーネス(毎回自動で効く)
「any 使わないでね」 ESLint が any をエラーにする
「コミット前にテスト回してね」 commit しようとすると自動でテストが走る
「このプロジェクトでは yarn を使ってね」 CLAUDE.md に書いておく(毎セッション自動で読まれる)
「勝手にファイル消さないでね」 権限設定で削除コマンドを許可しない
「レビューしてからマージしてね」 CI が PR ごとに別のAIレビューを自動で走らせる

「気をつけてね」と言う代わりに、気をつけなくても事故が起きない環境を作る — これがハーネスの中心思想です。

AI時代にハーネスの価値が跳ね上がった理由

ハーネスの部品(lint、テスト、CI)自体は昔からあります。AI時代に重要度が跳ね上がったのには理由があります。

  1. AIは書く量が桁違いに多い — 人間のレビューが追いつかない。機械のチェックで先に止めるしかない
  2. AIは指摘されれば文句を言わず直す — lint エラーは人間には小言だが、AIには「自動修正ループの燃料」。厳しくすればするほど品質が上がる
  3. AIは記憶を持たない — 環境に埋め込まれたルールだけが、セッションをまたいで一貫性を保つ

つまり、人間チームでは「厳しすぎて運用できない」ルールが、AIチームでは低コストで運用できる。だから遠慮なくガチガチにしてよい(第2章で実例を見ます)。

ハーネスが立脚する「AIという道具の性質」

姉妹編のリファクタリングの心得が「事実 → だから」で整理している通り、ハーネスの各部品は AI の性質から素直に導かれます。この表がシリーズ全体の地図にもなっています。

AIの性質(事実) だから(対策) 詳しくは
確率で生成するので、自信満々に間違える(幻覚) 機械で検証する: 型・lint・テスト・CI 第2章
渡されたコンテキスト(範囲)しか見えない コードは小さく・良い名前・型付きに。決まりと文脈は CLAUDE.md で明示的に渡す 第1章・第2章
学習データに多い「枯れた」技術ほど正確 定番の技術を選ぶ(AIがよく知っている = 幻覚と手戻りが減る) リファクタリングの心得
生成は速いが、人間が読める量が律速 小さく刻む(コミット/PR)+ レビューの網を増やす 第3章・Gitのルール
What は書くが Why は残さない 意図を CLAUDE.md・PR説明・決定記録に残す。AIに渡す md も全部 git 管理 第1章
「動く」を優先し、危険な書き方や過剰な抽象を出しがち セキュリティ lint + 最終判断は人間 第2章・第3章

ハーネスの部品一覧

部品 何をするか どこで設定するか 詳しくは
ルール(CLAUDE.md) プロジェクトの約束事を毎セッション AI に読ませる CLAUDE.md / ~/.claude/CLAUDE.md 第1章
整形(formatter) 書き方の揺れを機械的に統一 Prettier 第2章
lint まずい書き方・バグの芽を自動で指摘 ESLint 第2章
型チェック データの形の食い違いをコンパイル時に検出 TypeScript (tsc --noEmit) 第2章
テスト 「壊していないか」を毎回自動で確認 node:test / vitest / Playwright Vibe Coding
CI push のたびに上の全部を走らせる番人 GitHub Actions CI/CD入門
フック(hooks) AIの特定の行動に自動チェックを割り込ませる .claude/settings.json 第4章
権限(permissions) AIができる操作の範囲を制限する .claude/settings.json 第4章
レビュー体制 別のAI・別の人の目でチェックする subagent / CI cross review 第3章

このシリーズの読み方

  • ハーネスをこれから整える人 → 第1章から順に。まず約束を書き(第1章)、機械の強制に格上げし(第2章)、別の目のレビューを足し(第3章)、最後に破りようのない強制力で固める(第4章)
  • すでに Claude Code を使っている人 → 自分のプロジェクトに欠けている部品を上の一覧表で探して、該当章へ

各章

  1. CLAUDE.md の書き方 — AIへの「就業規則」を網羅的に — 置き場所の使い分け、書き方の7原則、フル装備テンプレート、実例の構成解剖
  2. AI向けガチガチ lint — Vue/React + Express の ESLint 設定 — lint とは何かから、インストール、コピーして使える設定、ルールごとの「なぜ」まで
  3. subagent と cross review — AIの仕事を別のAIがチェックする — 三重の網、CI で回す別AIレビュー、指摘のトリアージ
  4. フックと権限 — 破りようがない強制力 — commit 前の全チェック強制、最小権限、約束/チェック/強制の使い分け

付録:

合わせて読む

Table of contents