[skip deploy] docs(agents): specify how to write a PR description

AGENTS.md

@@ -25,6 +25,24 @@
 - Operator-only 設定（secret、deploy 流程、本機 dev）與程式寫作規範改 [`DEVELOPER.md`](DEVELOPER.md)。
 - **僅文件 / spec 更新 skip deploy**：如果這次的 PR 只有文件或 spec 更新，在 PR 的標題上加上 `[skip deploy]`。PR 階段會 job-level skip CI heavy jobs，merge 後也會 skip production deploy。不要把這個旗標用在程式碼、workflow、API surface 或其他需要 CI 驗證的改動。
 
+## PR 敘述怎麼寫
+
+按這個順序寫，順序本身就是重點：
+
+1. **使用者遇到的問題。** 第一段就講使用者實際看到什麼，用他們的語言，不要用內部術語。不是「快取的 key 沒有失效」，是「改了設定之後，舊的值還會再出現一個小時」。看 PR 的人第一個要知道的是「這在修什麼」，不是「這改了哪一行」。
+2. **背景。** 讀懂這個 bug 需要先知道的前提，假設讀的人沒有這塊的 context。單一檔案的小修正可以省略；只要牽涉兩個以上元件的互動就不要省。
+3. **問題出在哪裡。** 用講給 junior engineer 聽的方式。貼出有問題的那幾行，說明它原本想做什麼、實際做了什麼、以及為什麼平常看不出來。「平常這兩件事是同一件事，所以看不出差別」這種句子，比「edge case」有用得多。
+4. **修法。** 貼出改完的程式碼，然後解釋**為什麼是這樣改**。特別是那些看起來多餘、其實不能省的部分，要講清楚省掉會發生什麼事。
+5. **這個 PR 不修什麼。** 如果根因還沒解、或刻意只做一半，明講。不要讓 reviewer 以為問題結案了。
+6. **已知副作用。** 有就寫。
+7. **測試。** 測了什麼行為，以及**改動前是怎麼紅的**，貼出失敗訊息。
+
+不要寫的東西：
+
+- 不要重複 commit message。commit 講「改了什麼」，PR 講「為什麼」。
+- 不要只貼 diff 摘要，GitHub 已經有了。
+- 不要用「修了一個 edge case」帶過。是哪個 edge case、為什麼會走到那裡。
+
 ## 不要做的事
 
 - 不要在 commit message 加 AI co-author trailer（這個 repo 不接受）