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. 関連するベストプラクティスのスキーマパーティションルール

エンリッチメントとディメンションの参照

1. rules/decision-join-enrichment.md
2. 関連するベストプラクティスのクエリ結合ルール

可変状態／遅延到着イベント

1. rules/decision-late-arriving-upserts.md
2. 関連するベストプラクティスのミューテーション回避ルール

出力形式

次の形式で回答を構成してください。

## Workload Summary
- workload:
- latency target:
- data shape:
- primary query patterns:
- operational constraints:

## Key Decisions
- ...
- ...

## Recommendations

### <Recommendation title>

**What**
...

**Why**
...

**How**
...

**Category**
official | derived | field

**Confidence**
high | medium | heuristic

**Source**
- doc link(s)

**Validation**
- concrete SQL, metric, or smoke test

アーキテクチャ固有のガイダンス

一般的な助言よりも、意思決定のためのフレームワークを優先してください。良い回答では、次の内容を含めます。

• トレードオフを説明する
• ボトルネックとなる可能性が高い箇所を特定する
• すぐに実行できる対策と、構造的な再設計を分ける
• 個別の設定だけでなく、目標とするアーキテクチャのパターンを示す

参考情報全般

まとめられたバージョンは AGENTS.md を、出力例は examples/ を参照してください。