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

參照標準:OpenFeature 規格(CNCF)

文件用途:登記每個 Feature Flag 的用途、擁有者、預設值與移除日期,避免旗標變成無人管理的技術債

適用階段:開發、部署與維運階段

範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 8.4 節


📋 章節目錄

  1. 旗標登記
  2. 變更紀錄
  3. 清理檢查
  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-202026-11-15
admin-xml-import營運開關管理後台 XML 匯入(RA-2026-07 期間關閉)資安 李false全環境 off2025-03-01不移除(每季確認)

2. 變更紀錄

📝 範本

時間旗標環境變更執行者核准者原因
{YYYY-MM-DD HH:MM}{名稱}{環境}{舊值 → 新值}{姓名}{姓名}{原因/工單}

📖 使用說明

  • 正式環境的旗標變更等同上線,必須留稽核紀錄並經核准
  • 優先使用旗標平台內建的稽核日誌,本表作為摘要

💡 範例

時間旗標環境變更執行者核准者原因
2026-10-06 10:00new-leave-quota-checkPRD0% → 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 依本範本產出的登記表是否正確。

自動檢查

檢查項目方法
程式中的旗標都已登記grep -rhoE "get(Boolean|String|Integer)Value\(\"[a-z0-9-]+\"" src/ 擷取旗標名稱,與本表比對
過期旗標CI 比對「預計移除日」已過但程式仍引用的旗標,輸出警告
兩種狀態都有測試每個發布型旗標至少有開啟與關閉各一個測試

人工審查問題

  1. 預設值是否為安全的行為?
  2. 每個旗標都有擁有者與移除日期嗎?
  3. 正式環境的變更是否有核准紀錄?
  4. 是否有長期 100% 開啟卻未清理的旗標?

AI 常見錯誤

  • 預設值設為 true,旗標服務故障時啟用未完成功能。
  • 未登記移除日期。
  • 移除旗標時只改設定,未刪除舊流程程式碼。

📌 範本使用注意事項

  1. 程式中只依賴 OpenFeature API,旗標平台可替換
  2. 搭配「部署指引範本」「回滾計畫範本」使用:旗標是比回滾更快的止血手段