write-bug

バグの報告（FOLIO）

FOLIO のバグ報告は、再現可能で、具体的で、証拠に裏付けられている必要があります。読者が推測せずに不具合を再現できるようにしてください。

事前のコンテキスト検索

最初の完成したバグ報告の草案を作成する前に、影響を受ける領域と確認できる症状が検索できる程度に明らかになった時点で、関連する既存の Jira 課題を検索し、有力な一致項目を確認してください。これは、草案のみの依頼にも、チケットを起票する依頼にも適用されます。未解決のバグだけに絞らず、オープンの課題と解決済み／クローズ済みの課題を対象にしてください。

検索を始めるために本当に必要な情報だけを尋ねてください。領域と症状がわかったら、すべての受付項目が埋まるまで待たないでください。その後、検索で見つかった内容を反映し、実際に残っている不足情報を尋ねてください。

設定済みの Jira 検索／閲覧機能と、その実際のスキーマを使用してください。このスキル内のツール名は例であり、必須条件ではありません。検索が利用できない、不完全である、またはユーザーが検索を除外している場合は、利用可能な証拠に基づいて続行し、その制約を明示してください。十分な検索を実施していない場合に、「重複なし」と報告してはいけません。

検索クエリの作成、候補の確認、検索結果の分類方法については、references/context-search.mdを参照してください。

検索結果の活用

• 関連する一致項目だけを示してください。課題キーまたはリンク、ステータス、および関連性についての短い説明を含めてください。
• 重要なコンテキストは、「概要」、「期待結果」の根拠、または「追加情報」など、該当する場所に記載してください。長い検索レポートセクションは作成しないでください。
• 既存の課題が重複の可能性が高い場合は、そのチケットを推奨してください。草案のみの支援であれば、必要な再現手順や証拠を準備する作業を続けてください。
• 自発的に既存の課題を作成、コメント、更新、リンク、再オープン、またはクローズしてはいけません。重複の可能性が高いにもかかわらず新しいチケットを起票する場合は、関連性を示した後、ユーザーの明確な判断を得てください。

バグの構成

FOLIO のすべてのバグ報告には、以下のセクションを記載してください（順序もこのとおり）。(optional) と示されたセクションは、記載する価値がない場合は省略します。

1. 概要 — Jira 課題の1行タイトルです。影響を受ける領域と確認できる症状を明記してください。概要のルールを参照してください。
2. 概要／コンテキスト (推奨) — 影響、発生源（例：TICKET-123 からのリグレッション）、またはビジネス上の背景を説明する1～3文です。FOLIO のバグ報告の大半は「概要：」セクションから始まります。概要だけで不具合が完全に明らかな場合を除き、このセクションを含めてください。
3. 前提条件 — 手順を実行する前に必要な環境、データ、ロール、権限、機能フラグ、または先行チケットです。各前提条件は個別に検証可能でなければなりません。
4. 再現手順 — 番号付きの、個別に実行可能な操作です。各手順にはユーザー操作を1つだけ記載してください。事前の画面遷移を前提にしないでください。
5. 期待結果 — システムがどのように動作するべきかを記載してください。可能であれば、仕様、受け入れ基準、以前の動作など、根拠となる情報源を参照してください。
6. 実際の結果 — システムが実際にどのように動作するかを記載してください。エラーメッセージは原文どおりに引用し、関連する場合はステータスコードや ID も含めてください。
7. 追加情報 (任意ですが、強く推奨) — スタックトレース、リクエスト／レスポンスのペイロード、クエリプラン、ログ抜粋、スクリーンショット、動画、影響を受ける環境の URL、再現率などです。

テンプレート

## Overview

[1–3 sentences on impact, affected users, regression source, or related tickets.
Recommended for anything non-trivial — FOLIO bugs conventionally open with this.]

---

## Preconditions

1. [Environment / tenant / user role]
2. [Data state — e.g. "An Order in 'Open' status exists with one PO line"]
3. [Feature flag / configuration]

---

## Steps to reproduce

1. [Single user action]
2. [Single user action]
3. [Single user action]

---

## Expected result

- [Observable outcome #1]
- [Observable outcome #2, referencing spec/AC if applicable]

---

## Actual result

- [Observable outcome #1, including exact error text]
- [HTTP status / error code / record state]

---

## Additional information (optional)

**Reproducibility:** [Always / Intermittent (X of Y) / Once]
**Environment:** [folio-etesting-snapshot / folio-etesting-sprint / local]
**Module versions:** [mod-orders 13.0.5, ui-orders 9.1.2]
**Related tickets / prior fixes:** [PROJECT-123 — state how it relates]
**Regression status / evidence:** [Only when relevant; say whether it is possible or confirmed]
**Workaround:** [Describe any workaround found, or "None" / omit if not applicable]
**Test Cases:** [TestRail IDs, e.g. C15189, C15190 — omit if not used by your team]

\`\`\`
[paste stack trace or log excerpt]
\`\`\`

**Attachments:** screenshots / HAR / video (attach to Jira)

概要のルール

優れた概要は**「ひと目でわかるか」テスト**に合格します。トリアージ担当者が、タイトルだけで優先度と担当先を判断できるようにしてください。

形式

[<Area/Component>] <symptom> when <trigger/condition>

Jira プロジェクトですでに領域が限定されている場合（例：UIOR は Orders UI を示します）、[<Area>] の接頭辞は省略できます。

すべきこと

• 確認できる症状を明記してください。「500 を返す」、「重複行を表示する」、「更新されない」、「変更が反映されない」などです。
• 発生条件を含めてください。「所蔵を移動したとき」、「外貨で請求書を支払った後」、「注文が 50k 件を超えるテナントで」などです。
• 環境固有のバグである場合に限り、環境を記載してください（例：環境固有の課題では、接頭辞に「M-an dry-run |」を付けます）。

避けること

• 曖昧なタイトルは付けないでください。❌「注文のバグ」、❌「動作しない」。
• タイトルで修正方法を指定しないでください。❌「X に null チェックを追加する」。
• トリアージ担当者が把握していない実装の詳細を、必要以上に加えないでください。

例（実際の FOLIO のバグから）

• ✅「receiptDate を更新しても POL 監査履歴の updatedDate が更新されない」
• ✅「注文の使用済み金額で請求書の通貨が変換されない」
• ❌「POL のバグ」
• ❌「通貨処理を修正する」

作成ガイドライン

再現手順

• ログイン直後のクリーンな状態から始めるか、事前条件にその状態を記載してください。
• 各ステップでは操作を1つだけ行います。「注文を開いて［受領］をクリックする」は2つに分けてください。
• **文字どおりに記載してください。**正確な UI ラベルまたは API パスを使用します。 POST /orders/wrapper-pieces?query=...。
• ID ではなくプロパティでデータを示してください。「受領ワークフローが同期型で、ステータスが「Open」の注文」は、「注文 d4e7-...」より適切です。
• **失敗した時点で止めてください。**失敗後の調査は記載しないでください。

期待される動作と実際の動作

• どちらもテスターが確認できる内容である必要があります。内部状態ではなく、観察可能な内容を記載してください。「エラーが発生しない」では不十分です。「「注文を保存しました」というトーストが表示され、ステータスが Open になる」のように記載してください。
• エラーはステータスコード、エラーコード、メッセージを含め、原文どおり引用してください。
• **期待値と実際の値の違いを明示してください。**フィールドの値が誤っている場合は、両方の値を記載します。

証拠

• スタックトレース → フェンス付きコードブロック内に貼り付けてください。Jira ではスクロール可能な {code} ブロックとして表示されます。
• ログ → タイムスタンプ、ロガー名、レベル、相関 ID を含めてください。
• SQL／クエリプラン → パフォーマンスのバグでは含めてください。
• スクリーンショット／動画 → Jira に添付し、ファイル名を記載してください。
• 再現率はトリアージで重要です。必ず発生するのか、断続的に発生するのかを記載してください（例：「10回中3回」）。

優先度と重大度（FOLIO スケール）

このマトリックスを初期判断の目安として使用してください。トリアージチームが再割り当てする場合があります。

優先度	使用する条件
P1 — 致命的	正確性または可用性に深刻な問題がある場合。データの消失や破損、セキュリティの脆弱性、金額や計算結果の誤り、ログイン／認証の障害、アプリ全体または主要なワークフローが使用不能になる場合、リリースを妨げる場合、またはシステム全体の下流プロセスに影響する場合。
P2 — 重大	中核となるワークフローが機能しない、または誤った結果を生成し、妥当な回避策がなく、多くのユーザーに影響する場合。
P3 — 通常	回避策がある不具合で、特定のフローまたは一部のユーザーに影響する場合。
P4 — 軽微	見た目、誤字、影響の小さいエッジケースに関する問題。
TBD	優先度が未評価の場合。起票時は問題ありませんが、トリアージで評価されます。

ユーザーとのやり取りの流れ

最終的なバグ報告を作成する前に、必要な情報がユーザーから提供されているか確認してください。 以下の情報に不足または曖昧な点がある場合は、ユーザーに質問してください（関連する質問はまとめてください）。質問ツールが利用可能な場合は使用してください。利用できない場合は、チャットで直接質問して構いません。依頼内容やコンテキスト検索ですでに示されている情報は、再度質問しないでください。

1. 対象の Jira プロジェクト（例：MODORDERS、UIOR、FOLIO）。サマリーのプレフィックスを作成し、Jira での起票方法を判断するために必要です。
2. バグが発生する環境（スナップショット、bugfest、dry-run、ローカル、特定のテナント）。
3. 再現性（常に発生／断続的に発生／一度だけ発生）。トリアージの判断材料になります。
4. 症状しか示されていない場合は、再現手順。
5. 期待される動作の根拠（仕様、チケット、「以前のリリース」など）。「期待される動作」が主観的な場合に必要です。
6. 補足資料 — ログ、スタックトレース、スクリーンショット、HAR、録画。
7. 影響について情報がある場合は、優先度の提案。

修正バージョン、コンポーネント、ラベルなど、トリアージ担当者が判断できる項目については、ユーザーから情報が提示されていない限り質問しないでください。

任意：Jira にバグを登録する

ユーザーがドラフトを承認した後、mcp-atlassian_jira_create_issue を使ってチケットを作成するか確認します。

• 合意したプロジェクトキーと issue_type: "Bug" を使用します。
• Markdown のドラフトを Jira のマークアップに変換します（references/jira.md を参照）。
• priority、labels、components、fixVersions は、ユーザーが確認した場合に限り additional_fields を通じて渡します。
• 作成後、課題キーと URL を返します。

このセッションですでに確認したコンテキスト検索の結果を再利用します。症状、範囲、プロジェクト、または関連する根拠に重大な変更があった場合、結果が古くなったと考える具体的な理由がある場合、またはユーザーが更新を求めた場合は、検索結果を更新します。ドラフトが承認されたというだけの理由で、変更のない検索を繰り返してはいけません。

ベストプラクティス

する ✓

1. 1 チケットにつき 1 件のバグにします。複合的な不具合は分割します。
2. 他の人が開始状態に到達できるよう、前提条件を記述します。
3. エラーはコードや ID を含め、一字一句そのまま引用します。
4. 間欠的に発生するバグでは、再現率を記載します。
5. 関連するチケットや過去の修正へのリンクを記載し、それぞれとの関連性を説明します。
6. 最初の完全なドラフトを作成する前に、オープンおよびクローズ済みの課題を検索するか、検索できなかったことを明記します。
7. 回帰に関する表現は根拠に合わせます。可能性と確定を区別し、裏付けとなるデータなしに原因となったチケットやコミットを挙げてはいけません。

しない ✗

1. 要約や手順で根本原因を推測してはいけません。仮説は、明確にラベルを付けた 追加情報 の注記に記載します。
2. 1 つのチケットに複数の不具合を混在させてはいけません。
3. 「動作しない」「壊れている」「挙動がおかしい」のような曖昧な動詞を使ってはいけません。
4. シークレット（トークン、実際のユーザーメールアドレス、テナントの認証情報）を貼り付けてはいけません。
5. バグ自体に修正案を含めてはいけません。修正案は PR またはリンクされたストーリーに記載します。
6. 期待される結果を省略してはいけません。「正常に動作するはず」ではテストできません。

クイックリファレンスチェックリスト

• 要約に領域、症状、発生条件が記載されている
• 前提条件を第三者が個別に検証できる
• 手順に番号が振られ、各手順が独立しており、定義された状態から始まる
• 期待される結果が信頼できる情報源を参照している
• 実際の結果に正確なエラーテキスト／ステータスコードが含まれている
• 再現率が記載されている
• 環境とモジュールのバージョンが記録されている
• スタックトレース／ログ／スクリーンショットが添付または本文に記載されている
• 回避策がある場合は記録されている
• 個人を特定できる情報、シークレット、実際の認証情報が含まれていない
• 最初の完全なドラフトを作成する前に、オープンおよびクローズ済みの課題が検索されている。または、検索できなかった制約が明記されている
• 実際に調査した一致候補が、それぞれとの関連性とともに示されている
• 重複および回帰に関する表現が根拠と一致している
• 新しいチケットを作成する判断に、検索で判明した内容が反映されている
• 1 チケットにつき 1 件の不具合になっている

各セクションの詳しいガイダンスについては、references/section-details.md を参照してください。 完全なバグ報告の例については、references/example.md を参照してください。 Markdown から Jira のマークアップへの変換については、references/jira.md を参照してください。 修正前／修正後の書き換えでよくある落とし穴については、references/pitfalls.md を参照してください。 コンテキスト検索の範囲、調査、分類については、references/context-search.md を参照してください。