survey-sdk-audit

Surveys SDK 機能監査スキル

surveyVersionRequirements.ts を対象に、PostHog SDK 全体でのサーベイ機能サポートを監査するときにこのスキルを使用します。

監査する機能: $ARGUMENTS

サーベイ機能の作業については、サーベイ変更へのコントリビュートを参照してください。 リポジトリをチェックアウトせずに顧客の診断を行う場合は、公開されている debugging-surveys スキルを使用してください。

セットアップ確認（最初に実行）

開始する前に、SDK のパスにアクセスできることを確認します。各パスに対して ls を実行します:

• $POSTHOG_JS_PATH
• $POSTHOG_IOS_PATH
• $POSTHOG_ANDROID_PATH
• $POSTHOG_FLUTTER_PATH

いずれかのパスが空であるか存在しない場合は、ユーザーに尋ねてください: 「お使いのマシン上の [SDK リポジトリ] へのパスが必要です。どこにありますか？」

すべてのパスが揃ったら、.claude/settings.local.json に追加して今後のセッションのために保存しておくかどうかをユーザーに尋ねてください:

{
  "env": {
    "POSTHOG_JS_PATH": "/path/to/posthog-js",
    "POSTHOG_IOS_PATH": "/path/to/posthog-ios",
    "POSTHOG_ANDROID_PATH": "/path/to/posthog-android",
    "POSTHOG_FLUTTER_PATH": "/path/to/posthog-flutter"
  },
  "permissions": {
    "allow": [
      "Read(/path/to/posthog-js/**)",
      "Read(/path/to/posthog-ios/**)",
      "Read(/path/to/posthog-android/**)",
      "Read(/path/to/posthog-flutter/**)",
      "Grep(/path/to/posthog-js/**)",
      "Grep(/path/to/posthog-ios/**)",
      "Grep(/path/to/posthog-android/**)",
      "Grep(/path/to/posthog-flutter/**)"
    ]
  }
}

注意: Read および Grep のパーミッションにより、Claude は毎回プロンプトを出さずにこれらの外部 SDK リポジトリにアクセスできます。

コマンドでの SDK パスの使用

重要: $POSTHOG_JS_PATH のような環境変数は、Bash ツールのコマンドでは確実に展開されません。

bash コマンドの代わりに、以下を優先してください:

• Read ツールを使用してファイルを読み取る（パーミッションで動作します）
• Grep ツールを使用してファイルを検索する（パーミッションで動作します）

どうしても bash を使用する必要がある場合は、まず変数を展開してください:

echo $POSTHOG_JS_PATH

その後、後続のコマンドで echo されたパスをそのまま使用してください。

課題の可視性

サーベイ SDK の機能パリティには中央のトラッキング issue がありません。可視性はリポジトリレベルで担保されます: surveyVersionRequirements.ts が未サポートの SDK をその issue にリンクし、新しい各 issue は ## Related セクションを介して兄弟 issue に相互リンクします（以下の issue テンプレートを参照）。

SDK パスと変更履歴

SDK	コードパス	変更履歴
posthog-js (browser)	$POSTHOG_JS_PATH/packages/browser	$POSTHOG_JS_PATH/packages/browser/CHANGELOG.md
posthog-react-native	$POSTHOG_JS_PATH/packages/react-native	$POSTHOG_JS_PATH/packages/react-native/CHANGELOG.md
posthog-ios	$POSTHOG_IOS_PATH	$POSTHOG_IOS_PATH/CHANGELOG.md
posthog-android	$POSTHOG_ANDROID_PATH	$POSTHOG_ANDROID_PATH/CHANGELOG.md
posthog-flutter	$POSTHOG_FLUTTER_PATH	$POSTHOG_FLUTTER_PATH/CHANGELOG.md

Flutter のネイティブ依存関係

Flutter はネイティブ SDK をラップします。以下の依存関係のバージョンを確認してください:

• iOS: $POSTHOG_FLUTTER_PATH/ios/posthog_flutter.podspec（s.dependency 'PostHog' を探す）
• Android: $POSTHOG_FLUTTER_PATH/android/build.gradle（posthog-android 依存関係を探す）

監査プロセス

ステップ 1: 機能を理解する

surveyVersionRequirements.ts の check 関数を見て、どのフィールド/条件がこの機能をトリガーするかを理解します:

• s.conditions?.deviceTypes → "deviceTypes" を検索
• s.appearance?.fontFamily → "fontFamily" を検索
• s.conditions?.urlMatchType → "urlMatchType" を検索

ステップ 2: まず変更履歴を検索する

# Search changelog for the feature keyword
grep -n -i "KEYWORD" /path/to/CHANGELOG.md

見つかった場合は、周辺の行を読んでバージョン番号を取得します。

ステップ 3: 変更履歴にない場合はコードを検索する

# Find commits that added the keyword (use -S for exact string match)
cd /path/to/sdk && git log --oneline --all -S "KEYWORD" -- "*.swift" "*.kt" "*.ts" "*.tsx"

# Then find the first version tag containing that commit
git tag --contains COMMIT_HASH | sort -V | head -3

ステップ 4: Flutter の場合は、ネイティブ依存関係がいつ更新されたかを確認する

# Find when Flutter started requiring iOS version X.Y.Z
cd $POSTHOG_FLUTTER_PATH && git log --oneline -p -- "ios/posthog_flutter.podspec" | grep -B10 "X.Y.Z"

# Get the Flutter version for that commit
git tag --contains COMMIT_HASH | sort -V | head -1

ステップ 5: 機能が実際に動作することを確認する（型だけでなく）

重要: データモデルにフィールドがあるからといって、その機能が実装されているとは限りません。実際のフィルタリング/マッチングのロジックを確認する必要があります。

SDK のレンダリング機能:

• posthog-js (ブラウザ): 組み込みのアンケート表示 (HTML/CSS ポップアップ)
• posthog-react-native: 組み込みのアンケート表示 (packages/react-native/src/surveys/ 内の React Native コンポーネント)
• posthog-ios: 組み込みのアンケート表示 (PostHog/Surveys/ 内の SwiftUI ビュー — SurveySheet.swift、QuestionTypes.swift、MultipleChoiceOptions.swift)
• posthog-android: 組み込み UI なし — 純粋なデリゲートパターン。開発者が自身でレンダリングするための表示モデル (PostHogDisplaySurvey、PostHogDisplayChoiceQuestion など) を公開します。レンダリングのみの機能には issue: false を使用してください。
• posthog-flutter: 組み込みのアンケート表示 (lib/src/surveys/widgets/ 内の Flutter ウィジェット — survey_bottom_sheet.dart、choice_question.dart)

組み込みのレンダリングがある SDK の場合、機能は実際にレンダリングコード内で実装されている必要があり、データモデル上のフィールドとして存在するだけでは不十分です。Android (デリゲートのみ) の場合、表示モデルにフィールドを公開するだけで十分です — コメントを付けて issue: false としてマークしてください。

アンケートのフィルタリングロジックを確認すべき主要ファイル:

• posthog-js (ブラウザ): $POSTHOG_JS_PATH/packages/browser/src/extensions/surveys/surveys-extension-utils.tsx - canActivateRepeatedly、getSurveySeen、hasEvents などのユーティリティ関数
• posthog-js (ブラウザ): $POSTHOG_JS_PATH/packages/browser/src/extensions/surveys.tsx - メインのアンケートロジック
• posthog-react-native: $POSTHOG_JS_PATH/packages/react-native/src/surveys/getActiveMatchingSurveys.ts - メインのフィルタリングロジック
• posthog-react-native: $POSTHOG_JS_PATH/packages/react-native/src/surveys/surveys-utils.ts - canActivateRepeatedly、hasEvents などのユーティリティ関数
• posthog-ios: $POSTHOG_IOS_PATH/PostHog/Surveys/PostHogSurveyIntegration.swift → getActiveMatchingSurveys() メソッド、canActivateRepeatedly コンピューテッドプロパティ
• posthog-android: $POSTHOG_ANDROID_PATH/posthog-android/src/main/java/com/posthog/android/surveys/PostHogSurveysIntegration.kt → getActiveMatchingSurveys() メソッド、canActivateRepeatedly() 関数

SDK 間で比較すべき主要なユーティリティ関数:

• canActivateRepeatedly - 一度表示された後にアンケートを再度表示できるかどうかを判定します
• hasEvents - アンケートにイベントベースのトリガーがあるかどうかを確認します
• getSurveySeen - ユーザーがすでにアンケートを表示したかどうかを確認します

落とし穴の例 1: iOS と Android の両方で Survey モデルに linkedFlagKey がありますが、どちらも linkedFlagVariant のチェックを実装していません。flags[key] === variant を比較するのではなく、isFeatureEnabled(key) (ブール値) を呼び出すだけです。

落とし穴の例 2: ブラウザの canActivateRepeatedly は 3 つの条件をチェックします: (1) イベントの repeatedActivation、(2) schedule === 'always'、(3) アンケートが進行中。モバイル SDK は条件 (1) のみをチェックし、schedule チェックを完全に欠いている可能性があります。

アンケートのレンダリングロジックを確認すべき主要ファイル:

• posthog-js (ブラウザ): $POSTHOG_JS_PATH/packages/browser/src/extensions/surveys/surveys-extension-utils.tsx - getDisplayOrderQuestions()、getDisplayOrderChoices()
• posthog-react-native: $POSTHOG_JS_PATH/packages/react-native/src/surveys/surveys-utils.ts - getDisplayOrderQuestions()、getDisplayOrderChoices()
• posthog-ios: $POSTHOG_IOS_PATH/PostHog/Surveys/QuestionTypes.swift - SingleChoiceQuestionView、MultipleChoiceQuestionView、$POSTHOG_IOS_PATH/PostHog/Surveys/SurveySheet.swift - 質問の順序
• posthog-android: 組み込み UI なし — $POSTHOG_ANDROID_PATH/posthog/src/main/java/com/posthog/surveys/PostHogDisplaySurveyQuestion.kt と PostHogDisplaySurveyAppearance.kt での表示モデルの公開のみを確認してください
• posthog-flutter: $POSTHOG_FLUTTER_PATH/lib/src/surveys/widgets/survey_bottom_sheet.dart - 質問の順序、$POSTHOG_FLUTTER_PATH/lib/src/surveys/widgets/choice_question.dart - 選択肢のレンダリング

確認すべきポイント:

• フィールドは JSON からモデルにパースされていますか？（必要だが十分ではない）
• フィールドは getActiveMatchingSurveys() のようなフィルタリングロジックで使用されていますか？
• レンダリング機能の場合: フィールドは組み込み UI で実際に使用されていますか？（データモデルだけでなく、レンダリングコードを確認してください）
• ロジックはリファレンス実装の動作と一致していますか？
• テストファイルは実装としてカウントされません

リファレンス実装

posthog-js ブラウザが正規の実装です - すべての機能を備えており、あるべき動作の信頼できる情報源です。

機能を監査する際は、次の手順で進めます。

1. まず $POSTHOG_JS_PATH/packages/browser/src/extensions/surveys.ts を確認して、完全で正しい動作を理解します
2. 次にモバイル SDK を posthog-react-native（$POSTHOG_JS_PATH/packages/react-native/src/surveys/getActiveMatchingSurveys.ts）と比較します。これがモバイル固有の実装のリファレンスです

Web 専用機能とクロスプラットフォーム機能

一部の機能は Web でのみ意味を持ちます。

• URL ターゲティング: ネイティブアプリには「現在の URL」という概念がありません → すべてのモバイルで issue: false
• CSS セレクターターゲティング: ネイティブアプリには DOM がありません → すべてのモバイルで issue: false
• CSS によるカスタムフォント: ネイティブ実装が必要になるか、適用できない可能性があります

出力形式

各機能について、次を生成します。

{
    feature: 'Feature Name',
    sdkVersions: {
        'posthog-js': 'X.Y.Z',
        'posthog-react-native': 'X.Y.Z',  // or omit if unsupported
        'posthog-ios': 'X.Y.Z',
        'posthog-android': 'X.Y.Z',
        'posthog_flutter': 'X.Y.Z',  // add comment: first version to require native SDK >= X.Y
    },
    unsupportedSdks: [
        { sdk: 'sdk-name', issue: 'https://github.com/PostHog/repo/issues/123' },  // needs implementation
        { sdk: 'sdk-name', issue: false },  // not applicable (e.g., web-only feature)
    ],
    check: (s) => ...,
}

GitHub Issue の作成

重要: 新しい Issue を作成する前に、必ず既存の Issue を検索してください。

# Search in the SDK-specific repo
gh issue list --repo PostHog/posthog-ios --search "FEATURE_KEYWORD" --state all --limit 20
gh issue list --repo PostHog/posthog-android --search "FEATURE_KEYWORD" --state all --limit 20
gh issue list --repo PostHog/posthog-flutter --search "FEATURE_KEYWORD" --state all --limit 20

# Also search with broader terms
gh issue list --repo PostHog/posthog-ios --search "survey feature flag" --state all --limit 20

メインリポジトリ PostHog/posthog と SDK 固有のリポジトリの両方で Issue を検索し、どこにも Issue がまだ存在しないことを確認してください。

リポジトリ別のラベル

リポジトリ	サーベイ機能用のラベル
PostHog/posthog-js	feature/surveys
PostHog/posthog-ios	Survey, enhancement
PostHog/posthog-android	Survey, enhancement
PostHog/posthog-flutter	Survey, enhancement

Issue 作成コマンド

# posthog-js (covers browser and react-native)
gh issue create --repo PostHog/posthog-js --label "feature/surveys" --title "..." --body "..."

# posthog-ios
gh issue create --repo PostHog/posthog-ios --label "Survey" --label "enhancement" --title "..." --body "..."

# posthog-android
gh issue create --repo PostHog/posthog-android --label "Survey" --label "enhancement" --title "..." --body "..."

# posthog-flutter
gh issue create --repo PostHog/posthog-flutter --label "Survey" --label "enhancement" --title "..." --body "..."

Issue テンプレート

## 🚨 IMPORTANT

This issue is likely user-facing in the main PostHog app, see [`surveyVersionRequirements.ts`](https://github.com/PostHog/posthog/blob/master/frontend/src/scenes/surveys/surveyVersionRequirements.ts). If you delete or close this issue, be sure to update the version requirements list here.

## Summary

The [SDK] SDK does not support [feature] for surveys.

## Current State

- [What exists, if anything - types, partial implementation, etc.]

## Expected Behavior

[What should happen when this feature is configured]

## Reference Implementation

See posthog-js browser: `packages/browser/src/extensions/surveys.ts`
For mobile-specific patterns, see posthog-react-native: `packages/react-native/src/surveys/getActiveMatchingSurveys.ts`

## Related

- [links to the sibling SDK issues created for the same feature — list the ones that exist at creation time; the rest are backfilled below]

_This issue was generated by Claude using the `/survey-sdk-audit` skill._

兄弟リンクの後埋め

Issue は一度に 1 つずつ作成されるため、先に作成された Issue はまだ存在しない兄弟 Issue にリンクできません。機能のすべての Issue を作成した後、各 Issue の ## Related セクションを後埋めして、すべての Issue がすべての兄弟 Issue にリンクするようにします。

ステップ 1: 現在の本文を一時ファイルに取得します。

gh issue view 123 --repo PostHog/posthog-ios --json body --jq '.body' > /tmp/issue_body.md

ステップ 2: 一時ファイルに対して Edit ツールを使用して兄弟リンクを記入します（プレースホルダーは削除します）。これにより、何かをプッシュする前にユーザーが diff を確認できます。

ステップ 3: 更新をプッシュします。

gh issue edit 123 --repo PostHog/posthog-ios --body-file /tmp/issue_body.md

完了チェックリスト

監査を終える前に、すべてのステップが完了していることを確認してください。

• 機能を理解する - surveyVersionRequirements.ts のチェック関数を読みます
• ブラウザ SDK を確認する - changelog でバージョンを探します（これがリファレンス実装です）
• react-native SDK を確認する - changelog でバージョンを探します
• iOS SDK を確認する - 機能が実際に実装されているか（型だけでなく）を検証します
• Android SDK を確認する - 機能が実際に実装されているか（型だけでなく）を検証します
• Flutter SDK を確認する - ネイティブ依存関係のバージョンを確認します
• 既存の Issue を検索する - 新しいものを作成する前に
• GitHub Issue を作成する - サポートされていない SDK について（適切なラベルを付けて）
• surveyVersionRequirements.ts を更新する - バージョンを修正し、unsupportedSdks に Issue リンクを追加します
• SDK パリティドキュメントを再生成する - pnpm --filter=@posthog/frontend build:survey-sdk-docs を実行して docs/published/docs/surveys/sdk-feature-support.mdx を更新します
• 兄弟リンクを後埋めする - すべての Issue を作成した後、各 Issue の Related セクションを更新して、すべての Issue がすべての兄弟 Issue にリンクするようにします（「兄弟リンクの後埋め」を参照）

よくある落とし穴

1. バージョンを推測しない - 常に変更履歴または git 履歴で確認する
2. 型 ≠ 実装 - データクラスにフィールドがあるからといって、フィルタリングロジックが存在するわけではない
3. モデルのフィールド ≠ 機能のサポート - フィールドが解析されても、意思決定にまったく使われない場合がある（例: linkedFlagKey は存在するが、linkedFlagVariant のチェックが欠けている）
4. テストコード ≠ 本番コード - テストファイルにしかない関数は出荷されない
5. Flutter はネイティブを継承する - その「サポート」は、必要とする iOS/Android SDK のバージョンに依存する
6. 常に既存の issue を先に検索する - 新しい GitHub issue を作成する前に
7. ユーティリティ関数の実装を比較する - canActivateRepeatedly のような関数は SDK ごとにロジックが異なる場合がある。ブラウザが信頼できる情報源である
8. 組み込み UI ≠ デリゲート - iOS、React Native、Flutter には組み込みのサーベイレンダリングがあるが、Android はデリゲートのみ（組み込み UI なし）。表示モデルのフィールドは Android には十分だが（issue: false）、組み込みレンダリングを持つ SDK では、レンダリングコードが実際にそのフィールドを使用する必要がある
9. モデルだけでなくレンダリングコードを確認する - 例: iOS は PostHogDisplayChoiceQuestion で shuffleOptions を公開しているが、SwiftUI の QuestionTypes.swift は選択肢をレンダリングする際にそれを完全に無視している

監査後: スキルの改善

監査を完了したら、学んだことをこのスキルファイルに追加すべきか検討してください:

1. 新たに発見した落とし穴 - 「よくある落とし穴」セクションに追加
2. 新たに特定した主要ファイル - ステップ 5 のファイルパスに追加
3. 比較すべき新しいユーティリティ関数 - 「主要なユーティリティ関数」リストに追加
4. パターンの変更 - SDK 実装の構造が変わった場合は、パスを更新

改善点が見つかった場合は、ユーザーに提案してください:

I found some learnings during this audit that could improve the skill:
- [describe the improvement]

Would you like me to update the skill file?