cleaning-up-stale-feature-flags

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cleaning up stale feature flags

清理过期feature flags

This skill guides you through finding feature flags that are no longer serving a purpose and safely removing them.

本技能将引导你找出不再发挥作用的feature flags并安全移除它们。

When to use this skill

何时使用本技能

The user asks to clean up, audit, or review their feature flags
The user wants to find flags that are stale, unused, or fully rolled out
The user asks "which feature flags can I remove?" or similar
The user wants to reduce tech debt from old feature flags

用户要求清理、审计或审核他们的feature flags
用户想要查找过期、未使用或完全上线的flags
用户询问“哪些feature flags可以移除？”或类似问题
用户想要减少旧feature flags带来的技术债务

What makes a flag stale

什么是过期flag

A feature flag is considered stale when it's no longer doing useful work. PostHog tracks this with two signals:

Usage-based staleness: The flag has
```
last_called_at
```
data, but hasn't been evaluated in 30+ days. This is the strongest signal — the SDKs are no longer checking this flag.
Configuration-based staleness: The flag has no usage data (
```
last_called_at
```
is null), is 30+ days old, and is 100% rolled out (boolean at 100% with no property filters, or a multivariate flag with one variant at 100%). A fully rolled out flag with no conditions is equivalent to a hardcoded value — it can be replaced by removing the flag check from code.

Disabled flags (

active: false

) are not considered stale — they were intentionally turned off and may be kept for reactivation.

当feature flags不再发挥有用作用时，即被视为过期。PostHog通过两个信号来追踪：

基于使用情况的过期：flag有
```
last_called_at
```
数据，但已超过30天未被评估。这是最明确的信号——SDK不再检查该flag。
基于配置的过期：flag没有使用数据（
```
last_called_at
```
为null），已存在30天以上，且100%上线（布尔型flag设置为100%且无属性过滤器，或多变量flag的某个变体占比100%）。完全上线且无任何条件的flag等同于硬编码值——可以通过从代码中移除flag检查来替换。

已禁用的flag（

active: false

）不被视为过期——它们是被有意关闭的，可能会被保留以便重新激活。

Workflow

工作流

1. List stale flags

1. 列出过期flags

Call

posthog:feature-flag-get-all

with

active: "STALE"

. This returns all stale flags in a single request — PostHog handles the staleness detection server-side using the criteria described above.

调用

posthog:feature-flag-get-all

并设置

active: "STALE"

。该请求会一次性返回所有过期flags——PostHog会使用上述标准在服务器端处理过期检测。

2. Assess each candidate

2. 评估每个候选flag

For each stale flag, gather context before recommending action:

Check if it's tied to an experiment:

The

posthog:feature-flag-get-definition

tool returns an

experiment_set

field. If non-empty, the flag is used by an experiment — check the experiment status before touching it.

Check if other flags depend on it:

Feature flags can have dependencies (flag B only evaluates when flag A is true). The flag definition includes dependency information in its

filters

. Look for

flag_key

references in other flags' filter groups.

Check when it was last modified:

A flag last updated years ago with no recent calls is a stronger removal candidate than one updated last month with no calls (it might be newly deployed and waiting for a release).

Summarize for the user:

For each stale flag, present:

Flag key and description
Why it's considered stale (no calls in N days, or fully rolled out for N days)
Whether it's tied to experiments
When it was created and last modified
A recommended action (clean up from code and disable, or keep with explanation)

在建议操作前，为每个过期flag收集上下文信息：

检查是否与实验关联：

posthog:feature-flag-get-definition

工具会返回

experiment_set

字段。如果该字段非空，说明该flag被用于某个实验——在处理前先检查实验状态。

检查是否有其他flag依赖它：

feature flags可以存在依赖关系（只有当flag A为true时，flag B才会被评估）。flag定义的

filters

中包含依赖信息。在其他flag的过滤器组中查找

flag_key

引用。

检查最后修改时间：

多年未更新且近期无调用的flag比上月更新但无调用的flag更适合移除（后者可能是刚部署，等待发布）。

为用户总结：

为每个过期flag展示：

Flag键和描述
被视为过期的原因（N天无调用，或完全上线N天）
是否与实验关联
创建时间和最后修改时间
建议操作（从代码中清理并禁用，或保留并说明原因）

3. Generate code cleanup instructions

3. 生成代码清理说明

Generate a cleanup prompt the user can run in their code editor or coding agent. The cleanup instructions must be tailored to each flag's rollout state, because the rollout state determines which code path to keep. This list also serves as the approval checklist — if the user says their code is already cleaned up, they review it and confirm which flags to disable.

Classify each flag into one of three rollout states based on its definition:

fully_rolled_out
: A boolean flag with a release condition at 100% rollout and no property filters, or a multivariate flag where one variant is at 100%. Record which variant was active (for multivariate flags).
not_rolled_out
: All release conditions are at 0%, or the flag has no release conditions at all.
partial
: Everything else — the flag had some targeting but wasn't fully rolled out or fully off.

Then generate instructions following this structure:

For fully rolled out boolean flags — remove the flag check but keep the enabled code path:

text

Search for: isFeatureEnabled, useFeatureFlag, getFeatureFlag, posthog.isFeatureEnabled, posthog.getFeatureFlag

For flag "example-flag":
- Remove the if-check, keep the body
- If there is an else branch, remove the else branch entirely

For fully rolled out multivariate flags — keep only the winning variant's code:

text

For flag "example-flag" (keep variant: "winning-variant"):
- For if/else chains: keep only the branch matching "winning-variant", remove the flag check
- For switch statements: keep only the winning variant's case, remove the switch

For not-rolled-out flags — remove the entire flag check AND the enabled code path:

text

For flag "example-flag":
- Remove the if-check AND its body (the feature was never active)
- If there is an else branch, keep only the else body

For partial rollout flags — flag these for manual review:

text

For flag "example-flag":
- This flag had a partial rollout — check the flag's intent to determine which code path to keep
- Then remove the flag check

End the instructions with: "After cleanup, remove any dead code branches and unused imports."

Present the full cleanup prompt in a copyable format so the user can paste it directly into Claude Code, Cursor, Copilot, or any other AI code editor.

生成用户可在代码编辑器或编码Agent中运行的清理提示。清理说明必须根据每个flag的上线状态量身定制，因为上线状态决定了要保留哪个代码路径。该列表也可作为审批清单——如果用户表示代码已清理完成，他们会进行审核并确认要禁用哪些flags。

根据flag定义将每个flag分为三种上线状态：

fully_rolled_out
：布尔型flag的发布条件为100%上线且无属性过滤器，或多变量flag的某个变体占比100%。记录哪个变体处于激活状态（针对多变量flag）。
not_rolled_out
：所有发布条件均为0%，或flag完全没有发布条件。
partial
：其他情况——flag有一些目标设置，但未完全上线或完全关闭。

然后按照以下结构生成说明：

对于完全上线的布尔型flag——移除flag检查，但保留启用的代码路径：

text

Search for: isFeatureEnabled, useFeatureFlag, getFeatureFlag, posthog.isFeatureEnabled, posthog.getFeatureFlag

For flag "example-flag":
- Remove the if-check, keep the body
- If there is an else branch, remove the else branch entirely

对于完全上线的多变量flag——仅保留获胜变体的代码：

text

For flag "example-flag" (keep variant: "winning-variant"):
- For if/else chains: keep only the branch matching "winning-variant", remove the flag check
- For switch statements: keep only the winning variant's case, remove the switch

对于未上线的flag——移除整个flag检查以及启用的代码路径：

text

For flag "example-flag":
- Remove the if-check AND its body (the feature was never active)
- If there is an else branch, keep only the else body

对于部分上线的flag——标记为需要手动审核：

text

For flag "example-flag":
- This flag had a partial rollout — check the flag's intent to determine which code path to keep
- Then remove the flag check

在说明末尾添加："After cleanup, remove any dead code branches and unused imports."

将完整的清理提示以可复制格式呈现，以便用户直接粘贴到Claude Code、Cursor、Copilot或其他AI代码编辑器中。

4. Disable flags after code changes are deployed

4. 代码变更部署后禁用flags

Never disable flags before the code changes are deployed. Disabling a fully rolled out flag while code still checks it will cause that code path to stop working — a production regression.

Never disable flags without explicit user approval. Always present the list and recommendations first, then ask which flags to act on.

Present the user with both options and their tradeoffs:

Disable (
```
active: false
```
) via
```
posthog:update-feature-flag
```
: The flag stops being evaluated but the configuration is preserved. If something was missed in the code cleanup, re-enabling is instant. Recommended as the default.
Delete via
```
posthog:delete-feature-flag
```
: A soft-delete — the flag is marked as deleted but not physically removed. Keeps the flag list clean, but re-enabling requires recreating the flag. Better for flags the user is confident they'll never need again.

Once the user has chosen and confirms their code changes are deployed, apply the chosen action one flag at a time. Confirm each action so it's easy to stop if something goes wrong.

绝对不要在代码变更部署前禁用flags。 当代码仍在检查flag时，禁用完全上线的flag会导致该代码路径停止工作——这会引发生产环境故障。

绝对不要在未获得用户明确批准的情况下禁用flags。 始终先展示列表和建议，然后询问要对哪些flags执行操作。

向用户展示两种选项及其权衡：

禁用（
```
active: false
```
）：通过
```
posthog:update-feature-flag
```
实现。flag停止被评估，但配置会被保留。如果代码清理过程中有遗漏，重新启用即可生效。推荐作为默认选项。
删除：通过
```
posthog:delete-feature-flag
```
实现。软删除——flag被标记为已删除，但不会被物理移除。保持flag列表整洁，但重新启用需要重新创建flag。更适合用户确信永远不会再需要的flags。

一旦用户做出选择并确认代码变更已部署，逐个执行所选操作。确认每个操作，以便在出现问题时可以轻松停止。

Example interaction

示例交互

text

User: "Can you help me clean up our stale feature flags?"

Agent steps:
- Call posthog:feature-flag-get-all with active: "STALE" to get all stale flags in one request
- For each stale flag, call posthog:feature-flag-get-definition to check experiment_set and dependencies
- Present findings:

   "I found 7 stale feature flags in your project:

   | Flag | Last called | Reason | Recommendation |
   |------|-------------|--------|----------------|
   | old-checkout-flow | 45 days ago | No evaluations in 45 days | Clean up and disable |
   | beta-dashboard-v2 | Never | 100% rolled out, created 3 months ago | Clean up and disable |
   | holiday-promo-2024 | 90 days ago | No evaluations in 90 days | Clean up and disable |
   | new-pricing-page | 60 days ago | No evaluations in 60 days, tied to experiment #42 | Check experiment first |
   ...

   Want me to generate cleanup instructions for any of these? I'd recommend
   starting with old-checkout-flow and beta-dashboard-v2 since they have no dependencies."

- User confirms: "Yes, do old-checkout-flow and beta-dashboard-v2"
- Classify rollout states from the flag definitions:
   - old-checkout-flow: fully_rolled_out (boolean, 100% rollout, no conditions)
   - beta-dashboard-v2: fully_rolled_out (boolean, 100% rollout, no conditions)
- Generate and present cleanup prompt:

   "Here's a cleanup prompt you can paste into your code editor:

   ---
   Find and remove all references to these feature flags in the codebase.
   For each flag, search for all usages: isFeatureEnabled, useFeatureFlag,
   getFeatureFlag, posthog.isFeatureEnabled, posthog.getFeatureFlag, etc.

   ## Flags that were rolled out to 100%
   These flags were fully rolled out. Remove the flag check but KEEP the enabled code path.

   Boolean flags (remove the if-check, keep the body):
   - old-checkout-flow
   - beta-dashboard-v2

   If there is an else branch, remove the else branch entirely.
   After cleanup, remove any dead code branches and unused imports.
   ---

   Once you've cleaned up your code and deployed, let me know.
   Would you like to disable or delete these flags?
   - Disable (recommended): keeps the config, re-enabling is instant
   - Delete: removes from the list, but you'd need to recreate if needed"

- User confirms: "Disable them, code is deployed"
- Disable each flag using posthog:update-feature-flag (active: false)
- Confirm: "Both flags are now disabled in PostHog."

text

User: "Can you help me clean up our stale feature flags?"

Agent steps:
- Call posthog:feature-flag-get-all with active: "STALE" to get all stale flags in one request
- For each stale flag, call posthog:feature-flag-get-definition to check experiment_set and dependencies
- Present findings:

   "I found 7 stale feature flags in your project:

   | Flag | Last called | Reason | Recommendation |
   |------|-------------|--------|----------------|
   | old-checkout-flow | 45 days ago | No evaluations in 45 days | Clean up and disable |
   | beta-dashboard-v2 | Never | 100% rolled out, created 3 months ago | Clean up and disable |
   | holiday-promo-2024 | 90 days ago | No evaluations in 90 days | Clean up and disable |
   | new-pricing-page | 60 days ago | No evaluations in 60 days, tied to experiment #42 | Check experiment first |
   ...

   Want me to generate cleanup instructions for any of these? I'd recommend
   starting with old-checkout-flow and beta-dashboard-v2 since they have no dependencies."

- User confirms: "Yes, do old-checkout-flow and beta-dashboard-v2"
- Classify rollout states from the flag definitions:
   - old-checkout-flow: fully_rolled_out (boolean, 100% rollout, no conditions)
   - beta-dashboard-v2: fully_rolled_out (boolean, 100% rollout, no conditions)
- Generate and present cleanup prompt:

   "Here's a cleanup prompt you can paste into your code editor:

   ---
   Find and remove all references to these feature flags in the codebase.
   For each flag, search for all usages: isFeatureEnabled, useFeatureFlag,
   getFeatureFlag, posthog.isFeatureEnabled, posthog.getFeatureFlag, etc.

   ## Flags that were rolled out to 100%
   These flags were fully rolled out. Remove the flag check but KEEP the enabled code path.

   Boolean flags (remove the if-check, keep the body):
   - old-checkout-flow
   - beta-dashboard-v2

   If there is an else branch, remove the else branch entirely.
   After cleanup, remove any dead code branches and unused imports.
   ---

   Once you've cleaned up your code and deployed, let me know.
   Would you like to disable or delete these flags?
   - Disable (recommended): keeps the config, re-enabling is instant
   - Delete: removes from the list, but you'd need to recreate if needed"

- User confirms: "Disable them, code is deployed"
- Disable each flag using posthog:update-feature-flag (active: false)
- Confirm: "Both flags are now disabled in PostHog."

Important notes

重要注意事项

Code first, then disable. Disabling a flag while code still references it causes the enabled code path to silently stop working. Always clean up code and deploy before disabling.
Prefer disable over delete. Disabling is instantly reversible. Deletion is not — re-enabling requires recreating the flag. Always present both options with tradeoffs and let the user choose.
Always confirm before acting. This skill involves disabling flags, which can affect production behavior. Never disable without explicit user approval.
Disabled flags are not stale. Don't recommend disabling flags that are already intentionally disabled — they may be kept for emergency reactivation.
Experiment flags need extra care. If a flag is tied to an active or recently completed experiment, the user likely wants to keep it until they've analyzed results.
Seasonal flags may return. Flags like "black-friday-sale" might look stale but are intentionally reused. Ask the user before removing these.
Code cleanup is the real win. Removing the flag from PostHog is the easy part. The value comes from removing the dead code paths.

先清理代码，再禁用flag。 当代码仍引用flag时禁用它会导致启用的代码路径无声停止工作。始终先清理代码并部署，再禁用flag。
优先禁用而非删除。 禁用操作可立即撤销。删除则不可——重新启用需要重新创建flag。始终向用户展示两种选项及其权衡，让用户选择。
操作前务必确认。 本技能涉及禁用flags，这可能会影响生产环境行为。绝对不要在未获得用户明确批准的情况下禁用。
已禁用的flags不算过期。 不要建议禁用已被有意禁用的flags——它们可能被保留用于紧急重新激活。
实验相关flags需格外小心。 如果flag与活跃或近期完成的实验关联，用户可能希望保留它直到分析完结果。
季节性flags可能会复用。 类似“black-friday-sale”的flags看起来可能过期，但实际上是被有意复用的。移除前先询问用户。
代码清理才是真正的价值所在。 从PostHog中移除flag很简单。真正的价值在于移除无用的代码路径。

cleaning-up-stale-feature-flags

Original

Translation

Cleaning up stale feature flags

清理过期feature flags

When to use this skill

何时使用本技能

What makes a flag stale

什么是过期flag

Workflow

工作流

1. List stale flags

1. 列出过期flags

2. Assess each candidate

2. 评估每个候选flag

3. Generate code cleanup instructions

3. 生成代码清理说明

4. Disable flags after code changes are deployed

4. 代码变更部署后禁用flags

Example interaction

示例交互

Important notes

重要注意事项

Related tools

相关工具