Язык предметной области для AI-программирования: исправьте названия, пока ошибки не разошлись

Где начинается путаница

Проблемы с названиями обычно начинаются еще до того, как кто-то пишет код. У функции может появиться два или три названия по мере того, как она проходит через планирование, дизайн и разработку. Продукт называет ее "workspace", в тикете написано "account", а в базе данных по-прежнему осталось "organization" от старой версии приложения.

Сначала такое расхождение кажется безобидным. Люди все еще достаточно хорошо понимают друг друга и двигаются дальше. Потом AI пишет связующий код между UI, API, валидацией, логами и тестами. Ему приходится выбирать слова из того, что он видит. Если исходный язык смешан, вывод тоже получается смешанным.

Проблема проявляется в обычных местах. В тикете просят "invite teammate", а на кнопке написано "add user". В схеме хранится member_id, а старый отчет по-прежнему говорит "client". По отдельности ни одно из этих названий не выглядит абсурдным. Вместе они размывают реальное понятие.

Чаще всего больше всего проблем создают старые названия в схеме. Продукты меняются быстрее, чем базы данных, поэтому вчерашняя метка остается надолго после того, как смысл функции уже изменился. Команды избегают переименований, потому что это кажется рискованным, или потому что никому не хочется трогать старые миграции. Потом новый разработчик или AI-ассистент принимает старое название за истину и разносит его в новый код.

Свою роль добавляют и разные команды. Поддержка использует слова, которые говорят клиенты. Продажи — термины, которые помогают объяснить цену. Продукт идет за последними макетами. Разработка сохраняет то, что было в первой таблице и так и не было приведено в порядок. В итоге у одного понятия вокруг появляется целое облако почти одинаковых слов.

Вот так общий язык предметной области и ломается. AI отлично копирует шаблоны. Но он плохо понимает, какое из трех похожих названий действительно соответствует смыслу вашего бизнеса. Если термины расходятся между тикетами, подписями в UI и схемами, путаница не остается на этапе планирования. Она доходит до продакшена, а там исправлять ее уже дороже.

Почему AI повторяет путаницу

AI не исправляет расплывчатый язык за вас. Он копирует слова, которые находит в тикетах, старом коде, скриншотах, названиях в схеме, комментариях и прошлых примерах. Если в вашей команде одно и то же называют тремя разными словами, модель часто использует все три — в разных местах.

Поэтому ошибки в названиях так быстро расходятся, когда AI пишет связующий код. Разработчик просит небольшое изменение, в тикете написано "customer", в UI — "account", а в столбце базы данных — user_id. Модель пытается это состыковать. Вместо того чтобы остановиться и уточнить правильный термин, она просто заполняет пробелы догадками.

Эти догадки не остаются в одном файле. Они появляются в комментариях, тестах, полезной нагрузке API, подписях форм, миграциях и сообщениях об ошибках. Один небольшой разрыв в формулировках может превратиться в настоящий баг: UI отправляет accountType, бэкенд ожидает customerType, а в схеме по-прежнему хранится user_type. Внешне все выглядит достаточно близко, чтобы пройти быструю проверку, но в работе функция ломается.

Скорость только усугубляет ситуацию. AI может написать много кода за минуты, поэтому одна ошибка в названии успевает расползтись по всему стеку, прежде чем кто-то это заметит. Человек, возможно, создал бы одно неверное поле. Модель может создать поле, добавить для него валидацию, написать вокруг него тесты и упомянуть его в вспомогательном тексте. И вот уже неправильное название выглядит нормальным, потому что оно встречается везде.

Модели еще и доверяют тому, что выглядит устоявшимся. Если в старом примере использован неверный термин, он будет всплывать снова и снова. Если в промпте написано "archive", а продукт на самом деле означает "hide", модель может добавить неправильную кнопку, метод и значение статуса. Код при этом может продолжать работать, и из-за этого проблему сложнее заметить.

Команды, которые быстро развиваются с помощью AI, сталкиваются с этим очень рано. Лучше писать промпты — это помогает, но этого недостаточно. Нужен более чистый исходный язык. Когда одно понятие называется одинаково в тикетах, тексте UI, схемах и коде, у модели остается меньше пространства для выдумок. Это сокращает переделки и не дает мелким ошибкам в формулировках превратиться в путаницу на уровне всей системы.

Найдите слова, которые создают проблемы

Начинайте со слов, которые команда уже использует, а не с тех, которые вам хотелось бы видеть. AI будет копировать то, что встречается чаще всего. Если в тикетах написано "account", в UI — "workspace", а в схеме — "organization", код часто смешивает все три варианта.

Соберите термины из мест, где язык продукта просачивается в реализацию: из заголовков и комментариев тикетов, подписей на кнопках и в полях формы, таблиц и столбцов базы данных, запросов и ответов API, сообщений об ошибках, тестовых фикстур и тестовых данных. Сложите все в один простой список. Не приводите его в порядок сразу. Сначала просто вынесите беспорядок на бумагу.

Обычно быстро проявляются две модели.

Первая — разные слова для одного и того же. Команда может почти взаимозаменяемо использовать "client", "customer" и "account". Человек часто догадывается о смысле по контексту. AI-инструмент часто не может, поэтому пишет связующий код, который сопоставляет не то поле или выбирает неправильное название для нового эндпоинта.

Вторая — одно слово с двумя смыслами. "Status" — классический пример. В одном тикете это состояние платежа. В UI — признак того, активен ли пользователь. В схеме — прогресс синхронизации. Когда одно слово выполняет несколько ролей, баги расползаются тихо.

Отмечайте оба типа проблем по мере просмотра списка. Обведите синонимы. Пометьте слова с двойным смыслом. Потом добавьте еще один столбец под названием "не использовать". Поместите туда любые названия, которые путают людей или провоцируют AI на неверные догадки.

Простой пример все проясняет. Если в одной функции в тикетах используется "project", в UI — "app", а в API — "workspace", выберите один термин для этого понятия и откажитесь от двух остальных. Если "project" уже означает что-то другое в другой части продукта, здесь его тоже запретите.

Работа кажется небольшой, но она сильно сокращает переделки. Как только команда может показать короткий список запрещенных слов, промпты становятся чище, сгенерированный код лучше совпадает с продуктом, а ревью проходит быстрее.

Выберите одно название для каждого понятия

Самый быстрый способ сократить баги с названиями — дать каждому бизнес-понятию одно утвержденное имя и использовать его везде. Если в приложении написано "account", так же должны говорить тикет, база данных и API. Как только команда разрешает два или три названия для одного и того же, AI начинает копировать этот беспорядок в обработчики, формы, тесты и миграции.

Берите слово, которое уже используют ваши клиенты. Внутренние термины часто звучат аккуратно для команды, но запутывают всех остальных. Если клиенты говорят "invoice", не переименовывайте его в "billing document" в схеме и в "charge record" в тикетах. AI будет воспринимать их как разные идеи, даже если люди имеют в виду одно и то же.

Это особенно важно, когда AI пишет связующий код, потому что модели следуют шаблонам, а не намерениям. Если в бэклоге написано "workspace", в UI — "team", а в правилах доступа — "organization", модель начнет гадать. Иногда она угадывает верно. Но часто создает наполовину смешанную версию, которая проходит ревью, потому что все названия выглядят знакомыми.

Оставляйте единственное и множественное число скучными. Используйте "user" и "users", а не "member" в одном месте и "people" в другом. Небольшие смещения быстро приводят к странным названиям условий, неловким именам таблиц и запутанному тексту для пустого состояния. Простая грамматика экономит время на уборку позже.

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

Такой маленький документ дает авторам, дизайнерам, разработчикам и AI-инструментам один и тот же источник правды.

Пограничные случаи не должны перетягивать на себя основное название. Если у одного клиента особый контракт, который меняет поведение "account", оставьте "account" основным названием и отметьте исключение. Новое понятие создавайте только тогда, когда бизнес-смысл действительно другой.

Частый пример — "lead", "prospect" и "contact". Многие команды используют все три слова очень свободно. Выберите одно для нужной стадии, определите, когда оно меняет состояние, и придерживайтесь этого варианта. Так у вас будут более чистые тикеты, более понятный UI и названия в схеме, которые все еще будут иметь смысл через шесть месяцев.

Чистите названия по шагам

Переименование работает лучше всего, когда вы начинаете с малого и исправляете слово, которое наносит больше всего вреда. Если в тикете написано "customer", в UI — "account holder", а в схеме — "client", AI часто склеивает эти термины, будто они означают одно и то же.

Не пытайтесь переименовать все сразу. Выберите понятие, которое создает больше всего переделок, вопросов в поддержке или неверных предположений на ревью, и исправьте его в первую очередь.

Начните с тикетов и заметок по критериям приемки. Именно эти тексты задают первый вариант кода, тестов и промптов. Если команда согласовала термин "billing contact", используйте его без изменений в заголовке, описании, крайних случаях и ожидаемом результате.

Потом переходите к UI. Подписи, вспомогательный текст, пустые состояния и сообщения об ошибках должны использовать то же слово, что было в тикете. Когда интерфейс меняет название, разработчики и AI-инструменты начинают гадать.

После этого исправьте слой данных. Имена таблиц, полей, полезной нагрузки API и событий должны указывать на одну и ту же идею, даже если точный синтаксис немного отличается. Поле вроде billing_contact_id гораздо понятнее, чем старое название, которое сейчас никто бы уже не выбрал.

Дальше добавьте один короткий пример, который показывает термин в контексте. Пример запроса, реалистичное сообщение формы или заметка вроде "Use billing contact for invoices and payment notices" дают будущим промптам меньше пространства для дрейфа.

И наконец, зафиксируйте решение в небольшом глоссарии. Делайте его простым и удобным для просмотра, чтобы авторы, дизайнеры, разработчики и AI-инструменты опирались на один и тот же источник.

Полезно одно простое правило: переименовывайте снаружи внутрь. Сначала человекочитаемый язык, потом технические названия. Такой порядок уменьшает путаницу, потому что смысл продукта становится ясен еще до того, как кто-то начнет править схемы или события.

Именно здесь работа начинает приносить пользу. Модель перестает пытаться переводить между смешанными подписями и начинает повторять правильный термин везде.

И еще одно предупреждение: вам не нужна идеальная чистота. Если столбец в базе данных пока нельзя менять, отметьте это в тикете и промпте. Сопоставьте старое поле с утвержденным продуктовым термином. Такой небольшой контекст может уберечь от недели лишней уборки позже.

Простой пример на одной функции

Ошибки в названиях очень быстро становятся дорогими, когда AI пишет связующий код.

Представьте, что команда добавляет новую onboarding-форму. В тикете написано: "Add company details so sales can track each new customer." Но в UI этот же объект уже отображается как "Client". В схеме базы данных используются account_id и accounts, потому что раньше в продукте это казалось логичным.

Инженер просит AI-инструмент собрать форму по тикету и подстроиться под существующую схему. Инструмент делает то, что делает обычно: копирует слова, которые видит. Он создает форму с подписью "Company", пишет сообщения валидации со словом "company" и сопоставляет отправку с account_id, потому что это ближайшее поле в схеме.

Теперь путаница расползается. Служба поддержки открывает админ-панель и видит "Client". Отдел продаж выгружает отчет и видит "Account". Клиентская форма говорит "Company". Все три слова указывают на одну запись, но с первого взгляда этого не понять. Простой вопрос вроде "Почему эта company не появилась в client report?" превращается в длинную переписку в Slack.

Больше всего обычно страдают отчеты, потому что их названия и фильтры часто повторяют термины из схемы. Следом страдает поддержка, потому что UI использует слова, которые видят клиенты. AI усугубляет проблему, повторяя несоответствие в каждом патче, тесте и вспомогательной функции. Он не путается по-человечески. Он просто буквально следует словам.

Исправление скучное, и именно поэтому команды его пропускают. Выберите один термин для этого понятия и используйте его везде, где с продуктом работают люди: в тикетах и заметках по приемке, в подписях и подсказках UI, в названиях схемы, полях API и фильтрах отчетов.

Если команда решит, что правильное слово — "client", тогда следующий тикет тоже должен говорить "client", форма — "client", а схема либо использует это название, либо хотя бы явно документирует account_id как внутреннее поле для записей клиентов. Теперь у AI есть один понятный путь, по которому можно идти.

Такое единственное решение очень просто сокращает переделки. Поддержка видит то же слово, что и продуктовая команда. Отчеты совпадают с экраном. Инженерам больше не приходится переводить термины в голове. Небольшие баги перестают размножаться еще до продакшена.

Ошибки, которые повторяются снова и снова

Команды часто переименовывают поле в коде, а потом забывают про старый шаблон тикета, чеклист QA или форму для поддержки. В коде уже написано "organization", в тикете по-прежнему — "account", и AI пишет связующий код, который пытается соединить оба варианта. Никто не замечает этого, пока отчет не выглядит неправильно или форма не сохранит данные не туда.

Именно поэтому дисциплина в названиях важна еще до того, как модель начнет писать обработчик, тест или миграцию. AI не останавливается и не спрашивает: "Здесь они имели в виду одно и то же?" Обычно он выбирает ближайший шаблон и идет дальше.

Частая проблема начинается с внутренних сокращений. Команды продукта или разработки говорят "org", "member" или "status", потому что в ежедневной работе это быстрее. Потом та же сокращенная форма просачивается в пользовательские тексты, админские экраны и поля API. Пользователь читает один смысл, команда имеет в виду другой, а модель копирует оба варианта в комментарии, названия переменных и текст интерфейса.

Расплывчатые слова наносят еще больший ущерб. "Item", "data", "record" и "info" кажутся безопасными, потому что подходят почти ко всему. В этом и проблема. Если в тикете написано "show item data in the dashboard", один человек представляет заказ, другой — товар, а AI может выдумать третий смысл из соседних файлов.

Две команды могут также незаметно разделить один термин. Продажи могут использовать "customer" для компании. Поддержка — "customer" для одного контактного лица. Если оба смысла появляются в тикетах и схемах, модель смешает их. В итоге код хранит человека в одной таблице, а везде остальном называет его как компанию.

Один маленький пример показывает, как это расползается. Команда меняет "workspace" на "project" в приложении, потому что пользователям так понятнее. Они обновляют UI, но старые шаблоны тикетов все еще говорят "workspace", а в схеме остается поле workspace_id. Позже кто-то просит AI привести формулировки к одному виду сразу на нескольких экранах. Модель меняет подписи на "project", но многие backend-имена оставляет как есть — и теперь тикеты поддержки, логи и выгрузки используют разные слова для одного и того же.

Просить AI исправить формулировки без списка словаря — обычно ошибка. Модель может отшлифовать текст, но не может выбрать язык вашего продукта за вас. Сначала дайте ей короткий утвержденный глоссарий. Иначе она будет просто воспроизводить ту путаницу, которая у вас уже есть.

Быстрые проверки перед релизом

Небольшие разрывы в названиях очень быстро превращаются в баги в продакшене, когда AI пишет код, который все соединяет. Модель копирует ближайший термин, который видит, даже если в UI написано "customer", в тикете — "account", а в таблице — "user".

Проведите один короткий проход проверки с человеком, который не делал эту функцию. Если он спотыкается на каком-то термине или использует другое слово, модель, скорее всего, сделает то же самое.

Попросите нового члена команды объяснить каждый основной термин простыми словами. Если двое людей по-разному определяют "account", "workspace" или "member", переименуйте это до выпуска.

Сравните подписи в UI и текст тикета слово в слово. Если на экране написано "Archive project", а в тикете — "Deactivate workspace", у вас либо два разных понятия, либо одно плохое название.

Проверьте названия в схеме и полях на соответствие бизнес-смыслу. Поле status часто слишком расплывчатое. invoice_payment_status сразу объясняет людям и инструментам, что оно означает.

Просмотрите промпты, комментарии и правила генерации. Оставляйте в инструкциях для AI только утвержденные термины, чтобы формулировки оставались единообразными.

Проверьте примеры, фикстуры, тесты и тестовые данные на старые синонимы. Один устаревший тест может научить модель неправильному названию и вернуть путаницу обратно.

Этот проход не занимает много времени. На небольшой функции он часто занимает 15–20 минут и экономит часы последующей уборки.

Хорошо работает простой тест: выберите одно действие в продукте и проследите его название через тикет, подпись на кнопке, поле API и тест-кейс. Если на одном шаге используется другое слово, исправьте это сразу. Не надейтесь, что AI-связка сама поймет замысел. Она обычно просто повторяет те формулировки, которые видит.

Команды, которые двигаются быстро, часто пропускают это, потому что приложение вроде бы работает. Потом служба поддержки использует один термин, дашборды — другой, а следующий промпт разносит несоответствие еще по большему числу файлов. Чистые названия — это не косметика. Они не дают маленьким языковым ошибкам стать поведением в продакшене.

Что делать дальше

Выберите одну функцию, над которой команда уже работает на этой неделе. Этого достаточно: экран оплаты, регистрация или правило возврата. Положите рядом тикет, текст интерфейса, поля API, названия в схеме, тестовые фикстуры и текст промпта. Обычно вы найдете два или три названия для одного и того же менее чем за 30 минут.

Потом запишите по одному утвержденному термину для каждого понятия. Сделайте это просто: название, короткое определение и любые старые названия, от которых людям нужно отказаться. Для AI-разработки такой маленький общий список часто полезнее длинного style guide. Он дает и людям, и моделям одну и ту же цель.

Сначала держите проверку узкой. Проверьте одну активную функцию. Выберите одно название для каждого повторяющегося понятия, даже если старый код пока использует другой термин. В том же проходе обновите промпты, комментарии, тестовые данные и тестовые фикстуры. Добавьте утвержденные названия в шаблоны тикетов, чтобы новая работа начиналась аккуратнее.

Сделайте это вместе с теми, кто действительно трогает функцию. Продукт может говорить "plan", поддержка — "subscription", а схема по-прежнему — "tier". Если никто не закроет это расхождение, AI и дальше будет копировать его в обработчики, тесты и админские экраны. Полдня на уборку могут сэкономить недели мелких исправлений.

Не нужно переименовывать весь продукт сразу. Начните с одной функции, доведите ее до ума и используйте как пример для следующей команды. Маленькие победы обычно закрепляются. Большая перепись названий чаще всего застревает.

Если проблема проходит через несколько команд, систем и AI-процессов, внешняя помощь может сэкономить время. Олег Сотников из oleg.is делает такую работу в формате Fractional CTO и консультаций для стартапов, особенно когда язык продукта, архитектура и AI-разработка переплетены между собой.

Хороший первый результат скромный: одна приведенная в порядок функция, один общий список названий и меньше шансов на то, что следующий тикет научит систему неправильным словам.