Duo Agent を使った GitLab フォローアップ Issue の改善
概要
このドキュメントでは、Duo Agent を使って GitLab のフォローアップ Issue を改善するプロセスについて説明します。汎用的でコンテキストの乏しい Issue を、構造化された実行可能な作業項目に変換することを目的としています。
問題
マージリクエストのディスカッションからフォローアップ Issue を作成すると、GitLab は以下のような Issue を生成します:
- 「<MR タイトル> からのフォローアップ」のような汎用的なタイトル
- 最小限のコンテキスト（元のコメントのみ）
- 実装のガイダンスなし
- 曖昧な受け入れ基準
これにより、未対処の不明確な Issue を通じて技術的負債が蓄積する可能性があります。また、コンテキストが不足しているため、原著者以外のエンジニアがこれらの Issue を引き継ぐことが非常に困難になります。
解決策
標準化されたプロンプトを使って Duo Agent を活用し、以下の方法で Issue を改善します:
- 意味のある行動指向のタイトルの作成
- 包括的なコンテキストと背景の追加
- コード分析に基づく実装提案の提供
- 明確な受け入れ基準の定義
- 関連する依存関係とファイルのリンク
プロセス
ステップ 1: フォローアップ Issue の特定
「Follow-up from」で始まるタイトル、または MR ディスカッションからの短いコメントのみを含む Issue を探します。
ステップ 2: 改善プロンプトの適用
以下の Duo Agent プロンプトを使って Issue を分析・改善します:
# GitLab フォローアップ Issue 改善プロンプト
あなたはマージリクエストのディスカッションから作成された GitLab フォローアップ Issue を改善するタスクを担っています。これらの Issue は通常「<MR タイトル> からのフォローアップ」のような汎用的なタイトルを持ち、適切なコンテキストなしに元のコメントのみを含んでいます。
## 目標
以下によりフォローアップ Issue を変換してください:
### 1. 意味のあるタイトルの作成
- 汎用的な「<MR タイトル> からのフォローアップ」を具体的で実行可能なタイトルに置き換える
- どこから来たかではなく、何をする必要があるかに焦点を当てる
- 命令形を使用する（例:「認証ロジックのリファクタリング」「API 呼び出しのエラー処理の追加」）
- 簡潔でありながら説明的に保つ（理想は 50〜80 文字）
### 2. Issue 説明の改善
以下のセクション構造で説明を作成してください:
#### **背景とコンテキスト**
- 元のマージリクエストの目的を要約する
- このフォローアップが作成された理由を説明する
- 特定の MR ディスカッションスレッドへのリンクを貼る
#### **現状**
- 現在の実装・状況を説明する
- 関連するコードスニペットまたはファイル参照を含める
- 機能しているが改善可能な点を強調する
#### **要求される変更**
- 変更・改善すべき内容を明確に示す
- 複雑なリクエストを具体的なタスクに分解する
- 明確さのために箇条書きを使用する
#### **提案された実装**
- 参照されたコード・ファイルを分析する
- 可能なアプローチを軽く提案する
- アーキテクチャへの影響を考慮する
- 潜在的な課題や依存関係を特定する
#### **受け入れ基準**
- 機能要件と非機能要件の両方を含める
#### **技術的コンテキスト**
- 影響を受けるファイル・モジュール・コンポーネントをリストする
- 依存関係や関連 Issue を記載する
- 実装のタイムライン・優先度を提案する
## 分析の指示
改善された Issue を書く前に:
1. **ソースコードを確認する** 元のコメントで言及されている箇所
2. **より広いコンテキストを理解する** 変更される領域の
3. **パターンを特定する** システム的な問題を示す可能性があるもの
4. **影響を考慮する** 提案された変更の
5. **既存のソリューションを調査する** コードベース内の類似実装
## 品質ガイドライン
- 曖昧ではなく、具体的で実行可能な内容にする
- どのチームメンバーでも理解し実装できる十分な詳細を提供する
- 役立つ場合はコード例や疑似コードを含める
- 関連するドキュメント、ADR、または関連 Issue にリンクする
- 一貫した用語とフォーマットを使用する
- プロンプトで提供されたサンプル構造に厳密に従う
- ガイドラインで明示されたセクションのみを含める
## 出力フォーマット
改善された Issue を標準的な GitLab markdown フォーマットで提示してください:
- 明確なセクションヘッダー
- 適切なコードフォーマット
- 関連するリンク
- 適切なラベルの提案（該当する場合）
## サンプル構造
```markdown
## 背景とコンテキスト
[この Issue が存在する理由の説明]
## 現状
[現在の実装の説明]
## 要求される変更
[必要な具体的な変更]
## 提案された実装
[技術的な詳細を含む提案されたアプローチ]
## 受け入れ基準
- [ ] 基準 1
- [ ] 基準 2
## 技術的コンテキスト
**影響を受けるファイル:**
- `path/to/file1.js`
- `path/to/file2.py`
**依存関係:**
- #issue-number に関連
**優先度:** 中/高/低
```
では、提供されたフォローアップ Issue を分析し、これらのガイドラインに基づいた改善されたバージョンで Issue の説明を更新してください。
ステップ 3: レビューと改善
改善された Issue を以下の観点でレビューします:
- 技術的正確性
- 受け入れ基準の完全性
- 適切な優先度とラベル
- 明確な実装パス
改善前後の例
改善前
[スクリーンショットのプレースホルダー - 元のフォローアップ Issue]
典型的な特徴:
- 汎用的なタイトル: 「ユーザー認証の実装からのフォローアップ」
- 説明には次のみ含まれる: 「このメソッドを読みやすくするためにリファクタリングすべきです」
- どのメソッドやファイルかに関するコンテキストなし
- 実装のガイダンスなし
- 受け入れ基準なし
改善後
[スクリーンショットのプレースホルダー - 改善されたフォローアップ Issue]
改善された特徴:
- 具体的なタイトル: 「読みやすさ向上のための UserAuthenticator.validateCredentials() のリファクタリング」
- 背景、現状、提案された変更を含む包括的な説明
- 明確な受け入れ基準
- コード分析に基づく実装提案
- リンクされた依存関係と影響を受けるファイル
チームへのメリット
改善されたフォローアップ Issue はチーム全体に大きな改善をもたらします:
- 明確な理解: 何をする必要があるかについての推測が不要になり、どのチームメンバーでも Issue を引き継いで作業できる
- より良い計画: 明確に定義された Issue は正確な工数見積もりによってスプリントにスムーズに組み込まれる
- 技術的負債の削減: 曖昧な Issue が実際に対処される実行可能な改善に変わる
- 知識の保全: コンテキストと実装のガイダンスにより時間の経過とともに情報が失われることを防ぐ
- 時間の節約: 実装中のやり取りが少なくなる
使用ガイドライン
使用する場合
- MR ディスカッションから作成されたすべてのフォローアップ Issue
- 明確化が必要な既存の曖昧な Issue
- 「詳細情報が必要」とマークされた Issue
- より良い定義が必要な技術的負債項目
使用しない場合
- すでに明確に定義されている Issue
- 明確な再現手順を持つシンプルなバグレポート
- すでに包括的な要件が提供されている Issue
ガイドライン
- Issue を改善する際はドキュメント作成よりも実行可能性に焦点を当てる
- コードスニペットは明確さを加える場合にのみ含める
- 関連するアーキテクチャの決定やドキュメントにリンクする
- 技術的正確性とテスト可能な受け入れ基準について改善された Issue をレビューする
- 改善後に適切なラベルと担当者を追加する
成功基準
Issue 解決時間の改善、フォローアップ Issue の完了率の向上、実装中の明確化の必要性の減少を通じて成功を測定します。改善された Issue は、どのチームメンバーでも効率的に引き継いで完了できるほど明確であることが必要です。
フィードバックとイテレーション
このプロセスはチームのフィードバックと結果に基づいて進化させるべきです。定期的なレビューセッションでは以下を取り上げます:
- プロンプトの有効性と精度
- プロセスの効率性と採用率
- 品質の改善と提案
- ツールの制限と回避策
最終更新: [28/08/2025] プロセスオーナー: [Kamil Niechajewicz]
