Единый язык команды
Почему глоссарий пишется не для людей, а для того, кто не сидел в комнате, и как его собирать из речи, а не из головы
Единый язык (ubiquitous language) — идея Эрика Эванса из «Domain-Driven Design», и там она про людей: команда и заказчик должны называть вещи одинаково, иначе половина обсуждений уходит на выяснение, что кто имел в виду. Читать всю книгу ради этого не обязательно — у Эванса есть бесплатный DDD Reference на сорок страниц, где идея изложена сжато.
Честная правда в том, что как документ глоссарий часто не нужен. Четыре человека, которые каждый день разговаривают, за месяц договариваются сами: слова притираются, спорные вылетают, и все понимают друг друга без единой записанной строчки. Формат тут вообще ни при чём — таблица, список, страница в вики — работает не файл, а привычка называть одну сущность одним словом.
Что изменилось: в команде появился пятый
К этим четверым добавился агент, который при разговорах не
присутствовал. Он не слышал, как вы полчаса спорили и решили, что
«набор» — это не «тест». Он читает репозиторий, и если в коде
quiz, в use case «опрос», а в README «тест» — он будет считать это
тремя разными сущностями и спокойно нагенерирует под каждую свой класс.
Отсюда единственная причина, по которой глоссарий надо записать: не для себя, а для того, кто в комнате не сидел. Это тот же аргумент, что и у AGENTS.md: устная договорённость не доезжает до агента, письменная — доезжает.
Побочный эффект приятный: новый человек в команде тоже не сидел в комнате. К третьей лабе список терминов экономит ему неделю.
Как он собирается
Плохой глоссарий пишут за вечер, придумывая определения. Хороший накапливается по ходу и состоит из слов, которые команда уже произносит.
Практика простая: поймали разночтение — записали. Кто-то на созвоне
сказал «карточка», кто-то переспросил «в смысле материал?» — вот эта
секунда и есть повод для новой строки. Так же, как правило в AGENTS.md
появляется из пойманной ошибки агента, термин появляется из пойманного
непонимания между людьми.
Что писать в строке:
- **Материал** — файл курса, который студент загрузил в систему.
В коде: `Material`. Не «документ», не «файл», не «источник».
- **Набор** — сгенерированные по одному материалу вопросы.
В коде: `QuestionSet`. Не «тест» и не «квиз»: тест — это то, что
студент проходит, набор — то, что система сгенерировала.
- **Проверка** — сверка ответа студента с фрагментом материала.
В коде: `Check`. Не путать с прогоном evals: то мы проверяем систему,
это система проверяет студента.Три вещи делают строку рабочей: имя в коде (иначе язык разъедется между разговором и репозиторием), чем это не является (запрещённые синонимы ловят ошибку раньше, чем определение), и отличие от похожего — большинство путаницы возникает между двумя близкими сущностями, а не на пустом месте.
Где язык обязан совпадать дословно
Термин из глоссария должен звучать одинаково в четырёх местах:
| Где | Как проверить |
|---|---|
| Use cases | Читаешь UC — все существительные из глоссария, новых нет |
| Код | Классы и таблицы названы теми же словами |
| Интерфейс | То, что видит пользователь, называется так же |
AGENTS.md | Раздел «Глоссарий» — короткая выжимка для агента |
Разъехалось хоть где-то — это не косметика. Расхождение между UC и кодом означает, что кто-то из двоих описывает не ту систему, которую вы строите.
Признак, что язык не сложился
Проверить можно за минуту, не поднимая документов: попросите двоих из команды по отдельности объяснить, чем «набор» отличается от «теста». Ответы разошлись — глоссарий не работает, сколько бы файлов ни лежало в репозитории.
Второй признак — из практики агентной разработки: агент раз за разом называет одну сущность разными словами или заводит дубли классов. Это не он глупый, это в проекте нет единого языка, и он честно отражает то, что прочитал.