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 · Створіть запис сесії
Скопіюйте шаблон і обріжте / заповніть.
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).
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-нути. Додайте стільки, скільки є в завданні.
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— жорсткий діапазон D1must-imply-<archetype>— привʼязка D7<domain>-specific-acceptable/not-acceptable— дозвіл для вузької предметної галузіmust-be-self-explanatory— D3
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 запитань, навіть якщо відповідь — «ні / слабко»:
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 — по одному запису на кожного розглянутого кандидата, включно з відхиленими:
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. Кожна оцінка ОБОВʼЯЗКОВО має привʼязки:
scores:
- name: <кандидат>
score: <0_to_10>
anchors:
- "D1: <доказ кількості літер>"
- "D2: <доказ першого значення у словнику>"
- "D3: <доказ буквального значення складника>"
- "D4: <доказ trial проти real>"
- "D5: <доказ run проти test>"
- "D6: <доказ виразності>"
- "D7: <доказ великого обладнання>"
misses:
- "<чого бракує — перелічуйте лише справжні прогалини, не обовʼязково всі 7>"
final — оголошуйте вибір і резерв:
final:
pick: <winning_candidate>
backup: <runner_up_or_null>
Крок 3 · Аудит за допомогою meta-rule
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 — сесія іменування перевіряється через x rule
- score — кандидати оцінюються за фреймворком score
- ontology-database — обрана назва зберігається в ondb