在实现新功能或审查 PR 时用 PostHog…

为新增或变更的功能加上 PostHog 功能开关，实现按比例/用户/分组的安全灰度发布，并完成 SDK 初始化与环境变量配置。

适用场景

解决思路

1. STEP 1：分析代码库并识别平台。查看依赖文件（package.json、pubspec.yaml、Podfile、Package.swift、requirements.txt、go.mod、Gemfile、composer.json、mix.exs 等）判断语言与框架；查看锁文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、pubspec.lock、Podfile.lock、Package.resolved、mix.lock）判断包管理器；检查是否已有 PostHog 初始化（SDK 初始化、环境变量等），若已安装并初始化则跳到 STEP 3。
2. STEP 2：调研埋点方式（若 PostHog 已配置则跳过）。2.1 在下方参考文件中找到与识别平台匹配的文件——它是 SDK 初始化、开关求值方法和框架特定模式的权威来源，立即阅读。2.2 若无匹配参考文件，则回退到通用知识与网络搜索，以 posthog.com/docs 作为主要搜索来源。
3. STEP 3：创建或查找功能开关。检查是否连接了 PostHog MCP server；若可用，用其工具搜索用户想埋点的已有开关，或创建新开关。若无 MCP server，则指导用户在 PostHog 控制台创建开关。
4. STEP 4：规划发布条件。确定灰度策略（百分比灰度、用户定向、分组定向等），并规划功能开关在代码中如何门控新功能。
5. STEP 5：埋点功能。按平台特定参考模式添加功能开关代码；尽可能使用服务端求值以避免 UI 闪烁；不要改动现有文件的根本架构，只做最小且有针对性的新增；写入文件前必须先读取该文件。
6. STEP 6：配置环境变量。检查项目是否已配置 PostHog 环境变量（如 .env、.env.local 或框架特定 env 文件），若已有有效值则跳过此步。若缺少 PostHog project token，用 PostHog MCP server 的 projects-get 工具获取项目的 api_token；若返回多个项目，询问用户使用哪个；若 MCP server 未连接或未认证，则向用户索取 PostHog project token。对于 PostHog host URL：查看 projects-get MCP 响应中的 region 字段——US 对应 https://us.i.posthog.com，EU 对应 https://eu.i.posthog.com；若 MCP 响应或现有项目配置中无 region，则询问用户：“Are you on PostHog US Cloud or EU Cloud?”，不要默认 US Cloud。按框架命名约定将这些值写入合适的 env 文件，并在代码中引用这些环境变量而非硬编码。
7. 参考文件：按平台选择对应文件（react.md、react-native.md、web.md、nodejs.md、python.md、django.md、flask.md、php.md、laravel.md、ruby.md、ruby-on-rails.md、go.md、java.md、rust.md、dotnet.md、elixir.md、android.md、ios.md、usage.md、flutter.md、api.md、next-js.md），以及 adding-feature-flag-code.md、best-practices.md、COMMANDMENTS.md。每个平台参考文件包含 SDK 特定的安装、开关求值和代码示例；若未列出则用 API 参考作为回退。
8. 关键原则：始终用环境变量存放 PostHog key，绝不硬编码；在现有逻辑旁新增功能开关代码，不替换或重构现有代码；默认使用布尔开关，除非用户明确要求多变量开关；尽可能使用服务端开关求值以避免 UI 闪烁。

适用边界 · 注意事项

• 未使用 PostHog 或不愿引入 PostHog 作为功能开关/分析服务的项目
• 无法接受在代码中新增 PostHog SDK 依赖或环境变量的场景