inspecting-jira-issues

AI エージェント向け Jira 課題の調査

概要

Jira の要約は、バグを理解する方法としては最悪です。実際の再現手順はほとんどの場合、添付ファイル、コメント、またはリンクされた課題にあります。acli jira workitem view では、これら 3 か所はデフォルトで表示されません。「要約をもとに作業する」AI エージェントは、問題の半分を推測することになります。

このスキルは、コマンドラインから Jira チケットを漏れなく読み取るための標準的な手順であり、エージェントが実際に確認できる添付ファイルのデータをダウンロードする方法も説明します（ここが分かりにくい点です。acli には attachment download サブコマンドがありません）。

使用する場面

• Jira の URL を開いたばかりで、修正に取りかかろうとしている
• 説明欄が image-20260427-021811.png だけで、テキストがない
• エージェントが「要約をもとに作業します」や「スクリーンショットを貼ってもらえますか」と言う
• Jira REST API に対する curl が 401／403／406 を返す

添付ファイルもリンクされた課題もない情報量の少ないチケットには使用しないでください。その場合は acli jira workitem view KEY で十分です。

調査ワークフロー

最短の手順はコマンド 1 つです。絶対パスを使用してください。このスキルは ~/.claude/skills/inspecting-jira-issues/ に配置され、デフォルトでは PATH に含まれていません。

JIRA_SITE=https://your-site.atlassian.net \
  ~/.claude/skills/inspecting-jira-issues/jira-to-markdown.py KGM-3320
# → /tmp/jira/KGM-3320/ticket.md
# → /tmp/jira/KGM-3320/attachments/*
# → /tmp/jira/KGM-3320/subtasks/<CHILD-KEY>/...   (every child, recursively)

デフォルトでは、すべてのサブチケットも再帰的にダウンロードします。従来のサブタスクと、親／エピックの子課題の両方が対象です（parent = <KEY> 検索で取得するため、subtasks フィールドに含まれないエピックの子課題も取得されます）。各子課題は subtasks/<KEY>/ に完全なダンプとして保存され、孫課題用の subtasks/ もそれぞれに含まれます。最上位の課題のみを取得するには --no-subtasks を渡します。

（README の手順に従って ~/bin/ にシンボリックリンクを作成すると、jira-to-markdown.py KGM-3320 のようにパスを省略して実行できます。）

jira-to-markdown.py は、自己完結したディレクトリを書き出します。ticket.md には、値が入力されたすべてのフィールドが出力されます。ヘッダーテーブルには、すべてのスカラー値フィールド（標準フィールドとカスタムフィールド。ラベルは ?expand=names で解決）が含まれ、ADF ドキュメント形式の各フィールドには専用の ## Section（Description、Environment、および ADF 形式のカスタムフィールド）が作成されます。その後に添付ファイル、リンクされた課題、サブタスク、コメントが続きます。すべての添付ファイルは attachments/ にダウンロードされ、![alt](attachments/foo.png) の形式でインライン参照されます。また、--no-subtasks を渡さない限り、すべてのサブチケットが subtasks/ に再帰的にダウンロードされます。

網羅的に取得する理由は、TPT のバグチケットでは、実際の再現手順が fields.environment（発生工程、再現手順、プラットフォームなど）に記載されていることが多く、説明欄にも acli workitem view にもデフォルトでは表示されないためです。Severity、Urgency、Epic Link などのカスタムフィールドも同様です。事前に取得するフィールドを選定すると、チケットを 1 件ずつ確認するたびに欠落したフィールドを再発見することになります。

このスクリプトは、分かりにくい点にも対応しています。キーチェーンに保存された OAuth トークン、ADF から Markdown への変換（段落、リスト、見出し、コード、リンク、マーク、メンション、パネル、テーブル、メディア）、ファイル名の重複を避ける処理、そして 406 Not Acceptable を回避する Accept: */* の仕様です。

一部の情報だけが必要な場合は、より低レベルのコマンドも引き続き使えます。

KEY=KGM-3320

acli jira workitem view "$KEY" --fields '*all' --json     # full JSON
acli jira workitem attachment list --key "$KEY" --json    # attachment IDs
~/.claude/skills/inspecting-jira-issues/download-jira-attachment.sh 188469 /tmp/$KEY.png
acli jira workitem comment list --key "$KEY"              # comments alone

情報がある場所

知りたいこと	実際の場所
バグの再現手順	説明欄ではなくコメント
バグを示すスクリーンショット	添付ファイル
このチケットの重要性／顧客への影響	カスタムフィールド（重大度、緊急度）。--fields '*all' で取得
修正が別の場所ですでにリリースされたかどうか	親エピックのコメント、または「is duplicated by」というリンク
実際の症状	要約ではなく、スクリーンショット

添付ファイルのダウンロード — 見落としやすいポイント

acli には attachment download がありません。*.atlassian.net/rest/api/3/attachment/content/<id> に curl を直接実行すると、403 が返されます。エージェントが必ずつまずく4つの落とし穴は次のとおりです。

落とし穴	回避方法
OAuth トークンはどこにある？	macOS キーチェーン（security find-generic-password -s acli）にあります。~/.config/acli/ ではありません。go-keyring-base64:<base64(gzip(JSON))> として保存されています。
どの URL にアクセスすればいい？	https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/attachment/content/<id> — OAuth プロキシです。サイトの URL では acli のトークンは使えません。
cloudId はどこにある？	キーチェーンのアカウント名がそのまま oauth:<cloudId>:<userId> になっています。getAccessibleAtlassianResources を呼び出す必要はありません。
リクエストが 406 になるのはなぜ？	Accept: image/png を指定すると 406 が返されます（「Acceptable representations: [application/json]」）。Accept: */* を使うか、Accept を省略してください。

このスキルのディレクトリにある jira-to-markdown.py（チケット全体のダンプ）と download-jira-attachment.sh（添付ファイル1つのダウンロード）には、4つすべての回避策が組み込まれています。これらを $PATH（例：~/bin/）にコピーしてください。

前提条件

brew tap atlassian/homebrew-acli
brew install acli
acli auth login        # one-time OAuth dance — also re-run if you change sites

最初の acli auth login で、OAuth トークンが macOS キーチェーンに保存されます。このスキルの両方のスクリプトは、そこからトークンを読み取ります。

オプション：Excel 添付ファイルの解析

チケットに .xlsx / .xls / .xlsm ファイルが添付されている場合、jira-to-markdown.py は xlsx-to-markdown スキルを使って、シートごとの PNG と抽出テキストを含む Markdown に変換します。ファイルの隣にある attachments/<stem>-xlsx/ に出力し、添付ファイルセクションからリンクします。これはベストエフォートです。スキル（またはその CLI 依存関係）がインストールされていなくてもダンプは完了し、スキップしたことが stderr に記録されます。有効にするには、次を実行してください。

npx skills add coolbit/excel-to-markdown      # installs as xlsx-to-markdown
brew install poppler imagemagick              # + LibreOffice (soffice) — see that skill's README

コンバーターは ~/.claude/skills/ または ~/.agents/skills/ から自動的に検出されます（XLSX_TO_MD 環境変数で変更できます）。

トークンの有効期限

アクセストークンの有効期間は約1時間です。スクリプトは起動時に acli auth status を実行してサイレント更新を促すため、長期間使用していなかった後の最初の実行も、操作なしで成功します。acli auth status 自体がリフレッシュトークンの有効期限切れを報告する場合は、acli auth login を再実行してください。

よくある間違い

間違い	対処方法
要約だけを見て修正を始める	要約はラベルであり、バグそのものではありません。必ず最初に JSON と添付ファイルを取得してください。
「説明文にテキストがある」から添付ファイルを確認しない	説明文が画像を参照しているなら、その画像も説明の一部です。ダウンロードしてください。
コメントを無視する	再現手順、決定事項、「実際には PR #123 で修正済み」といった情報はここにあります。
関連チケットを確認しない	「is duplicated by」は、実際の修正計画が書かれたチケットを指していることがよくあります。
OAuth リクエストにサイトの URL を使う	api.atlassian.com/ex/jira/<cloudId>/... を使ってください。
Accept: image/png を使う	406 になります。Accept: */* を使ってください。
トークンを ~/.config/acli で探す	トークンは macOS キーチェーンにあります。設定ファイルにはメタデータしかありません。
キーチェーンのデータを生のトークンとして扱う	go-keyring-base64:<base64(gzip(JSON))> 形式です。デコードして access_token を抽出してください。
acli にダウンロードコマンドがないからと諦める	このスキルが存在する理由こそ、キーチェーンを使って迂回するためです。
ユーザーにスクリーンショットの貼り付けを頼む	API を直接使えるのに、ユーザーに手間をかけさせないでください。

危険信号 — 作業を止めて再確認する

次のように考えてしまった場合、チケットを最後まで読めていません。

• 「要約に基づいて、…」
• 「スクリーンショットを共有してもらえますか？」
• 「バグは…だと仮定します」
• 「説明にはあまり書かれていないので、…」
• 「添付ファイルはあるけれど、画像にはアクセスできない」

これらはすべて、上記の確認ワークフローを実行すべきという合図です。その後で考えてください。

鉄則

Jira チケットにスクリーンショット、添付ファイル、コメント、または関連チケットへの言及があり、それを読んでいないなら、まだバグを理解できていません。

チケットをすべて読んでください。その後で考えてください。