在实现新功能或审查 PR 后为代码添加 PostHog…

当需要在新功能或改动的代码中捕获有意义的用户行为（转化、流失、登录、错误）时，按框架集成 PostHog 埋点。

适用场景

解决思路

1. STEP 1：分析代码库并检测平台。查看依赖文件（package.json、pubspec.yaml、Podfile、Package.swift、requirements.txt、Gemfile、composer.json、go.mod、mix.exs 等）确定框架和语言；查看 lockfile（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、pubspec.lock、Podfile.lock、Package.resolved、mix.lock）确定包管理器；检查是否已有 PostHog 设置，若已安装并初始化则跳到 STEP 5。
2. STEP 2：研究集成（若 PostHog 已设置则跳过）。2.1 找到与检测到的框架匹配的参考文件——它是 SDK 初始化、provider 设置和事件捕获模式的唯一事实来源，立即阅读。2.2 若无匹配参考，回退到通用知识和网络搜索，以 posthog.com/docs 作为主要搜索来源。
3. STEP 3：安装 PostHog SDK（若已设置则跳过）。为检测到的平台添加 PostHog SDK 包，不要手动编辑 package.json，使用包管理器的安装命令。
4. STEP 4：初始化 PostHog（若已设置则跳过）。按框架参考文件确定初始化的位置和方式，各框架差异很大（例如 Next.js 15.3+ 用 instrumentation-client.ts，Django 用 AppConfig.ready()，Flask 用 create_app()）。
5. STEP 5：规划事件追踪。从项目文件列表中选出 10 到 15 个可能具有业务价值（尤其是转化和流失事件）的文件；查找与登录相关的文件用于识别用户，以及错误处理相关文件；查找已有的 posthog.capture() 代码，记录事件命名格式，不要重复已有事件，只做补充；只追踪动作，不追踪页面浏览（页面浏览可自动捕获），转化漏斗顶部的 "viewed" 类事件可例外；如果项目包含任何可埋点的服务端代码（API 路由、server actions、webhook 处理器、支付/结账完成、认证端点），则服务端事件是必需的。
6. STEP 6：实现事件捕获。为每个规划的事件添加带有用属性的 posthog.capture() 调用；如果文件已有其他工具或服务的集成代码，不要覆盖或删除，把 PostHog 代码放在其下方；不要改变现有文件的根本架构，改动要最小且有针对性；写入文件前必须先读取该文件。
7. STEP 7：识别用户。在客户端登录和注册事件时添加 PostHog identify() 调用，使用登录和注册表单的内容在提交时识别用户；如果前后端都存在，用 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 头把客户端会话和 distinct ID 传给服务端代码，服务端确保事件具有匹配的 distinct ID。
8. STEP 8：添加错误追踪。在相关文件中添加 PostHog 异常捕获错误追踪，尤其是关键用户流程和 API 边界附近。
9. STEP 9：设置环境变量。检查项目是否已配置 PostHog 环境变量（如 .env、.env.local 或框架特定的 env 文件），若已有有效值则跳过此步；若缺少 PostHog 项目 token，使用 PostHog MCP 服务器的 projects-get 工具获取项目的 api_token，若返回多个项目则询问用户使用哪个，若 MCP 服务器未连接或未认证则改为询问用户其 PostHog 项目 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 文件；在代码中引用这些环境变量而非硬编码。
10. STEP 10：验证并清理。检查项目错误，查看 package.json 中的类型检查或构建脚本；确保创建的任何组件确实被使用；运行 package.json 中的 linter 或 prettier 类脚本，但仅针对本次会话中编辑或创建的文件，绝不要在整个项目代码库上运行格式化或 lint。
11. 关键原则：始终使用环境变量存放 PostHog 密钥，绝不硬编码；最小改动，把 PostHog 代码与现有集成并列添加，不替换或重构现有代码；严格遵循框架参考文件的初始化和捕获模式。

适用边界 · 注意事项

• 项目已安装并初始化 PostHog 时，跳过 STEP 2-4（研究集成、安装 SDK、初始化）
• 项目已配置有效的 PostHog 环境变量时，跳过 STEP 9 的环境变量设置
• 不要追踪页面浏览（可自动捕获），除非是转化漏斗顶部的 "viewed" 类事件