AGENTS

This skill complements clickhouse-best-practices by adding a workload-aware architecture layer for ClickHouse. It is optimized for advisory, workshop, and system design workflows where a user needs more than a rule check. It provides decision frameworks for ingestion strategy, time-series partitioning, enrichment paths, late-arriving data, and real-time pre-aggregation.

Core principle

Official documentation is the source of truth. Every recommendation must be labeled as:

• official
• derived
• field

Decision areas

1. Ingestion strategy

Use when deciding between:

• direct inserts
• async inserts
• Kafka engine + MV
• upstream buffering

2. Time-series partitioning

Use when deciding:

• whether to partition
• partition granularity
• how retention and TTL affect design
• how to avoid excessive partition counts

3. Enrichment path selection

Use when deciding between:

• runtime JOINs
• dictionaries
• denormalization
• materialized enrichment

4. Late-arriving data and mutable state

Use when reasoning about:

• immutable append-only events
• latest-state queries
• replacing or collapsing semantics
• whether frequent mutations should be avoided

5. Real-time pre-aggregation

Use when deciding:

• raw-only design
• incremental materialized views
• refreshable MVs
• rollup tables

Output standard

A valid architecture response should include:

• workload summary
• key decisions
• recommendations with provenance labels
• suggested target architecture
• example DDL or SQL
• validation approach

Required recommendation schema

See schemas/recommendation_schema.yaml.

Rule index

1. decision-ingestion-strategy
2. decision-partitioning-timeseries
3. decision-join-enrichment
4. decision-late-arriving-upserts
5. decision-real-time-preaggregation

Implementation notes

This skill is intentionally narrow:

• it does not replace low-level rule enforcement
• it does not make commercial recommendations
• it does not claim field heuristics are official policy

Its purpose is to translate documented ClickHouse capabilities into workload-specific architecture decisions.