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. 相關的最佳實務查詢 join 規則

可變狀態 / 延遲到達事件

1. rules/decision-late-arriving-upserts.md
2. 相關的最佳實務避免變更規則

輸出格式

回應結構如下：

## 工作負載摘要
- 工作負載：
- 延遲目標：
- 資料型態：
- 主要查詢模式：
- 操作限制：

## 關鍵決策
- ...
- ...

## 建議

### <建議標題>

**內容**
...

**原因**
...

**做法**
...

**類別**
official | derived | field

**信心程度**
高 | 中 | 經驗法則

**來源**
- 文件連結

**驗證方式**
- 具體 SQL、指標或冒煙測試

架構特定指引

偏好決策框架而非通用建議。良好的回應應：

• 解釋取捨
• 識別可能的操作瓶頸
• 區分立即行動與結構性重新設計
• 提供目標架構模式，而非僅是孤立設定

完整參考

請參閱 AGENTS.md 以取得彙整版本，以及 examples/ 中的範例輸出。