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

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

はじめに

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

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

Duoワークフローのユースケース: スタイルガイドを使用したJavaアプリケーションの改善

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

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

GitLabリポジトリに保存されている集中管理されたスタイルガイドコンテンツへのアクセス
ドメイン固有のコーディング標準の理解
機能を維持しながら、Javaコードに一貫したフォーマットを適用します。

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

主な利点

すべてのJavaコードベースでEnforces consistent style（一貫したスタイルを適用）
手作業なしでAutomates style application（スタイル適用を自動化）
読みやすさを向上させながらMaintains code functionality（コードの機能を維持）
シームレスな実装のためにIntegrates with GitLab Workflow（GitLabワークフローとインテグレーション）
スタイルに関する問題の対応に費やすReduces code review time（コードレビュー時間を削減）
スタイルガイドラインを理解するためのServes as a learning tool（デベロッパー向けの学習ツールとして機能）

サンプル結果

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

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

基本設定

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

Enterprise Code Quality StandardsプロジェクトをクローンしてSet up the prompt and context library（プロンプトとコンテキストライブラリをセットアップする）
ライブラリファイル.gitlab/workflows/java-style-workflow.mdからプロンプトコンテンツを使用してCreate a GitLab issue（GitLabイシューを作成する） Review and Apply Style
Review and Apply Styleで、In the issue（イシューに）設定セクションで詳述されているように、ワークフロー変数を設定します
Enterprise Code Quality StandardsプロジェクトでIn your VS code（VS Code）で、簡単なワークフロープロンプトを使用してDuoワークフローを開始します
提案された計画と自動化されたタスクをレビューすることによりWork with the Duo Workflow（Duoワークフローを操作）し、必要に応じて、ワークフローにさらに入力を追加します
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ワークフローに次のことを指示するためです:

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

設定ガイド

プロンプトは、ソリューションパッケージの.gitlab/workflows/java-style-workflow.mdファイルで定義されています。このファイルは、AIアシスタントに指示する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プロジェクトのGitLab ID
{{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ワークフローは非決定的なエージェント型AIを使用します。つまり:

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

Best Practices for Working with AI-Generated Code Changes（AI生成コードの変更を操作するためのベストプラクティス）:

Always review generated code（生成されたコードを常にレビューする）: 綿密な人間のレビューなしに、AI生成された変更をマージしないでください
Follow proper merge request processes（適切なマージリクエストプロセスに従う）: 標準のコードレビュー手順を使用します
Run all tests（すべてのテストを実行する）: マージする前に、すべてのユニットテストとインテグレーションテストが合格していることを確認します
Verify style compliance（スタイルコンプライアンスを検証する）: 変更がスタイルガイドの期待に沿っていることを確認します
Incremental application（段階的な適用）: 最初は、より少ないファイルセットにスタイルの変更を適用することを検討してください

このツールは、コードレビュープロセスにおける人間の判断に代わるものではなく、デベロッパーを支援することを目的としていることを忘れないでください。

ステップごとの実装

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

Configure the Prompt（プロンプトを設定する）
- java-style-prompt.mdからテンプレートをコピーします
- すべての設定変数を入力します
- プロジェクト固有の例外または要件を追加します
Execute via GitLab Workflow（GitLabワークフロー経由で実行する）
- 設定されたプロンプトをDuoワークフローに送信します
- Duoワークフローは、サンプルワークフローの実行に見られるように、多段階プロセスで実行されます:
  - 特定のツール（run_read_only_git_command、read_file、find_files、edit_file）を使用してタスクを計画します
  - 参照されているイシューにアクセスします
  - エンタープライズJavaスタイルガイドを取得します
  - 現在のコード構造を分析します
  - 指定されたファイルにスタイルガイドラインを適用します
  - 変更が機能を維持することを確認します
  - 行われた変更の詳細なレポートを提供します
Review and Implement（レビューして実装する）
- 提案された変更をレビューします
- コードベースに変更を実装します
- テストを実行して、機能が維持されていることを確認します
- GitLabワークフローインターフェースを介してタスクの進行状況を監視します

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

適切に設定されると、GitLabワークフローは、スタイルガイドラインを適用するための詳細な計画を実行します。ワークフローの実行がどのように見えるかのサンプルを次に示します:

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

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

run_read_only_git_commandでサポートされている、ファイルcoding-style/java/guidelines/java-coding-standards.mdのhttps://gitlab.com/gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standards.gitでrun_read_only_git_commandを使用して、Enterprise Java Standardsプロジェクトからコンテンツを取得して、Javaスタイルガイドラインにアクセスします。
read_fileによってサポートされている、read_fileツールを使用してAssetManagementService.javaの現在のコンテンツを読み取り、分析して、その構造を理解し、スタイルの更新が必要な領域を特定します。
find_filesでサポートされているfind_filesを使用して、プロジェクト内の同様のファイルを検索し、関連するサービスクラス全体で一貫したスタイルの適用を確保します。
スタイルガイドラインを適用するためにedit_fileツールを使用してAssetManagementService.javaを編集し、以下に焦点を当てます:
- パッケージとインポートの編成
- クラスとメソッドのドキュメント
- コードのインデントと間隔
- アノテーションの配置
- edit_fileでサポートされているメソッドパラメータのフォーマット
grep_filesでサポートされている、grep_filesを使用してコードベース全体のアノテーションパターンをチェックし、すべてのLombokアノテーション（@Service、@RequiredArgsConstructor、@Slf4j）がスタイルガイドに従って適切にフォーマットされていることを確認します

サンプル分析出力

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

イシュー#3とAssetManagementService.javaファイルを分析しました。分析結果は次のとおりです:

イシュー＃3は、エンタープライズ標準JavaスタイルガイドラインをRoyal Bankingコードベースに適用することです。
AssetManagementService.javaファイルは、asset-management-apiモジュールにあります。
スタイルガイドラインは、gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standardsの別のGitLabプロジェクトに保存されています。
現在のAssetManagementService.javaファイルには以下が含まれています:
1. パッケージとインポートステートメント
2. Springアノテーションを使用したサービスクラス
3. 資産の可用性をチェックするための1つのパブリックメソッド
4. Lombokアノテーション
5. Javadocコメント

イシューに必要なものは次のとおりです:

エンタープライズ標準Javaスタイルガイドラインに従ってフォーマット
自動化されたスタイルチェックの実装
既存の機能の維持
スタイルの更新後にすべてのテストが合格することを確認する

実装を進めるには、次のことを行う必要があります:

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

サンプル実装結果

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

適用されたスタイルガイドラインの概要
適切なフォーマットの変換されたコード
主要なスタイル変更の説明
自動化されたスタイルの実施に関する推奨事項

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

標準化されたインポートの順序付け
演算子周辺の一貫した間隔
適切なJavadocフォーマット
標準化されたメソッドパラメータの配置
一貫した中括弧の配置

すべて、コードが元の機能を維持していることを確認しながら。

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

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

アカウントAPI
資産管理API
トランザクションAPI
通知API
APIゲートウェイ
設定サーバー
ディスカバリーサーバー

サンプル例では、エンタープライズスタイルガイドラインをAssetManagementService.javaクラスに適用し、適切なフォーマットを示します:

インポートの構成
Javadoc標準
メソッドパラメータの配置
変数の命名規則
例外処理パターン

組織向けにカスタマイズ

このプロンプトを組織のニーズに合わせるには:

Style Guide Replacement（スタイルガイドの交換）
- 組織のスタイルガイドリポジトリを指してください
- 特定のスタイルガイドドキュメントを参照してください
Target File Selection（対象ファイルの選択）
- スタイルガイドを適用する特定のファイルまたはパターンを選択します
- 初期実装のために、可視性の高いコードファイルを優先します
Additional Validation（追加の検証）
- カスタムの検証要件を追加します
- 標準スタイルのルールに対する例外を指定します
Integration with CI/CD（CI/CDとのインテグレーション）
- CI/CDパイプラインの一部として実行するようにプロンプトを設定します
- 継続的なコンプライアンスを確保するために、自動化されたスタイルチェックを設定します

トラブルシューティング

一般的な問題とその解決策:

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

コントリビュート

このプロンプトは、ご自由に拡張してください:

スタイルルールの説明をさらに追加する
さまざまなJavaプロジェクトタイプの例を作成する
検証ワークフローを改善する
追加の静的解析ツールとのインテグレーションを追加する