nothing: Skill for Claude Code

Naming

Vanilla conventions (snake_case in Rust, kebab-case in JS/TS, PascalCase exports, use-* hooks) are table stakes — assume them. This document is about the observations on top: what a name commits you to, what it reveals, and what it costs when it's wrong.

Name first

Pick the name before the types, before the tests, before the file exists. If the name doesn't come easily, the design isn't ready — don't start coding; sharpen the concept until the name falls out. Maintainability is downstream of naming. How a module grows, how cleanly it retires, how safely it can be deleted — all of it is decided at the moment you choose what to call it.

A strict, honest name is a scope gate

A name's primary job here is to refuse the wrong content. A module called painter should feel actively wrong to host a layout helper; a package called @grida/cmath should feel wrong to host color logic. The strictness is deliberate — it is the mechanism that keeps features from leaking into each other.

"Strict" requires "honest." A name that no longer describes what's inside has stopped being a gate: it won't reject foreign additions, and new readers can't trust it. When contents drift past the name, you have two moves — rename to match what the module has become, or extract the drifted pieces out — and you must pick one promptly. Letting a name go stale is how codebases rot quietly.

Three consequences cascade from the gate discipline, and together they produce the current repo structure:

1. Modules stay shallow. You will rarely see a module nested deeper than two levels inside a crate's src/ or a package's src/. When you're tempted to grow a third level, the parent's name has stopped describing what's inside — flatten or extract, don't nest.
2. Flatten with prefixed siblings, or collapse into one file. Before reaching for a subdirectory, ask whether the new thing is a sibling variant of an existing file (effects.rs + effects_noise.rs, image.rs + image_filters.rs) or whether it collapses into the existing file. Both preserve the parent's scope; a new subdirectory quietly widens it.
3. If it resists flattening, it is a new module. The thing that won't fit under the strict name doesn't belong there. It wants its own tiny, agnostic package or crate. The repo has many small @grida/* packages and small crates precisely because this extraction was made each time a sibling would have diluted the parent's name.