5.7 KiB
5.7 KiB
交付類型規則
這份規則是 /sdlc-analyze 與 /sdlc-feat 共用的交付文件正本。交付文件不是額外的程式碼待辦；先確認要交付哪一種文件，再依本表逐一確認內容骨架，最後才產出。
共通規則
- 每一種文件都要逐一確認：說明是否需要、列出必要內容骨架、給出建議與理由，再接受使用者確認或手動調整；不得把七種文件合併成一次模糊確認。
- 文件沒有足夠資料時標記未決事項，不代替使用者編造決策。能由需求、工作包、相依與排程資料重新推導的內容，優先保留來源與推導規則。
- 產出位置以本表為準。預覽能力存在時可交付可開啟、可分享的預覽；沒有預覽能力時依使用者確認的方式交付，不因缺少預覽而捏造網址或改寫目標專案。
- ELI5 變體要保留原文件的範圍、順序、相依、例外與驗收意義。可把術語換成日常說法並補一句解釋，但不能刪掉技術限制；圖表改成容易閱讀的視覺，不把 Mermaid 原碼當成 ELI5 交付物。
七種交付類型
1. 需求描述概要
- 必要內容：一句話說明做什麼與為什麼做；背景；目標與可驗收結果；非目標；影響範圍；假設與未決事項；必要的領域名詞定義。
- 產出位置：需求議題的結構化描述，對應
templates/requirement-issue.md的段落；可另外提供預覽，但議題內仍保留可機讀的白話概要。 - ELI5 變體：先用一句日常語言說明問題和得到的改善，再用短句解釋必要術語；不得用願景口號取代目標、非目標或驗收條件。
2. WBS（工作分解結構）
- 必要內容：可獨立交付的工作包；每個工作包的目標、範圍邊界、待辦與逐項驗收；工作包之間的先決與阻擋關係；交付文件工作包優先於純程式碼工作包，但不得違反先決關係。
- 產出位置：工作包議題的
待辦與巢狀驗收，以及整體驗收、repo 列表、關聯段落；不把 WBS 寫入目標專案。 - ELI5 變體：把每個工作包說成一個能交付的箱子，說清楚箱子裡有什麼、完成的判準，以及哪個箱子要先完成；不得只列職責或模糊階段名稱。
3. 流程圖
- 必要內容：起點、終點、主要步驟、分支條件、例外路徑與步驟間的方向；節點與邊都要能從需求或工作包驗證；超過可讀範圍時拆圖或改用文字。
- 產出位置：交付文件預覽或使用者確認的文件位置；需求議題只保留抽象節點與邊的文字描述，不產生 HTML、SVG、附件或平台 preview。
- ELI5 變體：用「先做什麼、接著看什麼、遇到哪種情況走哪條路」描述；保留失敗與回復路徑，圖表視覺化時不嵌入 Mermaid 原碼。
4. 甘特圖
- 必要內容：每個工作包或任務、開始日、截止日、工作日數、先決關係、交付里程碑與目前可辨識的重疊；日期必須能由排程資料重算。
- 產出位置：排程／交付文件預覽與終端摘要；Gitea 工作包議題只保留可追蹤的截止日、里程碑與關聯，不把圖表檔寫入目標專案。
- ELI5 變體：把它說成一張「每件事什麼時候開始、什麼時候完成、誰要等誰」的日曆；不以顏色或位置暗示未列出的依賴。
5. PERT 圖
- 必要內容：任務節點、先決關係、樂觀時間（O）、最可能時間（M）、悲觀時間（P）、期望時間與不確定性；三點估算要逐項向使用者確認，不能默認成單一工期。
- 產出位置：排程／交付文件預覽與終端摘要；O/M/P 與推導結果是排程資料，不寫入目標專案 repo。
- ELI5 變體：把 O/M/P 說成最快、通常、最慢三種情況，指出哪一段最不確定；不得只報一個看似精確的日期而隱藏風險。
6. 關鍵路徑圖
- 必要內容：完整相依網路、每個節點的工期、最長路徑、路徑總工期、關鍵任務與可用浮時；若有多條同長路徑要全部列出；相依成環要先報錯。
- 產出位置：排程／交付文件預覽與終端摘要；工作包議題保留相依關係與截止日作為可重算來源，不把圖表檔寫入目標專案。
- ELI5 變體：說明「哪一串事情任何一件延遲都會讓最後交付延遲」，同時列出不在關鍵路徑上的緩衝；不得把所有工作都稱為關鍵。
7. API 契約文件
- 必要內容：介面名稱、用途、產出者、消費者、輸入與輸出形狀、成功與錯誤情境、相容性限制、可驗收範例與來源；只記錄已確認的契約，未知內容列為未決事項。
- 產出位置：預覽或使用者確認的交付文件位置，以及可由需求議題、工作包與實作重新產生的摘要；禁止把 API 契約文件寫入目標專案 repo，也不得自動修改目標專案的設定檔或文件。
- ELI5 變體：把 API 說成「誰用什麼資料提出請求，會拿到什麼回覆，出錯時會收到什麼」；保留欄位名稱、資料型別、錯誤碼與相容性限制，不用白話改寫掉可執行的契約。
確認與重產
- 每份文件產出前都先展示該類型的必要內容骨架，逐一確認內容是否齊全；使用者拒絕或未確認時不把它標成已交付。
- 文件摘要必須保留來源議題、工作包、相依與排程資料的指向。來源更新後，摘要可由同一份來源重新產生，不以手工複製的摘要作為唯一真相。
- 預覽失效、不可分享或環境不具備預覽能力時，回報實際能力與限制並逐題詢問交付方式；不得回退成寫入目標專案 repo，尤其是 API 契約文件。