ClickHouse Architecture Advisor

このスキルは clickhouse-best-practices の上に、ワークロード対応アーキテクチャ決定を追加します。

公式ドキュメントは信頼できる情報源です。 このスキルは、利用可能な場合は常に公式 ClickHouse ドキュメントを優先する必要があります。

必須動作

推奨を行う前に:

1. ワークロード形状を特定する
   • observability（可観測性）
   • security / SIEM
   • product analytics（製品分析）
   • IoT / telemetry（テレメトリ）
   • market data / financial services（市場データ・金融サービス）
   • mixed OLAP with point-lookups（ポイント検索混在型 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. 関連するベストプラクティス insert ルール

時系列とデータ保持期間設計

1. rules/decision-partitioning-timeseries.md
2. 関連するベストプラクティス スキーマ パーティション ルール

エンリッチメントとディメンションルックアップ

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

ミューテーブルステート / 遅延到着イベント

1. rules/decision-late-arriving-upserts.md
2. 関連するベストプラクティス mutation avoidance ルール

出力形式

以下のようにレスポンスを構成します:

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

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

## Recommendations

### <推奨タイトル>

**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/ でサンプル出力を参照してください。