Claude Code 軽量ハーネス：型チェック＋テスト＋確認だけ回す最小ループ

「これくらいの修正、サッとやっといて」

個人ブログの文言を1つ直したかっただけなのに、Claude Code は気を利かせて隣のコンポーネントもリファクタし、ついでに古い内部リンクも一括置換していました。差分は12ファイル。動くには動く。でも、僕が頼んだのは1行の修正です。

このとき思ったんです。大げさな安全装置はいらない。でも「直した結果がちゃんと動くか」だけは、毎回機械に見てほしい、と。

ハーネス（harness、AIエージェントの足場）の全体像を作り込むのは、チーム開発や本番運用なら正解です。ただ、僕みたいに一人で小さいサイトをいじる場面では、フル装備は重すぎる。そこで使っているのが、**型チェック・テスト・公開確認の3つだけを回す「軽量ハーネス」**です。今日はこれを、コピペで動く形で渡します。

この記事の要点（先に結論）

• 個人開発・小規模サイトに、承認待ちや権限管理を全部盛った本格ハーネスは過剰。最小の検証ループだけで事故の8割は防げる。
• 軽量ハーネスの中身はたった3つ。型チェック → テスト → 公開確認。この順で1回だけ回す。
• Claude Code に渡すのは「良い感じにして」ではなく、この3つのコマンドが緑になるまで直してという指示。判断を人の目から機械に移す。
• 下に置いた30行のシェルスクリプトをコピペすれば、今日から自分のリポジトリで回せる。
• 軽量で足りなくなったら、本格的なスモークテストのループやハーネスエンジニアリングの全体像へ段階的に育てればいい。

軽量ハーネスって、何を省いたもの？

ハーネスをフルで組むと、だいたいこういう部品が並びます。読ませる範囲の制限、危険な操作の承認待ち、権限の記録、ログの保存、通知。どれも本番では効きます。

でも、一人で作っている個人サイトを思い出してください。本番DBに勝手に書く道具なんて、そもそも渡していない。force push で泣くのは自分だけ。承認ボタンを押すのも自分。つまり**「他人を守る仕組み」の多くが、最初は要らない**んです。

それでも事故は起きます。理由は1つで、直した結果を確かめずにコミットするから。型が壊れている、テストが落ちている、公開URLが真っ白。この3つは、人が目視で見落としても、機械なら一瞬で気づきます。

だから軽量ハーネスは、こう割り切ります。

• 省くもの：承認待ち、権限管理、ログ保存、通知（小規模なら後回しでいい）
• 残すもの：型チェック・テスト・公開確認の3点だけ

補助輪を全部つけるんじゃなくて、転んだら一番痛い1本だけ先に張る。そういう発想です。

軽量ハーネスの中身は3つだけ

順番が大事なので、表にしておきます。上から順に回すと、失敗が早く・安く見つかります。

順番	見るもの	使うコマンド例	落ちたら何がわかるか
1	型チェック	npx tsc --noEmit	引数の型ミス、消し忘れた参照
2	テスト	npm test	既存の動きを壊していないか
3	公開確認	curl -I http://localhost:4321/...	ページが本当に表示されるか

ポイントは順番です。型チェックは数秒で終わるのに、テストやビルドより前に大量のミスを拾えます。速くて安い検査を先に置くと、Claude Code が直す回数も減ります。

3番目の「公開確認」を入れているのには理由があります。型もテストも緑なのに、公開URLがトップページのフォールバックに化けていて、記事が出ていなかった——これ、僕が実際にやった失敗です。200 OK は「サーバーが落ちていない」だけで、「狙ったページが出ている」の保証にはなりません。だから h1 や本文の一部が含まれているかまで、軽く見ます。

ちなみに、ここで「読む範囲を狭く決める」「危険操作は人に聞く」まで足したくなったら、それはもう軽量の卒業サインです。そのときはハーネスエンジニアリングの全体像を読んでください。初見のリポジトリを触る前提なら、先にrepo map で地図化する手順を挟むと、どこを検証対象にすべきかが見えてきます。

コピペで動く：30行の検証ループ

説明より動かしたほうが早いです。型チェック・テスト・公開確認を上から順に回し、どれか1つでも落ちたらそこで止まるスクリプトを置きます。verify.sh として保存してください。

#!/usr/bin/env bash
# 軽量ハーネス：型チェック → テスト → 公開確認 を順に回す。
# どれか1つでも失敗したら、その場で止めて理由を出す。
set -euo pipefail

URL="${1:-http://localhost:4321/}"   # 確認したい公開URL（引数で上書き可）
MUST_CONTAIN="${2:-<h1}"             # ページに必ず含まれてほしい文字列

echo "▶ 1/3 型チェック (tsc --noEmit)"
npx tsc --noEmit \
  || { echo "✗ 型エラーで停止。引数の型か、消し忘れた参照を見直して。"; exit 1; }

echo "▶ 2/3 テスト (npm test)"
npm test --silent \
  || { echo "✗ テスト失敗で停止。既存の動きを壊していないか確認して。"; exit 1; }

echo "▶ 3/3 公開確認 ($URL)"
status=$(curl -s -o /tmp/page.html -w "%{http_code}" "$URL")
if [ "$status" != "200" ]; then
  echo "✗ HTTP $status。サーバーが起動しているか、URLが正しいか確認して。"; exit 1
fi
if ! grep -q "$MUST_CONTAIN" /tmp/page.html; then
  echo "✗ 200 だが '$MUST_CONTAIN' が無い。トップへのフォールバックを疑って。"; exit 1
fi

echo "✓ 3つとも通過。コミット前の最低条件は満たしている。"

使い方はこれだけです。

chmod +x verify.sh
./verify.sh "http://localhost:4321/blog/my-post/" "<h1"

30行ですが、もう「速い検査から順に」「落ちたら即停止」「理由を日本語で返す」という、ハーネスの骨格がそろっています。set -euo pipefail のおかげで、想定外のコマンド失敗もそこで止まります。あとは自分のプロジェクトに合わせて、tsc を npm run lint に替えたり、確認URLを増やしたりするだけです。

TypeScript を使っていない素のサイトなら、1番目を npm run build（ビルドが通るか）に差し替えれば、そのまま回ります。

Claude Code への渡し方が9割

スクリプトを用意したら、Claude Code への頼み方を1つ変えます。「良い感じにして」をやめて、検証コマンドを合格条件として渡す。これだけで挙動が変わります。

下のプロンプトをそのままコピペしてみてください。

このリポジトリで小さな変更を1つだけ行いたいです。

変更内容: （ここに1行で。例：トップ記事カードの日付表記を YYYY-MM-DD に統一）

ルール:
- 触っていいファイルは変更内容に直接関わるものだけ。ついでのリファクタは禁止。
- 変更後、必ず `./verify.sh` を実行する。
- 3つの検査（型・テスト・公開確認）が緑になるまで、自分で原因を読んで直す。
- どうしても緑にできない場合は、推測で直さず、落ちたログの該当行を貼って僕に聞く。

狙いは、判断の基準を「人の好み」から「機械が緑かどうか」に移すことです。Claude Code は失敗ログの最後の行だけ見て見当違いを直しがちなので、「該当行を貼って聞く」という逃げ道を先に用意しておくと、暴走せずに止まってくれます。

この「最小の検証を回させて、緑になるまで直させる」発想を、ビルド失敗の自動修正まで広げたのがスモークテストのループ記事です。回数上限や確認ゲートの付け方は、そちらが詳しいです。

僕がやらかした失敗3つ

正直に書きます。軽量ハーネスにたどり着くまで、けっこう転びました。

ひとつ目は、最初から全部盛りにしようとしたこと。承認待ちもログも通知も、と欲張った結果、設定だけで半日溶けて、肝心の記事修正に手が回りませんでした。個人開発では、まず3点だけ。重くしたくなったら足す、で十分でした。

ふたつ目は、公開確認をサボったこと。型もテストも緑だから安心してコミットしたら、本番の記事URLが404のままでした。原因は slug のタイプミス。curl で1行確認していれば30秒で気づけた事故です。それ以来、3番目の検査は絶対に外しません。

みっつ目は、Claude Code に「いい感じに直して」と渡し続けたこと。良い感じは人によって違うので、毎回ブレる。検証コマンドという共通言語を渡してからは、「緑になったら完了」で会話が一気に短くなりました。

軽量で足りなくなったら、どう育てる？

軽量ハーネスは入口です。使っているうちに「ここは自動で止めたい」が増えてきたら、順番に足していきます。

1. まず読ませる範囲の宣言を足す。触っていいフォルダ、触らないファイルを最初に書かせる。
2. 次に危険操作のゲート。削除・本番反映・課金・force push は「人に聞く」で固定する。
3. 最後に記録と通知。何をどのコマンドで確認したかを残す。チームならハーネスエンジニアリングの全体像の形まで育てます。

この順番なら、いきなり重くならずに、必要なぶんだけ安全装置が増えます。逆に言えば、一人で小さいサイトをいじっている間は、1番目のスクリプトだけでかなり戦えます。

よくある質問

Q. TypeScript を使っていません。型チェックは飛ばしていい？ A. はい。1番目を npm run build（ビルドが通るか）に差し替えてください。ビルドエラーは型エラーと同じくらい安く事故を拾えます。素のHTMLサイトなら、リンク切れチェッカーを1番目に置く手もあります。

Q. テストを書いていないプロジェクトでも意味ある？ A. あります。2番目を飛ばして「型（またはビルド）＋公開確認」の2点でも、白画面やビルド崩れは防げます。テストは後から1本ずつ足せば、そのぶん網が細かくなります。

Q. 本格的なハーネスとの境目はどこ？ A. 「他人やお客さんを守る必要が出たら」が境目です。本番DB、課金、チームでの共同編集が絡んだら軽量を卒業します。判断のしかたはハーネスエンジニアリングの全体像に書きました。

Q. Claude Code 側の権限設定はどうすれば？ A. 軽量のうちは、検証コマンドの実行だけ許可しておけば十分です。許可・確認・拒否の考え方は公式のPermissions ドキュメントが一次情報なので、そこを基準にしてください。

Q. verify.sh が Windows で動かない。 A. Git Bash か WSL で実行してください。PowerShell 派なら、3つのコマンドを順に呼んで途中で失敗したら止める、という同じ構造を if ($LASTEXITCODE -ne 0) で組めば、考え方はそのまま移せます。

実際に試した結果

冒頭の「12ファイル事故」以来、僕は Claude Code を信じるかどうかで悩むのをやめました。代わりに見るのは、verify.sh が緑かどうかだけです。

型チェックを1番目に置いてから、消し忘れた参照による事故はほぼゼロになりました。公開確認を3番目に足してから、白画面のまま公開する事故も止まりました。そして「緑になるまで直して」と渡すようにしてから、差分レビューの会話が体感で半分になりました。

賢いAIを探すより、転んでも痛くない検証ループを先に1本張る。個人開発なら、これがいちばん速い、というのが今の実感です。重さが足りなくなったら、そのときスモークテストのループへ進めばいい。まずは上の30行を、自分のリポジトリで1回回してみてください。

もっと体系的に学びたい人や、チームへの導入を相談したい人は、研修・相談もどうぞ。