| name | antalya-feature-design |
| description | Scaffold or review a feature design document for ClickHouse / Antalya. Use this whenever a developer wants to design or implement a new feature, add a SQL function, add a setting, add a new engine or format, or change server behavior in a non-trivial way — even if they don't explicitly ask for a "design doc". Also use when reviewing an existing design before implementation starts. |
Antalya Feature Design
Help the developer produce a feature design for ClickHouse / Antalya before code is
written. A good design shortens review, prevents abandoned branches, and surfaces compatibility
landmines before they become migrations.
When to create vs. review
- Create when the developer is starting new work and has no design yet, or only a rough idea.
- Review when the developer hands you an existing design (file path, paste, or PR link) and
asks for feedback, a critique, or to "check" it.
If unclear, ask one question: "Are we drafting a new design, or reviewing an existing one?"
Creating a design
1. Ask a few questions first (don't guess)
The template has four sections. Before filling them in, confirm the basics — a wrong premise wastes
more time than a short interview:
- What problem is being solved? Push for a concrete workload or user report, not "users want X".
- What's the rough shape? New SQL syntax? A new setting? A new engine/format? A behavior change?
- Any hard constraints? Upstream ClickHouse parity, on-disk compatibility, a specific release
train, a customer deadline.
- Where should the design file live? Default to
docs/design/<feature-slug>.md relative to the
repo root, but let the developer override.
If the developer has already answered these in conversation, skip ahead — don't re-interview them.
2. Copy the template, then fill it in
The template lives at assets/design-template.md next to this SKILL.md. Copy it to the chosen
path, then populate each section based on the conversation. Leave a section marked TBD with a
pointed question rather than inventing content — a visible gap is more useful than a plausible
fabrication.
The default location for designs is antalya/docs/design. Create a new directory for the design
and place the .md file within it.
3. Conventions to apply while writing
These match the project CLAUDE.md and make the design consistent with the rest of the codebase:
- Wrap SQL keywords, function names, class names, setting names, engine names, and literal log
message excerpts in inline code blocks:
MergeTree, SELECT, max_threads, system.errors.
- Refer to functions as
f (not f()) when naming the function itself rather than a call.
- Say "throws an exception" rather than "crashes" for logical errors — release builds don't crash
on
LOGICAL_ERROR.
- Cite files as
path/to/file.cpp:line so reviewers can jump directly.
- Prefer one-line statements of intent over prose padding.
Avoid long examples or deep specification detail in the design. Where
such detail is require, such as end-to-end examples or output formats,
put these in files of the form annex-<name>.md and reference them with
markdown links.
4. Push back on weak spots as you write
Drafting is also a review — don't wait for section 4 to think. In particular:
- If the Motivation reduces to "users want X" with no concrete workload, ask for one.
- If Requirements are not measurable, say so and suggest a measurable form.
- If there are no Non-requirements, propose a few. The absence of non-goals is the single biggest
source of scope creep.
- If Alternatives considered is empty, press for at least one rejected approach. A design with
no alternatives considered usually means the author has a solution looking for a problem.
Reviewing a design
Read the design end-to-end first, then walk the checklist below. Report findings grouped by
severity: blocking (must fix before implementation), should-address (fix before merge),
nit (optional). Quote the exact text you're critiquing so the author can find it fast.
Requirements
- The requirements section define the user problem. The problem should be stated in terms of needed
features, performance goals, delivery deadlines, plus topics we do not need to consider or solve.
- Motivation cites a concrete workload, incident, or user report — not a generic assertion.
- Requirements are measurable. "Faster" is not a requirement; "query
Q drops from 5s to <500ms on dataset D"
is.
- Non-requirements are listed. Missing non-requirement almost always produce scope creep in review.
- Requirements should be generic. Put user-visible product behavior such as SQL commands in the Functional
Specification. Put internal (non-visible behavior) in the Implementation section.
Functional specification
- The functional specification defines user visible product behavior including SQL commands, system tables,
settings, and error messages.
- Every new/changed SQL syntax has at least one concrete example.
- Every new setting has scope (server / user / query), default, and valid range.
- Default-value changes that alter behavior for existing workloads are called out explicitly.
- Error behavior specifies the error code, not just "throws an error".
- Backward compatibility covers: older client → newer server, newer client → older server,
mixed-version cluster, on-disk format. If any of these is genuinely N/A, the design should say
so — silence is not the same as "not applicable".
- Formatting convention: inline code blocks around SQL identifiers, engine names, settings.
Implementation
- The implementation section covers internal design that is not visible to the user.
- Architecture section names the subsystems touched (parser / analyzer / planner / executor /
storage / replication / keeper). If it touches many, that's a design smell worth flagging.
- New abstractions pull their weight. If an interface has one implementation and no foreseeable
second, flag it — per project
CLAUDE.md, three similar lines beat a premature abstraction.
- Storage format changes include a migration path and version-bump strategy.
- Performance section identifies the benchmark that will cover the hot path. Hand-wavy "shouldn't
be a regression" is not enough for hot-path code.
- Alternatives considered contains at least one rejected approach with a reason. A design with no
rejected alternatives is under-explored.
- Error handling lives at boundaries (user input, external systems), not scattered through
internal code that already trusts its callers.
Test plan
- The test plan defines happy path, edge cases, and error cases.
- Test case definitions should be specific, falsifiable propositions about feature behavior.
- Test case definitions should not contain implementation code, except as necessary
to describe the feature being tested.
- Tests use
tests/queries/0_stateless for functional coverage and tests/integration for
anything touching replication, keeper, distributed queries, S3, auth, or Kafka.
- Performance should be specified if the feature is in the hot path, i.e., affects response or resource usage.
Cross-cutting red flags
- Feature flags or backwards-compatibility shims added "just in case" — per project
CLAUDE.md,
prefer changing the code directly when you can.
- Comments in the proposed implementation that restate what the code does, or name the current
task/PR/issue — those belong in commit messages and PR descriptions, not in source.
- Unfinished sections left as
TBD with no owner or question — either resolve or annotate with
the specific decision needed and who owns it.
Output etiquette
- When creating, write the file and then tell the developer which sections need their input (the
TBD items) rather than showing the whole template in chat.
- When reviewing, lead with a one-line verdict ("ready to implement", "needs revisions in
sections 2 and 4", "fundamental rethink needed"), then the grouped findings.
- Keep the review terse. Block quotes from the design plus one-sentence critiques beat long prose.
