Claude Code Academia

第12章 ハーネス設計と運用

ついに最終章です。

ここまでで、Code を使って Web アプリを作って公開するまでの一連の流れが、すべて手元にあるはずです。

第12章では、その先の世界を見ます。「ハーネス」という、Code をさらに高度に使いこなすための考え方。

僕自身、訪看アプリを作り上げた後、「もっと複雑な作業も、Code で安全に進めるには？」と考え始めた時に出会ったコンセプトです。

この章で扱うこと：

  • ハーネスとは何か、なぜ必要か
  • Planner / Generator / Evaluator パターン
  • ハーネスを構築する具体ステップ
  • 評価基準の設計
  • 公開前セキュリティ自己点検

「もう Code は使えるようになった、その次は？」という人のための章です。

12-1. ハーネスとは：Claude Code の上位制御層という考え方

【学習目標】

  • ハーネスという概念を理解する
  • 「Code を直接使う」と「ハーネスを介して Code を使う」の違いを知る

【前提知識】

  • ここまでの全章を読んでいること

【概念解説】

「ハーネス」という言葉、聞き慣れないかもしれません。

馬具の「ハーネス」を思い浮かべると分かりやすい。馬を制御するための「装具」のこと。馬自体は強いし速いけど、ハーネスがあると人間が望む方向に走らせやすくなる。

AI 開発でいう「ハーネス」も同じ。Code 自体は強力だけど、**それを安全に・予測可能に動かすための「装具」**がハーネスです。

ハーネスを使わないとどうなるか

ここまでの章でやってきたのは、基本的に「Code を直接使う」スタイル。

  • 自分が依頼を打つ
  • Code が作業する
  • 結果を見て、次の依頼を打つ
  • 繰り返し

このやり方は、シンプルで強力。でも、規模が大きくなると課題が出てきます。

  • 自分が毎回判断しないといけない
  • 大量の作業を Code に任せたい時に、いちいち承認を求められる
  • 同じパターンの作業を何度もやる時、効率が悪い
  • 失敗を防ぐためのチェックが手動

ハーネスを使うとどうなるか

ハーネスを噛ませると、Code の使い方が変わります。

[自分]
   ↓ ハーネスに指示
[ハーネス]
   ↓ Code に依頼を組み立てる
[Code]
   ↓ 作業を実行
[ハーネス]
   ↓ 結果を評価
[自分] ← 必要な時だけ介入

つまり、自分と Code の間に「自動化層」を挟む。

これによって：

  • 同じパターンの作業を一気に進められる
  • 失敗のチェックが自動化される
  • 自分が監視する負担が減る
  • 大規模なタスクが現実的になる

ハーネスの典型例

  • テスト自動化：Code が書いたコードを自動でテストする仕組み
  • 品質チェック：コードの規約違反を自動で検出
  • 複数 Code の連携：複数の Code セッションを連携させて並列処理
  • Plan の自動評価：Plan の質を自動で評価して、不十分なら修正依頼

「いつ必要になる？」

僕の感覚として、ハーネスが必要になるのは、

  • 訪看アプリのような中規模アプリを「実運用」しはじめた時
  • 同じパターンの作業（新機能追加など）を何度も繰り返す時
  • 「もっと自動化できるはず」と感じた時

最初の数プロジェクトはハーネスなしで進める方が、感覚が掴みやすい。3〜5プロジェクト経験してから、ハーネスを意識するくらいのタイミングが適切です。

【ハンズオン手順】

▼ ブラウザ側でやること（ハーネスの概念を整理）

  1. ブラウザに次のように打つ
AI 開発で言う「ハーネス」とは何ですか？
個人開発者にとって、いつから必要になるものですか？
具体的な例を挙げて、初心者にも分かるように説明してください。
  1. ブラウザが概念を整理してくれる
  2. 自分の感覚と照らし合わせる

【つまずきポイント】

  • 「ハーネスを使わないとプロじゃない」は誤解。直接 Code 使うだけでも、十分に強力
  • 最初からハーネスを目指さない。基礎ができてから

【確認問題】

  • ハーネスを馬具のハーネスに例えた時、Code は何に相当しますか？
  • ハーネスを使う典型的なメリットを2つ挙げてください

【次のレッスンへの橋渡し】

次は、ハーネスを設計する時の代表的なパターン「Planner / Generator / Evaluator」を見ていきます。

12-2. Planner / Generator / Evaluator パターン

【学習目標】

  • 3つの役割を分けて Code を使うパターンを理解する
  • それぞれの役割が何をするかを言葉で説明できる

【前提知識】

  • 12-1 でハーネスの概念を理解していること

【概念解説】

ハーネスを設計する時の代表的なパターンに、「Planner / Generator / Evaluator」というのがあります。

3つの役割：

1. Planner（計画者）

  • やるべきことを設計する
  • 全体の手順を立てる
  • どんな成果物を期待するかを定義
  • 例：「ログイン機能を追加する。フォーム作成、認証連携、状態管理、テストの4ステップ」

2. Generator（生成者）

  • Planner が立てた計画に従って、実際にコードを書く
  • 1ステップずつ実装
  • 例：「フォーム作成のステップ：HTML/CSS を書く」

3. Evaluator（評価者）

  • Generator が書いたコードを評価
  • 計画通りに動くか、品質が満たされているかを判定
  • 例：「フォームは見た目OK。ただし、バリデーションが足りない」

これら3つの役割を別々のセッション（または別々のサブエージェント）で動かすのが、このパターンの肝。

3つを分ける意味

「全部1つの Code でやればいいじゃん」と思うかもしれません。でも、分けるメリットがあります。

1. 役割が明確になる

  • 「計画担当」「実装担当」「評価担当」とハッキリ
  • 役割ごとに違う「視点」で見られる

2. コンテキストを分離できる

  • Planner は計画のために大局を見る
  • Generator は実装の細部を見る
  • それぞれ別のコンテキストウィンドウを使える

3. チェックが入る

  • Generator が好き勝手しないように、Evaluator がチェック
  • 失敗を早期発見できる

実践イメージ

たとえば「アプリ全体のリファクタリング」を頼みたい時、

Step 1：Planner Code に「リファクタリング計画を立てて」と依頼
Step 2：Planner Code が計画を出す
Step 3：Generator Code に計画を渡して「これに従って実装して」と依頼
Step 4：Generator Code が実装
Step 5：Evaluator Code に成果物を渡して「計画通りか評価して」と依頼
Step 6：Evaluator Code が評価
Step 7：問題があれば Generator に戻る、なければ完了

このフローを自分でガイドしながら進める。これがミニ・ハーネス。

僕からのコツ

僕は「最初は、人間が Planner と Evaluator を兼ねる」のがいいと言っています。

  • 自分が「これをやりたい」と Planner として伝える
  • Code が Generator として実装
  • 自分が Evaluator として「これでいいか」をチェック

完全自動化を目指さず、要所要所で自分が役割を担う。これくらいから始めると、感覚が掴みやすい。

【ハンズオン手順】

▼ ブラウザ側でやること（パターンの応用例）

  1. ブラウザに次のように打つ
Planner / Generator / Evaluator パターンを、私の Web アプリ
開発に適用する場合、どんな進め方ができますか？
具体例を3つ挙げてください。
  1. ブラウザが具体例を提案
  2. 自分のプロジェクトに応用できそうな例を選ぶ

▼ Code 側でやること（3役割を意識した依頼）

  1. Code に次のように依頼
私が考えている新機能：[内容]

これを実装するために、3段階で進めたいです：
1. まず計画を提示してください（Planner）
2. 計画を確認したら、実装します（Generator）
3. 実装が終わったら、評価をお願いします（Evaluator）

まず Step 1 として計画を提示してください。
  1. Code が計画を提示
  2. 確認して OK
  3. 実装を依頼
  4. 完了したら評価を依頼

【つまずきポイント】

  • 3役割を厳密に分けすぎない。最初は人間が補完するのが現実的
  • Evaluator のフィードバックを必ず読む。読まないと意味がない
  • 同じセッション内で3役割を回しても十分効果がある。最初から別セッションを使わなくてOK

【確認問題】

  • 3つの役割の名前と、それぞれの仕事は何ですか？
  • 役割を分けるメリットを3つ挙げてください

【次のレッスンへの橋渡し】

パターンが見えました。次は、実際にハーネスを構築するステップを見ていきます。

12-3. ハーネスを構築する具体ステップ

【学習目標】

  • 自分のプロジェクトでハーネスを構築するステップを知る
  • 「シンプルから始める」流儀を身につける

【前提知識】

  • 12-2 で3役割を理解していること

【概念解説】

ハーネスは、いきなり大規模なものを作る必要はないです。シンプルなハーネスから始めるのがコツ。

ハーネス構築の段階

[段階1] CLAUDE.md にチェックリストを書く
   ↓
[段階2] テスト自動化のスクリプトを書く
   ↓
[段階3] 複数 Code の連携を試す
   ↓
[段階4] フル自動化に挑戦

最初は段階1で充分。段階1だけでも、ハーネスの効果は十分体感できます。

段階1：CLAUDE.md にチェックリスト

これが最も簡単なハーネスです。CLAUDE.md に次のようなチェックリストを書く：

# 重要な作業のチェックリスト

重要な変更（新機能追加、認証関連、決済関連）を行う時は、
以下のチェックリストを通してください。

## Planning フェーズ
- [ ] 変更の目的を明確に
- [ ] 影響範囲をリストアップ
- [ ] リスクを評価
- [ ] テスト方法を決定

## Implementation フェーズ
- [ ] 1ステップずつ実装
- [ ] 各ステップでスクショ伴走
- [ ] 既存テストが通ることを確認
- [ ] 新規コードに対するテストを追加

## Evaluation フェーズ
- [ ] 完了条件を満たしているか
- [ ] パフォーマンスへの影響
- [ ] セキュリティへの影響
- [ ] CHANGELOG.md と TODO.md の更新

これだけで、Code が大きな作業を始める時に「自動的にチェックリストを通そう」とする動きが出ます。**「Code に対する自動ガイド」**として機能します。

段階2：テスト自動化のスクリプト

次の段階は、テストの自動化。Code が書いたコードに対して、自動的にテストを実行する仕組み。

1. テストフレームワーク（Vitest や Jest など）を導入
2. Code に「このコードのテストを書いて」と依頼
3. テストを実行
4. 失敗があれば Code に戻して修正依頼

これも Code が手伝ってくれます。

段階3：複数 Code の連携

更に進むと、複数の Code セッションを連携させる段階。

  • セッション A：実装担当
  • セッション B：レビュー担当
  • セッション C：テスト担当

それぞれが別のコンテキストで動いて、結果を統合する。これは僕もまだ模索中の領域。

段階4：フル自動化

最終的には「人間が介入しなくても、Code が連続して大きな仕事を進める」状態。これはまだ未来形の話。僕も「いずれそうなる」と感じていますが、現在は段階1〜2のあたりで実用化しています。

個人開発者は段階1で充分

実用上、ほとんどの個人開発者は**段階1（CLAUDE.md のチェックリスト）**で必要十分です。これがあるだけで、Code の作業品質が安定します。

僕も訪看アプリで使っているハーネスは、段階1のチェックリストレベル。それで十分に効果を発揮しています。

【ハンズオン手順】

▼ Code 側でやること（段階1のチェックリスト導入）

  1. Code に次のように依頼
CLAUDE.md にハーネス的なチェックリストを追加したいです。
Planning / Implementation / Evaluation の3段階で、
それぞれにチェックリストを書いてください。

私のプロジェクトに合った内容にしてください。
  1. Code がチェックリストを追加
  2. 内容を確認・調整

▼ Code 側でやること（チェックリストの効果確認）

  1. 何か中規模の作業を依頼
  2. Code がチェックリストを参照しながら進めているか観察
  3. 必要に応じてチェックリストを改善

【つまずきポイント】

  • チェックリストを長くしすぎない。すべての作業に全項目を通すと、Code が窮屈に
  • 「重要な作業」の定義を明確に。何が重要か Code に分かるように
  • 段階2以降は無理に進めない。必要性を感じてから

【確認問題】

  • 最も簡単なハーネスの実装は何ですか？
  • 個人開発者はどの段階まで必要ですか？

【次のレッスンへの橋渡し】

具体的な構築ステップが見えました。次は、ハーネスの中核となる「評価基準」の設計について。

12-4. 評価基準の設計

【学習目標】

  • 「いい仕事」を評価する基準を自分で設計できる
  • Code に評価を頼む時の指針を持つ

【前提知識】

  • 12-3 までを読んでいること

【概念解説】

ハーネスの中で「Evaluator」が機能するためには、評価基準が明確である必要があります。

「いい実装」「悪い実装」を Code が判断するための、明確な物差し。

評価基準の典型例

実装の品質を評価する時の基準：

1. 機能的正しさ

  • 仕様通りに動くか
  • エラーケースをハンドリングしているか
  • 期待通りの結果を返すか

2. コード品質

  • 読みやすいか
  • 命名が適切か
  • 重複がないか
  • コメントが適度か

3. パフォーマンス

  • 動作が速いか
  • メモリを過剰に使わないか
  • 不要な処理がないか

4. セキュリティ

  • 認証が必要なところに認証があるか
  • データ漏洩のリスクがないか
  • 入力検証があるか

5. テスタビリティ

  • テストを書ける構造か
  • 副作用が分離されているか

これらを CLAUDE.md に書いておくと、Code が評価する時に参照してくれます。

評価基準を CLAUDE.md に書く例

# コード評価基準

## 機能的正しさ
- 仕様書に記載の機能をすべて満たすか
- エラーケース（無効入力、ネットワーク障害、認証失敗）を適切に処理するか

## コード品質
- 関数名・変数名は意図が明確か
- 1関数の長さは50行以内が目安（超える場合は分割を検討）
- マジックナンバー（直接書かれた数値）は定数化する
- コメントは「なぜ」を説明する（「何」はコードを読めば分かる）

## パフォーマンス
- ユーザー操作への反応は100ms以内
- API リクエストはバッチ化、または並列化
- 不要な再レンダリングを避ける

## セキュリティ
- ユーザー入力は必ずバリデーション
- SQL は parameterized query
- API キーや個人情報をクライアント側に露出しない

## ドキュメント
- 新規関数には JSDoc または日本語コメント
- 重要な設計判断は CHANGELOG.md に記録

これを CLAUDE.md に書いておくと、Code に「このコードを評価して」と頼んだ時に、この基準で評価してくれます。

評価結果の使い方

評価結果が出てきたら：

1. 「機能的正しさ：OK」→ 次へ
2. 「コード品質：要改善」→ 改善点を Code に伝えて修正依頼
3. 「パフォーマンス：未確認」→ パフォーマンステストを追加
4. 「セキュリティ：要確認」→ セキュリティ専門の評価をもう一度

評価を「やりっぱなし」にしない。改善点があれば、必ず修正依頼に戻す。

僕の実例

僕は訪看アプリのリリース前に、Code に次のように依頼しました：

このアプリを公開前に評価してください。次の観点で：
- 機能的正しさ
- セキュリティ
- パフォーマンス
- ユーザビリティ

問題があれば、優先度付きで指摘してください。

Code が10数項目の指摘を出して、優先度の高いものから順に対応していった、というプロセスを経ました。

【ハンズオン手順】

▼ Code 側でやること（評価基準の作成）

  1. Code に次のように依頼
このプロジェクトに合った「コード評価基準」を、CLAUDE.md に
追加してください。

機能・品質・パフォーマンス・セキュリティの観点を含めて、
日本語で書いてください。
  1. Code が CLAUDE.md に追記
  2. 内容を確認

▼ Code 側でやること（評価を実行）

  1. プロジェクトの主要なファイルを Code に評価させる
このプロジェクトのコードを、CLAUDE.md に書いた評価基準に
照らして評価してください。改善点を優先度付きでリストアップ。
  1. Code が評価結果を出す
  2. 優先度の高いものから対応

【つまずきポイント】

  • 評価基準を完璧にしようとしない。最初は粗くてOK、運用しながら磨く
  • すべての評価項目をクリアしないと公開できない、と思わない。重要度に応じて
  • 評価結果を読まないと意味がない。必ず目を通す

【確認問題】

  • 評価基準の典型的な観点を5つ挙げてください
  • 評価結果を「やりっぱなし」にしないために、どうしますか？

【次のレッスンへの橋渡し】

評価基準が設計できました。本書最後のレッスンは、特に重要な「公開前のセキュリティ自己点検」です。

12-5. 公開前セキュリティ自己点検と、よくあるエラーへの対処

【学習目標】

  • アプリを公開する前のセキュリティチェックリストを持つ
  • よくある運用エラーへの対処を知る

【前提知識】

  • ここまでの全章を読んでいること

【概念解説】

本書の締めくくりとして、公開前に絶対やっておくべきセキュリティチェックを整理します。

ブラウザでセキュリティチェックを依頼する

僕がやっているのは、ブラウザに次のような相談をすること：

私が作った Web アプリを公開する前に、セキュリティ的に
チェックすべき項目をすべてリストアップしてください。

技術構成：
- フロントエンド：HTML/CSS/JS
- バックエンド：Supabase
- ホスティング：Cloudflare Pages
- 認証：Supabase Auth
- 決済：Stripe（テストモード）

個人開発者が見落としがちな点を含めて教えてください。

ブラウザが綿密なチェックリストを返してくれます。

典型的なセキュリティチェック項目

1. 環境変数の確認

  • .env が GitHub に上がっていないか
  • .gitignore に .env が含まれているか
  • API キーが Public リポジトリに含まれていないか

2. RLS Policy の確認

  • すべてのテーブルに RLS が有効か
  • Policy がちゃんと意図通りに動くか
  • SELECT * が public で許可されていないか

3. 認証フローの確認

  • パスワード強度の設定
  • メール認証の必要性
  • セッションタイムアウト

4. CORS 設定

  • Site URL が正しく設定されているか
  • Redirect URLs が許可リストに入っているか
  • 不要なドメインが許可されていないか

5. 入力バリデーション

  • フォーム入力に対するバリデーション
  • SQL インジェクション対策
  • XSS（クロスサイトスクリプティング）対策

6. データ漏洩リスク

  • ログにパスワードや API キーを書いていないか
  • ブラウザの localStorage に機密情報を保存していないか

7. 決済関連

  • Webhook の署名検証
  • Secret key の保護
  • テストデータと本番データの分離

よくあるエラーと対処

実運用が始まると、いろんなエラーに出会います。代表的なものと対処：

1. CORS エラー

「CORS policy: No 'Access-Control-Allow-Origin' header...」
  • 原因：Supabase の Site URL や Redirect URLs が正しく設定されていない
  • 対処：Supabase ダッシュボードで本番ドメインを許可

2. 認証エラー

「Invalid login credentials」
  • 原因：メールアドレスやパスワードの誤り、または認証状態の不整合
  • 対処：Code に「認証フローを確認して」と依頼

3. RLS Policy エラー

「new row violates row-level security policy」
  • 原因：RLS Policy が厳しすぎて、本来許可されるべきアクセスが拒否されている
  • 対処：Code に「この Policy を見直して」と依頼、auth.uid() の判定を確認

4. API キーが見えない

ブラウザの開発者ツールで API キーが見える
  • 原因：anon key は公開でOKだが、service_role key は絶対にダメ
  • 対処：service_role key をクライアント側で使っていないか確認、漏洩していたら即時無効化

5. デプロイ失敗

「Build failed」
  • 原因：依存ライブラリの問題、ビルド設定の誤り
  • 対処：ビルドログをスクショして Code に貼って解析

最後のメッセージ

ここまでお疲れさまでした。

本書は、僕が3週間で訪看アプリを作り上げた経験を、できるだけ忠実に「学習可能な型」に落とし込んだものです。

12章74レッスンを通じて伝えたかったことは、シンプルです：

「専門職に頼まないと無理」と思っていたことが、自分の手で出来る時代になった

14年前、僕が Web デザイナーを雇って WEB 制作を始めた頃、コードを書ける人とそうでない人の間には深い壁がありました。

今、その壁は消えつつあります。Code がいれば、誰でも作りたいものを作れる。

ただし、それは「Code に丸投げ」ではない。自分が脳の主役で、Code が手と並走相談者、というスタンスを持ち続けることが大事。スクショ伴走モデル、作業開始の儀式、CHANGELOG / TODO の習慣、評価基準の設計……。これらは全部、「自分が主役で、Code を活用する」ための型でした。

これからアプリを作る皆さんへ。最初は失敗しても、Code とブラウザがそばにいます。1工程ずつ、スクショを撮って、確認しながら、進んでください。

作りたいものを、自分の手で作れる時代へ、ようこそ。

【ハンズオン手順】

▼ ブラウザ側でやること（自分のアプリの最終チェック）

  1. ブラウザに次のように依頼
私が作った Web アプリの公開前最終チェックをお願いします。

技術構成：[自分のアプリの構成]

セキュリティ、機能、パフォーマンス、ユーザビリティの
4観点から、優先度付きで点検項目をリストアップしてください。
  1. ブラウザが点検項目を提示
  2. Code と一緒に1項目ずつ対応

▼ Code 側でやること（実装の最終評価）

  1. Code に次のように依頼
CLAUDE.md の評価基準に基づいて、このアプリ全体を最終評価してください。
優先度の高い改善点があれば、リストアップしてください。
  1. Code が評価結果を出す
  2. 対応

▼ CHANGELOG.md と TODO.md の最終整理

  1. Code に「現時点のすべての作業を CHANGELOG.md に整理してください」と依頼
  2. TODO.md は「公開後にやりたいこと」を整理

【つまずきポイント】

  • 「セキュリティを完璧に」と思わない。最低限の項目を押さえてから、運用しながら改善
  • ブラウザのチェックリストを盲信しない。自分のアプリの特性も踏まえて判断
  • 最終チェックで100点を目指さない。70点で公開して、運用しながら90点に持っていく

【確認問題】

  • 公開前のセキュリティチェックで、最も優先度が高い項目は何だと思いますか？
  • 運用中のエラーに出会った時の基本動作は何ですか？

【最終メッセージ】

僕が訪看アプリを作って、現場からの「こんなアプリがあったらいいのに」を実装で応えていったように、あなたも自分の現場の課題を、自分の手で解決できる。

あなたはその力を手に入れました。

おめでとうございます。

お疲れさまでした。

← 第11章