正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

コーディングスタイルを適用するためのDuo Workflowのユースケース

  • プラン: UltimateとGitLab Duoワークフロー
  • 提供形態: GitLab.com
  • ステータス: 実験的機能

はじめに

ソリューションコンポーネントをダウンロード

  1. アカウントチームから招待コードを入手してください。
  2. 招待コードを使用して、ソリューションコンポーネントのウェブストアからソリューションコンポーネントをダウンロードしてください。

Duo Workflowユースケース: スタイルガイドでJavaアプリケーションを改善する

このドキュメントでは、GitLab Duo Workflow Solutionのプロンプトとコンテキストライブラリについて説明します。このソリューションの目的は、定義されたスタイルに基づいてアプリケーションのコーディングを改善することです。

このソリューションは、GitLabイシューをプロンプトとして、スタイルガイドをコンテキストとして提供し、GitLab Duo Workflowを使用して、Javaスタイルガイドラインをコードベースに自動適用するように設計されています。プロンプトとコンテキストライブラリにより、Duo Workflowは次のことが可能になります:

  1. Gitリポジトリに保存されている集中型スタイルガイドコンテンツにアクセスし、
  2. ドメイン固有のコーディング標準を理解し、
  3. 機能を維持しながら、Javaコードに一貫した書式設定を適用します。

GitLab Duo Workflowの詳細については、こちらのドキュメントをご覧ください。

主な利点

  • すべてのJavaコードベースでEnforces consistent style
  • 手動での作業なしでAutomates style application
  • 可読性を向上させながらコードの機能をMaintains code functionality
  • シームレスな実装のためにGitLab for VS CodeとIntegrates with GitLab for VS Code
  • スタイルイシューへの対応にかかるコードレビュー時間をReduces code review time
  • デベロッパーがスタイルガイドラインを理解するためのServes as a learning tool

サンプル結果

適切に設定すると、プロンプトは、この差分に示されている変換と同様に、コードをエンタープライズ標準に一致するように変換します:

手順、タスク分析、解決ステップを表示するDuo Workflowビュー

Duo Workflowによるスタイルガイド変換後の書式設定が統一された更新コードスニペット

ソリューションプロンプトとコンテキストライブラリを設定する

基本設定

エージェント型ワークフローを実行して、アプリケーションのスタイルをレビューし適用するには、このユースケースプロンプトとコンテキストライブラリを設定する必要があります。

  1. Enterprise Code Quality StandardsプロジェクトをクローンしてSet up the prompt and context library
  2. ライブラリファイル.gitlab/workflows/java-style-workflow.mdのプロンプトコンテンツを使用してCreate a GitLab issue Review and Apply Style
  3. In the issue Review and Apply Styleで、設定セクションに詳述されているように、ワークフロー変数を設定します。
  4. Enterprise Code Quality StandardsプロジェクトでIn your VS codeを使用し、シンプルなワークフロープロンプトでDuoワークフローを開始します。
  5. 提案された計画と自動タスクをレビューしてWork with the Duo Workflowし、必要に応じてワークフローにさらなる入力を追加します。
  6. スタイルが適用されたコード変更をReview and commitしてリポジトリに反映します。

Duoワークフロープロンプトの例

Follow the instructions in issue <issue_reference_id> for the file <path/file_name.java>. Make sure to access any issues or GitLab projects mentioned in the issue to retrieve all necessary information.

このシンプルなプロンプトは、Duo Workflowに次のことを指示するため強力です:

  1. 特定のイシューIDの詳細な要件を読み取ります。
  2. 参照されているスタイルガイドリポジトリにアクセスします。
  3. 指定されたファイルにガイドラインを適用します。
  4. イシュー内のすべての指示に従います。

設定ガイドライン

プロンプトは、ソリューションパッケージ内の.gitlab/workflows/java-style-workflow.mdファイルで定義されています。このファイルは、ワークフローエージェントに、アプリケーションでのスタイルガイドレビューを自動化し変更を適用するための計画をビルドするよう指示するGitLabイシューを作成するためのテンプレートとして機能します。

.gitlab/workflows/java-style-workflow.mdの最初のセクションでは、プロンプト用に設定する必要がある変数を定義しています。

変数の定義

変数は.gitlab/workflows/java-style-workflow.mdファイルに直接定義されています。このファイルは、AIアシスタントに指示するGitLabイシューを作成するためのテンプレートとして機能します。このファイル内の変数を修正してから、その内容で新しいイシューを作成します。

1. コンテキストとしてのスタイルガイドリポジトリ

プロンプトは、組織のスタイルガイドリポジトリを指すように設定する必要があります。java-style-prompt.mdファイルで、次の変数を置き換えます:

  • {{GITLAB_INSTANCE}}: GitLabインスタンスのURL（例: https://gitlab.example.com）
  • {{STYLE_GUIDE_PROJECT_ID}}: Javaスタイルガイドを含むGitLabプロジェクトID
  • {{STYLE_GUIDE_PROJECT_NAME}}: スタイルガイドプロジェクトの表示名
  • {{STYLE_GUIDE_BRANCH}}: 最新のスタイルガイドを含むブランチ（デフォルト: main）
  • {{STYLE_GUIDE_PATH}}: リポジトリ内のスタイルガイドドキュメントへのパス

例:

GITLAB_INSTANCE=https://gitlab.example.com
STYLE_GUIDE_PROJECT_ID=gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standards
STYLE_GUIDE_PROJECT_NAME=Enterprise Java Standards
STYLE_GUIDE_BRANCH=main
STYLE_GUIDE_PATH=coding-style/java/guidelines/java-coding-standards.md

2. スタイル改善を適用するターゲットリポジトリ

同じjava-style-prompt.mdファイルで、スタイルガイドを適用するファイルを設定します:

  • {{TARGET_PROJECT_ID}}: JavaプロジェクトのGitLabID
  • {{TARGET_FILES}}: ターゲットとする特定のファイルまたはパターン（例: 「src/main/java/**/*.java」）

例:

TARGET_PROJECT_ID=royal-reserve-bank
TARGET_FILES=asset-management-api/src/main/java/com/royal/reserve/bank/asset/management/api/service/AssetManagementService.java

AIが生成したコードに関する重要な注意事項

⚠️ Important Disclaimer:

GitLab for VS Codeは、非決定性であるエージェント型AIを使用しています。つまり:

  • 同じ入力であっても、実行ごとに結果が異なる場合があります。
  • AIアシスタントのスタイルガイドラインの理解と適用は、毎回わずかに異なる場合があります。
  • このドキュメントで提供されている例は説明のためのものであり、実際の環境では結果が異なる場合があります。

AIが生成したコードの変更を操作するためのBest Practices for Working with AI-Generated Code Changes:

  1. Always review generated code: 生成されたコードを常にレビューする: 徹底的な人間のレビューなしにAI生成された変更をマージすることは避けてください。
  2. Follow proper merge request processes: 適切なマージリクエストプロセスに従う: 標準のコードレビュー手順を使用してください。
  3. Run all tests: すべてのテストを実行する: マージする前に、すべての単体テストとインテグレーションテストが合格することを確認してください。
  4. Verify style compliance: スタイルコンプライアンスを検証する: 変更がスタイルガイドの期待値と一致していることを確認します。
  5. Incremental application: 段階的な適用: 最初は、より小さなファイルセットにスタイル変更を適用することを検討してください。

このツールは、デベロッパーを支援するためのものであり、コードレビュープロセスにおける人間の判断を置き換えるものではないことを覚えておいてください。

段階的な実装

  1. Create a Style Guide Issue (スタイルガイドイシューを作成)

    • プロジェクトで新しいイシューを作成します（例: イシュー #3）。

    • 適用するスタイルガイドラインに関する詳細情報を含めます。

    • 該当する場合は、外部スタイルガイドリポジトリを参照します。

    • 次のような要件を指定します:

      Task: Code Style Update
Description: Apply the enterprise standard Java style guidelines to the codebase.
Reference Style Guide: Enterprise Java Style Guidelines (https://gitlab.com/gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standards/-/blob/main/coding-style/java/guidelines/java-coding-standards.md)
Constraints:
- Adhere to Enterprise Standard Java Style Guide
- Maintain Functionality
- Implement automated style checks

  2. Configure the Prompt (プロンプトを設定する)

    • java-style-prompt.mdからテンプレートをコピーします。
    • すべての設定変数を入力します。
    • プロジェクト固有の例外または要件を追加します。

  3. Execute via GitLab for VS Code (実行)

    • 設定されたプロンプトをDuoワークフローに送信します。

    • Duoワークフローは、サンプルワークフロー実行に示されているように、多段階プロセスを実行します:

      • 特定のツール（run_read_only_git_command、read_file、find_files、edit_file）でタスクを計画します。
      • 参照されているイシューにアクセスします。
      • エンタープライズJavaスタイルガイドを取得する。
      • 現在のコード構造を分析します。
      • 指定されたファイルにスタイルガイドラインを適用します。
      • 変更が機能を維持していることを検証します。
      • 行われた変更の詳細なレポートを提供します。

  4. Review and Implement (レビューと実装)

    • 提案された変更をレビューします。
    • コードベースに変更を実装します。
    • 機能を維持するためにテストを実行します。
    • GitLab for VS Codeインターフェースを介してタスクの進行状況を監視します。

サンプルワークフロー実行

適切に設定すると、GitLab for VS Code拡張機能は、スタイルガイドラインを適用するための詳細な計画を実行します。ワークフローの実行例を以下に示します:

サンプルワークフロー計画

AIアシスタントは、まず特定のツールを使用して実行計画を作成します:

  1. https://gitlab.com/gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standards.git上でcoding-style/java/guidelines/java-coding-standards.mdファイルにrun_read_only_git_commandを使用してEnterprise Java Standardsプロジェクトからコンテンツを取得することで、Javaスタイルガイドラインにアクセスします。run_read_only_git_commandによってサポートされています。

  2. AssetManagementService.javaの現在のコンテンツをread_fileツールを使用して読み取り、その構造を理解し、スタイル更新が必要な領域を特定します。read_fileによってサポートされています。

  3. プロジェクト内で類似するファイルをfind_filesを使用して検索し、関連するサービスクラス全体で一貫したスタイル適用を確保します。find_filesによってサポートされています。

  4. edit_fileツールを使用してAssetManagementService.javaを編集し、スタイルガイドラインを適用します。特に次の点に焦点を当てます:

    • パッケージとインポートの整理
    • クラスとメソッドのドキュメント
    • コードのインデントとスペース
    • アノテーションの配置
    • メソッドパラメータの書式設定。edit_fileによってサポートされています。

  5. grep_filesを使用して、すべてのLombokアノテーション（@Service、@RequiredArgsConstructor、@Slf4j）がスタイルガイドに従って適切に書式設定されていることをコードベース全体のアノテーションパターンをチェックすることで確認します。grep_filesによってサポートされています。

サンプル分析出力

AIアシスタントは、ファイルと要件を分析します:

イシュー #3とAssetManagementService.javaファイルを分析しました。以下に調査結果を示します:

  1. イシュー #3は、エンタープライズ標準JavaスタイルガイドラインをRoyal Bankingコードベースに適用することに関するものです。

  2. AssetManagementService.javaファイルは、asset-management-apiモジュール内にあります。

  3. スタイルガイドラインは、gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standardsの別のGitLabプロジェクトに保存されています。

  4. 現在のAssetManagementService.javaファイルには以下が含まれます:

    1. パッケージおよびインポートステートメント
    2. Springアノテーションを持つサービスクラス
    3. アセットの可用性をチェックするための1つのpublicメソッド
    4. Lombokアノテーション
    5. Javadocコメント

このイシューでは次のことが求められています:

  1. エンタープライズ標準Javaスタイルガイドラインに準拠した書式設定
  2. 自動スタイルチェックの実装
  3. 既存の機能の維持
  4. スタイル更新後にすべてのテストが合格することの確認

実装を進めるには、次の作業が必要です:

  1. Enterprise Java StandardsプロジェクトからJavaスタイルガイドラインにアクセスします。
  2. AssetManagementService.javaにスタイルガイドラインを適用します。
  3. 変更が機能に影響しないことを検証します。
  4. 更新後にすべてのテストが合格することを確認します。

サンプル実装結果

実行後、AIアシスタントは、行われた変更の説明とともに変換されたコードを提供します:

  1. 適用されたスタイルガイドラインの概要
  2. 適切に書式設定された変換済みコード
  3. 主要なスタイル変更の説明
  4. 自動スタイル適用に関する推奨事項

変更には通常、以下が含まれます:

  • 標準化されたインポート順序
  • 演算子の周りの一貫したスペース
  • 適切なJavadoc書式設定
  • 標準化されたメソッドパラメータの配置
  • 一貫したブレースの配置

これはすべて、コードが元の機能を維持するようにしながら行われます。

サンプルチュートリアルユースケース: Royal Reserve Bank Javaプロジェクト

このリポジトリには、スタイルガイドアプリケーションが現実世界のシナリオでどのように機能するかを示す銀行チュートリアルの例が含まれています。Royal Reserve Bankプロジェクトは、複数のJavaサービスを含むマイクロサービスアーキテクチャに従います:

  • アカウントAPI
  • アセット管理API
  • トランザクションAPI
  • 通知API
  • API Gateway
  • 設定サーバー
  • Discovery Server

サンプルでは、AssetManagementService.javaクラスにエンタープライズスタイルガイドラインを適用し、次の適切な書式設定を示しています:

  1. インポートの整理
  2. Javadoc標準
  3. メソッドパラメータの配置
  4. 変数命名規則
  5. 例外処理パターン

組織に合わせてカスタマイズする

組織のニーズに合わせてこのプロンプトを調整するには、次の手順を実行します:

  1. Style Guide Replacement (スタイルガイドの置き換え)

    • 組織のスタイルガイドリポジトリを指定します。
    • 特定のスタイルガイドドキュメントを参照します。

  2. Target File Selection (ターゲットファイルの選択)

    • スタイルガイドを適用する特定のファイルまたはパターンを選択します。
    • 最初の実装では、表示レベルの高いコードファイルを優先します。

  3. Additional Validation (追加の検証)

    • カスタム検証要件を追加します。
    • 標準スタイルルールに対する例外を指定します。

  4. Integration with CI/CD (CI/CDとのインテグレーション)

    • プロンプトがCI/CDパイプラインの一部として実行されるように設定します。
    • 継続的なコンプライアンスを確保するために自動スタイルチェックを設定します。

トラブルシューティング

よくあるイシューとその解決策:

  • アクセスが拒否されました: AIエージェントが両方のリポジトリにアクセスするための適切な権限を持っていることを確認してください。
  • Missing Style Guide: スタイルガイドのパスとブランチが正しいことを確認します。
  • Functionality Changes: 機能性を検証するために、スタイル変更の適用後にすべてのテストを実行します。

コントリビュート

このプロンプトは、次の方法で自由に機能強化できます:

  • より多くのスタイルルールの説明を追加します。
  • さまざまなJavaプロジェクトタイプ向けの例を作成します。
  • 検証ワークフローを改善します。
  • 追加の静的解析ツールとのインテグレーションを追加します。