clickhouse-architecture-advisor

clickhouse-architecture-advisor 技能概览

这个技能是做什么的

clickhouse-architecture-advisor 技能帮助你设计 ClickHouse 工作负载，而不只是验证表或查询。它最适合在你需要选择摄取路径、建模可变或迟到数据、决定用 join 还是 dictionary，或者规划一个权衡清晰的时序架构时使用。

最适合的用户和工作负载

clickhouse-architecture-advisor 技能适用于后端开发、分析平台、可观测性、SIEM、产品分析、IoT 遥测以及金融市场数据管道。如果你已经明确业务目标，但需要一个更有依据、比通用提示词更站得住脚的 ClickHouse 架构建议，这个技能就很合适。

它为什么不一样

这个技能关注的是决策，而不是配方。它会明确区分 official、derived 和 field 指导，在有官方 ClickHouse 文档时优先使用，并且会先要求你对工作负载进行分类。这使它在架构评审和 POC 场景下比一次性的查询调优更有价值。

如何使用 clickhouse-architecture-advisor 技能

安装并启用它

使用仓库自带的 skill manager 安装 clickhouse-architecture-advisor 技能，然后在需要做架构选择的上下文里调用它。典型的安装方式如下：

npx skills add ClickHouse/agent-skills --skill clickhouse-architecture-advisor

如果你的环境使用的是其他 skill loader，也请保持相同的 repo 和 skill slug，只需按你的执行器调整命令即可。

提供合适的输入形态

当你提供工作负载形态、数据新鲜度目标、写入速率、查询模式、更新需求，以及保留周期、可重放性或补充 enrich 延迟等约束时，这个技能效果最好。差的提示会说“设计一个 ClickHouse schema”；好的提示会说：

“为 IoT 设备设计一个 ClickHouse 架构：每天 1.2 亿事件、2 秒级新鲜度、支持迟到更新、按小时扫描仪表盘，以及偶尔按设备状态做点查。”

这种细节能让 clickhouse-architecture-advisor 的使用路径选对决策文件，并产出有意义的权衡分析。

先读这些文件

先从 SKILL.md、AGENTS.md 和 metadata.json 读起，了解适用范围、溯源规则以及支持的 ClickHouse 版本。然后在开始自己的设计之前，再阅读 rules/decision-ingestion-strategy.md、rules/decision-partitioning-timeseries.md、rules/decision-join-enrichment.md、rules/decision-late-arriving-upserts.md 和 rules/decision-real-time-preaggregation.md。

把示例当作提示词模板

examples 文件夹是理解 clickhouse-architecture-advisor guide 模式最快的方式。examples/observability-high-throughput.md、examples/finserv-market-surveillance.md 和 examples/siem-security-analytics.md 展示了如何组织工作负载摘要、关键决策和推荐类别。向它提问时尽量沿用这种结构，这样输出才会保持“决策导向”，而不是泛泛而谈。

clickhouse-architecture-advisor 技能常见问题

这只适合高级 ClickHouse 用户吗？

不是。这个技能对需要安全起步方案的初学者也有帮助，但在选错方案代价很高时，它尤其有价值。如果你还在 raw ingestion、MV、dictionary 和反范式化之间做选择，它可以很快帮你缩小范围。

它和普通提示词有什么不同？

普通提示词通常只会生成一个“最可能正确”的架构。clickhouse-architecture-advisor 技能的设计目标是强制进行工作负载分类、标注溯源，并明确写出权衡，这样结果更容易被信任和审查。

什么时候不该用它？

不要把它用在琐碎的 schema 问题、单独的 SQL 语法帮助，或者你已经明确知道自己需要哪一个 ClickHouse 特性的场景里。如果你甚至无法描述工作负载，它也不适合，因为推荐质量高度依赖工作负载形态。

它会替代 clickhouse-best-practices 吗？

不会。clickhouse-architecture-advisor 技能是对 clickhouse-best-practices 的补充，它增加的是架构层面的决策能力。需要规则检查时用 best-practices 技能；需要围绕这些规则做系统设计时，用这个技能。

如何改进 clickhouse-architecture-advisor 技能

给技能能做决策的数据

提升质量最大的方式，是告诉它这个工作负载最难的地方是什么：突发写入、迟到数据、高基数字段、昂贵的 join、保留窗口，或者新鲜度与成本之间的冲突。这些细节能让 clickhouse-architecture-advisor 技能更准确地在 official、derived 和 field 指导之间做选择。

明确你的验收标准

如果你关心 1 秒内新鲜度、低存储成本、可重放性或可审计性，请直接说出来。技能通常能在知道哪种权衡最重要时给出更好的设计，而不是在速度、简洁性和耐久性之间盲猜。

要求它给决策，不要让它做导览

更好的输出来自会逼出推荐和理由的提示词。例如：“请为这个工作负载推荐摄取模式、分区策略、补充 enrich 方法，以及是否使用预聚合；并为每条建议标注溯源。”这比“解释 ClickHouse 架构”更有用。

用第一版结果继续迭代

先用第一版答案找出缺失输入，然后补齐后再跑一轮：精确的 event key、更新语义、查询频率、维度波动性和保留策略。这个迭代循环对 clickhouse-architecture-advisor for Backend Development 尤其有效，因为真正的难点通常是把产品需求翻译成 ClickHouse 的形态。