instrument-feature-flags

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add PostHog feature flags

添加PostHog功能标志

Use this skill to add PostHog feature flags that gate new or changed functionality. Use it after implementing features or reviewing PRs to ensure safe rollouts with feature flag controls. If PostHog is not yet installed, this skill also covers initial SDK setup. Supports any platform or language.

Supported platforms: React, Next.js, React Native, Web (JavaScript), Node.js, Python, PHP, Ruby, Go, Java, Rust, .NET, Elixir, Android, iOS, Flutter, and the REST API.

使用此技能添加PostHog功能标志，以管控新增或修改的功能。在完成功能开发或审核PR后使用该技能，借助功能标志控制确保安全发布。如果尚未安装PostHog，此技能还涵盖初始SDK设置。支持任意平台或语言。

支持的平台：React、Next.js、React Native、Web（JavaScript）、Node.js、Python、PHP、Ruby、Go、Java、Rust、.NET、Elixir、Android、iOS、Flutter以及REST API。

Instructions

操作步骤

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

Look for dependency files (package.json, requirements.txt, go.mod, Gemfile, composer.json, etc.) to determine the language and framework.
Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) to determine the package manager.
Check for existing PostHog setup (SDK initialization, env vars, etc.). If PostHog is already installed and initialized, skip to STEP 3.

STEP 2: Research instrumentation. (Skip if PostHog is already set up.) 2.1. Find the reference file below that matches the detected platform — it is the source of truth for SDK initialization, flag evaluation methods, and framework-specific patterns. Read it now. 2.2. If no reference matches, fall back to your general knowledge and web search. Use posthog.com/docs as the primary search source.

STEP 3: Create or find the feature flag.

Check if a PostHog MCP server is connected. If available, use its tools to search for an existing feature flag the user wants to instrument, or create a new one.
If no MCP server is available, instruct the user to create the flag in the PostHog dashboard.

STEP 4: Plan release conditions.

Determine the rollout strategy (percentage rollout, user targeting, group targeting, etc.).
Plan how the feature flag will gate the new functionality in code.

STEP 5: Instrument the feature.

Add the feature flag code following the platform-specific reference patterns.
Use server-side evaluation when possible to avoid UI flicker.
Do not alter the fundamental architecture of existing files. Make additions minimal and targeted.
You must read a file immediately before attempting to write it.

STEP 6: Set up environment variables.

Check if the project already has PostHog environment variables configured (e.g. in
```
.env
```
,
```
.env.local
```
, or framework-specific env files). If valid values already exist, skip this step.
If the PostHog API key is missing, use the PostHog MCP server's
```
projects-get
```
tool to retrieve the project's
```
api_token
```
. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
For the PostHog host URL, use
```
https://us.i.posthog.com
```
for US Cloud or
```
https://eu.i.posthog.com
```
for EU Cloud.
Write these values to the appropriate env file using the framework's naming convention.
Reference these environment variables in code instead of hardcoding them.

请按以下顺序执行步骤：

步骤1：分析代码库并检测平台。

查找依赖文件（package.json、requirements.txt、go.mod、Gemfile、composer.json等）以确定语言和框架。
查找锁定文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb）以确定包管理器。
检查是否已有PostHog设置（SDK初始化、环境变量等）。如果PostHog已安装并初始化，跳至步骤3。

步骤2：研究集成方法。（若已设置PostHog则跳过此步骤。） 2.1. 找到与检测到的平台匹配的下方参考文件——它是SDK初始化、标志评估方法和框架特定模式的权威来源。请立即阅读。 2.2. 如果没有匹配的参考文件，则依靠你的通用知识和网络搜索。以posthog.com/docs作为主要搜索来源。

步骤3：创建或查找功能标志。

检查是否已连接PostHog MCP服务器。如果可用，使用其工具搜索用户想要集成的现有功能标志，或创建新标志。
如果没有MCP服务器，指导用户在PostHog控制台中创建标志。

步骤4：规划发布条件。

确定发布策略（按百分比发布、用户定向、群组定向等）。
规划功能标志在代码中如何管控新功能。

步骤5：集成功能标志。

遵循平台特定的参考模式添加功能标志代码。
尽可能使用服务端评估以避免UI闪烁。
不要修改现有文件的基础架构。仅做最小化、针对性的添加。
在尝试写入文件前，必须先读取该文件。

步骤6：设置环境变量。

检查项目是否已配置PostHog环境变量（例如在
```
.env
```
、
```
.env.local
```
或框架特定的环境文件中）。如果已有有效值，跳过此步骤。
如果缺少PostHog API密钥，使用PostHog MCP服务器的
```
projects-get
```
工具获取项目的
```
api_token
```
。如果返回多个项目，请询问用户使用哪个项目。如果未连接MCP服务器或未通过认证，则请用户提供其PostHog项目API密钥。
对于PostHog主机URL，美国云使用
```
https://us.i.posthog.com
```
，欧盟云使用
```
https://eu.i.posthog.com
```
。
按照框架的命名约定将这些值写入合适的环境文件。
在代码中引用这些环境变量，而非硬编码。

Reference files

参考文件

```
references/react.md
```
- React feature flags installation - docs
```
references/react-native.md
```
- React native feature flags installation - docs
```
references/web.md
```
- Web feature flags installation - docs
```
references/nodejs.md
```
- Node.js feature flags installation - docs
```
references/python.md
```
- Python feature flags installation - docs
```
references/php.md
```
- Php feature flags installation - docs
```
references/ruby.md
```
- Ruby feature flags installation - docs
```
references/go.md
```
- Go feature flags installation - docs
```
references/java.md
```
- Java feature flags installation - docs
```
references/rust.md
```
- Rust feature flags installation - docs
```
references/dotnet.md
```
- .net feature flags installation - docs
```
references/elixir.md
```
- Elixir feature flags installation - docs
```
references/android.md
```
- Android feature flags installation - docs
```
references/ios.md
```
- Ios feature flags installation - docs
```
references/flutter.md
```
- Flutter feature flags installation - docs
```
references/api.md
```
- API feature flags installation - docs
```
references/next-js.md
```
- Next.js - docs
```
references/adding-feature-flag-code.md
```
- Adding feature flag code - docs
```
references/best-practices.md
```
- Best practices for production-ready flags - docs

Each platform reference contains SDK-specific installation, flag evaluation, and code examples. Find the one matching the user's stack. If unlisted, use the API reference as a fallback.

```
references/react.md
```
- React功能标志集成 - 文档
```
references/react-native.md
```
- React Native功能标志集成 - 文档
```
references/web.md
```
- Web功能标志集成 - 文档
```
references/nodejs.md
```
- Node.js功能标志集成 - 文档
```
references/python.md
```
- Python功能标志集成 - 文档
```
references/php.md
```
- PHP功能标志集成 - 文档
```
references/ruby.md
```
- Ruby功能标志集成 - 文档
```
references/go.md
```
- Go功能标志集成 - 文档
```
references/java.md
```
- Java功能标志集成 - 文档
```
references/rust.md
```
- Rust功能标志集成 - 文档
```
references/dotnet.md
```
- .NET功能标志集成 - 文档
```
references/elixir.md
```
- Elixir功能标志集成 - 文档
```
references/android.md
```
- Android功能标志集成 - 文档
```
references/ios.md
```
- iOS功能标志集成 - 文档
```
references/flutter.md
```
- Flutter功能标志集成 - 文档
```
references/api.md
```
- API功能标志集成 - 文档
```
references/next-js.md
```
- Next.js - 文档
```
references/adding-feature-flag-code.md
```
- 添加功能标志代码 - 文档
```
references/best-practices.md
```
- 生产就绪标志的最佳实践 - 文档

每个平台参考文件包含特定SDK的安装、标志评估和代码示例。找到与用户技术栈匹配的文件。如果未列出，则使用API参考作为备选。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add feature flag code alongside existing logic. Don't replace or restructure existing code.
Boolean flags first: Default to boolean flag checks unless the user specifically asks for multivariate flags.
Server-side when possible: Prefer server-side flag evaluation to avoid UI flicker.

环境变量：始终使用环境变量存储PostHog密钥。绝不硬编码。
最小化修改：在现有逻辑旁添加功能标志代码。不要替换或重构现有代码。
优先布尔标志：除非用户明确要求多变量标志，默认使用布尔标志检查。
尽可能使用服务端评估：优先选择服务端标志评估以避免UI闪烁。