PostHog在一年内把AI产品的日活跃用户做到了6000+，靠的是一次彻底的架构重构。这篇Thread总结了他们在Agent优先产品工程上学到的四条黄金法则。

法则一：人类能做的，Agent必须也能做

这是最基本的原则。如果人类能用你的产品做某件事，但Agent的工具里没有对应的功能，Agent就不得不停下来让用户自己去做。这打破了"Agent减少完成工作所需时间、注意力和专业知识"的核心价值。

实现方式：PostHog的v2方案是Django端点自动生成OpenAPI spec → 转Zod验证Schema → 产品团队通过YAML手动opt-in每个端点 → 生成最终的TypeScript工具处理器。结果是Agent能通过MCP做人类能做的任何事，即使工具和API端点不是1:1对应的。

法则二：找到Agent已经擅长的语义层

在v1版本里，回答"上周注册量为什么下降了？"需要Agent做4次独立调用：projects-get、insight-get、insight-query（两次）。这些对人类导航UI有意义，但对Agent来说是多余的翻译步骤。

v2里，PostHog让Agent直接用SQL查询数据。一次SQL解决：

SELECT
    toStartOfWeek(timestamp) AS week,
    countIf(event = 'signed_up') AS signups
FROM events
WHERE timestamp >= now() - INTERVAL 2 WEEK
GROUP BY week
ORDER BY week

暴露产品语义层的意义远不止省token——它解锁了创意潜力。给小孩一盒已经粘好的乐高，他们只能做汽车、卡车、飞机。但如果零件是分开的，他们可以组合出摩托车、轮胎秋千、雪橇。

法则三：预加载你知道的东西，让Agent发现其余的

v1的系统Prompt只有四行——"这是PostHog的一些工具，祝你好运"。每个Agent连接后都要浪费时间和token重新发现同样的东西。

v2的改进：连接PostHog MCP的每个Session一开始就知道：

  • PostHog特定分类学（什么是Feature Flag、Experiment等）
  • 他们的SQL语法
  • 关键查询规则（如：总是过滤时间范围）

其余的一切在需要时才拉取。Agent擅长推理，你只需要告诉它"每次Session都需要什么"。

法则四：像对待用户一样对待Agent

AI不像传统软件——同样的输入不一定产生同样的输出。这意味着传统自动化测试不够用了，需要新的方式来捕获错误。

PostHog的实践：

  • CLI优先：测试Agent功能时先用CLI而不是UI，这样和Agent在同一个环境里，能发现同样的错误和摩擦
  • 每周Trace Hour：Review有用户反馈评分的真实Session，抓到自动化测试抓不到的问题（Agent确实回应了但回答是错的）
  • 基于人工Review构建Evals：把人工发现的好/坏case转成评估用例，确保未来模型或Prompt变化不会退化好的行为

技能写作的核心原则

技能文件是弥合"产品能做什么"和"Agent开箱即能用你的工具做什么"之间差距的关键。但人们最大的错误是把技能写成"步骤手册"——太死板，Agent只会机械执行，失去即兴发挥能力。

正确的方式：把技能当成" onboarding一个已经完全合格的新员工"。只包含Agent自己无法发现的内容：

  • 特异知识（内部缩写、命名规范、风格指南）
  • 边界情况（哪些地方容易出问题、如何处理）
  • 判断力和工艺（不只是正确使用产品，而是优质使用）

判断标准：问自己——没有这条，Agent会在哪里出错？比如PostHog的例子：对于Session和Pageview事件，默认使用$pageview，避免使用不一致的事件如"signed in"，因为它们会扭曲数据。没有这条指导，Agent会用用户提到的任何事件，通常是误导性的。