This article is part of the "Road to Web 4.0" series. Originally published in Japanese on note.com.
Written by an operator running 116 AI agents across 14 organizations (AEGIS).
Claude Codeを3ヶ月間、毎日8時間使い続けた。
その中で磨き上げたテンプレートを全公開する。
テンプレートがあるかないかで、AIの出力品質は根本的に変わる。設定ファイルのコピペだけで生産性が2倍になる。大げさではない。
なぜテンプレートが重要なのか
Claude Codeは賢い。しかし、何も指示しなければ「賢いが方向性のない」出力をする。
CLAUDE.mdにルールを書いておけば、全ての会話で自動的に読み込まれる。一度書けば、永久に効く。
この記事に含まれるテンプレートは6つだ。
1つ目はCLAUDE.md。プロジェクト全体のルールを定義する。これが土台になる。2つ目はスキル定義。再利用可能なワークフローを自動化する。3つ目はエージェントプロンプト。AI人格と権限を定義する。4つ目はフック設定。コミット時の自動チェックを仕込む。5つ目はマルチエージェント連携。複数AIの協調ルーティング。6つ目は品質ゲート。7段階の自動検証チェックリスト。
全て、僕が実際に毎日使っているテンプレートがベースだ。
無料サンプル: CLAUDE.md 基本構造
まずは誰でも使える基本テンプレートを公開する。
# CLAUDE.md
## プロジェクト概要
[プロジェクト名]は[目的]のための[種類]です。
## 技術スタック
- 言語: [Python/TypeScript/etc]
- フレームワーク: [FastAPI/Next.js/etc]
## コーディング規約
- ファイル上限: 300行（超えたら分割）
- 命名: snake_case（Python）/ camelCase（JS）
- エラー: 例外は握りつぶさない、構造化ログに記録
## セキュリティ
- シークレットは絶対にコードに書かない
- 環境変数経由（デフォルト値は空文字列）
## 禁止事項
- [プロジェクト固有の禁止パターン]
これだけでも出力は格段に改善される。
僕が最初にCLAUDE.mdを書いたとき、Claude Codeの出力が一気に安定した。それまではファイルごとにコーディングスタイルがバラバラだったのが、プロジェクト全体で統一された。
しかし、これは入口に過ぎない。実戦で3ヶ月使い込んだテンプレートは、レイヤー別ルール、意思決定記録、承認フロー、セキュリティゲートまで含む。
ここから先は有料です
テンプレート1: CLAUDE.md 実戦版
基本版との違いは、レイヤー別ルールと意思決定記録の組み込みだ。
レイヤー別に分ける理由は明確で、バックエンドとフロントエンドでは品質基準が全く違うからだ。
バックエンド層には3つのルールを入れる。まずファイルサイズ制限。ルーター300行、サービス400行を超えたら分割する。次にセキュリティテスト4パターン。未認証は401、権限不足は403、他テナントのデータアクセスは404（存在を漏らさないために403ではなく404）、不正入力は422。最後にDB操作のパターン。サービス関数がDBセッションを引数で受け取る形にする。
フロントエンド層にはデザイントークン変数のみ使用を定義する。ハードコードされたカラーコードやフォント名は禁止。アクセシビリティ基準として、タッチターゲット44px以上、コントラスト比4.5:1以上も明記する。
インフラ層には外部API呼び出しのタイムアウト5秒とフォールバック値、サーキットブレーカー（連続失敗5回で回路オープン）、全サービスへのヘルスチェックエンドポイント設置を定義する。
最も見落とされがちなのが「意思決定の記録」セクションだ。日付、決定内容、理由、却下した代替案を形式として定めておく。Claude Codeはこの記録を読んで、過去の判断と一貫した決定を下せるようになる。プロジェクトが長期化するほど、この蓄積が効いてくる。
テンプレート2: スキル定義
スキルは再利用可能なワークフローだ。一度定義すれば、関連するタスクで自動的に発動する。
トリガー条件をキーワードとファイルパターンで定義する。例えば「リファクタリング」「コード改善」というキーワードと、対象ファイルパターン「.py」「.ts」を指定しておく。
核心は4フェーズ構成だ。
フェーズ1の調査では、対象ファイルの読み込み、同ディレクトリの既存パターン確認、変更の影響範囲特定を行う。
フェーズ2の計画では、変更計画の策定、リスク評価、テスト計画を立てる。
フェーズ3の実行では、計画に沿って実装し、各ステップで検証する。
フェーズ4の検証では、lint実行、テスト実行、セキュリティスキャンを走らせる。
なぜ4フェーズが重要か。Claude Codeは指示が曖昧だと、調査を飛ばしていきなり実装に入ることがある。フェーズを明示することで、順序が保証される。
末尾にはチェックリストを付ける。既存パターンに従っているか、テストが通るか、セキュリティルール違反がないか、ファイルサイズ上限を超えていないか。完了条件を明確にすることで、中途半端な成果物を防ぐ。
テンプレート3: エージェントプロンプト
複数のAIを使い分けるときのプロンプト構造。
最も重要なのは「判断基準の優先順位」だ。例えばセキュリティエージェントなら「セキュリティ > コンプライアンス > 信頼性 > パフォーマンス」と定義する。矛盾する要求を受けたとき、何を優先するかが自動的に決まる。
権限スコープも明示する。自律実行可能なタスク、承認が必要なタスク、絶対に禁止するアクション。この3分類で暴走を防ぐ。
報告先、連携先、報告形式も定義しておく。エージェント間の通信が構造化される。
テンプレート4: フック設定
品質の自動化に欠かせない。pre-commitフックにシークレット検知（失敗時はblock）、リント（block）、型チェック（warn）を設定する。
post-tool-useフックでサプライチェーン検証を走らせる。環境変数の外部送信や疑わしいパッケージを自動検知する。
on_failure設定が鍵だ。シークレット検知は必ずblock。認証情報がコードに混入するのは、warnで済む問題ではない。
テンプレート5: マルチエージェント連携
複数のAIエージェントが協調する場合に不可欠なルーティング定義だ。
まずデフォルトのエントリーポイントを決める。全メッセージがまずセクレタリーを通る。セクレタリーはキーワードから意図を解析し、適切な組織にルーティングする。
ルーティングテーブルは意図ベースで定義する。「収益」「マネタイズ」ならレベニュー組織、「コード」「バグ」ならプロダクト組織、「セキュリティ」「脆弱性」ならセキュリティ組織。
SLAも優先度別に設定する。criticalは即時（SLAなし）、highは4時間以内、standardは24時間以内。SLAがなければ依頼は永遠に放置される。
最重要はhalt_authority。セキュリティ組織とバックオフィス組織にだけ、全組織を停止する権限を与える。この非対称な権限設計が、安全な自律運用を可能にする。
エスカレーションルールも忘れずに。組織間の対立は議長が裁定、タイムアウトはオペレーター（人間）に上げる。最終的な安全網は常に人間だ。
テンプレート6: 品質ゲート
7ステップの自動検証スクリプトだ。CIパイプラインに組み込む。
ステップ1は構文チェック。ステップ2はリント。ステップ3はシークレット検知。ステップ4は依存関係の脆弱性チェック。ステップ5はテスト実行。ステップ6はカバレッジ確認（最低80%）。ステップ7はレジリエンスチェック（タイムアウト設定、サーキットブレーカーの有無）。
ただし全てを毎回実行するのは非効率だ。変更規模でティア分けする。
1ファイルの変更ならリント + シークレット検知だけで十分。複数ファイルの変更ならテストを追加する。新プロジェクトや大規模リファクタリングなら全7ステップ実行。この段階的な適用が、開発速度と品質のバランスを取る鍵だ。
組み合わせ方
6つのテンプレートは組み合わせると真価を発揮する。ただし、最初から全部導入する必要はない。
まずCLAUDE.mdから始める。次にフック設定で品質を自動化する。スキル定義で繰り返しワークフローを効率化する。必要に応じてエージェントプロンプト、マルチエージェント連携、品質ゲートを追加していく。
テンプレートは「使いながら育てる」ものだ。最初から完璧を目指さない。使っていく中で、足りないルールを追加し、不要なルールを削除する。自分のプロジェクトに合わせて最適化していく。
3ヶ月後には、あなただけのテンプレート体系ができているはずだ。そしてその体系こそが、Claude Codeを本当のパートナーに変える鍵になる。
この記事が参考になったら、スキとフォローをお願いします。Claude Codeの実践テクニックを定期的に発信しています。
Claude, AI, プログラミング, テンプレート, 開発
Top comments (0)