# Naming

> Фреймворк іменування для модулів / команд / підкоманд x-cmd. Субʼєктивно + сценарно-орієнтовано; skill — це тонка оболонка, а НЕ довідник правил. Три шари: дослідження (goal), naming.<user-task>.yml (OKR + запис сесії, файл .rule), naming.okr-creator.yml (meta-rule, що аудитує сесію).

- Skill: `x-cmd/naming-19` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx get-skill add x-cmd/naming-19`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-cmd/naming-19/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: x-cmd (https://skillmd.com/u/x-cmd)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/x-cmd/naming-19

---



# Naming

Іменування — це **субʼєктивно + сценарно-орієнтовано**. Цей skill — це **фреймворк**, а не довідник правил — він не запікає в собі субʼєктивних правил іменування.

## Швидка карта

```
┌─────────────────────────────────────────────────────────┐
│  1. ДОСЛІДЖЕННЯ мети                                    │
│     Що називаємо? Яка роль? Яке поняття?                │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  2. naming.<user-task>.yml  (файл .rule)                │
│     - goal-*        (завдання іменування)               │
│     - keyresult-*   (перевірювані результати)           │
│     - task-*        (обмеження під конкретне завдання)  │
│     - session:      (слід аудиту для goal-правила)      │
│         prefer     (5 відповідей init-004)              │
│         init_verdicts  (рішення по gate для кожного)    │
│         scores     (привʼязки D1-D7 для кожного)        │
│         final      (вибір + резерв)                     │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  3. АУДИТ шаблоном template/naming.okr-creator.yml      │
│     x rule check -r <naming-dir> naming.<user-task>.yml │
└─────────────────────────────────────────────────────────┘
```

## Робочий процес — крок за кроком

### Крок 1 · Дослідження мети

Перед тим як щось писати, дайте відповіді на ці запитання. **Не** пропускайте — без відповідей скорер не може прив'язати D4 (TRIAL/REAL) або D5 (RUN/TEST).

- **Що саме називаємо?** — модуль / підкоманда / поле / змінна — діють різні правила іменування за формою
- **Яку роль це відіграє?** — це визначає поняття, до якого привʼязується назва (напр. «модуль trial-run» → самостійний runner, Stage 1 двохетапного тесту)
- **Які попередні значення він ОБОВʼЯЗКОВО несе?** — домінантне значення голого слова має збігатися (напр. trial-run потребує TRIAL+RUN, а не REAL+TEST)
- **Яких попередніх значень він ОБОВʼЯЗКОВО має уникати?** — забруднення від unittest (`*test`/`*case`), фейковість (`*mock`/`*fake`/`*stub`/`*dry`), реальний деплой (`field*`/`*live*`)
- **Який архетип підходить?** — ship / plane / rocket / factory / abstract — керує D6/D7

Результат: однорядкове формулювання мети, наприклад
> «Обрати самостійну назву модуля x-cmd для trial-run (Stage 1 двохетапного тесту), яка набирає 8.0+ за D1-D7, зрозуміла з першого погляду й витримує всі fast-fail за червоними лініями / словником / довжиною.»

### Крок 2 · Створіть запис сесії

Скопіюйте шаблон і обріжте / заповніть.

```bash
cp naming.template.yml naming.<user-task>.yml
```

Далі заповніть 4 розділи (згори вниз):

#### 2a. Goal rule (завдання іменування)

Замініть `goal-TBD_task_id` на справжній ID. Суфікс ID має відображати завдання (напр. `goal-trial-run-naming`, `goal-mvp-prerelease-subcmd`).

```yaml
goal-trial-run-naming:
  name: <однорядкове формулювання мети з Кроку 1>
  apply: "naming.<user-task>.yml (self)"
  level: error
  desc:
  - <поняття + роль + анти-попередні значення, з Кроку 1>
```

#### 2b. Key results (перевірювані результати)

Замініть кожен `keyresult-kr*_TBD_short_label`. Кожен KR — це правило, яке має бути таким, щоб його можна було PASS-нути. Додайте стільки, скільки є в завданні.

```yaml
keyresult-kr1-top-pick-committed:
  name: <перевірюваний результат 1>
  level: error
  desc:
  - <що вважається проходженням — конкретний критерій, а не «схоже, добре»>
```

#### 2c. Правила під конкретне завдання (обмеження кандидатів)

Замініть кожен `TBD_task_id-*` на справжній ID обмеження, що відповідає суфіксу task-id цілі. Обріжте ті, що не застосовуються, додайте нові за потреби.

Поширені шаблони:
- `must-be-X-not-Y` — узгодження поняття (напр. `must-be-TRIAL-not-REAL`)
- `length-N-to-M-letters` — жорсткий діапазон D1
- `must-imply-<archetype>` — привʼязка D7
- `<domain>-specific-acceptable` / `not-acceptable` — дозвіл для вузької предметної галузі
- `must-be-self-explanatory` — D3

```yaml
trial-run-001:
  name: <обмеження, напр. "must-be-TRIAL-not-REAL">
  apply: "candidate words for <task-id>"
  level: error | warn
  desc:
  - <чому кандидат має відповідати>
  - <який вимір D1-D7 воно обмежує>
  tldr:
  - wrong: <контриприклад>
  - right: <хороший приклад>
```

#### 2d. Запис сесії (слід аудиту для goal-правила)

Заповніть усі 4 підрозділи:

**prefer** — ОБОВʼЯЗКОВО дайте відповідь на всі 5 запитань, навіть якщо відповідь — «ні / слабко»:
```yaml
prefer:
  vivid: yes | no | weak
  domain_acceptable: [<список вузьких галузей, які ОК, напр. [naval]>]   # [] = вузькі галузі не ОК
  length_priority: shorter | self_explanatory
  origin: english | chinese | coined
  trade_off: single_prior_ok | hit_every_dim
```

**init_verdicts** — по одному запису на кожного розглянутого кандидата, включно з відхиленими:
```yaml
init_verdicts:
  - { name: <кандидат>, gate: init-005 | init-006 | init-007 | pass, reason: "<чому>" }
  # init-005 = збіг із шаблоном червоної лінії (автоматичне відхилення)
  # init-006 = перше значення у словнику суперечить цілі
  # init-007 = довжина поза межами (< 2 або > 8)
  # pass     = пройшов усі init-gate, може йти на оцінювання
```

**scores** — по одному запису на кожного кандидата, який пройшов init. Усі оцінки >= 6.0. Кожна оцінка ОБОВʼЯЗКОВО має привʼязки:
```yaml
scores:
  - name: <кандидат>
    score: <0_to_10>
    anchors:
      - "D1: <доказ кількості літер>"
      - "D2: <доказ першого значення у словнику>"
      - "D3: <доказ буквального значення складника>"
      - "D4: <доказ trial проти real>"
      - "D5: <доказ run проти test>"
      - "D6: <доказ виразності>"
      - "D7: <доказ великого обладнання>"
    misses:
      - "<чого бракує — перелічуйте лише справжні прогалини, не обовʼязково всі 7>"
```

**final** — оголошуйте вибір і резерв:
```yaml
final:
  pick: <winning_candidate>
  backup: <runner_up_or_null>
```

### Крок 3 · Аудит за допомогою meta-rule

```bash
x rule check -r <naming-dir> naming.<user-task>.yml
```

OKR-creator (розташований у `template/naming.okr-creator.yml`) виконує 11 перевірок (суміш error і warn):

| Перевірка | Рівень | Що вона перевіряє |
|---|---|---|
| `okr-creator-001` has-goal-rule | error | файл містить щонайменше 1 правило `goal-*` |
| `okr-creator-002` has-keyresult-rules | error | файл містить щонайменше 1 правило `keyresult-*` |
| `okr-creator-003` has-task-specific-rules | error | файл містить щонайменше 1 правило завдання (не goal/keyresult) |
| `okr-creator-010` has-session-record | error | правило goal має поле `session:` |
| `okr-creator-011` prefer-answers-all-five | error | на всі 5 запитань init-004 дано відповідь |
| `okr-creator-012` init-verdicts-recorded | error | init_verdicts не порожній |
| `okr-creator-013` scores-have-anchors | error | у кожної оцінки є непорожній список anchors |
| `okr-creator-014` scores-no-below-6 | error | усі оцінки >= 6.0 |
| `okr-creator-015` final-section-present | error | оголошено `final.pick` |
| `okr-creator-020` pick-backup-gap-le-1 | warn | score(pick) - score(backup) <= 1.0 |
| `okr-creator-021` top-pick-at-least-7 | warn | оцінка pick >= 7.0 |

**Якщо впала будь-яка перевірка рівня error**: виправте файл і запустіть знову. Типові виправки:
- Бракує поля prefer → додайте до `session.prefer`
- Гола оцінка → додайте `anchors: [...]`
- Оцінка < 6 → перенесіть до `init_verdicts` (відхилено) або переформулюйте оцінку
- Бракує final → додайте `final: { pick, backup }`

**Якщо впали перевірки рівня warn**: вирішіть, чи виправляти це, чи задокументувати компроміс.

### Крок 4 · Користувач обирає фінальну назву

Skill пропонує — користувач вирішує. Фінальну назву оголошують у `session.final.pick` і фіксують комітом.

## Файли

| Файл | Роль | Формат |
|---|---|---|
| `SKILL.md` | Цей файл — робочий процес + індекс файлів | markdown |
| `naming.template.yml` | ШАБЛОН із плейсхолдерами `TBD_*` — скопіювати, перейменувати, заповнити | `.rule` |
| `naming.trial-run-module.yml` | Практичний приклад повного запису сесії | `.rule` |
| `template/naming-concept.yml` | Обʼєктивний фреймворк оцінювання (D1–D7, червоні лінії, привʼязки оцінок) — у вигляді записів `.rule` | `.rule` |
| `template/naming-brand.yml` | Бренд-правила x-cmd (довжина, регістр, уподобання щодо попередніх значень) — у вигляді записів `.rule` | `.rule` |
| `template/naming.okr-creator.yml` | Meta-rule: аудитує `naming.<user-task>.yml` (11 перевірок вище) | `.rule` |
| `template/naming-x-cmd-mod.yml` | Необовʼязковий пресет іменування модулів x-cmd (стартовий запис сесії) | `.rule` |

## Субʼєктивне проти обʼєктивного

| Обʼєктивне (у файлах / коді) | Субʼєктивне (питається на init, не оцінюється) |
|---|---|
| Перше значення у словнику | «Мені треба виразно, а не абстрактно» |
| Кількість літер | «Мені ок вузька галузь X» |
| Семантичний клас Trial / Real / Run / Test | «Мені ок метафора naval чи ні» |
| Буквальне значення складника | «Мені треба китайського чи англійського походження» |
| Забруднення попередніми значеннями (unittest testcase, dryrun) | «Мені коротше, а не зрозуміліше» |

## Правила

- **ПОВИННО** спершу дослідити мету — що називаємо, яку роль це відіграє, яке поняття служить опорою.
- **ПОВИННО** починати з `naming.template.yml` (плейсхолдери `TBD_*`) і обрізати / заповнювати за потребами завдання.
- **ПОВИННО** створити `naming.<user-task>.yml` (формат `.rule`) з goal / key results / task rules / записом сесії.
- **ПОВИННО** запустити `x rule check` з `template/naming.okr-creator.yml`, щоб перевірити запис сесії.
- **ПОВИННО** привʼязувати оцінки до обʼєктивних фактів — ніколи не завищувати/занижувати за реакцією користувача.
- **ПОВИННО** дати користувачу обрати фінальну назву — skill пропонує, користувач вирішує.
- **НЕ МОЖНА** додавати субʼєктивні правила до `template/naming-concept.yml` — вони належать до `session.prefer` конкретного завдання.

## Related

- [rule](../rule/SKILL.md) — сесія іменування перевіряється через x rule
- [score](../score/SKILL.md) — кандидати оцінюються за фреймворком score
- [ontology-database](../ontology-database/SKILL.md) — обрана назва зберігається в ondb
