From 453cf47188dcbb6a958e0beabf8fc5bdf5d0f6c2 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 17 Sep 2026 04:44:46 +0000
Subject: [PATCH] =?UTF-8?q?feat(sdlc-plan):=20=E6=96=B0=E5=A2=9E=E9=9C=80?=
 =?UTF-8?q?=E6=B1=82=E8=AD=B0=E9=A1=8C=E6=A8=A1=E6=9D=BF=E8=88=87=E6=B5=81?=
 =?UTF-8?q?=E7=A8=8B=E6=AD=A3=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

templates/requirement-issue.md 固定需求議題的九個段落與順序：總覽／背景／
目標／非目標／領域名詞表／流程圖／驗收標準／影響範圍／未決事項。段落順序即
下游 issue-extract 的解析依據，總覽段落預留總覽網頁的連結佔位。

流程圖段落只放佔位、不寫死 mermaid 圍欄：正本允許「乾脆不畫」，若圍欄寫死在
模板裡，不畫時就會在議題頁留下一塊渲染失敗的空 mermaid 區塊。圍欄改由填入的
內容自己帶。

prompts/sdlc-plan.md 是流程正本，平台中立 markdown，不含任何平台專屬語法，
description 以「僅由 /sdlc-plan 指令叫用。」起頭。正本交代：三種輸入來源、
一次問一題且不得替使用者編造、九個段落的填法、Mermaid flowchart 的 12 節點與
8 字上限、標籤只能從 labels-list 挑、寫入前先 --dry-run。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 prompts/sdlc-plan.md           | 97 ++++++++++++++++++++++++++++++++++
 templates/requirement-issue.md | 39 ++++++++++++++
 2 files changed, 136 insertions(+)
 create mode 100644 prompts/sdlc-plan.md
 create mode 100644 templates/requirement-issue.md

diff --git a/prompts/sdlc-plan.md b/prompts/sdlc-plan.md
new file mode 100644
index 0000000..661e2f5
--- /dev/null
+++ b/prompts/sdlc-plan.md
@@ -0,0 +1,97 @@
+name: sdlc-plan
+description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構化的需求議題，寫入 Gitea。
+
+# sdlc-plan
+
+把使用者給的一段需求，變成一顆結構完整、下游指令讀得動的需求議題。
+
+這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。
+
+## 輸入
+
+使用者給的東西可能是下列任一種，也可能三種混用：
+
+- **自由文字** — 一段口語描述。
+- **規格檔** — 一個檔案路徑，內容是既有的規格或筆記。
+- **議題編號** — 既有議題的編號，用來補充脈絡或作為延伸的起點。
+
+先把三種來源讀齊，再開始問問題。規格檔用檔案讀取工具讀；議題編號用
+`scripts/issue-extract.js` 取（若該腳本尚未可用，改用 `scripts/issue-create.js` 以外的
+既有讀取途徑，並在摘要中註明資料來源）。
+
+## 步驟
+
+### 1. 讀齊輸入，列出還缺什麼
+
+把九個段落逐一對照使用者給的材料，列出哪些段落已經有依據、哪些沒有。
+
+### 2. 逐項詢問
+
+**一次問一題**，等使用者回答完再問下一題，讓他能看著前一題的答案回答下一題。
+
+每一題都附上你的建議與理由，讓使用者多數時候只要點頭；同時保留讓他自己寫答案的餘地。
+
+**未獲得答覆的欄位不得自行編造。** 使用者沒說過的目標、沒提過的驗收標準，一個字都不能自己
+填。問不到就放進「未決事項」，那一段本來就是給未決的東西用的。
+
+### 3. 組出議題內容
+
+套用 `templates/requirement-issue.md`，依序填滿九個段落：
+
+1. **總覽** — 一句話講完這件事在做什麼，讓非技術的利害關係人不必讀完技術細節。圖解版總覽的
+   連結此時先留空，由後續流程回填。
+2. **背景** — 不超過三行。為什麼現在要做這件事。
+3. **目標** — 可量測。寫得出「怎樣算達成」才算數。
+4. **非目標** — 明列這次不做什麼，用來抵抗範圍蔓延。
+5. **領域名詞表** — 這份需求裡會反覆出現的詞，各給一行定義，讓團隊對同一個詞的理解一致。
+6. **流程圖** — 見下方「流程圖的限制」。
+7. **驗收標準** — 逐條列出，每一條都要能被驗證。
+8. **影響範圍** — 會動到哪些 repo、哪些既有功能。
+9. **未決事項** — 問不到答案、或需要他人拍板的事。
+
+### 4. 挑標籤
+
+先用 `scripts/labels-list.js --repo <owner/name>` 取得該 repo 的既有標籤，**只能從這份清單裡
+挑**。找不到合適的就不貼。**不得自行建立新標籤** —— 標籤體系由專案維護者決定，不該在多個
+repo 之間長出雜草。
+
+### 5. 先試跑，再寫入
+
+把組好的內容寫到一個暫存檔，然後：
+
+```
+node scripts/issue-create.js --repo <owner/name> --title "<標題>" --body-file <暫存檔> \
+  --labels "<標籤1,標籤2>" --dry-run
+```
+
+`--dry-run` 會印出將要送出的請求而不真的寫入。確認無誤後拿掉該旗標再跑一次。
+
+同一段需求重跑不會產生第二顆議題：`issue-create` 以標題查重，發現同名議題就回傳既有那一顆
+並把 `created` 設為 `false`。
+
+### 6. 回報
+
+把議題編號與網址告訴使用者。不要把整份議題內容再貼一次 —— 連結點進去就看得到。
+
+## 流程圖的限制
+
+用 Mermaid 的 `flowchart`。節點數上限 **12**，每個節點的文字上限 **8 字**。
+
+超過就拆成多張圖，或者乾脆不畫 —— 一張塞了二十個節點的圖，比沒有圖更難懂。
+
+節點文字寫該步驟在做什麼，不要寫成編號或代號。
+
+模板的 `{{流程圖}}` 要填入**完整的內容**，兩種形式擇一：
+
+- 要畫：一個或多個完整的 ```mermaid 圍欄區塊。
+- 不畫：一行說明為什麼不畫（例如「流程為單一直線，畫圖無助理解」），**不要加圍欄**。
+
+圍欄寫在填入的內容裡而不是模板裡，否則不畫圖時會留下一個空的 mermaid 區塊，
+在議題頁上是一塊渲染失敗的紅字。
+
+## 邊界
+
+- 不修改使用者的專案檔案。這個流程只讀輸入、寫 Gitea 議題。
+- 不建立標籤、不建立 Milestone、不建立專案看板。
+- 不關閉或刪除任何既有議題。
+- 規劃階段本身已含問題釐清，因此寫入 Gitea 前不再設額外的確認點；`--dry-run` 就是那道關卡。
diff --git a/templates/requirement-issue.md b/templates/requirement-issue.md
new file mode 100644
index 0000000..94dc261
--- /dev/null
+++ b/templates/requirement-issue.md
@@ -0,0 +1,39 @@
+## 總覽
+
+{{總覽}}
+
+圖解版總覽：{{總覽網頁}}
+
+## 背景
+
+{{背景}}
+
+## 目標
+
+{{目標}}
+
+## 非目標
+
+{{非目標}}
+
+## 領域名詞表
+
+| 名詞 | 定義 |
+| --- | --- |
+{{名詞表}}
+
+## 流程圖
+
+{{流程圖}}
+
+## 驗收標準
+
+{{驗收標準}}
+
+## 影響範圍
+
+{{影響範圍}}
+
+## 未決事項
+
+{{未決事項}}