feature-flags-architect

功能开关架构师

为功能开关建立端到端的管理规范：对其分类、发布、逐步放量并最终退役。大多数团队把开关当作一次性的 if 语句；本技能则将其视为可衡量债务的受控生命周期。

适用场景

• 添加新开关并需要制定发布计划
• 审查代码库，查找过时或无归属的开关
• 选择开关提供商（LaunchDarkly、GrowthBook、Statsig、Unleash、Flipt，或自行构建）
• 为高风险发布设计紧急关闭路径
• 发布冻结前清理开关债务
• 评估某项功能是否确实需要通过开关控制发布

核心原则：开关有生命周期，而不只是一个 if

request → design → ship → ramp → cleanup → archive

未清理的开关会变成债务：失效分支、过时的默认值、未经测试的代码路径，以及无法控制的影响范围。本技能中的三个脚本用于落实这一生命周期。

快速开始

# 1. Audit the repo for flag debt
python scripts/flag_debt_scanner.py --repo . --max-age-days 90

# 2. Plan a progressive rollout for a new flag
python scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring

# 3. Verify every flag has a documented kill switch
python scripts/kill_switch_audit.py --repo . --flag-doc docs/feature-flags.md

开关的 4 种类型（分类体系）

不同类型的开关有不同的生命周期和负责人。分类错误会造成债务。

类型	用途	典型生命周期	负责人	清理触发条件
发布	在生产环境中隐藏未完成的功能	数天至数周	工程团队	已达到 100% 放量
实验	对不同变体进行 A/B 测试	数周	产品/市场营销	测试结束；已选出优胜方案
运维	断路器、性能切换开关、紧急关闭开关	数月至数年	工程团队/SRE	已由自动扩缩容机制替代／功能已退役
权限	针对用户／账户／套餐的授权	数年（永久）	产品团队	套餐／角色已移除

只有发布和实验开关应纳入债务扫描器的监控列表。运维和权限开关本就会长期存在。决策树参见 references/flag_taxonomy.md。

3 个 Python 工具

这三个工具都只依赖标准库。运行时使用 --help。

flag_debt_scanner.py

查找使用次数较少且存在时间超过 --max-age-days 的开关，并建议将其作为清理候选项。

python scripts/flag_debt_scanner.py --repo . --max-age-days 90 --format text
python scripts/flag_debt_scanner.py --repo . --max-age-days 60 --format json > debt.json

检测启发式：

1. 遍历 --repo，查找符合常见开关调用模式的代码引用：
   • flag("...")、isFlagEnabled("...")、featureFlag("...")、getFlag("...")
   • client.variation("...", ...)、unleash.isEnabled("...")、growthbook.feature("...")
2. 对每个唯一的开关标识符，查找引入该标识符的最早提交（git log --diff-filter=A -S <name>）。
3. 如果引入时间早于 --max-age-days 天前，且使用位置数 ≤--min-uses，则将其标记为 DEBT。

输出开关名称、存在天数、文件引用和建议操作。JSON 模式适用于 CI。

rollout_planner.py

根据用户群体规模、目标百分比、持续时间和策略生成分阶段放量计划。

python scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring
python scripts/rollout_planner.py --population 50000 --target-percent 25 --duration-days 7 --strategy linear
python scripts/rollout_planner.py --population 1000000 --target-percent 100 --duration-days 30 --strategy log

策略：

• ring：1% → 5% → 25% → 50% → 100%，间隔均匀。高风险发布的默认策略。
• linear：每天按固定速率放量。中风险发布的默认策略。
• log：前期放量快，后期放量慢。对结果有信心时，低风险发布的默认策略。
• cohort：按指定用户群体放量（内部 → Beta → 免费用户 → 付费用户 → 全部用户）。

输出 Markdown 表格，列出每个阶段的日期、百分比、预期用户数、中止标准和验证步骤。

kill_switch_audit.py

将代码中发现的开关与文档进行交叉核对，确认每个开关都有记录在案的紧急关闭路径。

python scripts/kill_switch_audit.py --repo . --flag-doc docs/feature-flags.md
python scripts/kill_switch_audit.py --repo . --flag-doc runbooks/flags.md --format json

检查内容：

1. 每个代码中发现的开关都在 --flag-doc 中有对应条目
2. 每个条目都注明：负责人、类型、紧急关闭触发条件、监控仪表板
3. 报告缺少文档的开关（FAIL）或缺少字段的开关（WARN）

新开关发布前，将此检查作为合并前的关卡。

提供商选择器（5 种 + 自行实现）

提供商	最适合	定价模式	锁定风险	开源选项
LaunchDarkly	企业、复杂定向、审计/合规	按 MAU 计费，价格昂贵	高	否
GrowthBook	中型市场、专注于 A/B 测试、支持开源	按 MAU 计费 + 开源版	低	是（可自托管）
Statsig	增长/产品团队、高级实验	免费套餐 + 按 MAU 计费	中	否
Unleash	开源优先、可自托管、对开发者友好	开源版 + 企业版	低	是
Flipt	轻量级、原生支持 k8s、需求简单	仅开源	无	是
自行实现	少于 100 个标记、无需定向、完全掌控	无	无	不适用

决策规则：

• 少于 50 个标记且无需定向 → 使用配置文件或环境变量自行实现
• 需要分析 + 实验 → 选择 Statsig 或 GrowthBook
• 需要合规/SOC2 审计日志 → 选择 LaunchDarkly
• 必须自托管（数据驻留/隔离网络） → 选择 Unleash 或 Flipt
• 详情请参阅 references/provider_comparison.md。

工作流

工作流 1：在标记后发布新功能

1. Classify: which of the 4 flag types?
   → Release (most common for engineering work)
2. Run rollout_planner.py to design the ramp
3. Add flag entry to docs/feature-flags.md BEFORE writing code:
   - name, owner, type, kill-switch trigger, dashboard URL
4. Write the code with the flag
5. Run kill_switch_audit.py — must pass before merge
6. Deploy at 0%; verify kill switch works
7. Execute rollout schedule; abort if abort criteria met
8. At 100% for 7+ days: remove flag, delete dead branch, archive doc entry

工作流 2：季度标记清理

1. Run flag_debt_scanner.py --repo . --max-age-days 90 > debt.md
2. For each flagged item:
   a. Confirm it reached 100% (or was killed)
   b. Find the issue/PR that introduced it; verify owner agrees to remove
   c. Delete dead branches; remove flag config
   d. Run kill_switch_audit.py — should now show one fewer flag
3. Update CHANGELOG: "Removed N stale flags"

工作流 3：选择提供商

1. Estimate flag count (current + 12-month projection)
2. Required features:
   - Targeting rules (user, account, geo, %)?
   - A/B testing + stats?
   - Audit log / SOC2?
   - Self-hosting / data residency?
3. Pricing budget (MAU * cost-per-MAU)
4. See provider_comparison.md decision tree
5. Build a 30-day proof-of-concept before signing

工作流 4：设计紧急关闭开关

1. Identify the failure modes:
   - Latency spike (which threshold?)
   - Error rate spike (which threshold?)
   - Business metric regression (which threshold?)
2. Wire each to an abort:
   - Manual: dashboard link + on-call playbook
   - Automated: alert threshold flips flag back to 0%
3. Test the kill switch in staging BEFORE production rollout
4. Document in flag-doc; pass kill_switch_audit.py

参考资料

• references/flag_taxonomy.md — 4 种类型、决策树、所有权、生命周期
• references/provider_comparison.md — LaunchDarkly / GrowthBook / Statsig / Unleash / Flipt / 自行实现的权衡
• references/rollout_strategies.md — 分环 / 线性 / 对数 / 群组 / 地理区域、终止标准、监控
• references/flag_lifecycle.md — 请求 → 设计 → 发布 → 扩大覆盖 → 清理 → 归档

斜杠命令

/flag-cleanup — 在当前仓库运行完整的清理工作流：扫描技术债，生成移除计划，审计紧急关闭开关。

资源模板

• assets/flag_request_template.md — 新标记申请填写表（名称、负责人、类型、紧急关闭开关、发布计划）

反模式

• 永久标记在 50 处使用 if (FLAG_FOO) — 应使用带运行时配置的权限标记，而不是发布标记
• 标记没有负责人 — 原工程师离职后，就没人会清理它
• 未记录紧急关闭开关 — 功能出问题时，没人知道如何禁用它
• 运行了 6 个月的 A/B 测试 — 选出胜者；无限期运行会造成技术债
• 将标记用作外观改动的功能开关 — 应通过部署发布，而不是使用标记

可验证的成功标准

使用此技能的团队应达到：

• 100% 的新标记在合并时通过 kill_switch_audit.py 检查
• flag_debt_scanner.py --max-age-days 90 在整个仓库中返回 ≤5 个过期标记
• 每个标记都有记录在案的负责人、类型和紧急关闭开关
• 发布标记从 100% 覆盖到退役的平均时间：<60 天