--- title: "GitHub Copilotのドキュメント生成｜VS Codeの/docと指示ファイルの使い分け" url: "https://www.issoh.co.jp/tech/details/2647/" published: 2024-06-19 updated: 2026-08-18 categories: ["GitHub"] publisher: "株式会社一創" --- # GitHub Copilotのドキュメント生成｜VS Codeの/docと指示ファイルの使い分け GitHub Copilot Chat を開いて `/doc` と打っても候補に出てこない、という詰まり方をした方が多いはずです。これは機能が廃止されたからではありません。VS Code では `/doc` の実行場所がチャットビューではなくインラインチャットに限定されているためです。ここでは公式ドキュメントの記述に沿って、docstring・プロジェクト文書・コード説明の3種類を切り分け、書式をリポジトリ側で固定する方法と、Copilot に任せてはいけない文書の線引きまでを整理します。 ## まとめ：ドキュメント生成は3層に分けて指示する Microsoft Learn の公式モジュールは、Copilot が生成するドキュメントを「コードの説明」「プロジェクトドキュメント」「インラインコードコメント」の3種類に分けています。実務では対象の粒度がそのまま指示方法の違いになります。関数やクラス単位の docstring はインラインチャットの `/doc`、リポジトリ全体を見渡す README や設計メモはチャットビューで `#search/codebase` を添えた依頼、既存コードの読解メモは `/explain` の出力を編集して使う、という対応です。 書式の揺れは指示ファイルで抑えます。`.github/instructions/NAME.instructions.md` はパスを限定して適用できるため、言語ごとにコメント規約が違うリポジトリでも分けて指定できます。ただし、API契約や監査対象の仕様書をCopilotの生成物のまま提出する運用は避けてください。以降で各層の手順と判断基準を示します。 ## Copilotが生成する3種類のドキュメントと対象範囲 ### インラインコードコメント（docstring）が対象にする単位 関数・メソッド・クラスといった記号（symbol）1つが対象です。VS Code 公式の機能リファレンスは `/doc` を「Generate code documentation comments from editor inline chat.」と定義しています。エディタで対象を選択してから実行する前提の機能で、引数・戻り値・例外といったシグネチャから導ける情報の記述精度が高い層です。逆に、その関数がプロジェクト内でなぜ必要かという背景は選択範囲に含まれないため出てきません。 ### プロジェクトドキュメントが対象にする単位 README、セットアップ手順、ディレクトリ構成の説明など、複数ファイルを横断する文書がここに入ります。対象が選択範囲を超えるので、チャットビューから依頼し、コンテキストを明示的に渡す必要があります。渡し方は後述の `#search/codebase` です。 ### コード説明を文書化に流用するときの判断基準 `/explain` は「Explain a code block, file, or programming concept.」と定義された読解支援機能です。出力はそのままでは文書になりません。説明が冗長で、コードを読めば分かる内容の言い換えが混ざるためです。引き継ぎメモや調査記録のように「読んだ結果を残す」用途なら下書きとして使え、公開ドキュメントに載せるなら要約と再構成が前提になります。 ## VS Codeで/docがチャットビューに出ない理由 ### IDEごとの/doc対応と公式説明文の差 GitHub公式のChatチートシートとVS Code公式リファレンスで、記載が食い違っています。GitHub側はVS Code欄のスラッシュコマンドを7個しか挙げておらず、そこに `/doc` がありません。`/doc` が載っているのは Visual Studio 欄と Xcode 欄です。 | IDE | /doc の記載 | 公式の説明文 | | ------------- | ------------------------------------- | ------------------------------------------------------------- | | VS Code | GitHub側チートシートには無い / VS Code側リファレンスに有り | Generate code documentation comments from editor inline chat. | | Visual Studio | GitHub側チートシートに有り | Add documentation comment for this symbol | | Xcode | GitHub側チートシートに有り | Generate documentation for this symbol | | JetBrains | 記載なし | – | GitHub側がVS Code欄に挙げている7個は `/clear`、`/explain`、`/fix`、`/fixTestFailure`、`/help`、`/new`、`/tests` です。いずれもチャットビューで完結するコマンドで、インラインチャット専用の `/doc` だけが抜けています。つまり「廃止された」のではなく、チャットビューの一覧を基準にしたドキュメントからは構造上こぼれる、という差です。参照先を VS Code 側のリファレンスに切り替えると解決します。 ### インラインチャットからのdocstring生成手順 実行場所を変えるだけです。 1. docstring を付けたい関数・クラスをエディタで選択します。 2. Ctrl+I（macOS は Command+I）でインラインチャットを開きます。 3. `/doc` を入力して実行します。 4. 差分を確認してから反映します。 チャットビュー（サイドバー）では候補に出ません。書式の指定を毎回プロンプトに書き足すのは続かないので、次節の指示ファイルへ寄せます。 ## docstringの書式をリポジトリ側で固定する指示ファイル 指示ファイルは3系統あり、適用範囲が違います。`.github/copilot-instructions.md` はリポジトリ全体のリクエストに適用されます。`.github/instructions/` 配下に置く `NAME.instructions.md` は、指定したパスに一致するファイルを扱うリクエストにだけ適用されます。`AGENTS.md` はリポジトリ内のどこにでも置ける形式です。 ドキュメント生成で効くのはパス限定の `.instructions.md` です。Python と TypeScript でコメント規約が違うリポジトリなら、それぞれのパスに対して別の指示を当てられます。なお、GitHub公式ドキュメントは指示ファイルの用途としてビルド手順やアーキテクチャ、検証プロセスの記述を挙げており、docstring書式の例示は載せていません。書式統一は「公式が推奨する使い方」ではなく、パス一致で適用される仕組みを流用した運用だと理解しておいてください。配置場所と書き方の違いは[copilot-instructions.mdとは？書き方・配置場所とAGENTS.md・.instructions.mdの違いを解説](/tech/details/10330/)で個別に扱っています。 ## プロジェクト全体を対象にするときのコンテキスト指定 ### #codebaseから#search/codebaseへの変更 ここが古い記事と現行仕様のズレが最も大きい箇所です。VS Code の現行リファレンスに `#codebase` は載っていません。該当する機能は `#search/codebase`（Perform a code search in the current workspace）へ名前空間付きの表記に変わっています。`#read/readFile`、`#edit/editFiles` のように、ツール参照が機能グループごとの階層表記へ整理されたためです。 一方、GitHub公式のChatチートシートは `#block`、`#class`、`#comment`、`#file`、`#function`、`#line`、`#path`、`#project`、`#selection`、`#sym` という旧来のフラットな変数群を掲載しています。日本語の解説記事も `#codebase` 表記のまま残っているものが多いので、補完候補に出てこない場合は表記の世代を疑ってください。 ### /initによるワークスペース指示の生成 プロジェクト文書を繰り返し生成するなら、先に土台を作った方が早く済みます。`/init` は「Generate or update workspace instructions.」と定義されたコマンドで、ワークスペースの指示ファイルを生成・更新します。リポジトリの構成をCopilot側に読ませてから文書生成に入るため、README生成のたびに前提を説明し直す手間が減ります。 ## Copilotのドキュメント生成を採用すべきでない文書 3種類の層に当てはまらない文書もあります。ここは判断を明確にしておきます。 **外部提出する仕様書・設計書の最終版には使わないでください。**「github copilot 仕様書」という検索が一定数ありますが、Copilot が参照できるのは基本的にリポジトリ内のコードです。要件の背景、却下された代替案、非機能要件の根拠といった、コードに書かれていない情報は生成できません。コードから読み取れる範囲を仕様書の体裁で出力できてしまうため、埋まっていない前提が本文中に見えないまま残ります。 API の外部契約を記述する文書も同様です。実装が誤っている場合、生成されたドキュメントは誤った実装を正確に記述します。仕様と実装の乖離を見つける目的には使えません。 監査・コンプライアンス対象の文書は、生成物をレビューなしで確定させない運用が前提です。docstring の一括生成は差分が大量に出るので、レビューが形式的な承認に流れやすくなります。生成対象を1コミットあたり数ファイルに区切る方が、結果的に修正コストが下がります。 ## よくある質問 ### VS CodeのCopilot Chatで/docが使えないのはなぜですか？ チャットビューでは候補に出ない仕様です。VS Code公式リファレンスは `/doc` を「Generate code documentation comments from editor inline chat.」と定義しており、実行場所がインラインチャットに限定されています。対象コードを選択してから Ctrl+I（macOS は Command+I）でインラインチャットを開き、そこで `/doc` を実行してください。GitHub公式のChatチートシートではVS Code欄に `/doc` の記載がなく、Visual Studio欄とXcode欄にのみ載っているため、参照先によって「存在しない」ように見えます。 ### GitHub Copilotで仕様書や設計書は作れますか？ コードから読み取れる範囲の記述は生成できますが、外部提出する最終版には向きません。Copilot が参照するのはリポジトリ内のコードが基本で、要件の背景や却下した代替案、非機能要件の根拠はコードに存在しないためです。体裁の整った出力が返るぶん、埋まっていない前提が見えにくくなります。既存実装の棚卸しメモや引き継ぎ資料の下書きに用途を限定するのが安全です。 ### docstringの書式を統一するにはどうすればよいですか？ 指示ファイルに寄せます。`.github/instructions/` 配下の `NAME.instructions.md` は適用対象のパスを限定できるため、言語ごとにコメント規約が異なるリポジトリでも分けて指定できます。リポジトリ全体に効かせるなら `.github/copilot-instructions.md` です。ただしGitHub公式ドキュメントは指示ファイルの用途としてビルド手順やアーキテクチャを挙げており、docstring書式の例示は載せていません。パス一致で適用される仕組みを流用した運用だと理解して使ってください。 ### プロジェクト全体のドキュメントを一度に生成できますか？ チャットビューから `#search/codebase` を添えて依頼すれば、ワークスペース内のコード検索を経たうえで回答が返ります。ただし一括生成した差分は量が多く、レビューが形式化しやすくなります。README やセットアップ手順のように横断的な文書はまとめて依頼し、docstring は対象を区切って `/doc` で個別に付ける、という分け方が現実的です。繰り返す場合は `/init` でワークスペースの指示ファイルを用意しておくと前提説明の手間が減ります。 ### #codebaseが補完候補に出てこないのはなぜですか？ 表記が変わっています。VS Code の現行リファレンスに `#codebase` は掲載されておらず、該当機能は `#search/codebase` へ名前空間付きの表記に整理されました。`#read/readFile` や `#edit/editFiles` も同じ形式です。GitHub公式のChatチートシートや日本語の解説記事は旧来のフラットな変数表記のまま残っているものが多いため、候補に出ない場合は参照している情報の世代を確認してください。 ## 関連記事 - [VS CodeでGitHub Copilotを使うには？導入から使い方までわかりやすく解説【2026年版】](/tech/details/6860/) - [copilot-instructions.mdとは？書き方・配置場所とAGENTS.md・.instructions.mdの違いを解説](/tech/details/10330/) - [GitHub Copilot Chatとは？使い方・料金・マルチモデル対応を2026年版で解説](/tech/details/6584/) - [GitHub Copilotでテストコードを自動生成する方法｜/testsコマンドと活用のコツ【2026年版】](/tech/details/2495/) - [GitHub Copilotエージェントモードの使い方｜Ask・Edit・Agentの違いと有効化・料金【2026年版】](/tech/details/6733/) --- 出典: [GitHub Copilotのドキュメント生成｜VS Codeの/docと指示ファイルの使い分け]()（株式会社一創）