58 lines
2.5 KiB
Markdown
58 lines
2.5 KiB
Markdown
|
---
|
||
|
|
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.
|