Feature Flag 登記表範本(Feature Flag Register Template)

Feature Flag 登記表範本(Feature Flag Register) 參照標準:OpenFeature 規格(CNCF) 文件用途:登記每個 Feature Flag 的用途、擁有者、預設值與移除日期,避免旗標變成無人管理的技術債 適用階段:開發、部署與維運階段 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 8.4 節 📋 章節目錄 旗標登記 變更紀錄 清理檢查 審查與驗證 1. 旗標登記 📝 範本 旗標名稱 類型 用途 擁有者 預設值(安全值) 目前狀態 建立日 預計移除日 {kebab-case 名稱} {發布/營運開關/實驗/權限} {說明} {姓名} {值與理由} {各環境狀態} {日期} {日期} 📖 使用說明 類型 用途 生命週期 發布(Release) 隱藏未完成功能、逐步開放 短:全面開放後 30 天內移除 營運開關(Ops) 緊急關閉高耗能或不穩定功能(Kill Switch) 長:需定期確認仍需要 實驗(Experiment) A/B 測試 實驗結束即移除 權限(Permission) 依客戶或方案開放功能 長:視同產品設定 預設值必須是「安全」的行為(通常是舊流程或關閉):旗標服務故障時不得啟用未完成的功能 名稱用 kebab-case,描述行為而非人名或工單號 💡 範例 旗標名稱 類型 用途 擁有者 預設值(安全值) 目前狀態 建立日 預計移除日 new-leave-quota-check 發布 新版特休額度檢查 Tech Lead 王 false(走舊檢查) DEV on/UAT on/PRD 25% 2026-09-20 2026-11-15 admin-xml-import 營運開關 管理後台 XML 匯入(RA-2026-07 期間關閉) 資安 李 false 全環境 off 2025-03-01 不移除(每季確認) 2. 變更紀錄 📝 範本 時間 旗標 環境 變更 執行者 核准者 原因 {YYYY-MM-DD HH:MM} {名稱} {環境} {舊值 → 新值} {姓名} {姓名} {原因/工單} 📖 使用說明 正式環境的旗標變更等同上線,必須留稽核紀錄並經核准 優先使用旗標平台內建的稽核日誌,本表作為摘要 💡 範例 時間 旗標 環境 變更 執行者 核准者 原因 2026-10-06 10:00 new-leave-quota-check PRD 0% → 25% DevOps 林 PO 王 漸進開放(CHG-2026-118) 3. 清理檢查 📝 範本 旗標名稱 是否已全面開放或廢止 程式中引用處 清理 PR 狀態 {名稱} {是/否} {檔案:行數} {PR 連結} {待清理/已移除} 📖 使用說明 每個 Sprint 檢查過期的旗標;移除旗標時同時刪除舊流程程式碼與對應測試 長期不清理的旗標會產生無法測試的組合,並增加事故風險 💡 範例 旗標名稱 是否已全面開放或廢止 程式中引用處 清理 PR 狀態 leave-attachment-v2 是(2026-08-01 起 100%) LeaveController.java:88、LeaveService.java:142 #1301 已移除 4. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的登記表是否正確。 ...

October 6, 2026 · 2 min · 224 words · Eric Cheng

Pull Request 說明範本(Pull Request Template)

Pull Request 說明範本(Pull Request Template) 參照標準:GitHub Pull Request Templates / Conventional Commits 1.0.0 文件用途:統一 PR 說明格式,讓 Reviewer 知道改了什麼、為什麼改、如何驗證,以及 AI 參與了哪些部分 適用階段:開發階段,每個 PR 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 1.5、7.1 節 📋 章節目錄 放置位置 PR 說明內容 自動檢查 PR 說明 審查與驗證 1. 放置位置 📝 範本 平台 檔案位置 GitHub .github/pull_request_template.md GitLab .gitlab/merge_request_templates/Default.md Azure DevOps .azuredevops/pull_request_template.md 📖 使用說明 範本放在預設分支後,開 PR 時會自動帶入 PR 標題採 Conventional Commits 格式(例:feat(leave): 新增特休額度檢查),便於自動產生 CHANGELOG 💡 範例 .github/ ├── pull_request_template.md ├── CODEOWNERS └── workflows/ 2. PR 說明內容 📝 範本 ## 變更摘要 {一到三句話說明改了什麼}(工作項目:{編號}) ## 變更原因 {為什麼需要這個變更;連結需求或事件} ## 變更類型 - [ ] 新功能(feat) - [ ] 修正(fix) - [ ] 重構(refactor) - [ ] 不相容變更(BREAKING CHANGE) ## 驗證方式 - [ ] 自動化測試:{新增/修改的測試} - [ ] 手動驗證:{步驟與結果} ## AI 參與範圍 - 使用工具:{工具名稱與版本,或「未使用」} - AI 產生:{檔案/方法} - 人工修改:{修改了 AI 產出的哪些部分與原因} - 人工驗證方式:{如何確認 AI 產出正確} ## 審查重點 {請 Reviewer 特別注意的地方} ## 檢查清單 - [ ] 文件已更新(OpenAPI、SDD、ADR、README) - [ ] 無機敏資訊(密碼、Token、真實個資) - [ ] 資料庫變更可與舊版程式並存(Expand/Contract) 📖 使用說明 「驗證方式」必須能證明功能正確,「看起來沒問題」不算 「AI 參與範圍」讓 Reviewer 分配審查力道;作者必須能解釋 AI 產生的每一行 不相容變更必須說明影響與遷移方式 💡 範例 ## 變更摘要 申請特休時檢查剩餘額度,不足時回傳 422 Problem Details(工作項目:HRMS-412) ## 變更原因 主管每月約退件 40 筆額度不足的申請(需求 FR-LV-002) ## 變更類型 - [x] 新功能(feat) ## 驗證方式 - [x] 自動化測試:`LeaveQuotaPolicyTest`(6 個案例,含剛好等於額度的邊界值)、`LeaveControllerIT`(422 回應格式) - [x] 手動驗證:測試環境以 E20260001 申請 3 天(剩 2 天)→ 422,畫面顯示正確訊息 ## AI 參與範圍 - 使用工具:GitHub Copilot(公司核准版本) - AI 產生:`LeaveQuotaPolicy#check` 初版、`LeaveQuotaPolicyTest` 4 個案例 - 人工修改:補上半天假的額度計算(AI 版本只處理整天);補上邊界值測試 - 人工驗證方式:本機 `mvn verify` 通過;PIT mutation score 85% ## 審查重點 - 半天假(0.5 天)的比較是否有浮點誤差(已改用 BigDecimal) ## 檢查清單 - [x] 文件已更新(OpenAPI:新增 422 回應) - [x] 無機敏資訊 - [x] 無資料庫變更 3. 自動檢查 PR 說明 📝 範本 # .github/workflows/pr-description.yml:檢查 PR 說明的必要段落 name: PR description check on: pull_request: types: [opened, edited, synchronize] permissions: contents: read jobs: check: runs-on: ubuntu-latest steps: - name: Require sections env: BODY: ${{ github.event.pull_request.body }} run: | for section in "## 變更摘要" "## 驗證方式" "## AI 參與範圍"; do if ! printf '%s' "$BODY" | grep -qF "$section"; then echo "::error::PR 說明缺少段落:$section" exit 1 fi done 📖 使用說明 PR 說明屬使用者可控內容,必須透過 env 傳入,不可在 run: 中直接寫 ${{ github.event.pull_request.body }},否則可能造成指令注入 此 Job 設為分支保護的必要檢查 💡 範例 PR 說明缺少「AI 參與範圍」時,Job 輸出: ...

October 6, 2026 · 2 min · 381 words · Eric Cheng

SLO 定義與錯誤預算政策範本(SLO & Error Budget Policy Template)

SLO 定義與錯誤預算政策範本(SLO & Error Budget Policy) 參照標準:Google SRE Book/SRE Workbook(SLO、Error Budget、Multiwindow Multi-burn-rate Alerts) 文件用途:定義服務的 SLI、SLO 與錯誤預算,並約定預算耗盡時的處理方式 適用階段:設計階段定義,上線前完成告警,每季檢討 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 10.2 節 📋 章節目錄 服務與使用者旅程 SLI 定義 SLO 與錯誤預算 錯誤預算政策 審查與驗證 1. 服務與使用者旅程 📝 範本 項目 內容 服務名稱 {名稱} 關鍵使用者旅程 {使用者最在意的 2–3 件事} SLO 擁有者 {團隊/負責人} 相關 SLA {對客戶的合約承諾,若有} 📖 使用說明 SLO 從「使用者感受」出發,不是從伺服器指標出發 SLO 應比 SLA 嚴格,保留緩衝 💡 範例 項目 內容 服務名稱 HRMS API 關鍵使用者旅程 1. 打卡;2. 請假申請;3. 薪資單查詢 SLO 擁有者 HRMS 開發部(SRE 窗口:張) 相關 SLA 內部服務,無對外 SLA;對 HR 部門承諾每月可用率 99.5% 2. SLI 定義 📝 範本 SLI 好事件定義 總事件定義 量測位置 PromQL(比例) {名稱} {條件} {條件} {負載平衡器/應用程式/合成監控} {查詢式} 📖 使用說明 SLI 寫成「好事件 ÷ 總事件」,結果介於 0 與 1 指標名稱必須與實際 instrumentation 相符,並在 Prometheus 確認查得到資料 💡 範例 SLI 好事件定義 總事件定義 量測位置 PromQL(比例) 可用性 回應狀態非 5xx 所有請求 應用程式(Micrometer) 1 - (sum(rate(http_server_requests_seconds_count{job="hrms-api",status=~"5.."}[30d])) / sum(rate(http_server_requests_seconds_count{job="hrms-api"}[30d]))) 延遲 回應時間 ≤ 300 ms 所有請求 應用程式(histogram) sum(rate(http_server_requests_seconds_bucket{job="hrms-api",le="0.3"}[30d])) / sum(rate(http_server_requests_seconds_count{job="hrms-api"}[30d])) 延遲 SLI 的 le="0.3" 必須是 histogram 實際存在的 bucket 邊界;Spring Boot 可用 management.metrics.distribution.slo.http.server.requests=300ms 加入此邊界。 ...

October 6, 2026 · 2 min · 356 words · Eric Cheng

User Story 與驗收條件範本(User Story & Acceptance Criteria Template)

User Story 與驗收條件範本(User Story & Acceptance Criteria) 參照標準:INVEST 原則 / Gherkin(Cucumber)/ ISO/IEC/IEEE 29148:2018 需求品質特性 文件用途:以使用者觀點描述需求,並以可自動化的 Gherkin 驗收條件定義「完成」 適用階段:需求分析與 Sprint 規劃(Backlog Refinement) 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 3.2、2.4(DoR)節 📋 章節目錄 Story 基本資訊 Story 描述與 INVEST 檢查 驗收條件(Gherkin) 非功能與安全考量 審查與驗證 1. Story 基本資訊 📝 範本 項目 內容 Story 編號 {專案代碼}-{序號} 對應需求 {FR/PRD 功能編號} 優先序 {Must/Should/Could/Won’t} 估點 {Story Points,超過 8 點需拆分} 相依項目 {API、資料表、其他 Story} UI 設計 {Figma 連結/線框圖} 📖 使用說明 「相依項目」與「UI 設計」是 DoR(就緒定義)的檢查項目,缺少時不得排入 Sprint 估點超過團隊約定上限(例:8 點)時必須拆分 💡 範例 項目 內容 Story 編號 HRMS-412 對應需求 FR-LV-002 優先序 Must 估點 5 相依項目 GET /api/v1/leave-quotas(HRMS-398,已完成) UI 設計 Figma「請假申請 v3」 2. Story 描述與 INVEST 檢查 📝 範本 身為 {角色}, 我想要 {功能}, 以便 {商業價值}。 原則 檢查問題 結果 Independent 獨立 能否單獨交付? {✅/❌ 說明} Negotiable 可協商 描述需求而非規定實作? {✅/❌} Valuable 有價值 使用者或業務能感受到價值? {✅/❌} Estimable 可估算 團隊能估出大小? {✅/❌} Small 夠小 一個 Sprint 內可完成? {✅/❌} Testable 可測試 有明確驗收條件? {✅/❌} 📖 使用說明 「以便」寫的是業務價值,不是技術手段(❌「以便呼叫 API」) INVEST 任一項 ❌ 時,於 Refinement 會議中修改或拆分 💡 範例 身為 員工, 我想要 在申請特休時看到剩餘天數,並在額度不足時被擋下, 以便 不必等主管退件才知道申請無效。 原則 檢查問題 結果 Independent 能否單獨交付? ✅ 額度 API 已完成 Negotiable 描述需求而非實作? ✅ Valuable 有業務價值? ✅ 減少主管退件(每月約 40 件) Estimable 可估算? ✅ 5 點 Small 一個 Sprint 內? ✅ Testable 有驗收條件? ✅ 見第 3 節 3. 驗收條件(Gherkin) 📝 範本 # language: zh-TW 功能: {功能名稱}({需求編號}) 場景: {正常情境} 假設 {前置條件} 當 {使用者動作} 那麼 {可觀察的結果} 場景: {例外情境} 假設 {前置條件} 當 {使用者動作} 那麼 {錯誤處理結果} 📖 使用說明 至少 1 個正常情境與 1 個例外情境;邊界值(剛好等於上限)另列場景 「那麼」必須可觀察、可自動判定:寫出畫面訊息、HTTP 狀態碼或資料變化,不寫「系統正常運作」 中文關鍵字需在第一行宣告 # language: zh-TW;也可使用英文關鍵字 Feature/Scenario/Given/When/Then 每個 .feature 檔都必須有 功能:(Feature:)行,否則 Cucumber 無法解析 💡 範例 # language: zh-TW 功能: 特休額度檢查(FR-LV-002) 場景: 額度足夠時可送出申請 假設 員工 "E20260001" 的特休剩餘 5 天 當 員工申請 3 天特休 那麼 申請狀態為 "pending" 而且 畫面顯示 "申請已送出,剩餘特休 2 天(核准後扣除)" 場景: 額度不足時拒絕申請 假設 員工 "E20260001" 的特休剩餘 2 天 當 員工申請 3 天特休 那麼 API 回應狀態碼 422 而且 畫面顯示 "特休剩餘 2 天,不足申請天數 3 天" 場景: 申請天數剛好等於剩餘額度 假設 員工 "E20260001" 的特休剩餘 3 天 當 員工申請 3 天特休 那麼 申請狀態為 "pending" 4. 非功能與安全考量 📝 範本 類別 要求 驗證方式 權限 {誰可以執行、可以存取誰的資料} {整合測試} 效能 {量化目標} {k6/APM} 稽核 {需記錄的事件} {日誌檢查} 個資 {涉及的欄位與分級} {資料分級對照表} 📖 使用說明 每個 Story 都要想一次「誰不應該能做這件事」,並寫成測試 涉及個資時引用《資料分級對照表範本》的分級 💡 範例 類別 要求 驗證方式 權限 員工只能查詢與申請自己的假;主管可查部屬 整合測試:以 A 員工 Token 查 B 員工額度 → 403 效能 額度查詢 p95 < 300 ms k6 負載測試 稽核 申請送出記錄員工編號、天數、結果 日誌檢查 個資 請假事由屬「機密」,日誌禁止記錄 日誌 grep 測試 5. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的 User Story 是否正確。 ...

October 6, 2026 · 2 min · 410 words · Eric Cheng

安全政策範本(SECURITY.md Template)

安全政策範本(SECURITY.md) 參照標準:GitHub Security Policy / ISO/IEC 29147:2018(弱點揭露)/ ISO/IEC 30111:2019(弱點處理流程)/ RFC 9116(security.txt) 文件用途:告訴使用者與研究人員如何安全地通報弱點、會得到什麼回應、哪些版本仍受支援 適用階段:專案建立時放入 Repository 根目錄或 .github/ 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 9.2、11.1 節 📋 章節目錄 支援版本 通報方式 處理流程與時限 審查與驗證 1. 支援版本 📝 範本 ## 支援版本 | 版本 | 是否提供安全更新 | |------|----------------| | {x.y.z} | ✅ | | < {x.0} | ❌ | 📖 使用說明 與 CHANGELOG、Release Note 的支援政策一致 不再支援的版本要明確寫出,避免使用者以為仍會修補 💡 範例 ## 支援版本 | 版本 | 是否提供安全更新 | |------|----------------| | 2.4.x | ✅ | | 2.3.x | ✅(至 2027-03-31) | | < 2.3 | ❌ | 2. 通報方式 📝 範本 ## 通報弱點 **請不要在公開 Issue 中回報安全問題。** - 通報管道:{GitHub Private Vulnerability Reporting/security@{domain}} - 加密:{PGP 公鑰連結(如有)} - 請提供:受影響版本、重現步驟、影響說明、可行的修補建議(如有) 📖 使用說明 公開 Repository 建議啟用 GitHub 的 Private vulnerability reporting 內部系統可改為公司資安信箱,並在網站加上 /.well-known/security.txt(RFC 9116) 💡 範例 ## 通報弱點 **請不要在公開 Issue 中回報安全問題。** - 通報管道:本 Repository 的「Security → Report a vulnerability」,或 security@company.com - 請提供:受影響版本、重現步驟、影響說明 3. 處理流程與時限 📝 範本 ## 處理流程 | 階段 | 時限 | |------|------| | 確認收到 | {N} 個工作日內 | | 初步評估(嚴重度) | {N} 個工作日內 | | 修補 | 依嚴重度:Critical {N} 天、High {N} 天… | | 公開揭露 | 修補發布後,與通報者協調 | 📖 使用說明 修補時限與公司弱點管理 SLA 一致(手冊 9.2) 嚴重度以 CVSS v4.0 評分,並參考 EPSS 與 CISA KEV 💡 範例 ## 處理流程 | 階段 | 時限 | |------|------| | 確認收到 | 2 個工作日內 | | 初步評估(CVSS v4.0) | 5 個工作日內 | | 修補 | Critical:24 小時內緩解、7 天內修復;High:7 天;Medium:30 天 | | 公開揭露 | 修補發布後 30 天內,與通報者協調時間 | 4. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的 SECURITY.md 是否正確。 ...

October 6, 2026 · 2 min · 271 words · Eric Cheng

專案裁剪紀錄範本(Tailoring Record Template)

專案裁剪紀錄範本(Tailoring Record) 參照標準:ISO/IEC/IEEE 12207:2026(流程裁剪)/ CMMI V3.0(組織標準流程裁剪) 文件用途:依專案的規模與風險,記錄哪些標準活動與文件被簡化、理由與核准者 適用階段:專案啟動時(G1 之前);專案範圍或風險變更時更新 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 2.5 節 📋 章節目錄 專案基本資訊 風險分級判定 裁剪項目 核准與複核 審查與驗證 1. 專案基本資訊 📝 範本 項目 內容 專案名稱/代號 {名稱}({代號}) 系統說明 {一句話描述} 使用者範圍 {內部/外部;人數} 處理的資料 {是否含個資、金流、機密} 預估規模 {人月、期程} 📖 使用說明 這些資訊是判定風險等級的依據,必須據實填寫 「處理的資料」需參照《資料分級對照表範本》 💡 範例 項目 內容 專案名稱/代號 會議室預約系統(ROOM-2026) 系統說明 員工預約會議室並同步 Outlook 行事曆 使用者範圍 內部員工約 180 人 處理的資料 員工姓名、Email(機密);無金流 預估規模 3 人月、8 週 2. 風險分級判定 📝 範本 判斷條件 是否符合 說明 處理金流、極機密個資或機密資料 {是/否} 對外公開服務 {是/否} 受法規要求(資通安全管理法、金融監理等) {是/否} 停機造成重大營運損失 {是/否} 與 L1 系統介接或影響多部門 {是/否} 判定等級 {L1 高/L2 中/L3 低} {符合任一 L1 條件即為 L1} 📖 使用說明 符合任一 L1 條件即為 L1;無 L1 條件但符合 L2 條件為 L2;其餘為 L3 等級判定必須寫出理由,不得為了減少文件而刻意降級 💡 範例 判斷條件 是否符合 說明 處理金流、極機密個資或機密資料 否 僅姓名與 Email,屬機密但無極機密 對外公開服務 否 僅內網 受法規要求 否 停機造成重大營運損失 否 可改用紙本登記 與 L1 系統介接或影響多部門 否 僅讀取 AD 判定等級 L3 低 無 L1/L2 條件 3. 裁剪項目 📝 範本 活動/文件 標準要求(依等級) 本專案作法 理由 補償措施 {活動} {必須/應/得} {作法} {理由} {如有} 📖 使用說明 只列與標準不同的項目;標準要求「必須」的項目不得裁剪,除非經架構審查委員會核准並寫明補償措施 安全掃描(SAST/SCA/Secrets)在所有等級都是「必須」,不得裁剪 💡 範例 活動/文件 標準要求(L3) 本專案作法 理由 補償措施 SAD/SDD 得以 README + ADR 代替 README + 3 份 ADR 單體應用,架構單純 — 威脅模型 應(檢核表即可) 使用安全檢核表 內網、資料敏感度低 — 效能測試 得 不執行 使用者 < 200 人,尖峰 < 5 TPS 上線後監控 p95 UAT 應 PO 驗收 + Demo 錄影 使用者為內部同仁 — 4. 核准與複核 📝 範本 角色 姓名 日期 意見 專案經理 {姓名} {日期} 架構審查委員會 {姓名} {日期} 資安代表(L1/L2 必填) {姓名} {日期} 複核時機 是否需要重新判定 新增對外服務、金流或極機密資料 必須 使用者規模成長 10 倍以上 應 📖 使用說明 核准者必須有權限(例如架構審查委員會成員),PM 不得自行核准 範圍變更時重新判定,並保留歷次版本 💡 範例 角色 姓名 日期 意見 專案經理 陳大文 2026-09-28 架構審查委員會 王大明 2026-10-01 同意,上線後若開放外部訪客預約需重新判定 5. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的裁剪紀錄是否正確。 ...

October 6, 2026 · 2 min · 270 words · Eric Cheng

架構決策紀錄範本(ADR, Architecture Decision Record Template)

架構決策紀錄範本(Architecture Decision Record, ADR) 參照標準:MADR 4.0.0(Markdown Architectural Decision Records)/ ISO/IEC/IEEE 42010:2022 文件用途:記錄一個重要技術決策的背景、考慮過的選項、取捨與後果 適用階段:系統設計階段(Design Phase)起,貫穿整個生命週期 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 4.6 節 📋 章節目錄 何時必須寫 ADR 檔案命名與存放 ADR 主體(MADR 格式) 狀態與生命週期 審查與驗證 1. 何時必須寫 ADR 📝 範本 情境 是否必須寫 ADR 本案判定 選用或更換框架、資料庫、訊息系統 必須 {是/否} 改變系統間的整合方式(同步改非同步、新增閘道) 必須 {是/否} 偏離公司標準或《軟體開發標準程序教學手冊》 必須 {是/否} 難以反悔(回頭成本高)的決策 必須 {是/否} 只影響單一類別的實作細節 不需要 {是/否} 📖 使用說明 ADR 是「決策的快照」,回答半年後有人問「為什麼當初這樣做?」 判斷原則:如果這個決策錯了,修正成本是否超過一個 Sprint?是 → 寫 ADR ADR 要短(一到兩頁),長篇設計放在 SDD,ADR 只記錄決策本身 💡 範例 情境 是否必須寫 ADR 本案判定 請假事件通知由同步 REST 改為 Kafka 事件 必須 是 → ADR-0007 請假服務的 DTO 改用 Java record 不需要 否(屬《程式寫作指引》範圍) 2. 檔案命名與存放 📝 範本 docs/decisions/ ├── 0001-{決策標題-kebab-case}.md ├── 0002-{決策標題}.md └── README.md # ADR 索引:編號、標題、狀態、日期 📖 使用說明 ADR 與程式碼放在同一個 Repository,走同一個 PR 審查流程(Docs-as-Code) 編號遞增、不重用;標題用動詞開頭描述決策(例:「採用 Kafka 作為訂單事件骨幹」) 索引檔讓新人快速找到所有決策 💡 範例 docs/decisions/ ├── 0001-use-postgresql-as-primary-database.md ├── 0006-adopt-rfc9457-problem-details.md ├── 0007-use-kafka-for-leave-events.md └── README.md 3. ADR 主體(MADR 格式) 📝 範本 --- status: {proposed | accepted | rejected | deprecated | superseded by NNNN} date: {YYYY-MM-DD} decision-makers: {決策者姓名與角色} consulted: {諮詢對象} informed: {知會對象} --- # {NNNN} {決策標題} ## Context and Problem Statement {兩到三句描述背景與要解決的問題;可附事件編號、數據} ## Decision Drivers * {驅動因素 1,例:下游故障不得影響主流程} * {驅動因素 2,例:尖峰 N 筆/秒} ## Considered Options * {選項 1} * {選項 2} * {選項 3(含「維持現狀」)} ## Decision Outcome 選擇「{選項}」,因為 {對照 Decision Drivers 說明理由}。 ### Consequences * Good:{正面影響} * Bad:{負面影響與需要處理的新問題} ### Confirmation {如何確認決策被正確實作,例:整合測試、ArchUnit 規則、上線後監控指標} ## Pros and Cons of the Options ### {選項 2} * Good:{優點} * Bad:{缺點} 📖 使用說明 必填段落:Context、Considered Options(至少兩個,含「維持現狀」)、Decision Outcome、Consequences Bad 後果必須寫:沒有缺點的決策通常代表分析不完整 Confirmation 段落讓決策可驗證,例如用 ArchUnit 測試確保「訂單服務不得直接呼叫點數服務」 引用的效能數據、事件編號需可查證 💡 範例 --- status: accepted date: 2026-09-20 decision-makers: 架構師 林志明、Tech Lead 陳大文 consulted: DBA 王小美、資安 李小華 informed: HRMS 開發團隊 --- # 0007 請假事件改用 Kafka 通知下游 ## Context and Problem Statement 請假核准後需通知薪資、出勤、Email 三個服務。目前以同步 REST 呼叫, 2026 Q3 薪資服務維護期間造成請假核准失敗 3 次(INC-20260712-002)。 ## Decision Drivers * 下游服務故障不得影響請假核准 * 事件需可重播 7 天,以便薪資重算 * 維運團隊已有 Kafka 叢集與維運經驗 ## Considered Options * Apache Kafka * RabbitMQ * 維持同步 REST + 重試 ## Decision Outcome 選擇 Apache Kafka,因為它是唯一同時滿足「下游故障不影響核准」與「事件可重播 7 天」的選項,且不需新增維運技能。 ### Consequences * Good:下游故障不再影響核准;新服務可自行訂閱事件 * Bad:事件可能重複投遞,消費端必須冪等;需監控 consumer lag ### Confirmation 整合測試驗證「薪資服務停止時仍可核准請假」;上線後監控 consumer lag < 1,000。 ## Pros and Cons of the Options ### RabbitMQ * Good:團隊熟悉 AMQP 路由 * Bad:訊息消費後即刪除,不支援 7 天重播 ### 維持同步 REST + 重試 * Good:不需新元件 * Bad:重試會延長核准回應時間,且下游長時間故障時仍會失敗 4. 狀態與生命週期 📝 範本 stateDiagram-v2 [*] --> proposed: 提出 proposed --> accepted: 審查通過 proposed --> rejected: 審查否決 accepted --> deprecated: 不再適用 accepted --> superseded: 被新 ADR 取代 rejected --> [*] deprecated --> [*] superseded --> [*] 📖 使用說明 ADR 一經 accepted 就不修改內容(錯字除外);決策改變時新增一份 ADR,舊 ADR 的 status 改為 superseded by NNNN rejected 的 ADR 也要保留,避免同樣的提案反覆討論 💡 範例 編號 標題 狀態 日期 0003 請假通知使用同步 REST superseded by 0007 2025-11-02 0007 請假事件改用 Kafka 通知下游 accepted 2026-09-20 5. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的 ADR 是否正確。 ...

October 6, 2026 · 3 min · 492 words · Eric Cheng

流程成熟度自我評估範本(Process Maturity Self-Assessment Template)

流程成熟度自我評估範本(Process Maturity Self-Assessment) 參照標準:CMMI V3.0(成熟度等級 0–5)/ DORA 軟體交付績效指標(五項)/ OWASP SAMM v2.1 文件用途:定期評估組織或部門的開發流程成熟度,找出下一步最值得投資的改善項目 適用階段:每季或每半年 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 12.2、12.3 節 📋 章節目錄 評估範圍 實務領域評估 交付績效指標 改善計畫 審查與驗證 1. 評估範圍 📝 範本 項目 內容 評估單位 {部門/團隊} 評估期間 {YYYY Qn} 評估者 {姓名,建議含一位非本單位成員} 參照模型 CMMI V3.0(自評,非正式評鑑) 📖 使用說明 自評不等於 CMMI 正式評鑑(需由 ISACA 授權的評鑑師執行),請在文件中註明 建議邀請其他部門的人參與,減少自評偏差 💡 範例 項目 內容 評估單位 人資系統開發部 評估期間 2026 Q3 評估者 部門主管 王、品保部 黃(外部觀點) 參照模型 CMMI V3.0(自評,非正式評鑑) 2. 實務領域評估 📝 範本 實務領域 目前等級(0–5) 證據 缺口 目標等級 {領域} {N} {文件、工具紀錄} {缺口} {N} 等級對照(CMMI V3.0): 0 不完整、1 初始、2 已管理(專案層級)、3 已定義(組織標準流程並裁剪使用)、4 量化管理、5 最佳化。 ...

October 6, 2026 · 2 min · 330 words · Eric Cheng

知識交接檢核範本(Knowledge Transfer Checklist Template)

知識交接檢核範本(Knowledge Transfer Checklist) 參照標準:ISO/IEC 20000-1:2018(服務移轉)/ ITIL 4 Knowledge Management 文件用途:確保人員異動、專案移交維運時,文件、知識、權限與實作能力都完整交接 適用階段:專案結案(G4)、人員異動、委外移轉 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 11.2、2.4(G4)節 📋 章節目錄 交接基本資訊 文件與系統知識 權限交接 實際演練 審查與驗證 1. 交接基本資訊 📝 範本 項目 內容 交接範圍 {系統/模組} 交出方 {姓名、角色} 接手方 {姓名、角色} 交接期間 {開始日}~{完成日} 見證人 {主管或維運主管} 📖 使用說明 交接期間建議至少兩週,涵蓋一次部署與一次例行維運作業 見證人負責確認演練結果 💡 範例 項目 內容 交接範圍 HRMS 請假模組 交出方 開發 Tech Lead 王 接手方 維運工程師 張、林 交接期間 2026-10-13~2026-10-24 見證人 維運主管 吳 2. 文件與系統知識 📝 範本 # 項目 位置 已說明 接手方確認 1 {文件或知識} {連結} {☐/☑} {☐/☑} 📖 使用說明 「已說明」由交出方勾選,「接手方確認」由接手方在能自行回答相關問題後才勾選 必含:README、架構(SAD/ADR)、Runbook、監控與告警、已知問題與技術債 💡 範例 # 項目 位置 已說明 接手方確認 1 README 與本機建置 Repository 根目錄 ☑ ☑ 2 架構與 ADR(0001–0007) docs/decisions/ ☑ ☑ 3 Runbook(6 個告警的處理) Wiki|HRMS Runbook ☑ ☐ 4 已知問題:AD 同步偶發逾時 Runbook 附錄 ☑ ☑ 5 技術債清單 Jira 篩選器「HRMS 技術債」 ☑ ☑ 3. 權限交接 📝 範本 系統 接手方已取得 交出方已移除或降級 個人金鑰/Token 已輪換 {系統} {☐/☑} {☐/☑/不適用} {☐/☑/不適用} 📖 使用說明 權限採最小權限原則,依接手方的職責申請 交出方離開職務時,其權限與個人持有的金鑰/Token 必須移除或輪換 💡 範例 系統 接手方已取得 交出方已移除或降級 個人金鑰/Token 已輪換 Git Repository(維護者) ☑ 降級為 Developer 不適用 Kubernetes(hrms-prod namespace) ☑ ☑ ☑(個人 kubeconfig 憑證已撤銷) PagerDuty 值班 ☑ ☑ 不適用 Vault(hrms/* 路徑) ☑ ☑ ☑ 4. 實際演練 📝 範本 演練項目 執行者(接手方) 日期 結果 見證人 {演練} {姓名} {日期} {成功/需補強:說明} {姓名} 📖 使用說明 演練必須由接手方獨立完成,交出方只能在旁觀察 至少包含:一次部署、一次告警處理(可用模擬告警)、一次回滾演練 💡 範例 演練項目 執行者 日期 結果 見證人 部署 v2.4.1 至 UAT 張 2026-10-16 成功(12 分鐘) 吳 處理模擬告警 HRMSErrorBudgetFastBurn 林 2026-10-20 需補強:未依 Runbook 先確認最近部署 吳 回滾演練(預生產) 張 2026-10-22 成功(6 分鐘) 吳 5. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的交接紀錄是否正確。 ...

October 6, 2026 · 2 min · 258 words · Eric Cheng

缺陷報告範本(Bug Report Template)

缺陷報告範本(Bug Report) 參照標準:ISO/IEC/IEEE 29119-3:2021(Incident Report) 文件用途:讓開發者不必再詢問就能重現、定位與修復缺陷,並讓 PO 判斷優先序 適用階段:測試驗證與維運階段 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 6.4 節 📋 章節目錄 基本資訊與分級 重現資訊 證據與影響 修復與驗證 審查與驗證 1. 基本資訊與分級 📝 範本 項目 內容 缺陷編號 {BUG-專案-序號} 標題 [{模組}] {現象}({在什麼情況下}) 嚴重度(Severity) {P1 Critical/P2 High/P3 Medium/P4 Low}(QA 判定:影響多大) 優先序(Priority) {Highest/High/Medium/Low}(PO 判定:多快要修) 環境/版本 {SIT/UAT/PRD},{版本或 commit SHA} 對應需求/測試案例 {FR-xxx}/{TC-xxx} 是否為安全問題 {是:改走弱點管理流程/否} 📖 使用說明 標題要能單獨看懂:寫出模組、現象、條件;避免「系統錯誤」 嚴重度與優先序不同:報表標題錯字嚴重度低,但明天要交主管機關時優先序最高 安全問題不要寫在公開的缺陷系統中,改依弱點管理流程處理 💡 範例 項目 內容 缺陷編號 BUG-HRMS-0731 標題 [請假] 申請 0.5 天特休時,剩餘額度剛好 0.5 天仍被拒絕 嚴重度(Severity) P3 Medium(有替代方案:改請 4 小時事假) 優先序(Priority) High(月底結算前需修正) 環境/版本 UAT,v2.4.0-rc.2(commit a41f9c2) 對應需求/測試案例 FR-LV-002/TC-LV-002-03 是否為安全問題 否 2. 重現資訊 📝 範本 ### 前置條件 - {帳號、資料狀態} ### 重現步驟 1. {步驟} 2. {步驟} ### 預期結果 {依據需求或驗收條件,寫出應有的結果} ### 實際結果 {實際看到的結果,含錯誤訊息原文} ### 重現頻率 {每次/偶發(N 次中 M 次)} 📖 使用說明 步驟要具體到「另一個人照做就能重現」 預期結果要引用需求或驗收條件,不是「應該要正常」 錯誤訊息貼原文,不要轉述 💡 範例 ### 前置條件 - 帳號 E20260001,特休剩餘 0.5 天 ### 重現步驟 1. 登入 UAT,進入「請假申請」 2. 假別選「特休」,日期 2026-10-15 上午(0.5 天) 3. 按「送出」 ### 預期結果 申請成功,狀態為 pending(驗收條件「申請天數剛好等於剩餘額度」) ### 實際結果 HTTP 422,畫面顯示「特休剩餘 0.5 天,不足申請天數 0.5 天」 ### 重現頻率 每次 3. 證據與影響 📝 範本 項目 內容 traceId {從錯誤回應或日誌取得} 日誌/截圖 {連結;須遮罩個資} 影響範圍 {功能、使用者數、資料是否受損} 替代方案 {有/無:說明} 📖 使用說明 提供 traceId 讓開發者直接在日誌與追蹤系統找到該請求 截圖與日誌中的個資必須遮罩(依資料分級對照表) 💡 範例 項目 內容 traceId 4bf92f3577b34da6a3ce929d0e0e4736 日誌/截圖 UAT 日誌連結(員工姓名已遮罩) 影響範圍 剩餘額度為小數的員工(約 12%)無法用完最後半天 替代方案 有:改請 4 小時事假後由 HR 人工調整 4. 修復與驗證 📝 範本 項目 內容 根本原因 {開發者填寫} 修復 PR {連結} 新增的回歸測試 {測試名稱} 驗證者/日期 {QA 姓名,日期} 📖 使用說明 每個缺陷修復都必須附對應的自動化回歸測試,避免再犯 由提出者或 QA 驗證後才能關閉 💡 範例 項目 內容 根本原因 額度比較使用 double,0.5 的運算結果為 0.49999… 修復 PR #1287(改用 BigDecimal) 新增的回歸測試 LeaveQuotaPolicyTest#shouldAllowWhenRequestEqualsRemainingHalfDay 驗證者/日期 QA 陳,2026-10-09 5. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的缺陷報告是否正確。 ...

October 6, 2026 · 2 min · 262 words · Eric Cheng