feature-flags-architect

feature-flags-architect skill 概览

feature-flags-architect 适合解决什么问题

feature-flags-architect 是一项面向工程团队的技能，用于把 feature flags 作为完整的发布生命周期来规划、评审、审计和清理，而不是把它们变成散落在代码里的 if 判断。它最适合正在做 progressive delivery、高风险发布、实验、kill switches，或需要在 LaunchDarkly、GrowthBook、Statsig、Unleash、Flipt、自研 flag 系统等工具之间做选型的团队。

最适合的用户与使用场景

当你需要一份具体的 rollout 计划、flag 申请模板、过期 flag 检测、kill-switch 文档，或 provider 取舍分析时，可以使用这个 skill。它尤其适合 release engineers、platform teams、staff engineers 和 product engineers，用来回答这些问题：这个变更是否应该加 flag？它属于哪种类型？谁负责？如何逐步放量？哪些指标触发中止？什么时候移除？

它与通用 prompt 的区别

普通 prompt 可能只会建议“使用 feature flag”；feature-flags-architect 会推动你建立完整生命周期：request → design → ship → ramp → cleanup → archive。该 repository 提供了 flag taxonomy、lifecycle、provider comparison 和 rollout strategies 等实用参考，还包含基于 stdlib 的 Python 脚本，用于 flag debt scanning、rollout planning 和 kill-switch audits。

采用前需要重点考虑什么

当你的 repository 里有可识别的 flag 调用，并且有类似 docs/feature-flags.md 的书面 flag registry 时，这个 skill 效果最好。它的扫描器会查找常见模式，例如 isEnabled(...)、useFlag(...)、LaunchDarkly 风格的 variation(...)，以及 Unleash、GrowthBook、Statsig 的 SDK 调用。如果你的组织大量使用自定义 wrapper，在依赖审计结果之前，通常需要先调整 regex patterns。

如何使用 feature-flags-architect skill

feature-flags-architect 安装方式与 repository 路径

使用你的 skill manager 从 GitHub source 安装该 skill，例如：

npx skills add alirezarezvani/claude-skills --skill feature-flags-architect

源码位于：

engineering/skills/feature-flags-architect

安装后，先阅读 SKILL.md，再查看 assets/flag_request_template.md、references/flag_taxonomy.md、references/flag_lifecycle.md、references/rollout_strategies.md 和 references/provider_comparison.md。如果要用于日常发布与运维流程，还应查看 scripts/flag_debt_scanner.py、scripts/kill_switch_audit.py 和 scripts/rollout_planner.py。

为了得到有用结果，你需要提供哪些输入

要让 feature-flags-architect 产出高质量结果，不要只说“加一个 flag”。应提供 feature name、risk level、affected path、expected lifetime、owner、current provider、code locations、metrics、rollout target 和 cleanup rule。

较弱的 prompt：

Add a flag for the new checkout.

更强的 prompt：

Use feature-flags-architect for Deployment. We are launching new-checkout-flow in a TypeScript service using LaunchDarkly. It affects payment confirmation and order creation. Start at 1%, target 100% in 21 days, abort if error rate rises by more than 1 percentage point or p99 latency exceeds baseline by 20%. Owner is payments-platform. Produce a flag request, rollout plan, kill-switch criteria, tests, and cleanup conditions.

这些上下文能帮助该 skill 判断 flag 类型，选择更安全的放量节奏，并定义可度量的中止规则。

新建 flag 的推荐工作流

从 assets/flag_request_template.md 开始，在提交 PR 前填写每个字段。然后让该 skill 根据 references/flag_taxonomy.md 将 flag 分类为 Release、Experiment、Operational 或 Permission。接着，使用 references/rollout_strategies.md 中基于风险的策略生成 rollout 计划。合并前，运行或改造 scripts/kill_switch_audit.py，确保每个代码里的 flag 都有 owner、type、kill switch 和 dashboard entry。

一份高质量输出应包含：代码中只有一个决策点；对于 release flags，生产环境默认 OFF；ON/OFF 分支测试；dashboard link；明确的中止阈值；以及清理触发条件，例如“100% rollout 后稳定 7 天且无事故即移除”。

清理与审计的推荐工作流

对于 stale flags，运行 flag debt scanner 扫描你的 repository，并调整阈值：

python scripts/flag_debt_scanner.py --repo /path/to/repo --max-age-days 90 --min-uses 2

把结果当作 review queue，而不是自动删除清单。让 feature-flags-architect 将发现的问题分组为 safe removals、needs-owner-review，以及 permanent permission/operational flags。对于 kill-switch readiness，可以用 kill_switch_audit.py 将代码中的 flags 与你的 registry 交叉核对；它最适合作为 pre-merge 或 release-freeze gate 使用。

feature-flags-architect skill 常见问题

feature-flags-architect 只适用于 LaunchDarkly 吗？

不是。feature-flags-architect skill 覆盖 LaunchDarkly、GrowthBook、Statsig、Unleash、Flipt 以及 DIY 方案。provider comparison reference 可帮助你根据 flag count、targeting、audit requirements、experimentation needs、self-hosting 和 budget 做选择。LaunchDarkly 适合大型企业级项目；GrowthBook 和 Unleash 是常见的可 self-host 选项；Flipt 更轻量；DIY 只适合需求非常简单的场景。

什么时候不应该使用 feature flag？

不要给每个变更加 flag。这个 skill 会明确挑战低价值 flags：纯视觉改动、没有 rollback 价值的变更、重复 flags，或没有 cleanup criteria 的 flags。如果直接发布更安全、更简单，就应直接发布。Feature flags 会增加运维暴露面、测试分支、stale code 风险和 ownership 要求。

初学者可以使用这个 skill 吗？

可以，只要严格按模板走。taxonomy 和 lifecycle references 会把模糊的发布问题转化为 checklist，因此对初学者友好。不过，在 payments、authentication、data migrations、authorization 或 infrastructure behavior 等高风险领域，初学者仍应让有经验的 reviewer 参与，因为错误的默认值或 targeting rule 可能导致生产事故。

它为什么比单纯要求 rollout plan 更好？

普通 rollout prompt 往往只会给出通用百分比。feature-flags-architect 会把 rollout 与风险、监控、kill-switch 触发条件、ownership、cleanup 和 provider 约束关联起来。它还包含可检查真实代码的脚本，因此在 Deployment 工作流中更有价值：你需要的是来自 repository 的证据，而不是一份孤立的建议。

如何改进 feature-flags-architect skill 的使用效果

用更充分的上下文提升 feature-flags-architect 结果

最重要的输入是运维层面的具体性。提供 baseline metrics、target cohorts、provider name、SDK/wrapper details、environment defaults、release deadline、blast-radius concerns，以及什么情况算“bad”。不要只要求“a safe rollout”，而应说明：“authentication path, 2M daily users, abort on login failure +0.5pp, p99 latency x1.15, start with internal users, hold each ring 48 hours.”

根据你的 codebase 调整脚本

内置 Python 脚本使用的是常见 regex patterns 和标准代码扩展名。你可以通过加入内部 wrapper 名称、config file 位置、registry 格式和需要跳过的目录来提升准确率。如果你的 flags 声明在 YAML、Terraform、database migrations 或 generated clients 中，应把发现范围扩展到应用代码之外。脚本输出应作为 review 信号，而不是绝对准确的真相来源。

留意常见失败模式

最常见的失败包括：owner 模糊；“临时” release flags 永久存在；conditional checks 分散在多处；缺少 OFF-branch tests；kill switches 未文档化；cleanup dates 从未触发实际行动。让该 skill 在 code review 输出中明确标出这些问题。好的 review 应说明哪些 flags 应被拒绝，哪些需要更强的 runbook，哪些应改为 permission 或 operational flags，而不是 release flags。

在第一次输出后继续迭代

拿到第一次回答后，继续让 feature-flags-architect 按你的约束收紧方案：“reduce rollout duration to 10 days”、“make this work for Unleash”、“convert this into a PR checklist”、“write the docs/feature-flags.md entry”，或 “turn scanner findings into cleanup tickets”。最佳效果来自把这个 skill 当作 release-engineering reviewer 持续使用，而不是一次性生成器。