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

  • 6 分

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

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

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

Von Bedeutung

エージェント モードでチャット ビューを使用すると、入力した各プロンプトは 1 つの Premium 要求としてカウントされ、モデルの乗数が乗算されます。 GitHub Copilotタスクを完了するためにいくつかのフォローアップ アクションが実行される場合がありますが、これらのフォローアップ アクションは Premium 要求の使用量にはカウントされません。 入力したプロンプトのみが課金されます。 使用される Premium 要求の合計数は、入力するプロンプトの数と選択したモデルによって異なります。

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

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

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

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

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

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. ドキュメント タスクを説明するプロンプトを入力します。

    例: "このプロジェクトの README ファイルとサポート ドキュメントを作成する必要があります。 README には、プロジェクト タイトル、説明、目次、インストール、使用法、機能、構成、ライセンスが含まれている必要があります。

  4. 実装計画を確認します。

    しばらくすると、プラン エージェントによってチャット ビューにプランが出力されます。 このプランでは、概要と手順の内訳が提供されます。これには、明確にするための未解決の質問も含まれます。 繰り返し繰り返して要件を明確にしたり、範囲を調整したり、質問に答えたりすることができます。

  5. プランが完了したら、[ 実装の開始 ] を選択してプランをエージェント モードに引き渡すか、[ エディターで開く ] を選択して後で使用できるようにプランをマークダウン ファイルとして保存します。

    Start Implementation を選択すると、GitHub Copilotはエージェント モードに切り替え、承認済みのプランに基づいてドキュメントの実装を開始します。 生成されたドキュメント ファイルを確認し、変更を受け入れるか破棄します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

概要

GitHub Copilotは、プロジェクトとその利害関係者の特定のニーズを満たすプロジェクト ドキュメントを生成するのに役立ちます。 チャット ビューを使用すると、Ask、Agent、Plan の 3 つの異なるモードでプロジェクト ドキュメントを生成できます。 各モードには独自の長所と短所があり、使用するのに最適なモードは、手元の特定のタスクによって異なります。 Ask エージェント モードは、コードベースやテクノロジの概念について質問するのに最適です。 エージェント モードは、プロジェクトの詳細な理解を必要とするプロジェクト ドキュメントを生成するのに最適です。 プラン モードは、ドキュメントを生成する前に詳細な実装プランを作成する場合に最適です。その後、実行のためにエージェント モードに渡すことができます。