GitHub Copilot を使用してプロジェクト ドキュメントを生成する

  • 6 分

プロジェクトのドキュメントでは、プロジェクトの目的、目標、要件について説明します。 プロジェクトドキュメントを作成するには、プロジェクト構造、そのコンポーネント、およびコンポーネントが相互にどのように相互作用するかを理解する必要があります。

GitHub Copilot のチャット ビューは、プロジェクト構造全体を分析し、プロジェクトの概要を提供できるため、プロジェクト ドキュメントを生成するための理想的なツールです。 チャット ビューを使用して、README ファイル、API 参照、その他のプロジェクト関連ドキュメントなど、特定の種類のドキュメントを生成することもできます。

各チャット ビュー モード (Ask、Edit、または Agent) を使用して、プロジェクト ドキュメントを生成できます。 各モードには、独自の長所と短所があります。 プロジェクトの仕様やその他の制約は、使用するモードに影響します。

Von Bedeutung

エージェント モードでチャット ビューを使用する場合、GitHub Copilot は 1 つのタスクを完了するために複数の Premium 要求を行う場合があります。 Premium 要求は、ユーザーが開始したプロンプトと、Copilot がユーザーに代わって実行するフォローアップ アクションで使用できます。 使用される Premium 要求の合計数は、タスクの複雑さ、関連するステップの数、選択したモデルによって異なります。

プロジェクト ドキュメントの要件を確立する

ドキュメントの種類とコンテンツの要件は、プロジェクト、目的のコンシューマー、組織で採用されている標準によって異なります。

たとえば、README.md には次のセクションを含めることができます。

  • プロジェクト タイトル: プロジェクトの名前。
  • 説明: プロジェクトの実行内容と、プロジェクトが存在する理由の簡単な概要。
  • 目次: 省略可能ですが、長い READM に役立ちます。
  • インストール: プロジェクトをインストールして設定する方法について説明します。
  • 使用法: コード スニペットやスクリーンショットなど、プロジェクトの使用方法の例。
  • 機能: 主要な機能の一覧。
  • 構成: 構成オプションまたは環境変数の詳細。
  • 投稿: プロジェクトに貢献するためのガイドライン。
  • ライセンス: 分散プロジェクトで使用されるすべてのライセンス。
  • クレジットと謝辞: 貢献者、ライブラリ、または使用したリソースへの感謝。
  • 連絡先: メンテナーまたはプロジェクト チームに連絡する方法。
  • 変更ログ: 変更と更新の履歴 (別のファイルにリンクされている場合があります)。

GitHub Copilot Chat は、プロジェクトとその利害関係者の特定のニーズを満たすプロジェクト ドキュメントを生成するのに役立ちます。

ask モードを使用してプロジェクトドキュメントを生成する

ask モードを使用してワークスペースを分析し、ドキュメントを生成できます。

ask モードを使用してプロジェクト ドキュメントを生成するには、次のプロセスを使用します。

  1. ドキュメントの要件とサポート リソースを特定します。

    • プロジェクトのドキュメント要件を特定します。 ドキュメントの種類と必要なドキュメント セクションを特定します。

    • ドキュメントを生成するために必要なリソースを特定します。 コード ワークスペースが唯一必要なリソースである可能性があります。 ただし、"投稿中"、"クレジット"、"連絡先" などのセクションのコンテキストをチャットに追加する必要がある場合があります。

  2. チャット ビューを開き、ask モードを使用して新しいチャット セッションを開始します。

  3. チャット セッションにコンテキストを追加します。

    • Visual Studio Code のエクスプローラー ビューからチャット ビューにファイルをドラッグ アンド ドロップすることで、チャット セッションにコンテキストを追加できます。 [ コンテキストの追加] ボタンを使用することもできます。
    • コード エディターで外部ファイルを開いて、ワークスペースに含まれていないリソースを含め、それらを使用してより多くのコンテキストを提供できます。 たとえば、共同作成者のガイドラインや連絡先情報を含むマークダウン ファイルを開き、[ コンテキストの追加] ボタンを使用してチャット ビュー コンテキストに追加できます。

  4. ドキュメントの要件を調査する一連のプロンプトを入力します。

    Ask モードを使用してワークスペースを分析し、ドキュメントの要件をサポートするチャット セッション履歴を作成できます。 目標を記述すると、チャット セッションのコンテキストを確立するのに役立ちます。 要件に対応する質問をすると、GitHub Copilot がドキュメントの生成に必要な情報を特定するのに役立ちます。

    必要に応じて、追加されたコンテキストを更新します。

  5. 最初の手順で特定した必要なセクションを一覧表示して、推奨されるプロジェクト ドキュメントを求めるプロンプトを入力します。

    例: "@workspace /explain I need help creating a README file that can be used in the GitHub repository for this workspace. The file should be formatted as markdown. The README file needs to include the following sections: Project Title, Description, Table of Contents, Installation, Usage, Features, Configuration, and License."

  6. 提案されたプロジェクトドキュメントを確認し、必要に応じて新しいプロンプトを使用して結果を絞り込みます。

  7. 提案されたプロジェクト ドキュメントをプロジェクト ドキュメント ファイルに移動します。

    たとえば、ワークスペースのルートに README.md ファイルを作成し、提案されたコンテンツをファイルに挿入します。

    Ask モードを使用して、ドキュメントの作成後にプロジェクトの特定のセクションの更新を提案したり、他の GitHub Copilot ツールを使用して更新を支援したりできます。

編集モードを使用してプロジェクト ドキュメントを生成する

編集モードは、プロジェクト内の特定のファイルに変更を加える場合に最適です。 編集モードを使用すると、チャットにコンテキスト ファイルを追加し、ドキュメント ファイルを作成または更新することで、プロジェクト ドキュメントを生成できます。

編集モードを使用して、README.md ファイルなどのプロジェクト ドキュメントを生成するには、次のプロセスを使用します。

  1. ドキュメントの要件とサポート リソースを特定します。

  2. チャット ビューを開き、編集モードを使用して新しいチャット セッションを開始します。

  3. チャット セッションにコンテキストを追加します。

    チャット参加者は編集モードでは使用できないため、プロンプトの一部として @workspace を指定することはできません。 ただし、 #codebase を使用し、Visual Studio Code のエクスプローラー ビューからチャット ビューにファイルまたはフォルダーをドラッグ アンド ドロップすることで、チャット セッションにコンテキストを追加できます。 Visual Studio Code を使用して、共同作成者のガイドラインを含むマークダウン ファイルなどの外部ファイルを開き、[ コンテキストの追加] ボタンを使用してチャット コンテキストに追加します。

  4. 目的のプロジェクト ドキュメントを作成するためのプロンプトを入力します。

    例: "GitHub リポジトリに使用できる README ファイルを作成する必要があります。 ファイルはマークダウンとして書式設定する必要があります。 ルート ワークスペース フォルダーに README.md ファイルを作成します。 README ファイルには、プロジェクト タイトル、説明、目次、インストール、使用法、機能、構成、ライセンスの各セクションが含まれている必要があります。

  5. 編集モードを使用して作成された README.md ファイルを確認し、ファイルを保存または破棄します。

    プロンプトを使用してファイルを更新し、必要に応じて特定のセクションを修正または拡張できます。

エージェント モードを使用してプロジェクトドキュメントを生成する

エージェント モードは、プロジェクトの詳細な理解を必要とするプロジェクト ドキュメントを生成する場合に最適です。 エージェント モードでは、プロジェクトドキュメントを生成する前に、プロジェクト構造全体を分析します。 エージェント モードでは、複数のファイルとフォルダーから情報を収集することで、複雑なリレーションシップを記述し、ドキュメント間のリンクを含めることができます。

編集モードを使用して、README.md ファイルなどのプロジェクト ドキュメントを生成するには、次のプロセスを使用します。

  1. ドキュメントの要件とサポート リソースを特定します。

  2. チャット ビューを開き、エージェント モードを使用して新しいチャット セッションを開始します。

  3. チャット セッションにコンテキストを追加します。

    チャット参加者はエージェント モードでは使用できないため、プロンプトの一部として @workspace を指定することはできません。 ただし、 #codebase を使用し、ワークスペース ファイルとフォルダーをチャット コンテキストに追加することで、チャット セッションにコンテキストを追加できます。 Visual Studio Code で外部ファイルを開き、[ コンテキストの追加 ] ボタンを使用してチャット コンテキストに追加できます。

  4. 目的のプロジェクト ドキュメントを作成するためのプロンプトを入力します。

    例: "プロジェクト ドキュメント ファイルのコレクションを生成します。 このリポジトリのワークスペース README.md ファイルを作成または更新します。 UsageExamples.md ファイルを作成または更新します。 ChangeLog.md ファイルを作成または更新します。 ドキュメント ファイル間のリンクを含め、クラスとメソッドを相互参照し、ドキュメント全体の一貫性を確保します。

  5. ドキュメント ファイルを確認し、更新プログラムを保存または破棄します。

    プロンプトを使用してファイルを更新し、必要に応じて特定のセクションを修正または拡張します。

エージェント モードの機能

エージェント モードが最適な場合は、いくつかのドキュメント タスクがあります。

  1. 複数ファイルとファイル間のドキュメント生成。

    • エージェント モードでは、プロジェクト構造全体を分析し、複数のファイルとフォルダーから情報を収集し、コードベース全体のコンテンツをリンクして要約するドキュメントを生成できます。 Ror の例:完全な API 参照またはすべての主要なコンポーネントを記述する README を生成します。

  2. プロジェクトの分析と要約の自動化。

    • エージェント モードでは、アーキテクチャの要約、メイン クラス/サービスの識別、ファイルとコンポーネント間のリレーションシップを理解する必要があるダイアグラムまたはテーブルの生成などのタスクを実行できます。

  3. 動的なコンテンツ生成 (使用例、クラス テーブルなど)

    • エージェント モードでは、プロジェクトをスキャンして、使用例、クラス責任テーブル、またはパブリック API の一覧を生成できます。

  4. バッチ ドキュメント タスク。

    • エージェント モードでは、一連のドキュメント タスク (README の更新、CONTRIBUTING.md の作成、API ドキュメントの生成、変更ログの更新など) を 1 つのワークフローで実行できます。

  5. インテリジェントなリンクとナビゲーション。

    • エージェント モードでは、ドキュメント ファイル間、相互参照クラスとメソッド間のリンクを作成し、ドキュメント間の一貫性を確保できます。

エージェント モードは、分析、合成、調整を必要とするプロジェクト全体、マルチファイル、コンテキストに対応したドキュメント タスクに最適です。

概要

GitHub Copilot は、プロジェクトとその利害関係者の特定のニーズを満たすプロジェクト ドキュメントを生成するのに役立ちます。 チャット ビューを使用すると、3 つの異なるモード (Ask、Edit、Agent) でプロジェクト ドキュメントを生成できます。 各モードには独自の長所と短所があり、使用するのに最適なモードは、手元の特定のタスクによって異なります。 質問モードは、コードベースまたはテクノロジの概念について質問するのに最適です。 編集モードは、プロジェクト内の特定のファイルを変更する場合に最適です。 エージェント モードは、プロジェクトの詳細を理解する必要があるプロジェクト ドキュメントを生成する場合に最適です。