finding-deleted-feature-flags

最近削除されたフィーチャーフラグを探す

このスキルでは、指定された期間内にアクティブなプロジェクトでソフト削除されたフィーチャーフラグの一覧と、それぞれを削除したユーザーおよび削除日時を取得します。

このスキルを使う場面

• ユーザーが「先週／過去 N 日間に削除されたフラグは？」と尋ねた場合
• ユーザーが最近のフラグ削除について監査したい場合（誰が、いつ、何を削除したか）
• ユーザーが特定のフラグがいつ、または誰によって削除されたかを知りたい場合
• 「最近削除されたフィーチャーフラグ」に関する依頼全般

アクティブな古いフラグの整理には使わないでください。その場合は cleaning-up-stale-feature-flags を使います。このスキルは、すでに削除されたフラグを対象としています。

難しいポイント

system.feature_flags には deleted がブール値として公開されていますが、deleted_at、updated_at、last_modified_at は公開されていません。1 回の SQL クエリでソフト削除されたフラグを削除時刻で絞り込む方法はありません。これらの列を使おうとすると、Unable to resolve field が返されます。

実際の削除タイムスタンプはフラグごとのアクティビティログに記録されており、posthog:feature-flags-activity-retrieve からのみ取得できます（フラグ ID ごとに 1 回呼び出します）。一括アクティビティ取得エンドポイントはありません。

そのため、ワークフローは 2 段階になります。まず SQL で候補を列挙し、次にアクティビティログを並列で照会して、それぞれの削除イベントを探します。

ワークフロー

1. 期間が曖昧な場合は確認する

「先週」は曖昧で、今日から遡った 7 日間を指す場合も、前の暦週（月曜～日曜）を指す場合もあります。ユーザーの意図が明確でなければ確認するか、最終報告で両方の解釈を示してください。

締め切り時刻は必ず UTC で計算し、ユーザーのローカル時間での解釈は別に把握しておいてください。

2. SQL でソフト削除されたフラグを列挙する

アクティブなプロジェクト内の system.feature_flags を対象に、deleted = true で絞り込み、created_at DESC の順に並べてクエリします。

SELECT id, key, created_at
FROM system.feature_flags
WHERE team_id = <team_id> AND deleted = true
ORDER BY created_at DESC
LIMIT 100

削除は経験上、作成直後に集中する傾向があるため（ほとんどのフラグは作成から数日以内に削除されます）、created_at DESC で並べると、最近作成された候補から調べることで最近の削除をすばやく見つけられます。**ただし、**これはあくまでヒューリスティックであり、保証ではありません。最近削除された古いフラグが、この一覧の上位に表示されるとは限りません。報告する際には、この制約を明示してください。

team_id はデフォルトでアクティブなプロジェクトに設定されますが、明確にするため明示的に含めてください。

3. アクティビティログの照会を並列で実行する

候補の ID ごとに、limit: 5, page: 1 を指定して posthog:feature-flags-activity-retrieve を呼び出します。すべての呼び出しを 1 つのメッセージにまとめ、並行して実行されるようにしてください。 順番に呼び出すと大幅に時間がかかります。

call feature-flags-activity-retrieve {"id": <flag_id>, "limit": 5, "page": 1}

妥当なバッチサイズは次のとおりです。

• 「過去 7 日間」→ 上位 20～25 件の候補
• 「過去 30 日間」→ 上位 50 件
• 「過去 90 日間」→ 約 100 件すべてを確認

全件を確認せずに一部だけを調べた場合は、報告でそのことを伝え、残りも確認できると案内してください。

4. 各レスポンスから削除イベントを抽出する

各レスポンスで、activity == "deleted" となっているエントリを探します。そのエントリの created_at が実際の削除時刻で、user.email／user.first_name が削除したユーザーを示します。これらのフィールドは、どの削除経路でも確実に取得できます。

ほとんどのフラグには削除イベントが 1 件だけあります。フラグが複数回削除・復元されている場合は、期間内で最も新しい activity: deleted イベントを採用してください。

5. 元のキーを復元して報告する

ソフト削除された機能フラグが別の場所から参照されている場合（停止済みの実験など）、そのキーは <original>:deleted:<flag_id> に変更されます。ID ベースのサフィックスを付けることで、元のキーを再利用できます。アクティビティログ自体のフィールドから元のキーを復元しようとしないでください。detail.changes に名前変更が記録されるのは、UI／ORM による削除の場合のみです。API／MCP／プログラムによる削除では空の場合が多く、key エントリが欠けていることもあります。また、detail.name は、現在のキー（削除済みかどうかを問わず）をそのまま示すだけです。

代わりに、scripts/strip_deleted_suffix.py を使ってサフィックスを確実に取り除きます。手順 2 の候補リスト全体を JSON として 1 回の呼び出しで渡してください。フラグごとに個別に実行しないでください。

echo '[{"id": 1001, "key": "example-banner:deleted:1001"}]' | python3 scripts/strip_deleted_suffix.py
# prints the same array back (pretty-printed), each object gaining an "original_key" field:
# "original_key": "example-banner"

収集した削除イベントのうち、created_at が指定された期間内にあるものに絞り込みます。各行の「Key」列には、生の削除済み形式ではなく、復元した元のキーを使って表にまとめてください。

| フラグ ID | キー | 削除日時（UTC） | 削除者 |

レポートには調査した候補数と、ソフト削除されたフラグの総数を記載し、調査した範囲と未調査の範囲がユーザーにわかるようにしてください。

注意点

• 境界付近のケース：削除時刻が期間の境界から約 1 時間以内の場合は、黙って除外せず、境界付近のケースとして提示してください。
• created_at を削除時刻の代わりとして信用しないでください：2024 年に作成されたフラグが先週削除された可能性もあります。唯一の確かな情報源はアクティビティログです。
• キーの名前変更は通常の動作です：キーが foo:deleted:12345 のフラグは、もともと foo というキーのフラグでした。復元方法は手順 5 を参照してください。
• すべての候補を調べることは可能ですが、時間がかかります：アクティビティログの呼び出しを約 100 件並列で行うことは可能です。期間が短い場合は、デフォルトではなく追加対応として提案してください。

やり取りの例

ユーザー：「過去 1 週間に削除されたフラグは？」

1. 必要に応じて確認するか、両方の解釈を提示します：「現在から遡る 7 日間（UTC）、アクティブなプロジェクトを対象とします」

2. SQL で列挙し、created_at DESC の順にソフト削除された候補を最大 100 件取得します

3. 上位約 25 件の候補について、アクティビティログを並列で取得します

4. activity: deleted のエントリを抽出し、created_at >= now - 7 days のものに絞り込みます

5. scripts/strip_deleted_suffix.py で元のキーを復元し、報告します。 以下の値は説明用であり、実際のプロジェクトデータではありません。

   Found 2 feature flags deleted in the last 7 days (rolling, ending 2026-08-14 09:30 UTC):
   
   | Flag ID | Key                     | Deleted at (UTC)     | Deleted by  |
   |---------|-------------------------|----------------------|-------------|
   | 1001    | example-banner          | 2026-08-13 15:12     | Jane D.     |
   | 1002    | example-checkout-test   | 2026-08-09 21:48     | John S.     |
   
   Methodology: walked the activity log for the 25 most-recently-created soft-deleted flags.
   The step 2 query hit its 100-row cap, so the project may have more soft-deleted flags than that.
   The other 75 returned candidates were created before late June 2026 and were not checked.
   Want me to walk the rest?
   

関連ツール

• posthog:execute-sql：手順 2 で system.feature_flags を対象に、ソフト削除された候補を列挙するために使用します
• posthog:feature-flags-activity-retrieve：手順 3 で各候補の実際の削除イベントを見つけるために使用します
• posthog:feature-flag-get-definition：削除されたフラグの内容を確認したいとユーザーが希望した場合に役立ちます

スクリプト

• scripts/strip_deleted_suffix.py：元のフラグキーを復元します。手順 5 を参照してください。