# Единый язык команды

> Почему глоссарий пишется не для людей, а для того, кто не сидел в комнате, и как его собирать из речи, а не из головы

_Источник: https://sii.sergeivolchkov.ru/materials/use-cases/glossary_



Единый язык (ubiquitous language) — идея Эрика Эванса из «Domain-Driven
Design», и там она про людей: команда и заказчик должны называть вещи
одинаково, иначе половина обсуждений уходит на выяснение, что кто имел в
виду. Читать всю книгу ради этого не обязательно — у Эванса есть
бесплатный [DDD Reference](https://www.domainlanguage.com/ddd/reference/)
на сорок страниц, где идея изложена сжато.

Честная правда в том, что **как документ глоссарий часто не нужен**.
Четыре человека, которые каждый день разговаривают, за месяц
договариваются сами: слова притираются, спорные вылетают, и все понимают
друг друга без единой записанной строчки. Формат тут вообще ни при чём —
таблица, список, страница в вики — работает не файл, а привычка называть
одну сущность одним словом.

## Что изменилось: в команде появился пятый [#что-изменилось-в-команде-появился-пятый]

К этим четверым добавился агент, который **при разговорах не
присутствовал**. Он не слышал, как вы полчаса спорили и решили, что
«набор» — это не «тест». Он читает репозиторий, и если в коде
`quiz`, в use case «опрос», а в README «тест» — он будет считать это
тремя разными сущностями и спокойно нагенерирует под каждую свой класс.

Отсюда единственная причина, по которой глоссарий надо **записать**: не
для себя, а для того, кто в комнате не сидел. Это тот же аргумент, что и
у [AGENTS.md](/materials/agent/context): устная договорённость не
доезжает до агента, письменная — доезжает.

Побочный эффект приятный: новый человек в команде тоже не сидел в
комнате. К третьей лабе список терминов экономит ему неделю.

## Как он собирается [#как-он-собирается]

Плохой глоссарий пишут за вечер, придумывая определения. Хороший
накапливается по ходу и состоит из слов, которые команда уже произносит.

Практика простая: **поймали разночтение — записали**. Кто-то на созвоне
сказал «карточка», кто-то переспросил «в смысле материал?» — вот эта
секунда и есть повод для новой строки. Так же, как правило в `AGENTS.md`
появляется из пойманной ошибки агента, термин появляется из пойманного
непонимания между людьми.

Что писать в строке:

```markdown title="docs/glossary.md"
- **Материал** — файл курса, который студент загрузил в систему.
  В коде: `Material`. Не «документ», не «файл», не «источник».
- **Набор** — сгенерированные по одному материалу вопросы.
  В коде: `QuestionSet`. Не «тест» и не «квиз»: тест — это то, что
  студент проходит, набор — то, что система сгенерировала.
- **Проверка** — сверка ответа студента с фрагментом материала.
  В коде: `Check`. Не путать с прогоном evals: то мы проверяем систему,
  это система проверяет студента.
```

Три вещи делают строку рабочей: **имя в коде** (иначе язык разъедется
между разговором и репозиторием), **чем это не является** (запрещённые
синонимы ловят ошибку раньше, чем определение), и **отличие от
похожего** — большинство путаницы возникает между двумя близкими
сущностями, а не на пустом месте.

## Где язык обязан совпадать дословно [#где-язык-обязан-совпадать-дословно]

Термин из глоссария должен звучать одинаково в четырёх местах:

| Где                                       | Как проверить                                            |
| ----------------------------------------- | -------------------------------------------------------- |
| [Use cases](/materials/use-cases/writing) | Читаешь UC — все существительные из глоссария, новых нет |
| Код                                       | Классы и таблицы названы теми же словами                 |
| Интерфейс                                 | То, что видит пользователь, называется так же            |
| `AGENTS.md`                               | Раздел «Глоссарий» — короткая выжимка для агента         |

Разъехалось хоть где-то — это не косметика. Расхождение между UC и кодом
означает, что кто-то из двоих описывает не ту систему, которую вы
строите.

## Признак, что язык не сложился [#признак-что-язык-не-сложился]

Проверить можно за минуту, не поднимая документов: попросите двоих из
команды **по отдельности** объяснить, чем «набор» отличается от «теста».
Ответы разошлись — глоссарий не работает, сколько бы файлов ни лежало в
репозитории.

Второй признак — из практики агентной разработки: агент раз за разом
называет одну сущность разными словами или заводит дубли классов. Это не
он глупый, это в проекте нет единого языка, и он честно отражает то, что
прочитал.