故事式逐步解說 是做什麼的？
使用者想要了解一個他們未曾親身經歷的問題。他們不熟悉相關的元件、術語或事件發生的順序。一份發現清單或差異摘要對他們沒有幫助。故事才能幫助他們：一次介紹每個角色，然後按順序展示每個角色的行為，直到故障自然地發生。
請先進行調查。故事的品質取決於其背後的事實，因此在撰寫之前，請先閱讀程式碼、日誌、工單、文件和歷史記錄。如果對話中已經進行過調查，請重複使用結果，而不是再次調查。
回答的結構
開頭用一句話設定框架，例如：「這是從頭開始的完整故事，假設你不知道程式碼。」然後使用以下章節。如果某個章節沒有實際內容可說，請跳過它，不要為了填充而硬寫。
角色
介紹故事所需的所有角色，且僅限於這些角色：元件、類別、訊息、計時器、資料，以及對於流程而言，相關的人員、團隊、表單和設定。為每個角色提供一個粗體的名稱，並用一兩句簡單的句子說明它是什麼以及在這個故事中它做什麼。
- 精確地命名每個角色，並連結到程式碼。 例如，寫
price_cache_key()並附上file:line連結，而不是寫「金鑰建構器」。模糊的標籤會讓讀者停下來思考它的含義。如果一個角色橫跨多個程式碼片段（一個方法加上圍繞它的框架鉤子），請在此處說明。對於程式碼以外的問題，請改為連結來源：文件和步驟、表單欄位或設定路徑。 - 為抽象機制選擇一個具體的隱喻，並在整個故事中保持一致。 例如，將訊息標頭比喻為「釘在信封上的便條」，將快取比喻為「白板」，將鎖比喻為「鑰匙」。在角色真實名稱旁邊介紹這個隱喻（例如「價格快取，每個網頁伺服器旁的一塊白板」），以便讀者可以將其對應回程式碼。不要在途中切換隱喻，也不要堆疊兩個隱喻。
- 說明每個角色遵循的規則，並以角色自己的思考用斜體表示：「今天是『我的時鐘顯示的日期』。」 錯誤和流程失敗通常來自兩個合理規則的碰撞，這能讓碰撞在後續的章節中變得明顯。
章節
按時間順序說明發生的事情，每一步一個章節：## 第1章：購物者在午夜前查看價格、## 第2章：新價格到來，依此類推。使用簡短的標題來說明發生什麼事。
- 保持每個章節簡短：幾句話或幾個要點。
- 加粗章節的關鍵細節，即讀者絕對不能錯過的一件事（例如「「匯入操作擦除了白板上錯誤的角落」」）。
- 當兩件事同時發生時，單獨設立一個章節，並依序展示兩者的情況。
- 故障章節應以引用區塊的形式引用確切的錯誤訊息，並說明哪個程式碼捕獲了它以及它記錄了什麼。
為什麼症狀會是這樣
在故障之後，解釋觀察到的模式：為什麼只出現在前幾個小時、為什麼只出現在某些伺服器上、為什麼只在重啟之後。將其與工單或日誌中實際顯示的內容聯繫起來。這是驗證故事是否正確的檢查點，請務必保留。
當問題是風險，而非故障時
有時故事是關於可能出錯的事情：審查意見、潛在的錯誤、「萬一」的情況。既然沒有發生故障，就沒有日誌行或工單症狀來錨定故事。請以不同的方式講述，因為看到引用錯誤的讀者會假設它已經發生了。
- 及早說明它尚未發生。 在開頭或第一章中說明這是透過閱讀程式碼發現的潛在故障，而非在日誌或測試中看到的。
- 詳述條件。 故障章節列出故障發生必須滿足的確切條件，以編號條件表示（例如「1. 操作在其作用域關閉後呼叫了另一個服務，且 2. 該呼叫周圍沒有開啟新的作用域」）。然後說明會出什麼問題：斷言、異常類型、程式碼行。不要引用沒有人看過的錯誤訊息。如果你提到了異常，請說明這來自於閱讀程式碼。
- 將「為什麼症狀是這樣」替換為「為什麼今天沒有人觸發它」。 逐一檢查每個實際的呼叫者或流程，並展示它不滿足哪個條件，並附上連結。這部分承載了故事的重點，因為讀者必須判斷風險是否真實存在。
- 尋找你尚未檢查的呼叫者。 撰寫風險的「嚴重程度」清單時，未經檢查的路徑會顯現出來：在非正常位置進行的呼叫、不同的傳輸方式、背景任務。列出每一個為「未檢查」，而不是直接忽略，並說明現有的證據（例如，一個執行了該功能但未追蹤其路徑的乾淨測試運行）。
- 在修復方案部分比較成本。 針對風險的修復可能會帶回實際的故障。如果是這樣，請明確說明：這個修復是用一個沒人會觸發的風險，換取一個會發生的故障。
為什麼現在才開始
如果行為是迴歸，請說明什麼變了、何時變的，以及為什麼那個改變本身是合理的。先用文字說明 PR 或提交，然後在括號中給出 ID。讀者需要知道先前的改變並非粗心大意，只是不完整。
嚴重程度
列出實際影響：資料、數字、警報、日誌噪音。區分哪些是已確認的，哪些是推斷的，因為讀者會向其他人重複這些說法。
- 將每個說法標記為已檢查（並說明如何檢查：測試、日誌查詢、端到端程式碼路徑閱讀）或未檢查。
- 除非有驗證過，否則不要寫「資料沒問題」。一個看似合理但結果錯誤的說法，比一個誠實的「尚未檢查」更損害信任度。
如何修復
從小到大列出選項（例如快速修復和適當修復），用故事的語言說明每個選項改變了什麼（例如「給兩個角色同樣的日曆」），以及它的限制。最後以一個簡短的建議結尾。
風格
- 使用簡單的詞彙。每個術語首次出現時都要定義，否則就不要使用。
- 將程式碼標識符放在反引號內，緊鄰隱喻旁邊，以便故事始終可以對應回程式碼。
- 首選簡短段落和要點，而不是長篇幅的區塊。
- 遵循使用者的
CLAUDE.md或AGENTS.md檔案中的寫作風格規則。
故事之後
預期會有關於某個角色的後續問題（例如：「所以 X 是處理器？」）。回答時要將角色錨定到確切的程式碼：列出按順序執行的內容，附上 file:line 連結，並說明哪一部分做了重要的事。如果問題顯示原始故事命名不夠精確，請在回答中修正命名，而不是為其辯護。
範例
references/example-stale-prices.md 包含一個針對快取過時錯誤的完整故事，以及關於它哪裡寫錯的筆記。在你於會話中撰寫第一個故事之前，請先閱讀它以校準篇幅和語氣。