---
name: storage-cassandra
description: "Cassandra-specific code design reference for the Code Design Agent. Load only when the architecture or repository indicates Cassandra. Covers query-driven data modeling, partition/clustering key design, denormalization, and repository boundaries."
---

This skill provides Cassandra-specific guidance for code-level design.

**Announce at start:** "I'm using the storage-cassandra skill to apply Cassandra-specific code design conventions."

## When To Load

Load this skill only when one or more of the following is true:
- The architecture explicitly names Cassandra
- The repository uses Cassandra drivers, CQL, or keyspace/table terminology
- The architecture requires query-oriented denormalized wide-column storage

Do not load this skill for relational or document-first systems.

## Purpose

Translate wide-column architecture into Cassandra-aware code design: query-based table design, partition key choices, denormalized models, repository contracts, and operational constraints.

## Cassandra Design Rules

1. Model tables from query patterns first; never start from normalization
2. Make partition key and clustering key choices explicit for every table
3. Accept denormalization as a feature, not a smell, when it serves read paths
4. Avoid cross-partition transactions; design for eventual consistency unless the architecture states otherwise
5. Keep write amplification and hot partition risk visible in the code design document

## Table Guidance

- Document the primary key for every table in full: partition key and clustering columns
- State the exact query each table serves
- Add a separate table when a new query pattern cannot be served efficiently by the existing key design

## Repository Guidance

- Repository methods should map directly to supported query shapes
- Do not promise arbitrary filtering or sorting that Cassandra cannot support efficiently
- Make pagination token strategy explicit

## Model Guidance

- Keep persistence models aligned with CQL table layout
- Document TTL usage, static columns, and collection column types when used
- Call out duplicate data ownership across denormalized tables

## Operational Safeguards

- Note consistency level expectations for reads and writes
- Note compaction, tombstone, and TTL implications when they affect design
- Surface hot partition, wide row, and backfill risks explicitly

## Output Constraint

This skill is reference-only. It does not create files by itself. Apply its guidance inside `docs/code-design/{date}-{feature}.md` only.