この記事について
GitHub Copilot、Claude Code、Gemini Code Assist、Cursor など、AIコーディング支援ツールが当たり前になってきた。しかしデフォルトのままでは、プロジェクト固有の規約やレビュー方針を無視したコードや提案が出てくることも多い。
各ツールには「リポジトリにファイルを置くだけで、AIにプロジェクト固有の指示を与えられる」仕組みがある。本記事ではその概要と、実際にどんな内容を書くと効果的かを整理する。
各AIツールの指示ファイル一覧
| ツール | ファイルパス | 備考 |
|---|---|---|
| GitHub Copilot | .github/copilot-instructions.md |
VS Code / GitHub上で自動読み込み |
| Claude Code |
.claude/instructions.md, CLAUDE.md
|
サブディレクトリごとの指示も可 |
| Gemini Code Assist | .gemini/instructions.md |
Google公式 |
| Cursor |
.cursor/rules/ ディレクトリ |
ファイル単位でルールを分割可能 |
いずれもリポジトリにコミットしてチーム全体で共有できる点が共通している。自然言語で書けるので、非エンジニアでも内容を理解・レビューしやすい。
何を書くべきか
指示ファイルに書く内容は大きく分けて以下のカテゴリになる。
技術スタック・アーキテクチャ方針
使用言語、フレームワーク、ディレクトリ構成のルールなど。AIが生成するコードの前提知識となる部分。
コーディング規約
命名規則、フォーマット、禁止パターンなど。linterで拾えない暗黙のルールほど書く価値がある。
コードレビュー方針
レビューコメントの粒度や優先度の付け方。AIにレビューを任せる場合に特に重要。
PR・コミットの規約
PR説明文のテンプレート、コミットメッセージの形式、ブランチ命名規則など。
出力フォーマットの指定
ドキュメントやシーケンス図の出力形式（Markdown、Mermaid など）を指定しておくと、毎回プロンプトで指示する手間が省ける。
実例：指示ファイルのサンプル
以下は一般的なWebアプリケーションプロジェクトを想定したサンプル。全部入れる必要はなく、チームで実際に困っている部分だけ書けば十分。
プロジェクトの前提情報
## プロジェクト概要
- 言語：TypeScript
- フロントエンド：React 18 + Vite
- バックエンド：Node.js (Express)
- DB：PostgreSQL
- テスト：Vitest + Playwright
- パッケージマネージャ：pnpm
## ディレクトリ構成
- src/features/ — 機能ごとにまとめる（コロケーション）
- src/shared/ — 複数機能で使う共通モジュール
- src/infrastructure/ — DB接続、外部API連携など
AIにとって最も基本的な前提情報。これがあるだけで、生成コードの技術選定のブレが大幅に減る。
コーディング規約
## コーディング規約
- any 型は使用禁止。unknown を使い、型ガードで絞り込む
- React コンポーネントは関数コンポーネント + hooks のみ。class component は使わない
- 状態管理に useState を多用しない。関連する状態は useReducer でまとめる
- API通信は src/infrastructure/api/ に集約する。コンポーネントから直接 fetch しない
- マジックナンバー禁止。定数として定義し、意図が伝わる名前をつける
linter やフォーマッタで強制できないルールを書くのがポイント。ESLint で検出できるものはここに書いても冗長になるだけ。
コードレビュー方針
## コードレビュー方針
レビューコメントには以下のプレフィックスをつけて、重要度を明示する。
- [must] — セキュリティ・バグ・データ損失につながる問題。マージブロック
- [should] — パフォーマンスや保守性に関わる改善提案
- [nits] — 好みの範囲。対応は任意
- [good] — 良い実装への称賛。省略しない
レビューの優先順位：
セキュリティ > 正確性 > パフォーマンス > 可読性 > スタイル
レビューの粒度が揃うだけで、レビュアーごとのバラつきが減る。AIレビューでも同じプレフィックスを使わせると、チームのワークフローに自然に溶け込む。
コミット・ブランチ規約
## コミット規約
Conventional Commits に従う。
形式： type(scope): description
type の種類：
- feat — 新機能
- fix — バグ修正
- refactor — 機能変更を伴わないコード改善
- docs — ドキュメントのみ
- test — テストの追加・修正
- chore — ビルド設定、依存更新など
例：
- feat(cart): 商品数量の変更機能を追加
- fix(payment): 税額計算の丸め誤差を修正
## ブランチ命名
形式： type/短い説明
例： feat/cart-quantity, fix/tax-rounding
PR説明文のガイドライン
## PR 説明文
以下の構造で記述する。
### 概要
何を・なぜ変更したかを2〜3行で。
バグ修正の場合は再現条件も簡潔に書く。
### 変更内容
主な変更点を箇条書きで。差分を見ればわかることは書かない。
### テスト
追加・更新したテストの概要。手動テストが必要な場合はその手順。
### 関連 Issue
対応する Issue へのリンク。
ドキュメント出力の形式指定
## ドキュメント出力
機能仕様を出力する際は、以下の形式に従う。
- 概要説明：Markdown
- 画面遷移・処理フロー：Mermaid 記法のシーケンス図またはフローチャート
- API仕様：OpenAPI 3.0 形式の YAML
シーケンス図では、ユーザー操作からバックエンド処理、外部サービス連携まで
一連の流れを省略せずに記載する。
毎回「Mermaidで書いて」と言わなくて済むようになる。地味だが積み重なると効果が大きい。
複数AIツール併用時の管理方法
チームで複数のAIツールを使っている場合、.github/copilot-instructions.md と .claude/instructions.md と .cursor/rules/ に同じ内容を書いて回るのは現実的ではない。
方法 A：共通ファイルからコピー
CONVENTIONS.md のような共通ファイルに規約をまとめておき、各AI指示ファイルの更新時にそこから内容を反映する。手動管理になるが、シンプル。
方法 B：シンボリックリンク
各AI指示ファイルを共通ファイルへのシンボリックリンクにする。ただしツールによってはシンボリックリンクを辿らない場合もあるため、事前に動作確認が必要。
方法 C：CIで同期
共通ファイルの変更をトリガーに、CIで各指示ファイルへ自動コピーする。最も確実だがセットアップコストがある。
書くときのコツ
短く具体的に書く。 AIのコンテキストウィンドウを無駄に消費しないよう、冗長な説明は避ける。「～してください」より、具体例を1つ示すほうが効果的。
禁止事項も書く。 「anyは使わない」「console.logをコミットしない」など、やってほしくないことを明示するとAIの出力精度が上がる。
定期的に見直す。 技術スタックやチーム規約は変わるもの。指示ファイルも放置せず、スプリントの振り返りなどで更新するのが望ましい。
効果が出にくいものは消す。 書いても守られない指示は、コンテキストを圧迫するだけ。指示を足すだけでなく、効いていないものを削る運用も大事。
まとめ
AIコーディング支援ツールは便利だが、プロジェクト固有のコンテキストを知らない状態ではノイズの多い出力になりがちだ。指示ファイルを1つ置くだけで、コード生成・レビュー・PR作成の品質が目に見えて変わる。
まだ導入していないなら、まずはコーディング規約やコミットルールなど、チームで一番ブレやすい部分から書いてみるところから始めてほしい。