jira-report-comment

Jira Report Comment

チケットでリリースされた内容を説明する短い Jira コメントを作成し、ローカルの Markdown ファイルとして保存します。

読み手となるのは、チケットをすでに開いている PM、QA エンジニア、アーキテクトです。チケットの内容を言い換える文はどれも読み飛ばされます。そのような文が2つ続けば、コメント全体を読まなくなります。したがって、コメントにはチケットからは分からないこと、つまり実際にリリースされた内容と、それによって後続の担当者が変更する必要のあることだけを記載します。

デフォルトでは、要約の段落を1つ記載します。バグ修正には Root Cause を追加します。Verify と Deploy のセクションは、差分に具体的な理由がある場合にのみ追加します。

Step 1 — Issue キーを特定する

次の順に確認します。ユーザーが指定したキー、指定がなければ git branch --show-current の最初の [A-Z]+-[0-9]+ に一致する文字列、それもなければユーザーに確認します。

続行する前に、次のように確認します。「ブランチから CX-4328 を検出しました。この Issue キーを使用しますか？」

次に出力ファイルを確保し、セッションの残りの間は同じパスに書き込みます。同じ Issue に対してスキルを再実行した場合、別のファイルを追加するのではなく、既存のファイルを更新します。

mkdir -p docs/jira-reports
touch "docs/jira-reports/$(date +%Y-%m-%d-%H%M%S)-<ISSUE_KEY>.md"

Step 2 — チケットを取得する

Atlassian MCP サーバーの getJiraIssue ツールを使ってキーを指定します。利用できない場合は、タイトル、説明、受け入れ条件を貼り付けるようユーザーに依頼します。

タイトル、説明、タイプ、ステータスを確認します。これらは記載する内容ではなく、記載から除外する内容です。 除外リストとして使用します。

Step 3 — 差分を取得する

git log --grep="<ISSUE_KEY>" --format="%H %s" --reverse

見つからない場合は、--all を付けて再試行します。それでも見つからない場合は、ブランチとそのベースとの差分を取得します。main、次に master、次に develop の順で試します。

git diff $(git merge-base HEAD main)..HEAD --stat
git diff $(git merge-base HEAD main)..HEAD

コミットが見つかったら、段階ごとの差分ではなく、範囲全体の差分を取得して最終的な変更内容を確認します。

git diff <FIRST_COMMIT>^..<LAST_COMMIT> --stat
git diff <FIRST_COMMIT>^..<LAST_COMMIT>

最初のコミットがリポジトリの初回コミットである場合は、git diff $(git hash-object -t tree /dev/null)..<LAST_COMMIT> を使用します。意味のある差分が見つからない場合は、その旨を伝えて終了します。

ファイル数が約50を超える場合は、stat の概要をもとに、対象を絞って読みます。通常、設定ファイル、マイグレーション、テストからは実装よりも早く意図を把握できます。

Step 4 — 追加するセクションを決める

構成、制限、スタイルについては references/output-format.md を確認します。

Root Cause — チケットが既存の問題を修正する場合に追加します。説明に、動作不良、誤った結果、欠陥、またはリグレッションが記載されています。Issue のタイプが Bug であることは有力な手がかりですが、必須ではありません。Story や Task でも問題を修正することがあります。チケットには症状が記載されており、それを繰り返すだけではこのセクションの意味がありません。差分とコミットメッセージから原因と修正方法を導き出します。

Verify — 次のいずれか1つ以上に該当する場合に追加します。

• 差分でフィーチャーフラグが追加され、テスト経路がその状態に依存する
• 差分で、チケットに記載されていない副作用（メール、Webhook、ログ、メトリクス）が発生する
• 差分で、チケットに記載されていない入力値によって実行されるコードパスが追加される
• 差分で、チケットに触れられていないロールまたは権限レベルの動作が変更される

Deploy — 次のいずれか1つ以上に該当する場合に追加します。

• 差分で環境変数が追加または改名される
• 差分でフィーチャーフラグが追加される（名前とデフォルト値を記載する）
• 差分で、手動調整が必要なマイグレーション（バックフィル、ロック負荷の高いスキーマ変更）が追加される
• 差分でキュー、スケジュールジョブ、または cron エントリーが追加される
• 別のシステム（CDN、IAM、DNS）の設定変更が必要になる

どの条件にも該当しない場合、コメントには要約だけを記載します。大半の機能開発ではそれが想定される結果であり、何かを見落としたということではありません。

ステップ 5 — 作成、監査、保存

まず概要を書き、条件に該当したセクションだけを追加します。その後、次の点を監査します。

• 定型作業を説明する箇条書きは削除します — コードのプッシュ、サービスの再起動、キャッシュのクリア、標準的なマイグレーションの実行などです。これらは実施済みだと読者は想定しています。
• チケットの言い換えを削除します。 ステップ 2 のチケット本文と照らし合わせて読み直し、内容を反映している表現をすべて削ります。
• 差分で確認できない変更は決して記述しないでください。

ステップ 1 で予約したパスに書き込み、「レポートを <path> に保存しました。」と確認します。ファイルは未追跡のままにし、ステージングやコミットは決して行わないでください。humanize-text スキルが利用できる場合は、提示する前にレポートに適用してください。

例 — バグ修正

BUG-789「ユーザーがサブスクリプションをキャンセルすると、キャンセル通知メールが 2 通送信される」。差分では、古い onCancellation ハンドラーの登録を削除し、onSubscriptionCancelled だけがメールを送信するようにしています。また、1 通だけ送信されることを確認するテストを追加しています。

BUG-789

キャンセル時に確認メールが 1 通だけ送信されるようになりました。

根本原因

• 一部のリファクタリング後、キャンセルイベントに 2 つのハンドラーが登録され、両方が実行されていました。
• 古い登録を削除し、新しいハンドラーだけが唯一の信頼できる処理元となるようにしました。

テストの内容はチケットからすでに想定できるため、Verify は不要です。通常のコード変更のため、Deploy も不要です。

例 — Deploy が必要な場合

XYZ-456「アクティブなメンバーに週次ダイジェストメールを送信する」。差分では、cron ジョブ、デフォルトでオフの weekly_digest_enabled フラグ、および DIGEST_SENDER_EMAIL 環境変数を追加しています。

XYZ-456

アクティブなメンバーに毎週月曜日の午前 9 時に週次ダイジェストメールを送信するようになりました。過去 7 日間にアクティビティがないアカウントは対象外です。

Deploy

• 機能を有効にする前に、本番環境で DIGEST_SENDER_EMAIL を設定します
• スモークテスト後に weekly_digest_enabled をオンにします
• 最初のスケジュール実行は、デプロイ後の最初の月曜日に行われます

環境変数、フラグ、cron エントリの 3 点に該当するため、Deploy が必要です。テストの内容がチケットの記述と一致するため、Verify は不要です。

問題が発生した場合

• イシューが見つからない — キーが無効と思われることをユーザーに伝え、確認を依頼します。
• コミットがない — その旨を明確に報告し、ブランチ名またはコミットメッセージで別のキー形式を使うよう提案します。
• MCP が利用できない — チケットのコンテキストを手動で提示するよう依頼します。
• 書き込みに失敗する — エラーを表示し、ディレクトリのアクセス権限を確認します。