XeroBis/website

計畫與文件化

為什麼

像是「移植卡片」或「為作品集新增標籤」這類請求聽起來像是最終決定，但通常隱藏著未解決的選擇：這次要建置多少？要從舊儲存庫中保留、更改或捨棄哪些內容？哪個結構定義擁有資料？哪些部分屬於 @shared？立即建置的風險是做了不該做的事、需要重做，或是偏離了已在 documentation/decisions.md 中記錄的選擇。先提問能確保文件——以及後續的程式碼——準確記錄使用者真正想要的內容。

何時適用

任何會改變 documentation/ 所追蹤內容的請求：功能或使用者面對的行為、結構定義/表格/欄位/業務規則、技術或函式庫選擇、資料夾/架構結構，或 migration-plan.md 中的步驟。小而明確的編輯（修正這個錯字、將此標籤重新命名為精確的 X）則不需要此訪談環節——請自行判斷實際上有多少模糊之處。

步驟

1. 在提問前先閱讀。 瀏覽與請求相關的 documentation/*.md 章節（以及相關程式碼）。在移植時，也請閱讀舊儲存庫自身的文件（../<repo>/documentation/、../<repo>/CLAUDE.md）以及被移植的程式碼。不要問已經有答案的問題。將這些內容作為你提問的基準。

2. 使用 AskUserQuestion 提出釐清問題。 偏好提出數個具體的小問題，而非一個籠統的大問題。此儲存庫中好的提問目標包括：

   • 現在要建置多少，以及之後再建置多少；
   • 移植時：從舊應用程式中保留、更改或捨棄哪些內容（舊行為不一定是想要的）；
   • 哪個結構定義擁有新的表格（應用程式自己的，還是如果每個應用程式都需要則歸屬於 core）；
   • 某個部分屬於一個應用程式，還是屬於 @shared / 共享後端模組；
   • features.md 需要記錄的使用者體驗細節，以及新資料的形狀。

   為每個問題提供一個建議的預設值，以便使用者能快速做出決定。

3. 嚴格遵守使用者回覆的範圍。 如果他們將範圍縮小到「僅限文件」或「只要 X，不要 Y」，請不要默默做更多——在稍後擴大範圍之前再次確認。

4. 在同一步驟中根據 CLAUDE.md 的表格更新文件：

   • 資料夾結構、環境、連接埠、請求流程 → architecture.md
   • 結構定義、表格、欄位、關係、業務規則 → data-model.md，放在該結構定義的章節下
   • 技術/函式庫/架構選擇 → decisions.md：一個帶有日期的條目，說明選擇了什麼、捨棄了什麼、以及原因，符合該檔案的風格
   • 使用者面對的行為、驗證規則 → features.md，放在該應用程式的章節下
   • 任何延期、排除或僅屬可能性的事項 → ideas.md
   • 移植進度 → migration-plan.md 的狀態欄
   • 正式運作手冊變更 → deployment.md

5. 將已解決的想法從 ideas.md 中移出。 如果某個變更將 ideas.md 中的一個條目變成了實際決定，請刪除或改寫該條目，而不是留下一個過時的副本。