VS Code でカスタム指示を使用する

カスタム指示を使用すると、AI によるコード生成やその他の開発タスクの処理方法に自動的に影響を与える共通のガイドラインやルールを定義できます。すべてのチャットプロンプトに手動でコンテキストを含める代わりに、Markdown ファイルでカスタム指示を指定することで、コーディング慣習やプロジェクト要件に沿った一貫性のある AI 回答を確保できます。

カスタム指示をすべてのチャットリクエストに自動的に適用するように構成することも、特定のファイルのみに適用するように構成することもできます。あるいは、特定のチャットプロンプトに手動でカスタム指示を添付することも可能です。

指示ファイルのタイプ

VS Code は 2 種類のカスタム指示をサポートしています。プロジェクト内に複数の指示ファイルがある場合、VS Code はそれらを結合してチャットコンテキストに追加します。特定の順序は保証されません。

常時適用される指示 (Always-on instructions)

常時適用される指示は、すべてのチャットリクエストに自動的に含まれます。プロジェクト全体のコーディング標準、アーキテクチャの決定、すべてのコードに適用される規約などに使用してください。

• 単一の .github/copilot-instructions.md ファイル

  • ワークスペース内のすべてのチャットリクエストに自動的に適用されます
  • ワークスペース内に保存されます

• 1 つ以上の AGENTS.md ファイル

  • ワークスペース内で複数の AI エージェントを使用する場合に便利です
  • ワークスペース内のすべてのチャットリクエスト、または特定のサブフォルダーに自動的に適用されます（実験的機能）
  • ワークスペースのルート、またはサブフォルダーに保存されます（実験的機能）

• 組織レベルの指示

  • GitHub 組織内の複数のワークスペースおよびリポジトリ間で指示を共有します
  • GitHub 組織レベルで定義されます

• CLAUDE.md ファイル

  • Claude Code およびその他の Claude ベースのツールとの互換性のため
  • ワークスペースのルート、.claude フォルダー、またはユーザーのホームディレクトリに保存されます

ファイルベースの指示

ファイルベースの指示は、エージェントが作業しているファイルが指定されたパターンと一致する場合、または説明が現在のタスクと一致する場合に適用されます。言語固有の規約、フレームワークのパターン、または特定のコード部分のみに適用されるルールには、ファイルベースの指示を使用してください。

• 1 つ以上の .instructions.md ファイル
  • glob パターンを使用して、ファイルの種類や場所に基づいて条件付きで指示を適用します
  • ワークスペースまたはユーザープロファイルに保存されます

指示内でファイルや URL などの特定のコンテキストを参照するには、Markdown リンクを使用できます。

.github/copilot-instructions.md ファイルを使用する

VS Code はワークスペースのルートにある .github/copilot-instructions.md Markdown ファイルを自動的に検出し、このワークスペース内のすべてのチャットリクエストにそのファイル内の指示を適用します。

copilot-instructions.md の用途

• プロジェクト全体に適用されるコーディングスタイルと命名規則
• 技術スタックの宣言と推奨ライブラリ
• 従うべき、または避けるべきアーキテクチャパターン
• セキュリティ要件とエラー処理のアプローチ
• ドキュメント化の標準

ワークスペースに .github/copilot-instructions.md ファイルを作成するには、以下の手順に従ってください

1. ワークスペースのルートに .github/copilot-instructions.md ファイルを作成します。必要に応じて、まず .github ディレクトリを作成してください。

2. Markdown 形式で指示を記述します。最適な結果を得るために、簡潔かつ要点を絞ってください。

---
applyTo: "**"
---
# Project general coding standards

## Naming Conventions
- Use PascalCase for component names, interfaces, and type aliases
- Use camelCase for variables, functions, and methods
- Prefix private class members with underscore (_)
- Use ALL_CAPS for constants

## Error Handling
- Use try/catch blocks for async operations
- Implement proper error boundaries in React components
- Always log errors with contextual information

.instructions.md ファイルを使用する

*.instructions.md Markdown ファイルを使用してファイルベースの指示を作成できます。これらは、エージェントが取り組んでいるファイルやタスクに基づいて動的に適用されます。

エージェントは、指示ファイルのヘッダーにある applyTo プロパティで指定されたファイルパターンや、指示の説明と現在のタスクとの意味的な一致に基づいて、適用する指示ファイルを決定します。

.instructions.md ファイルの用途

• フロントエンドとバックエンドのコードに対する異なる規約
• モノレポにおける言語固有のガイドライン
• 特定のモジュールに対するフレームワーク固有のパターン
• テストファイルやドキュメントに対する特別なルール

指示ファイルの場所

特定のワークスペースまたはユーザーレベルで指示を定義できます。ユーザーレベルで定義すると、すべてのワークスペースに適用されます。次の表は、スコープに基づいた指示ファイルのデフォルトの場所を示しています。ワークスペース指示ファイルの追加の場所は、 chat.instructionsFilesLocations 設定で構成できます。

VS Code はこれらのフォルダーを再帰的に検索するため、サブディレクトリで指示ファイルを整理できます。例えば、チーム、言語、またはモジュールごとに指示をグループ化できます。

.github/instructions/
  frontend/
    react.instructions.md
    accessibility.instructions.md
  backend/
    api-design.instructions.md
  testing/
    unit-tests.instructions.md

次の例は、指示ファイルの場所をワークスペースレベルの指示のみに制限するように構成する方法を示しています。

"chat.instructionsFilesLocations": {
  ".github/instructions": true,
  ".claude/rules": true,
  "~/.copilot/instructions": false,
  "~/.claude/rules": false
}

指示ファイルのフォーマット

指示ファイルは .instructions.md 拡張子を持つ Markdown ファイルです。オプションの YAML フロントマターヘッダーで、指示を適用するタイミングを制御します。

本体には Markdown 形式で指示を記述します。エージェントツールを参照するには、#tool:<tool-name> 構文（例: #tool:web/fetch）を使用します。

---
name: 'Python Standards'
description: 'Coding conventions for Python files'
applyTo: '**/*.py'
---
# Python coding standards
- Follow the PEP 8 style guide.
- Use type hints for all function signatures.
- Write docstrings for public functions.
- Use 4 spaces for indentation.

指示ファイルを作成する

指示ファイルを作成する際は、ワークスペースに保存するか、ユーザープロファイルに保存するかを選択します。ワークスペース指示ファイルはそのワークスペースのみに適用されますが、ユーザー指示ファイルは複数のワークスペースで利用可能です。

指示ファイルを作成するには

1. チャットビューで Configure Chat (歯車アイコン) を選択して Chat Customizations エディターを開き、Instructions タブを選択します。

2. ドロップダウンから New Instructions (Workspace) または New Instructions (User) を選択し、指示ファイルの保存先を指定します。

   

   または、コマンドパレット (⇧⌘P) から Chat: New Instructions File コマンドを使用します。

3. 場所を選択し、指示ファイルの名前を入力します。これが UI で使用されるデフォルト名になります。

4. Markdown 形式を使用してカスタム指示を作成します。

   • ファイル上部の YAML フロントマターに記入して、指示の説明、名前、および適用タイミングを構成します。
   • ファイル本体に指示を追加します。

既存の指示ファイルは、Chat Customizations エディターで開いて変更できます。

AI で指示ファイルを生成する

AI を使用してターゲットを絞った指示ファイルを生成できます。チャットで /create-instruction と入力し、適用したい規約やガイドラインを説明します（例: "このプロジェクトでは常にタブとシングルクォートを使用する"）。エージェントは明確な質問を行い、適切な applyTo パターンと内容を含む .instructions.md ファイルを生成します。

進行中の会話から指示を抽出することもできます。例えば、チャットセッション中にエージェントのインポートスタイルを修正した場合、"extract an instruction from this" と質問して、その修正をプロジェクトの規約として取り込むことができます。

---
applyTo: "**/*.ts,**/*.tsx"
---
# Project coding standards for TypeScript and React

Apply the [general coding guidelines](./general-coding.instructions.md) to all code.

## TypeScript Guidelines
- Use TypeScript for all new code
- Follow functional programming principles where possible
- Use interfaces for data structures and type definitions
- Prefer immutable data (const, readonly)
- Use optional chaining (?.) and nullish coalescing (??) operators

## React Guidelines
- Use functional components with hooks
- Follow the React hooks rules (no conditional hooks)
- Use React.FC type for components with children
- Keep components small and focused
- Use CSS modules for component styling

---
applyTo: "docs/**/*.md"
---
# Project documentation writing guidelines

## General Guidelines
- Write clear and concise documentation.
- Use consistent terminology and style.
- Include code examples where applicable.

## Grammar
* Use present tense verbs (is, open) instead of past tense (was, opened).
* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would".
* Use active voice where the subject performs the action.
* Write in second person (you) to speak directly to readers.

## Markdown Guidelines
- Use headings to organize content.
- Use bullet points for lists.
- Include links to related resources.
- Use code blocks for code snippets.

コミュニティから提供されたその他の例については、Awesome Copilot リポジトリ を参照してください。

AGENTS.md ファイルを使用する

VS Code はワークスペースのルートにある AGENTS.md Markdown ファイルを自動的に検出し、このワークスペース内のすべてのチャットリクエストに適用します。これは、ワークスペースで複数の AI エージェントを使用しており、それらすべてに共通の指示を認識させたい場合や、モノレポの特定のパーツに適用されるサブフォルダーレベルの指示が必要な場合に便利です。

AGENTS.md を使用すべきタイミング

• 複数の AI コーディングエージェントを使用していて、すべてに共通の指示を認識させたい場合
• モノレポの特定のパーツに適用されるサブフォルダーレベルの指示が必要な場合

AGENTS.md ファイルのサポートを有効または無効にするには、 chat.useAgentsMdFile 設定を構成します。

複数の AGENTS.md ファイルを使用する (実験的)

サブフォルダーで複数の AGENTS.md ファイルを使用すると、プロジェクトの異なるパーツに異なる指示を適用できるため便利です。例えば、フロントエンドコード用に 1 つ、バックエンドコード用に別の AGENTS.md ファイルを持つことができます。

実験的な chat.useNestedAgentsMdFiles 設定を使用して、ワークスペース内のネストされた AGENTS.md ファイルのサポートを有効または無効にします。

有効にすると、VS Code はワークスペースのすべてのサブフォルダーを再帰的に検索して AGENTS.md ファイルを探し、その相対パスをチャットコンテキストに追加します。エージェントは、編集中のファイルに基づいて使用する指示を決定できます。

CLAUDE.md ファイルを使用する

VS Code は CLAUDE.md ファイルを自動的に検出し、AGENTS.md と同様に常時適用される指示として適用します。これは、Claude Code や他の Claude ベースのツールを VS Code と併用していて、それらすべてで共通の指示を認識させたい場合に便利です。

VS Code は以下の場所で CLAUDE.md ファイルを検索します

CLAUDE.md ファイルのサポートを有効または無効にするには、 chat.useClaudeMdFile 設定を構成します。

ワークスペース用のカスタム指示を生成する

VS Code はワークスペースを分析し、コーディング慣習やプロジェクト構造に一致する常時適用されるカスタム指示を生成できます。これらの指示は、ワークスペース内のすべてのチャットリクエストに自動的に適用されます。

指示を生成する際、VS Code は以下の手順を実行します

1. copilot-instructions.md や AGENTS.md ファイルなど、ワークスペース内の既存の AI 規約を検出します。
2. プロジェクトの構造とコーディングパターンを分析します。
3. プロジェクトに合わせて調整された包括的なワークスペース指示を生成します。

ワークスペース用のカスタム指示を生成するには

• チャット入力ボックスに /init と入力し、Enter を押します。

• /create-instructions と入力し、その後に生成したい指示の説明を入力します。

• Chat Customizations エディターで、ドロップダウンから Generate Instructions を選択します。

チーム間でカスタム指示を共有する

GitHub 組織内の複数のワークスペースおよびリポジトリ間でカスタム指示を共有するには、それらを GitHub 組織レベルで定義できます。

VS Code は、アカウントがアクセスできる組織レベルで定義されたカスタム指示を自動的に検出します。これらの指示は、個人およびワークスペースの指示と並んで Chat Instructions メニューに表示され、すべてのチャットリクエストに自動的に適用されます。

組織レベルのカスタム指示の検出を有効にするには、 github.copilot.chat.organizationInstructions.enabled を true に設定します。

GitHub ドキュメントで 組織のカスタム指示を追加する方法 について確認してください。

デバイス間でユーザー指示ファイルを同期する

VS Code は Settings Sync (設定同期) を使用して、デバイス間でユーザー指示ファイルを同期できます。

ユーザー指示ファイルを同期するには、Settings Sync を有効にし、コマンドパレット (⇧⌘P) から Settings Sync: Configure を実行します。同期する設定のリストから Prompts and Instructions を選択します。

設定でカスタム指示を指定する

コードレビュー、コミットメッセージ、プルリクエストの説明については、引き続き VS Code 設定を使用してカスタム指示を定義できます。これらの設定は、text プロパティ (インライン指示) または file プロパティ (Markdown ファイルへのパス) を持つオブジェクトの配列を受け入れます。

指示の優先順位

複数の種類のカスタム指示が存在する場合、それらはすべて AI に提供されます。競合が発生した場合は、優先度の高い指示が優先されます。

1. 個人用指示 (ユーザーレベル、最優先)
2. リポジトリ指示 (.github/copilot-instructions.md または AGENTS.md)
3. 組織指示 (最低優先度)

効果的な指示を書くためのヒント

• 指示は短く、自己完結させてください。各指示は単一のシンプルなステートメントにするべきです。複数の情報を提供する必要がある場合は、複数の指示を使用してください。

• ルールの背後にある根拠を含めてください。指示が「なぜ」その規約が存在するのかを説明すると、AI はエッジケースでより良い判断を下せます。例: "moment.js は非推奨であり、バンドルサイズを大きくするため、moment.js の代わりに date-fns を使用してください。"

• 具体的なコード例を使って、推奨されるパターンと避けるべきパターンを示してください。AI は抽象的なルールよりも例に対してより効果的に反応します。

• 自明ではないルールに焦点を当ててください。標準のリンターやフォーマッターが既に強制している規約はスキップしてください。

• タスク固有または言語固有の指示については、トピックごとに複数の *.instructions.md ファイルを使用し、applyTo プロパティを使用して選択的に適用してください。

• チームメンバーと共有し、バージョン管理に含めるために、プロジェクト固有の指示をワークスペースに保存してください。

• プロンプトファイル や カスタムエージェント で指示ファイルを参照・再利用することで、ファイルを整理し、重複を避けてください。

• 指示間の空白は無視されるため、読みやすさのために単一の段落としてフォーマットすることも、別々の行にする、あるいは空行で区切ることもできます。

よくある質問

なぜ指示ファイルが適用されないのですか？

指示ファイルが適用されない場合は、以下を確認してください

• 指示ファイルが正しい場所にあることを確認してください。.github/copilot-instructions.md ファイルはワークスペースのルートの .github フォルダー内にある必要があります。*.instructions.md ファイルは chat.instructionsFilesLocations 設定（デフォルト: .github/instructions）で指定されたフォルダー（またはそのサブディレクトリ）、あるいはユーザープロファイル内にある必要があります。

• *.instructions.md ファイルについては、applyTo glob パターンが作業中のファイルと一致していることを確認してください。applyTo プロパティが指定されていない場合、指示ファイルは自動的に適用されません。どの指示ファイルが使用されたかを確認するには、チャット応答の References セクションを確認してください。

• 関連する設定が有効になっていることを確認してください: パターンベースの指示には chat.includeApplyingInstructions 、Markdown リンク経由で参照される指示には chat.includeReferencedInstructions 、AGENTS.md ファイルには chat.useAgentsMdFile を確認してください。

詳細な診断については、チャットデバッグビューで言語モデルのリクエストを確認する か、applyTo マッチングロジックをデバッグ してください。

カスタム指示ファイルのソースを知るにはどうすればよいですか？

カスタム指示ファイルには、組み込み、ユーザープロファイルで定義されたもの、現在のワークスペースで定義されたもの、組織レベルの指示、または拡張機能によって提供されたものなど、異なるソースがあります。

カスタム指示ファイルのソースを確認するには

1. コマンドパレット (⇧⌘P) から Chat: Configure Instructions を選択します。
2. リスト内の指示ファイルにホバーします。ツールチップにソースの場所が表示されます。

チャットカスタマイズ診断ビューを使用して、読み込まれたすべての指示ファイルとエラーを確認してください。チャットビューを右クリックし、Diagnostics を選択します。VS Code での AI のトラブルシューティング についての詳細はこちらをご覧ください。

関連リソース

• エージェントスキルを使用する
• カスタムエージェントを作成する
• コミュニティから提供された指示、プロンプト、およびカスタムエージェント