用途：为 PostHog 仓库编写或修改 ClickHouse 迁移时提供规范，详细模式见 posthog/clickhouse/migrations/AGENTS.md。
主要能力与规则：迁移以 operations 列表定义，使用 run_sql_with_exceptions 配置 node_roles、sharded（分片表为 True）、is_alter_on_replicated_table（副本表 ALTER 为 True）。节点角色只能取 connection.py 中 NodeRole 枚举值（ALL、DATA、INGESTION_EVENTS、INGESTION_SMALL、INGESTION_MEDIUM、ENDPOINTS、LOGS、APM、AI_EVENTS、AUX、BATCH_EXPORTS、OPS、SESSIONS），按拥有该对象的集群选择，而非仅看类型。写入前须用 ClickHouse MCP 在 dev、prod-us、prod-eu 核实表位置与命名。预聚合/汇总通常放在卫星集群，经 DATA 上的 Distributed 表读取。
关键约束：禁止 ON CLUSTER；始终用 IF EXISTS/IF NOT EXISTS；同迁移内重建副本表用 DROP TABLE IF EXISTS ... SYNC；有 on_cluster 参数一律设 False；不要自己写 DROP COLUMN 迁移；不要删除重建 kafka_events_json_ws / events_json_ws_mv；列上不要写 CODEC(ZSTD(1))。
PR 范围：含迁移的 PR 必须仅含迁移文件、其依赖 SQL 定义及直接测试，不能混入功能代码。本地对齐：每个迁移创建的表也须存在于本地 dev；云守卫基于 posthog.run_mode（如 run_mode().is_deployed_cloud），不可直接比较 settings.CLOUD_DEPLOYMENT，新表 SQL 函数要加入 schema.py 对应元组。
HCL 声明式 schema：受管角色新增表须同步更新 posthog/clickhouse/hcl，并运行 bash $HCL/gen-golden.sh && bash $HCL/gen-sql.sh，再 bash $HCL/check.sh，否则 CI 报 DRIFT。测试时可删除 infi_clickhouse_orm_migrations 表中的记录以重跑迁移。其他细节（如 Kafka 参数、字典凭据）参见原文。