plugins/tea-sdlc
2
0
Fork 0
Code Issues 3 Pull Requests Actions Releases Activity

以交付文件為先重整 tea-sdlc 指令組 #70

New Issue
Open
opened 2026-09-22 02:15:47 +00:00 by jiantw83 · 5 comments
jiantw83 commented 2026-09-22 02:15:47 +00:00
Member
Copy Link
Copy Source

總覽

把 tea-sdlc 指令組改成「交付文件優先」：/sdlc-analyze 在可行性分析時必須先確認這顆需求要不要產出交付文件、推薦交付類型與內容，並把交付文件排成最優先的待辦；/sdlc-feat 領到交付文件待辦時，環境若有預覽能力就直接產出預覽，沒有就停下來問使用者要怎麼產、並附上建議。這兩點落地後，再對六份流程正本做一次整體重整：步驟細節不重要的地方腳本化或交給子代理，正本改以英文書寫並以專有名詞、概念取代冗長的步驟描述，但對使用者的輸出仍是繁體中文、不得出現亂碼。這顆需求議題是常駐計畫，會被反覆更新與重跑，任何流程都不得把它關閉。

圖解版總覽：（本流程不產生）

背景

  • 目前 /sdlc-analyze 的共識摘要之後有一步「列出要交付或驗收的項目逐項確認」，但沒有要求判斷「要不要產生交付文件」、也沒有推薦交付類型的依據；交付項目只是排在工作包待辦第一項，不是最優先完成的東西。
  • /sdlc-feat 目前對交付文件類的待辦沒有任何專門處理，與程式碼待辦一視同仁。使用者所在的平台（例如 Claude Code 的 artifact）能直接產出可預覽的文件時，這個能力沒有被用上；沒有預覽能力的平台則沒有人問使用者要怎麼交。
  • commit 7f723ad（「移除計時並停用報表預覽」）把六份正本從約 1,100 行縮到約 440 行，同時刪除了 artifact 契約、圖解總覽產生腳本、〔可委派〕標記與對應的資產測試。references/delegation.md 的委派表與 AGENTS.md 對 scripts/overview-render.js、artifact 契約的描述已與正本漂移；這次重整要一併對齊。
  • 流程正本是平台中立 markdown（docs/adr/0002：以能力描述而非工具名表達委派），「有無預覽能力」也必須用同一種能力描述表達，不能寫死某個助理的工具名。
  • 目前 npm test 有兩個與環境相關的失敗（打包白名單、PATH 上找不到 tea-sdlc 的情境），與本需求無關，但重整時要能區分既有失敗與新引入的失敗。

目標

  1. /sdlc-analyze 在可行性分析的共識摘要裡，新增「是否需要交付文件」的判斷與推薦：依階段列出建議的交付類型與各自應包含的內容，逐題向使用者確認；被確認的交付文件在工作包切分與排序上都是最優先項目，不得排在任何程式碼待辦之後（先決關係仍須遵守）。
  2. 三個階段各自固定的交付類型（2026-09-22 使用者決定），內容骨架先依下列建議寫入 references/ 規則正本，實作階段產出各文件時再逐一向使用者確認：
    • 規劃階段「需求描述概要」：作為需求議題總覽段落的擴充，不另開文件。含一句話價值陳述（誰、要什麼、為什麼現在做）、問題陳述與現況痛點、可量測的目標與非目標、利害關係人與角色（誰決策、誰使用、誰驗收）、範圍邊界與假設限制、高階驗收標準與完成定義、未決事項與風險。
    • 分析階段「工作分解結構圖」：層級固定為需求 → 交付項目 → 工作包 → 待辦；每個工作包節點帶議題編號與人天；遵守 100% 規則（範圍全覆蓋、節點不重疊），缺口以「待定」節點標出；Mermaid mindmap 或由上而下 flowchart。
    • 分析階段「流程圖」：畫改完之後的業務或系統流程，以泳道區分角色與系統，含決策節點、正常路徑與錯誤路徑，每個節點標對應工作包編號。
    • 分析階段「甘特圖」：每顆工作包一列（開始、結束、相依），資料來自排程腳本；關鍵路徑以 crit 標記；含里程碑與今日線；只算工作日並扣除本地節假日。
    • 分析階段「PERT 圖」：活動節點網路，節點為工作包、邊為相依，加虛擬起點與終點；每節點列樂觀、最可能、悲觀三值（三值都向使用者詢問），期望工期 (O+4M+P)/6 與變異數；輸出專案總工期期望值與標準差。
    • 分析階段「關鍵路徑圖」：與 PERT 同一張網路，節點顯示最早開始、最早完成、最晚開始、最晚完成與浮時；浮時為零者高亮為關鍵路徑，另列浮時小於等於一個工作日的近關鍵工作包；輸出總工期與關鍵路徑工作包清單。
    • 實作階段「API 契約文件」：格式依目標專案選 OpenAPI 3.1（HTTP）、AsyncAPI（事件）或 Protobuf（gRPC）；文件不寫入目標專案 repo，經預覽能力或使用者選定的方式交付，工作包議題保留足以重新產生該文件的摘要（端點清單、schema 要點、版本）；含版本與變更紀錄、相容性政策（何謂破壞性變更）、認證授權、基底網址與環境、每個端點的方法路徑／用途／請求參數與 body schema／成功與錯誤回應 schema／範例／錯誤碼／冪等性／分頁／速率限制、共用 schema 與列舉、端點對應的工作包編號與驗收項；契約工作包排在實作工作包之前。
  3. 分析階段五張圖以 Mermaid 寫入需求議題描述的「文件」段落（## 文件 下以 ### 圖名 分小節）；甘特圖、PERT 圖、關鍵路徑圖共用 scripts/schedule.js 的計畫檔為單一資料來源，腳本擴充算出最早／最晚開始與完成、浮時與關鍵路徑。
  4. 需求議題模板以「文件」段落取代「流程圖」段落；抽取契約新增 文件 欄位並移除 流程圖，舊議題缺段落時回空字串不報錯；/sdlc-plan 在「文件」段落只留一句「待 /sdlc-analyze 產生」或抽象節點與邊的文字描述。
  5. 排程改以工作日計算：跳週末並扣除台灣節假日；節假日來源為台灣行政機關辦公日曆表（政府資料開放平臺，2026-09-22 使用者決定），以內建 fetch 取得並快取於 ~/.tea-sdlc/ 下，計畫檔可另行手動補充。 節假日資料抓不到時退回只跳週末並印出警告；資料集網址與每年更新時機於實作時確認。
  6. /sdlc-feat 領到的待辦若是交付文件：環境具備預覽能力（以能力描述表達，例如「能把 HTML 或文件發佈成可預覽頁面」）時直接產出並回報位置；不具備時停下來問使用者要以何種方式產生，由 agent 依當下情境提出建議做法與理由（不維護固定選項清單），不得自行決定。
  7. 前述各項完成後，重整六份流程正本（含 /sdlc-report）與相鄰資產：
    • 只在意結果、不問使用者、不寫入 Gitea 或 git 的步驟，依 references/delegation.md 的四條判準標為可委派或改為腳本；
    • 以專有名詞或概念（例如共識摘要、交付文件、工作包、工作樹）取代逐步的技能描述，正本維持繁體中文書寫，不改寫成英文；
    • 面向使用者的所有輸出（終端訊息、議題與 PR 內容、回報）維持繁體中文，且在各平台轉接鏈上不得出現亂碼；
    • references/delegation.md、AGENTS.md、README.md 與正本重新對齊，恢復正本標記與委派表的雙向資產測試；
    • 順手修復既有兩個環境相關的測試失敗（打包白名單、PATH 上找不到 tea-sdlc 的情境），讓 npm test 全數通過。
  8. 這顆需求議題是常駐計畫：重跑 /sdlc-plan 以同一標題走查重更新內容，不新建重複議題。「不得關閉」只靠議題描述宣告（本段與總覽），各正本邊界照著遵守，不在腳本層另加擋關閉的機制。
  9. 所有交付文件都可套用提示詞「Explain like I'm someone who knows nothing about this topic, using a HTML artifact with big pictures and few words.」產生 ELI5 版本（2026-09-22 使用者決定）：以預覽能力產出 HTML，圖表全部重新繪製為圖片式視覺，不得直接嵌入 Mermaid 版本；ELI5 版本是每種交付類型的可選變體，規格寫入交付類型規則正本。

非目標

  • 不恢復已移除的計時、工時補登與週報／月報／年報功能；/sdlc-report 維持 REPORT_UNAVAILABLE。
  • 不在 /sdlc-plan 與 /sdlc-analyze 產生 HTML、SVG、截圖或平台 preview；預覽只在 /sdlc-feat 處理交付文件待辦時產生。分析階段的圖以平台中立的文字圖語法（如 Mermaid）寫在議題描述裡。
  • 不把任何平台的工具名（artifact、canvas 等）寫進流程正本；一律以能力描述表達。
  • 不把流程正本、規則正本或模板改寫成英文（2026-09-22 使用者決定）。
  • 不在腳本層新增擋下關閉議題的機制；常駐計畫僅靠議題描述宣告。
  • 不新增外部套件、不建立標籤、Milestone 或看板。
  • 不修改目標專案的設定檔，也不把交付文件（含 API 契約文件）寫入目標專案 repo。
  • 不維護「沒有預覽能力時」的固定選項清單；建議做法由 agent 依情境提出。
  • 不改變六個指令的名稱、數量與轉接檔契約（tea-sdlc prompt --name <指令名>）。

領域名詞表

名詞 定義
交付文件（deliverable document） 需求完成時要交給使用者或利害關係人閱讀的成品；相對於程式碼變更。本需求固定七種：需求描述概要、工作分解結構圖、流程圖、甘特圖、PERT 圖、關鍵路徑圖、API 契約文件。
交付類型（deliverable type） 交付文件的分類與對應的內容骨架；/sdlc-analyze 據此推薦「要產哪幾種、各自該有什麼」。
交付優先（deliverable-first） 交付文件的待辦在工作包內排第一項、工作包整體也依交付排序，且不得被程式碼待辦擠到後面的排序規則。
需求描述概要（requirement brief） 規劃階段的交付文件，一頁看完的需求摘要，落在需求議題的總覽段落。
工作分解結構圖（WBS） 需求 → 交付項目 → 工作包 → 待辦的層級分解圖，遵守 100% 規則。
甘特圖（Gantt chart） 以工作日為單位的工作包時間軸，標示相依、關鍵路徑、里程碑與今日線。
PERT 圖 以三點估算（樂觀／最可能／悲觀）計算期望工期與變異數的活動節點網路。
關鍵路徑圖（CPM） 在同一張活動網路上標示最早／最晚開始與完成、浮時，並高亮浮時為零的路徑。
API 契約文件（API contract） 實作階段的交付文件，以 OpenAPI 3.1、AsyncAPI 或 Protobuf 描述介面，契約先於實作。
文件段落 需求議題描述的 ## 文件 段落，存放分析階段五張 Mermaid 圖，取代原「流程圖」段落。
工作日（working day） 排程的計日單位：跳過週末並扣除本地節假日。
預覽能力（preview capability） 執行環境能把文件即時發佈成可開啟、可分享的預覽頁面的能力；以能力描述判定，不指名工具。
能力描述（capability description） 以「你的環境若能……就……；不能就……」表達平台專屬能力的寫法，讓同一份正本在各平台自然降級（docs/adr/0002）。
委派（delegation） 把只在意結果的步驟交給子代理執行、只帶結果回主脈絡；四條判準見 references/delegation.md。
腳本化（scripting） 把步驟細節下沉到 scripts/ 的零相依 Node 腳本，正本只留呼叫與結果判讀。
流程正本（canonical prompt） prompts/sdlc-*.md，唯一的流程事實來源；各平台轉接檔只指回它。
常駐計畫議題（long-lived plan issue） 會被反覆更新與重跑、不得關閉的需求議題；重跑以標題查重更新，不新建。
ELI5 版本 交付文件的可選變體：套用固定提示詞產生大圖少字的 HTML 頁面，圖表重繪為圖片式視覺，不嵌入 Mermaid。

流程圖

節點與邊（文字描述）：

  • 需求議題（本顆）→ /sdlc-analyze：可行性四清單 → 共識摘要
  • 共識摘要 → 「需要交付文件？」判斷 → 是：推薦交付類型與內容 → 使用者逐題確認 → 交付文件待辦置頂
  • 共識摘要 → 「需要交付文件？」判斷 → 否：記入摘要，工作包照原順序
  • 工作包（交付文件待辦） → /sdlc-feat → 「環境有預覽能力？」判斷
    • 是 → 直接產出預覽 → 回報位置與內容摘要
    • 否 → 詢問使用者產生方式（附建議選項） → 依回答產出
  • 工作包（程式碼待辦） → /sdlc-feat → 既有實作流程 → PR
  • 前兩條路徑完成 → 重整工作包：委派／腳本化標記 → 英文正本改寫 → 繁體中文輸出驗證 → 資產測試對齊
  • 任一指令重跑 → 讀取本議題 → 更新描述或工作包 →（不得關閉本議題）

驗收標準

  • /sdlc-analyze 的共識摘要包含「交付文件」一節，依規劃／分析／實作三階段列出是否需要、推薦的交付類型與各類型的內容項目，並逐題向使用者確認。
  • 使用者確認的交付文件在工作包待辦的第一項，且工作包排序上優先於所有純程式碼工作包；先決關係不被違反。
  • references/ 有一份交付類型規則正本，涵蓋需求描述概要、工作分解結構圖、流程圖、甘特圖、PERT 圖、關鍵路徑圖、API 契約文件七種，每種列出必含內容與產出位置；/sdlc-feat 產出各文件前逐一向使用者確認內容骨架。
  • API 契約文件不出現在目標專案 repo 的任何 PR 中；對應工作包議題含足以重新產生該文件的摘要。
  • 分析階段五張圖以 Mermaid 寫入需求議題的「文件」段落，抽取契約以 文件 欄位帶出，缺段落的舊議題回空字串。
  • 排程腳本以工作日計算，讀入台灣行政機關辦公日曆表；資料抓不到時退回只跳週末並印出警告。
  • /sdlc-feat 遇到交付文件待辦時，具備預覽能力的環境直接產出預覽並回報位置；不具備者停下來以「一次一題、附 agent 依情境提出的建議與理由」的方式詢問使用者，不自行決定，正本中沒有固定選項清單。
  • 「預覽能力」在正本中以能力描述表達，全文搜尋不到任何平台工具名。
  • 六份正本以專有名詞或概念取代逐步描述，維持繁體中文；正本 description 仍以「僅由 /sdlc-xxx 指令叫用。」起頭。
  • 以七個平台的轉接檔各叫用一次 tea-sdlc prompt，輸出的繁體中文無亂碼（install-verify 或等價測試涵蓋 UTF-8 檢查）。
  • 符合委派四條判準的步驟在正本標記〔可委派〕，references/delegation.md 的表與正本標記由資產測試雙向綁住；可腳本化的步驟有對應 scripts/ 腳本與測試。
  • AGENTS.md、README.md、references/delegation.md 不再指向已刪除的檔案或不存在的步驟。
  • 重跑 /sdlc-plan 帶同一標題時不建立第二顆議題；本議題描述載明「常駐計畫，不得關閉」，且在整個流程走完後仍為 open 狀態。
  • npm test 全數通過，包含修復後的兩個原環境相關失敗；六份正本（含 /sdlc-report）都完成重整。

影響範圍

  • prompts/sdlc-analyze.md、prompts/sdlc-feat.md：新增交付文件判斷、推薦、置頂、三點估算提問與預覽能力分支。
  • prompts/sdlc-plan.md：填「文件」段落取代「流程圖」段落；prompts/sdlc-fix.md、prompts/sdlc-sync.md、prompts/sdlc-report.md：委派標記、專有名詞化、不得關閉常駐計畫議題的邊界。
  • templates/requirement-issue.md：「流程圖」段落改為「文件」段落；templates/work-package-issue.md：若交付文件需要固定段落則調整佔位。
  • scripts/issue-extract.js：抽取契約以 文件 取代 流程圖，缺段落回空字串。
  • scripts/schedule.js：計日改為工作日並讀入節假日資料；新增最早／最晚開始與完成、浮時、關鍵路徑、三點估算期望值與變異數的計算與 Mermaid 輸出（甘特、PERT、關鍵路徑）。
  • scripts/：可能新增節假日資料取得與快取腳本（零外部套件，只用內建 fetch）、UTF-8 輸出檢查；install-verify.js 補繁體中文完整性檢查。
  • references/：新增交付類型與內容骨架的規則正本；delegation.md 委派表更新。
  • test/：issue-extract、schedule、comments-merge 測試隨契約調整；恢復委派資產測試；新增輸出繁體中文的資產測試。
  • AGENTS.md、README.md、docs/adr/：對齊描述，必要時新增 ADR 記錄「交付優先」、「預覽以能力描述表達」與「文件段落取代流程圖」的決策。
  • 各平台轉接檔內容不變（只含 tea-sdlc prompt --name），不需重跑 tea-sdlc install。

未決事項

無。2026-09-22 /sdlc-analyze 已將委派門檻（維持四條判準）釐清，見留言紀錄。

## 總覽 把 tea-sdlc 指令組改成「交付文件優先」：`/sdlc-analyze` 在可行性分析時必須先確認這顆需求要不要產出交付文件、推薦交付類型與內容，並把交付文件排成最優先的待辦；`/sdlc-feat` 領到交付文件待辦時，環境若有預覽能力就直接產出預覽，沒有就停下來問使用者要怎麼產、並附上建議。這兩點落地後，再對六份流程正本做一次整體重整：步驟細節不重要的地方腳本化或交給子代理，正本改以英文書寫並以專有名詞、概念取代冗長的步驟描述，但對使用者的輸出仍是繁體中文、不得出現亂碼。這顆需求議題是常駐計畫，會被反覆更新與重跑，任何流程都不得把它關閉。 圖解版總覽：（本流程不產生） ## 背景 - 目前 `/sdlc-analyze` 的共識摘要之後有一步「列出要交付或驗收的項目逐項確認」，但沒有要求判斷「要不要產生交付文件」、也沒有推薦交付類型的依據；交付項目只是排在工作包待辦第一項，不是最優先完成的東西。 - `/sdlc-feat` 目前對交付文件類的待辦沒有任何專門處理，與程式碼待辦一視同仁。使用者所在的平台（例如 Claude Code 的 artifact）能直接產出可預覽的文件時，這個能力沒有被用上；沒有預覽能力的平台則沒有人問使用者要怎麼交。 - commit `7f723ad`（「移除計時並停用報表預覽」）把六份正本從約 1,100 行縮到約 440 行，同時刪除了 artifact 契約、圖解總覽產生腳本、〔可委派〕標記與對應的資產測試。`references/delegation.md` 的委派表與 `AGENTS.md` 對 `scripts/overview-render.js`、artifact 契約的描述已與正本漂移；這次重整要一併對齊。 - 流程正本是平台中立 markdown（`docs/adr/0002`：以能力描述而非工具名表達委派），「有無預覽能力」也必須用同一種能力描述表達，不能寫死某個助理的工具名。 - 目前 `npm test` 有兩個與環境相關的失敗（打包白名單、PATH 上找不到 tea-sdlc 的情境），與本需求無關，但重整時要能區分既有失敗與新引入的失敗。 ## 目標 1. `/sdlc-analyze` 在可行性分析的共識摘要裡，新增「是否需要交付文件」的判斷與推薦：依階段列出建議的交付類型與各自應包含的內容，逐題向使用者確認；被確認的交付文件在工作包切分與排序上都是最優先項目，不得排在任何程式碼待辦之後（先決關係仍須遵守）。 2. 三個階段各自固定的交付類型（2026-09-22 使用者決定），內容骨架先依下列建議寫入 `references/` 規則正本，實作階段產出各文件時再逐一向使用者確認： - 規劃階段「需求描述概要」：作為需求議題總覽段落的擴充，不另開文件。含一句話價值陳述（誰、要什麼、為什麼現在做）、問題陳述與現況痛點、可量測的目標與非目標、利害關係人與角色（誰決策、誰使用、誰驗收）、範圍邊界與假設限制、高階驗收標準與完成定義、未決事項與風險。 - 分析階段「工作分解結構圖」：層級固定為需求 → 交付項目 → 工作包 → 待辦；每個工作包節點帶議題編號與人天；遵守 100% 規則（範圍全覆蓋、節點不重疊），缺口以「待定」節點標出；Mermaid mindmap 或由上而下 flowchart。 - 分析階段「流程圖」：畫改完之後的業務或系統流程，以泳道區分角色與系統，含決策節點、正常路徑與錯誤路徑，每個節點標對應工作包編號。 - 分析階段「甘特圖」：每顆工作包一列（開始、結束、相依），資料來自排程腳本；關鍵路徑以 `crit` 標記；含里程碑與今日線；只算工作日並扣除本地節假日。 - 分析階段「PERT 圖」：活動節點網路，節點為工作包、邊為相依，加虛擬起點與終點；每節點列樂觀、最可能、悲觀三值（三值都向使用者詢問），期望工期 (O+4M+P)/6 與變異數；輸出專案總工期期望值與標準差。 - 分析階段「關鍵路徑圖」：與 PERT 同一張網路，節點顯示最早開始、最早完成、最晚開始、最晚完成與浮時；浮時為零者高亮為關鍵路徑，另列浮時小於等於一個工作日的近關鍵工作包；輸出總工期與關鍵路徑工作包清單。 - 實作階段「API 契約文件」：格式依目標專案選 OpenAPI 3.1（HTTP）、AsyncAPI（事件）或 Protobuf（gRPC）；文件不寫入目標專案 repo，經預覽能力或使用者選定的方式交付，工作包議題保留足以重新產生該文件的摘要（端點清單、schema 要點、版本）；含版本與變更紀錄、相容性政策（何謂破壞性變更）、認證授權、基底網址與環境、每個端點的方法路徑／用途／請求參數與 body schema／成功與錯誤回應 schema／範例／錯誤碼／冪等性／分頁／速率限制、共用 schema 與列舉、端點對應的工作包編號與驗收項；契約工作包排在實作工作包之前。 3. 分析階段五張圖以 Mermaid 寫入需求議題描述的「文件」段落（`## 文件` 下以 `### 圖名` 分小節）；甘特圖、PERT 圖、關鍵路徑圖共用 `scripts/schedule.js` 的計畫檔為單一資料來源，腳本擴充算出最早／最晚開始與完成、浮時與關鍵路徑。 4. 需求議題模板以「文件」段落取代「流程圖」段落；抽取契約新增 `文件` 欄位並移除 `流程圖`，舊議題缺段落時回空字串不報錯；`/sdlc-plan` 在「文件」段落只留一句「待 /sdlc-analyze 產生」或抽象節點與邊的文字描述。 5. 排程改以工作日計算：跳週末並扣除台灣節假日；節假日來源為台灣行政機關辦公日曆表（政府資料開放平臺，2026-09-22 使用者決定），以內建 `fetch` 取得並快取於 `~/.tea-sdlc/` 下，計畫檔可另行手動補充。 節假日資料抓不到時退回只跳週末並印出警告；資料集網址與每年更新時機於實作時確認。 6. `/sdlc-feat` 領到的待辦若是交付文件：環境具備預覽能力（以能力描述表達，例如「能把 HTML 或文件發佈成可預覽頁面」）時直接產出並回報位置；不具備時停下來問使用者要以何種方式產生，由 agent 依當下情境提出建議做法與理由（不維護固定選項清單），不得自行決定。 7. 前述各項完成後，重整六份流程正本（含 `/sdlc-report`）與相鄰資產： - 只在意結果、不問使用者、不寫入 Gitea 或 git 的步驟，依 `references/delegation.md` 的四條判準標為可委派或改為腳本； - 以專有名詞或概念（例如共識摘要、交付文件、工作包、工作樹）取代逐步的技能描述，正本維持繁體中文書寫，不改寫成英文； - 面向使用者的所有輸出（終端訊息、議題與 PR 內容、回報）維持繁體中文，且在各平台轉接鏈上不得出現亂碼； - `references/delegation.md`、`AGENTS.md`、`README.md` 與正本重新對齊，恢復正本標記與委派表的雙向資產測試； - 順手修復既有兩個環境相關的測試失敗（打包白名單、PATH 上找不到 tea-sdlc 的情境），讓 `npm test` 全數通過。 8. 這顆需求議題是常駐計畫：重跑 `/sdlc-plan` 以同一標題走查重更新內容，不新建重複議題。「不得關閉」只靠議題描述宣告（本段與總覽），各正本邊界照著遵守，不在腳本層另加擋關閉的機制。 9. 所有交付文件都可套用提示詞「Explain like I'm someone who knows nothing about this topic, using a HTML artifact with big pictures and few words.」產生 ELI5 版本（2026-09-22 使用者決定）：以預覽能力產出 HTML，圖表全部重新繪製為圖片式視覺，不得直接嵌入 Mermaid 版本；ELI5 版本是每種交付類型的可選變體，規格寫入交付類型規則正本。 ## 非目標 - 不恢復已移除的計時、工時補登與週報／月報／年報功能；`/sdlc-report` 維持 `REPORT_UNAVAILABLE`。 - 不在 `/sdlc-plan` 與 `/sdlc-analyze` 產生 HTML、SVG、截圖或平台 preview；預覽只在 `/sdlc-feat` 處理交付文件待辦時產生。分析階段的圖以平台中立的文字圖語法（如 Mermaid）寫在議題描述裡。 - 不把任何平台的工具名（artifact、canvas 等）寫進流程正本；一律以能力描述表達。 - 不把流程正本、規則正本或模板改寫成英文（2026-09-22 使用者決定）。 - 不在腳本層新增擋下關閉議題的機制；常駐計畫僅靠議題描述宣告。 - 不新增外部套件、不建立標籤、Milestone 或看板。 - 不修改目標專案的設定檔，也不把交付文件（含 API 契約文件）寫入目標專案 repo。 - 不維護「沒有預覽能力時」的固定選項清單；建議做法由 agent 依情境提出。 - 不改變六個指令的名稱、數量與轉接檔契約（`tea-sdlc prompt --name <指令名>`）。 ## 領域名詞表 | 名詞 | 定義 | | --- | --- | | 交付文件（deliverable document） | 需求完成時要交給使用者或利害關係人閱讀的成品；相對於程式碼變更。本需求固定七種：需求描述概要、工作分解結構圖、流程圖、甘特圖、PERT 圖、關鍵路徑圖、API 契約文件。 | | 交付類型（deliverable type） | 交付文件的分類與對應的內容骨架；`/sdlc-analyze` 據此推薦「要產哪幾種、各自該有什麼」。 | | 交付優先（deliverable-first） | 交付文件的待辦在工作包內排第一項、工作包整體也依交付排序，且不得被程式碼待辦擠到後面的排序規則。 | | 需求描述概要（requirement brief） | 規劃階段的交付文件，一頁看完的需求摘要，落在需求議題的總覽段落。 | | 工作分解結構圖（WBS） | 需求 → 交付項目 → 工作包 → 待辦的層級分解圖，遵守 100% 規則。 | | 甘特圖（Gantt chart） | 以工作日為單位的工作包時間軸，標示相依、關鍵路徑、里程碑與今日線。 | | PERT 圖 | 以三點估算（樂觀／最可能／悲觀）計算期望工期與變異數的活動節點網路。 | | 關鍵路徑圖（CPM） | 在同一張活動網路上標示最早／最晚開始與完成、浮時，並高亮浮時為零的路徑。 | | API 契約文件（API contract） | 實作階段的交付文件，以 OpenAPI 3.1、AsyncAPI 或 Protobuf 描述介面，契約先於實作。 | | 文件段落 | 需求議題描述的 `## 文件` 段落，存放分析階段五張 Mermaid 圖，取代原「流程圖」段落。 | | 工作日（working day） | 排程的計日單位：跳過週末並扣除本地節假日。 | | 預覽能力（preview capability） | 執行環境能把文件即時發佈成可開啟、可分享的預覽頁面的能力；以能力描述判定，不指名工具。 | | 能力描述（capability description） | 以「你的環境若能……就……；不能就……」表達平台專屬能力的寫法，讓同一份正本在各平台自然降級（`docs/adr/0002`）。 | | 委派（delegation） | 把只在意結果的步驟交給子代理執行、只帶結果回主脈絡；四條判準見 `references/delegation.md`。 | | 腳本化（scripting） | 把步驟細節下沉到 `scripts/` 的零相依 Node 腳本，正本只留呼叫與結果判讀。 | | 流程正本（canonical prompt） | `prompts/sdlc-*.md`，唯一的流程事實來源；各平台轉接檔只指回它。 | | 常駐計畫議題（long-lived plan issue） | 會被反覆更新與重跑、不得關閉的需求議題；重跑以標題查重更新，不新建。 | | ELI5 版本 | 交付文件的可選變體：套用固定提示詞產生大圖少字的 HTML 頁面，圖表重繪為圖片式視覺，不嵌入 Mermaid。 | ## 流程圖 節點與邊（文字描述）： - 需求議題（本顆）→ `/sdlc-analyze`：可行性四清單 → 共識摘要 - 共識摘要 → 「需要交付文件？」判斷 → 是：推薦交付類型與內容 → 使用者逐題確認 → 交付文件待辦置頂 - 共識摘要 → 「需要交付文件？」判斷 → 否：記入摘要，工作包照原順序 - 工作包（交付文件待辦） → `/sdlc-feat` → 「環境有預覽能力？」判斷 - 是 → 直接產出預覽 → 回報位置與內容摘要 - 否 → 詢問使用者產生方式（附建議選項） → 依回答產出 - 工作包（程式碼待辦） → `/sdlc-feat` → 既有實作流程 → PR - 前兩條路徑完成 → 重整工作包：委派／腳本化標記 → 英文正本改寫 → 繁體中文輸出驗證 → 資產測試對齊 - 任一指令重跑 → 讀取本議題 → 更新描述或工作包 →（不得關閉本議題） ## 驗收標準 - [ ] `/sdlc-analyze` 的共識摘要包含「交付文件」一節，依規劃／分析／實作三階段列出是否需要、推薦的交付類型與各類型的內容項目，並逐題向使用者確認。 - [ ] 使用者確認的交付文件在工作包待辦的第一項，且工作包排序上優先於所有純程式碼工作包；先決關係不被違反。 - [ ] `references/` 有一份交付類型規則正本，涵蓋需求描述概要、工作分解結構圖、流程圖、甘特圖、PERT 圖、關鍵路徑圖、API 契約文件七種，每種列出必含內容與產出位置；`/sdlc-feat` 產出各文件前逐一向使用者確認內容骨架。 - [ ] API 契約文件不出現在目標專案 repo 的任何 PR 中；對應工作包議題含足以重新產生該文件的摘要。 - [ ] 分析階段五張圖以 Mermaid 寫入需求議題的「文件」段落，抽取契約以 `文件` 欄位帶出，缺段落的舊議題回空字串。 - [ ] 排程腳本以工作日計算，讀入台灣行政機關辦公日曆表；資料抓不到時退回只跳週末並印出警告。 - [ ] `/sdlc-feat` 遇到交付文件待辦時，具備預覽能力的環境直接產出預覽並回報位置；不具備者停下來以「一次一題、附 agent 依情境提出的建議與理由」的方式詢問使用者，不自行決定，正本中沒有固定選項清單。 - [ ] 「預覽能力」在正本中以能力描述表達，全文搜尋不到任何平台工具名。 - [ ] 六份正本以專有名詞或概念取代逐步描述，維持繁體中文；正本 `description` 仍以「僅由 /sdlc-xxx 指令叫用。」起頭。 - [ ] 以七個平台的轉接檔各叫用一次 `tea-sdlc prompt`，輸出的繁體中文無亂碼（`install-verify` 或等價測試涵蓋 UTF-8 檢查）。 - [ ] 符合委派四條判準的步驟在正本標記〔可委派〕，`references/delegation.md` 的表與正本標記由資產測試雙向綁住；可腳本化的步驟有對應 `scripts/` 腳本與測試。 - [ ] `AGENTS.md`、`README.md`、`references/delegation.md` 不再指向已刪除的檔案或不存在的步驟。 - [ ] 重跑 `/sdlc-plan` 帶同一標題時不建立第二顆議題；本議題描述載明「常駐計畫，不得關閉」，且在整個流程走完後仍為 open 狀態。 - [ ] `npm test` 全數通過，包含修復後的兩個原環境相關失敗；六份正本（含 `/sdlc-report`）都完成重整。 ## 影響範圍 - `prompts/sdlc-analyze.md`、`prompts/sdlc-feat.md`：新增交付文件判斷、推薦、置頂、三點估算提問與預覽能力分支。 - `prompts/sdlc-plan.md`：填「文件」段落取代「流程圖」段落；`prompts/sdlc-fix.md`、`prompts/sdlc-sync.md`、`prompts/sdlc-report.md`：委派標記、專有名詞化、不得關閉常駐計畫議題的邊界。 - `templates/requirement-issue.md`：「流程圖」段落改為「文件」段落；`templates/work-package-issue.md`：若交付文件需要固定段落則調整佔位。 - `scripts/issue-extract.js`：抽取契約以 `文件` 取代 `流程圖`，缺段落回空字串。 - `scripts/schedule.js`：計日改為工作日並讀入節假日資料；新增最早／最晚開始與完成、浮時、關鍵路徑、三點估算期望值與變異數的計算與 Mermaid 輸出（甘特、PERT、關鍵路徑）。 - `scripts/`：可能新增節假日資料取得與快取腳本（零外部套件，只用內建 `fetch`）、UTF-8 輸出檢查；`install-verify.js` 補繁體中文完整性檢查。 - `references/`：新增交付類型與內容骨架的規則正本；`delegation.md` 委派表更新。 - `test/`：`issue-extract`、`schedule`、`comments-merge` 測試隨契約調整；恢復委派資產測試；新增輸出繁體中文的資產測試。 - `AGENTS.md`、`README.md`、`docs/adr/`：對齊描述，必要時新增 ADR 記錄「交付優先」、「預覽以能力描述表達」與「文件段落取代流程圖」的決策。 - 各平台轉接檔內容不變（只含 `tea-sdlc prompt --name`），不需重跑 `tea-sdlc install`。 ## 未決事項 無。2026-09-22 `/sdlc-analyze` 已將委派門檻（維持四條判準）釐清，見留言紀錄。
jiantw83 added the ready-for-agent label 2026-09-22 02:15:47 +00:00
jiantw83 commented 2026-09-22 02:35:01 +00:00
Author
Member
Copy Link
Copy Source

2026-09-22 重跑 /sdlc-plan 時使用者給的決策（由 agent 代為記錄）：

  1. 交付文件依階段固定為：規劃階段「需求描述概要」；分析階段「甘特圖、PERT 圖、關鍵路徑圖、工作分解結構圖、流程圖」；實作階段「API 契約文件」。各文件應包含的內容另行討論。
  2. 不改寫英文：流程正本維持繁體中文，只以專有名詞或概念取代冗長的步驟描述。
  3. 「不能被關閉」靠議題描述宣告就好，不在腳本層加擋關閉的機制。
2026-09-22 重跑 `/sdlc-plan` 時使用者給的決策（由 agent 代為記錄）： 1. 交付文件依階段固定為：規劃階段「需求描述概要」；分析階段「甘特圖、PERT 圖、關鍵路徑圖、工作分解結構圖、流程圖」；實作階段「API 契約文件」。各文件應包含的內容另行討論。 2. 不改寫英文：流程正本維持繁體中文，只以專有名詞或概念取代冗長的步驟描述。 3. 「不能被關閉」靠議題描述宣告就好，不在腳本層加擋關閉的機制。
👍 1
jiantw83 commented 2026-09-22 02:41:24 +00:00
Author
Member
Copy Link
Copy Source

2026-09-22 第二輪 /sdlc-plan 討論的決策（由 agent 代為記錄）：

  1. 需求議題模板新增「文件」段落，存放分析階段的五張圖；「流程圖」段落評估後可移除（以「文件」取代，抽取契約同步調整，舊議題缺段落時抽取回空字串）。
  2. PERT 三點估算：樂觀、最可能、悲觀三個值都向使用者詢問。
  3. 甘特圖與排程只算工作日，並參考本地節假日。
  4. 七種交付文件的內容骨架依同日提出的建議稿，使用者未提出異議，先寫入目標段落；仍可在後續輪次修改。
2026-09-22 第二輪 `/sdlc-plan` 討論的決策（由 agent 代為記錄）： 1. 需求議題模板新增「文件」段落，存放分析階段的五張圖；「流程圖」段落評估後可移除（以「文件」取代，抽取契約同步調整，舊議題缺段落時抽取回空字串）。 2. PERT 三點估算：樂觀、最可能、悲觀三個值都向使用者詢問。 3. 甘特圖與排程只算工作日，並參考本地節假日。 4. 七種交付文件的內容骨架依同日提出的建議稿，使用者未提出異議，先寫入目標段落；仍可在後續輪次修改。
👍 1
jiantw83 commented 2026-09-22 02:49:07 +00:00
Author
Member
Copy Link
Copy Source

2026-09-22 第三輪 /sdlc-plan 決策（由 agent 代為記錄）：

節假日資料來源採用台灣行政機關辦公日曆表（政府資料開放平臺），以內建 fetch 取得並快取於 ~/.tea-sdlc/ 下，計畫檔可另行手動補充。

2026-09-22 第三輪 `/sdlc-plan` 決策（由 agent 代為記錄）： 節假日資料來源採用台灣行政機關辦公日曆表（政府資料開放平臺），以內建 `fetch` 取得並快取於 `~/.tea-sdlc/` 下，計畫檔可另行手動補充。
👍 1
jiantw83 commented 2026-09-22 02:58:20 +00:00
Author
Member
Copy Link
Copy Source

2026-09-22 第四輪 /sdlc-plan 決策，逐條回應原未決事項（由 agent 代為記錄）：

  1. 七種交付文件的內容骨架：實作階段產出各文件時再逐一向使用者確認。
  2. 沒有預覽能力時不維護固定選項清單，由 AI agent 依情境提出建議做法再問使用者。
  3. API 契約文件不寫入目標專案 repo；工作包議題可包含足以重新產生該文件的摘要。
  4. 「步驟細節不重要時使用子代理」與委派四條判準是否等價：使用者不確定，保留待 /sdlc-analyze 釐清。
  5. 重整包含 /sdlc-report。
  6. 既有兩個環境相關測試失敗在本需求內順手修。
  7. 節假日資料抓不到時退回只跳週末並警告；資料集網址與更新時機於實作時確認。
2026-09-22 第四輪 `/sdlc-plan` 決策，逐條回應原未決事項（由 agent 代為記錄）： 1. 七種交付文件的內容骨架：實作階段產出各文件時再逐一向使用者確認。 2. 沒有預覽能力時不維護固定選項清單，由 AI agent 依情境提出建議做法再問使用者。 3. API 契約文件不寫入目標專案 repo；工作包議題可包含足以重新產生該文件的摘要。 4. 「步驟細節不重要時使用子代理」與委派四條判準是否等價：使用者不確定，保留待 `/sdlc-analyze` 釐清。 5. 重整包含 `/sdlc-report`。 6. 既有兩個環境相關測試失敗在本需求內順手修。 7. 節假日資料抓不到時退回只跳週末並警告；資料集網址與更新時機於實作時確認。
👍 1
jiantw83 commented 2026-09-22 03:42:20 +00:00
Author
Member
Copy Link
Copy Source

2026-09-22 /sdlc-analyze 共識（由 agent 代為記錄）：

  1. 委派門檻維持 references/delegation.md 四條判準，不修訂 ADR 0002；「步驟細節不重要」只當動機。
  2. #70 自身的五張分析圖由 agent 手寫 Mermaid 先交，寫入現有「流程圖」段落，日後由工作包改名為「文件」；同時作為新工具的對照樣本。
  3. 排程起始日 2026-09-22，以工作日計算並扣除台灣行政機關辦公日曆表的假日。
  4. 新增決策：所有交付文件都可套用提示詞「Explain like I'm someone who knows nothing about this topic, using a HTML artifact with big pictures and few words.」產生 ELI5 版本；ELI5 版本的圖表全部重新繪製為圖片式視覺，不得直接嵌入 Mermaid 版本。
  5. 七顆工作包全部確認：A 交付類型規則正本與「文件」段落／抽取契約、B 排程腳本擴充、C sdlc-analyze 正本、D sdlc-feat 正本、E sdlc-plan 正本、F 六份正本重整與測試修復、G 留言 50 則上限修正（Gitea 議題留言端點無 page/limit 參數，改走 timeline 分頁）。
  6. 三點估算（樂觀／最可能／悲觀，工作日）：A 2/3/5、B 3/4/7、C 1/2/3、D 1/2/3、E 0.5/1/2、F 2/3/5、G 1/2/3。
2026-09-22 `/sdlc-analyze` 共識（由 agent 代為記錄）： 1. 委派門檻維持 `references/delegation.md` 四條判準，不修訂 ADR 0002；「步驟細節不重要」只當動機。 2. #70 自身的五張分析圖由 agent 手寫 Mermaid 先交，寫入現有「流程圖」段落，日後由工作包改名為「文件」；同時作為新工具的對照樣本。 3. 排程起始日 2026-09-22，以工作日計算並扣除台灣行政機關辦公日曆表的假日。 4. 新增決策：所有交付文件都可套用提示詞「Explain like I'm someone who knows nothing about this topic, using a HTML artifact with big pictures and few words.」產生 ELI5 版本；ELI5 版本的圖表全部重新繪製為圖片式視覺，不得直接嵌入 Mermaid 版本。 5. 七顆工作包全部確認：A 交付類型規則正本與「文件」段落／抽取契約、B 排程腳本擴充、C sdlc-analyze 正本、D sdlc-feat 正本、E sdlc-plan 正本、F 六份正本重整與測試修復、G 留言 50 則上限修正（Gitea 議題留言端點無 page/limit 參數，改走 timeline 分頁）。 6. 三點估算（樂觀／最可能／悲觀，工作日）：A 2/3/5、B 3/4/7、C 1/2/3、D 1/2/3、E 0.5/1/2、F 2/3/5、G 1/2/3。
👍 1
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
ready-for-agent
規格已就緒可交由agent實作
 進行中
工作包正在實作
No labels ready-for-agent
Milestone
No items
No Milestone
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: plugins/tea-sdlc#70