researching-jira-issues

Jira の課題を調査する

ツールの出力をつなぎ合わせるのではなく、情報を統合してください。以下の各ステップでは生データを収集します。このスキルの価値は、課題、ドキュメント、コメントを横断して関連性を見つけ、人が行動に移せる一貫した理解にまとめることにあります。

ワークフロー

ステップ 1：メインの課題を取得する

課題キーを指定して get_issue MCP ツールを使用します。このツールはデフォルトで renderedFields と names を展開し、HTML 形式でレンダリングされたフィールドと、人が読み取れるカスタムフィールドの表示名を取得します。

以下を抽出して記録します。

• 課題タイプ（Epic、Story、Task、Bug、Sub-task など）
• 概要と説明
• 現在のステータスと優先度
• 担当者と報告者
• 作業内容を理解するうえで重要なフィールド（ラベル、コンポーネント、スプリントなど）
• 重要な背景情報を含むコメント（関係者による明確化、技術的な決定、実装に関するガイダンス）
• カスタムフィールド：レスポンスの Additional Fields セクションにある、null ではないカスタムフィールドをすべて提示します。names の展開により、フィールド ID が人が読み取れる表示名に自動的に対応付けられます。

ステップ 2：関連する課題をすべて特定する

メインの課題のレスポンスを調べ、以下から関連する課題を特定します。

1. 課題リンク：API レスポンスの issuelinks フィールドを確認します。このフィールドは Jira が返す型なし配列で、以下が含まれます。

   • ブロックする／ブロックされる関係
   • 依存する／依存関係
   • 関連リンク
   • クローン、重複、置き換えの関係
   • その他すべてのリンクタイプ

2. 階層リンク：以下を確認します。

   • 親課題（サブタスクの場合）
   • エピックリンク（エピックにリンクされている場合）
   • サブタスク（この課題にサブタスクがある場合）
   • 次世代プロジェクト：課題タイプが Epic または Feature で、subtasks が空の場合は、JQL parent = <ISSUE-KEY> を指定して search_issues MCP ツールを使用し、子課題を特定します。次世代の Jira プロジェクトでは、subtasks フィールドではなく parent の関係を使用します。

3. リモートリンク：課題キーを指定して get_issue_remote_links MCP ツールを使用し、以下を特定します。

   • リンクされた Confluence ページ（出力では「Confluence Pages」の下にまとめられています）
   • プルリクエストとコミット（「GitHub」の下にまとめられています）
   • 外部ドキュメントやその他のリソース

Step 3: 深さを制御してリンクされた課題を取得する

関連する課題を取得してコンテキストを構築しますが、効果が薄れ始める前に止めてください。ホップを追加するたびに API 呼び出しとコンテキストウィンドウの使用量が増える一方、直接的な関連性は低下します。

1. 優先順位：

   • 高優先度：Blocks、Depends on、Parent、Epic Link — 作業を開始できるかどうか、および課題が階層内のどこに位置するかを決定します
   • 中優先度：サブタスク、関連課題 — スコープを定義し、背景情報を提供します
   • 低優先度：Clones、Duplicates — 他では得られない固有のコンテキストが含まれる場合にのみ取得します

2. 深さの制御：

   • メインの課題から最大 2 レベル先までたどります（メインの課題 -> リンクされた課題 -> 高優先度のリンクのみ、さらにもう 1 ホップ）。2 レベルを超えるとコンテキストの関連性は急激に低下し、応答が膨らむリスクが高まります。
   • インラインの説明 URL（例：VULN-、SEC-）を介して他の Jira プロジェクトの課題が参照されている場合は、文脈に沿って参照に触れますが、正式な課題リンク（blocks/depends-on/relates-to）として表示されない限り、たどらないでください。プロジェクト間のインライン参照は情報提供を目的としたものであり、依存関係を示すものではありません。
   • 循環参照を避けるため、取得した課題キーを記録します（A が B にリンクし、B が A にリンクする場合など）
   • リンクされた課題ごとに、get_issue MCP ツールを使用して重要な情報を抽出します

3. 選択的な取得：

   • サブタスク：作業の全スコープを把握するため、すべて取得します。子課題が 10 件を超える場合は、最初の 10 件を取得し、残りは検索結果からコンパクトなリスト（キー、ステータス、要約）にまとめます。
   • ブロッキング課題：依存関係を把握するために取得します
   • 関連課題：理解に不可欠と思われる場合に取得します
   • 重複課題やクローン課題は、固有の情報が含まれていない限りスキップします

4. レート制限：API 呼び出しを多数行う場合は、リクエストの間隔を空けます。連続して 5 回呼び出すごとに、Atlassian のレート制限に達しないよう短時間（1 秒）待機します。429 応答を受け取った場合は、再試行する前に 10 秒待機します。

Step 4: リンクされた Confluence ドキュメントを取得する

Confluence ページには、要件、設計ドキュメント、仕様が記載されていることがよくあります。

1. 次の場所から Confluence ページのリンクを抽出します。

   • リモートリンクの出力（Step 2 — 「Confluence Pages」の下にグループ化されたリンク）
   • */wiki/spaces/*/pages/*/ に一致する課題の説明 URL
   • Confluence を指すコメント URL

2. Confluence のリンクごとに、次の操作を行います。

   • URL から pageId を抽出します（例：https://domain.atlassian.net/wiki/spaces/SPACE/pages/123456789/Title -> 123456789）
   • ページ ID を指定して get_confluence_page MCP ツールを使用します
   • ページのタイトルと、内容に含まれる重要な情報を記録します

3. ページのコンテキスト予算：2000 語を超える Confluence ページについては、ページ全体を再掲するのではなく、課題に関連するセクションを要約します。要件、受け入れ基準、技術的制約、設計上の決定事項に焦点を当てます。

Step 5: 失敗に適切に対処する

取得に失敗した場合は、その失敗を記録し、利用可能なデータを使って処理を続行します。具体的な失敗ケースは次のとおりです。

• リンクされた課題で 404 が発生：課題が削除または移動されています。キーを記録してスキップします。
• Confluence ページで 403 が発生：アクセス権がありません。リモートリンクからページタイトルを記録してスキップします。
• リモートリンクで 404 が発生：エンドポイントを利用できない可能性があります。スキップし、メインの応答に含まれる課題リンクを使用します。

取得できなかった項目は、最後に必ず報告してください。

Step 6: 情報を統合して提示する

収集した情報を整理し、包括的に把握できる形にします。

課題の概要

• この課題の主な目的は何ですか？
• どのような種類の作業ですか（新機能、バグ修正、技術的負債など）？
• 現在のステータスと担当者は誰ですか？

要件とコンテキスト

• 主な要件や受け入れ基準は何ですか？
• どのような問題を解決しますか？
• この作業を裏付けるドキュメントは何ですか？
• null 以外のカスタムフィールドがある場合は、表示名を見出しとして、その内容を Markdown 形式で表示します

依存関係と関連性

• 先に完了する必要がある課題（ブロッキング依存関係）は何ですか？
• この課題がブロックする課題（後続への影響）は何ですか？
• より大きなエピックやプロジェクトの中で、この課題はどのような位置づけですか？

作業範囲

• サブタスクには何がありますか？
• 作業の内訳はどうなっていますか？
• 追加の背景情報が得られる関連課題はありますか？

主なポイント

• コメントやドキュメントに記載された技術的な決定事項や制約
• 言及されているリスクや懸念事項
• 重要な経緯（なぜクローンされたのか、何に置き換えられたのかなど）

コンテキストの上限

全体をまとめると約4000語を超える場合（読み手が内容を吸収するよりも流し読みし始める目安です）、優先度の低いリンク済み課題（関連、クローン、重複）は、キー、ステータス、概要のみを含む1行の要約に簡略化してください。ユーザーから追加の指定がない限り、表示するコメントは直近3件までにしてください。

例

examples/deep_read_workflow.md

サブタスク、ブロッキング課題、リンクされたConfluenceドキュメントがあるストーリーの詳細な読み解きを、最初から最後まで説明します。