review-hog-authoring

编写 PostHog Review 技能

PostHog Review 是 PostHog 的自动化 PR 审查工具。审查会将 PR 拆分成多个片段，然后针对每个片段，并行运行所有已启用的视角（独立的专家视角），之后执行一次盲点检查（根据各视角的发现进行最后一轮检查），最后使用一个验证标准技能评判每个仍然成立的候选发现——只有通过的发现才会发布到拉取请求中。审查结果发布后，解决阶段会重新检查 PR 中尚未解决的审查讨论串，并使用一个解决标准技能逐一评判——值得处理且安全的请求会在 PR 分支上落实，并为每个讨论串回复。

这四种类型都是团队 LLMSkill 记录，审查 Agent 会在运行时通过 MCP 获取这些记录。PostHog 提供规范版本；本技能是编写自定义版本的指南。本技能本身在团队级别；是否_运行_则是每位用户在 收件箱 → 代码审查中的设置。

类型	名称约定	每位用户的数量限制	规范示例
审查视角	review-hog-perspective-<slug>	可启用多个，且至少有一个保持启用	review-hog-perspective-logic-correctness
盲点检查	review-hog-blind-spots-<slug>	有且仅有一个处于启用状态；选择时会替换	review-hog-blind-spots-general
验证标准	review-hog-validation-<slug>	有且仅有一个处于启用状态；选择时会替换	review-hog-validation-criteria
解决标准	review-hog-resolution-<slug>	有且仅有一个处于启用状态；选择时会替换	review-hog-resolution-criteria

编写流程

1. 熟悉背景。 使用 PostHog MCP 技能工具，对团队的 review-hog-* 技能执行 skill-list，并对你要编写的类型（见上表）执行 skill-get，获取其规范技能——它是结构和语气的参考。为了了解不同视角，快速浏览所有现有 review-hog-perspective-* 的描述，确保新视角不会重复已有启用视角负责的内容（重叠部分之后会去重，但会浪费评审轮次）。
2. 访谈用户。 询问技能应聚焦什么，并基于你在第 1 步中看到的内容，以及在有帮助时基于项目本身，提供当前技能集尚未覆盖的几个具体方向。选定方向之前不要开始编写。
3. 起草正文，遵循下方针对各类型的指引。将其写成聚焦的指令集，让评审 Agent 能在一轮中检查一个代码块，而不是写成一篇长文。
4. 使用 posthog:skill-create 亲自创建技能——实际创建团队的 LLMSkill 行；绝不要只把正文交给用户复制粘贴。按上文约定传入准确名称（小写 slug）、一段话的 description，说明该视角／扫描／标准的作用，以及正文。名称前缀就是完整身份标识——Code review 选项卡和评审运行都通过它发现技能。技能工具没有 category 参数，也无需设置：后端会自行标记 review_hog 分组类别（它只影响 Skills 页面上的分组），不要浪费轮次去设置或验证。若用户需要修改，使用 posthog:skill-update 迭代。创建时请从头编写，不要复制规范技能后再编辑：复制会继承预置元数据，而规范技能同步时可能覆盖或清理这些元数据。
5. 告知用户如何启用。 自定义技能对用户而言初始为未启用状态：
   • 视角——在 Inbox → Code review → Perspectives 中将其切换为启用（在启用前会显示为禁用；必须至少保留一个启用的视角）。
   • 盲点检查／验证标准／解决标准——在对应区域中选中该技能；每次只能运行一个，因此选择它会替换当前技能，但仅影响他们自己的评审。 评审在运行开始时会固定技能版本，因此评审中途的编辑会从下一次运行开始生效。

编写评审视角

正文用于指导专家对一个 PR 代码块进行一轮评审。结构应与规范的逻辑正确性技能一致：

• 负责范围——用一句话说明此视角负责什么；报告范围内的所有问题，其余内容交由其他视角处理。
• 检查重点——列出少量具体检查项，每项都应是 Agent 能针对代码块逐一核查的具体内容（例如“拆分了必须共同提交的写入操作的事务边界”），而非抽象的品质要求（例如“确保正确性”）。
• 范围边界——指出相邻关注点分别由哪个视角负责，此视角必须避免涉及这些内容。
• 问题标准——可发布的问题必须指出具体触发条件和具体后果；最后以完成标准收尾（“完成条件：每个变更文件都已针对每项检查重点标记或排除”）。

评审框架已向 Agent 说明流程机制——并行视角、后续去重、严重级别、非测试文件规则——因此技能只需定义视角；重复框架规则会冲淡重点。

编写盲点检查

正文会指导最终检查：在每个已启用的视角完成一轮审查后运行。它以已覆盖的发现为依据（提示词会列出哪些视角参与了审查以及它们发现了什么），因此正文应说明如何利用这些信息：已覆盖的发现标明了注意力已经投向哪些地方，而检查的价值在于填补空白——错误路径、未处理的输入、跨文件交互、各类假设。检查不应局限于某一专业领域；没有发现也好过凑数。自定义检查可以缩小或重新调整搜索重点（例如，针对团队反复踩坑的领域）。

编写验证标准

正文会定义每条候选发现发布前都要依据的采纳或舍弃标准。默认原则是精确率优先于召回率——带来噪声的审查器会被静音——因此要明确：什么样的发现真实存在且值得作者关注（影响用户的正确性、安全性、数据丢失、契约破坏、性能问题）；哪些发现应舍弃（过度设计、猜测、防御性多疑、不可触达的边界情况、风格问题）；以及如何处理确实存在的不确定性（默认：舍弃）。自定义标准可以调整严格程度或重新分配关注重点，但仍应要求以当前代码库中的证据为依据，而不是凭感觉。

编写解决标准

正文会定义解决阶段处理 PR 中每条未解决审查讨论时所采用的标准：值得实现（确实能带来改进、PR 应当纳入，且属于其变更范围）以及适合在无人监督下安全实现（影响范围小、不更改契约或 API、不进行跨领域重写，并且可在本地验证）。要明确哪些内容会被实现，哪些内容会给出有理有据的拒绝（过度设计的要求、范围蔓延、仅涉及风格的反复修改、通过后续工作更适合处理的请求），以及哪些情况需要升级交由人工处理。底层框架负责强制执行不可逾越的底线——机器人绝不会解决人工撰写的讨论，升级处理不会解决讨论，回复始终会解释决定——因此，自定义技能可以提高标准，或重新调整哪些事项值得处理，但绝不能降低这些底线。