clickhouse-architecture-advisor

ClickHouse 架构顾问

本技能在 clickhouse-best-practices 之上增加了工作负载感知的架构决策能力。

官方文档是最终权威。
本技能在可用时必须优先参考 ClickHouse 官方文档。

必需行为

在给出建议前：

1. 识别工作负载类型
   • 可观测性
   • 安全/SIEM
   • 产品分析
   • IoT/遥测
   • 市场数据/金融服务
   • 混合 OLAP 与点查
2. 阅读 rules/ 中相关的决策规则文件
3. 使用 mappings/doc_links.yaml 关联官方文档
4. 将每条建议分类为：
   • official（官方）
   • derived（衍生）
   • field（经验）
5. 切勿将经验指导呈现为官方指导
6. 如果建议不确定，需明确说明

来源规则

official

当建议直接来自官方文档时使用此标签。

derived

当建议并非文档原文，但根据 ClickHouse 的已知行为逻辑推导得出时使用此标签。

field

仅用于基于经验的、可能因场景而异的指导。
使用 field 时，需包含：

• 免责声明，说明该建议为启发式
• 部分适用的相关官方文档链接
• 该建议依赖工作负载上下文的原因

按场景阅读以下规则文件

实时数据摄入设计

1. rules/decision-ingestion-strategy.md
2. rules/decision-real-time-preaggregation.md
3. 相关的最佳实践插入规则

时间序列与保留设计

1. rules/decision-partitioning-timeseries.md
2. 相关的最佳实践 schema 分区规则

数据丰富与维度查询

1. rules/decision-join-enrichment.md
2. 相关的最佳实践查询连接规则

可变状态/延迟到达事件

1. rules/decision-late-arriving-upserts.md
2. 相关的最佳实践避免突变规则

输出格式

按如下结构组织回复：

## 工作负载摘要
- 工作负载：
- 延迟目标：
- 数据形态：
- 主要查询模式：
- 运维约束：

## 关键决策
- ...
- ...

## 建议

### <建议标题>

**内容**
...

**原因**
...

**方法**
...

**类别**
official | derived | field

**置信度**
高 | 中 | 启发式

**来源**
- 文档链接

**验证**
- 具体的 SQL、指标或冒烟测试

架构特定指导

优先使用决策框架而非泛泛建议。好的回复应：

• 解释权衡
• 识别可能的性能瓶颈
• 区分即时操作与结构性重构
• 提供目标架构模式，而非孤立的设置

完整参考

参见 AGENTS.md 获取编译版本，以及 examples/ 获取示例输出。