Контекст проекта для ИИ: артефакты, которые держат качество

Почему ответы ИИ со временем становятся нестабильными

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

Противоречия чаще всего приходят из трех мест.

Во-первых, переписка. Важные детали тонут в обсуждениях, а новые сообщения иногда перетирают старые договоренности.

Во-вторых, требования меняются по чуть-чуть. Вы добавили исключение "на один кейс", потом еще одно, и картина перестала быть цельной.

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

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

Простой пример: в мини-CRM сначала был статус "Новая". Потом в обсуждении появляется "В работе", а через время кто-то пишет "Взято". ИИ честно подставляет каждый вариант в разные места, и получается хаос.

Признаки, что проектного контекста не хватает:

• ИИ задает одни и те же уточняющие вопросы в похожих задачах.
• В разных ответах появляются разные названия сущностей и статусов.
• Предлагаются новые поля, хотя вы их не обсуждали.
• Экран и API "не сходятся" по данным.
• Тексты в UI скачут по тону и формулировкам.

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

Что считать контекстом проекта и как его организовать

Контекст для ИИ - это не ТЗ на 40 страниц. Это набор коротких, согласованных документов, которые отвечают на одни и те же вопросы одинаково сегодня и через несколько недель.

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

Держите все в одном источнике правды. Это может быть репозиторий с папкой docs или отдельное пространство, но с понятной структурой и датой обновления. Команда должна знать: "если есть спор, смотрим сюда", а не "у каждого своя заметка". Если вы собираете продукт в TakProsto, такие артефакты удобно хранить рядом с проектом и обновлять по мере изменений.

Чтобы документы не превратились в свалку, достаточно нескольких правил: у каждого артефакта есть владелец, единый шаблон, версия и дата в начале, и короткая история изменений на пару строк. Рядом полезно держать один пример "как правильно", чтобы не спорить о формате.

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

Минимальный набор артефактов без лишнего

Чтобы ИИ не зависел от формулировки запроса и не придумывал детали, ему нужны опоры, которые легко поддерживать. Обычно достаточно пяти документов:

• словарь домена (термины, сущности и запреты на синонимы)
• примеры данных (типовые записи, границы и ошибки)
• карта экранов и ключевые сценарии (что где находится и какие шаги делает пользователь)
• правила UI (стиль, поведение форм, ошибки, загрузка)
• контракт API (поля, типы, статусы, ошибки)

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

На старте можно не писать полную архитектуру, детальные UML-диаграммы, все edge cases и длинные тексты про миссию продукта. Это полезно, но чаще всего меньше влияет на стабильность, чем пять опор выше. Начните с черновиков на 1-2 страницы и дополняйте по фактам.

По формату лучше выбирать то, что проще поддерживать: Markdown с заголовками, короткие таблицы (сущность, поля, правила, пример) и схема экранов в виде списка "Экран -> цель -> действия".

Словарь домена: чтобы все называлось одинаково

Если в одном месте вы пишете "заявка", в другом "лид", а в третьем "обращение", ИИ начнет менять слова, поля и даже логику. Хороший словарь домена фиксирует значения и убирает двусмысленность.

Словарь не должен быть большим. Обычно хватает 1-3 страниц, где вы задаете правила языка проекта и явно запрещаете спорные замены.

Практичный состав:

• 15-40 ключевых терминов, каждое определение - 1-2 предложения
• роли пользователей простыми словами: кто что видит и что может делать
• статусы и этапы: значения и правила переходов (что можно и что нельзя)
• синонимы и запреты: чем можно заменять, а какие названия нельзя использовать
• нотации: как вы пишете даты, деньги, телефоны, идентификаторы, единицы измерения

Полезный формат записи для каждой сущности:

Сущность: Заявка
Определение: запрос клиента на услугу, который проходит обработку до закрытия.
Поля: id, created_at, источник, клиент, тема, описание, ответственный, статус, сумма
Связи: клиент (1), комментарии (N), файлы (N)
Правила: статус меняет только менеджер; закрытую заявку нельзя редактировать; сумма в RUB
Синонимы: нельзя говорить «лид»; допускается «обращение» только в тексте уведомлений

Отдельно зафиксируйте цепочку статусов и запреты. Например: "Новая -> В работе -> Ожидает клиента -> Закрыта" и правило "из Закрыта переходов нет". Такие мелочи чаще всего и ломают стабильность.

Примеры данных: что именно считать корректным

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

Для каждой ключевой сущности подготовьте несколько коротких наборов. Обычно хватает 3-5 типовых примеров, но они должны быть разными, не только "идеальные". Например, для "Заявки" в простой CRM: новая заявка с минимумом полей, заявка в работе с исполнителем, закрытая заявка с причиной отказа.

Минимум для одной сущности:

• 3-5 нормальных примеров (реалистичные значения, не test1)
• 2-3 граничных случая (пусто, максимум длины, необычный формат)
• 2-3 плохих примера (что отклоняем и почему)
• небольшой набор тестовых пользователей (роли, права, часовой пояс)
• 3-5 тестовых сценариев на этих данных (создать, изменить, закрыть)

Граничные случаи спасают от сюрпризов: "телефон только с +7", "комментарий до 500 символов", "дата в ISO-формате", "сумма без копеек". Плохие данные важны, чтобы ИИ не "разрешал" то, что вы потом запретите в валидации.

Чтобы примеры было легко переиспользовать, называйте их одинаково:

• имя сущности + цель: Заявка - создание - минимальная
• статус: valid или invalid
• ожидаемый результат: "принять", "отклонить", "автозаполнить поле X"
• версия: v1, v2 (когда меняются правила)

Так примеры становятся якорями: их легко вставлять в новые задачи и сравнивать после изменений.

Карта экранов и сценарии: чтобы ИИ не придумывал UI

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

Удобный формат - короткий документ, где каждый экран описан одинаково. На один экран обычно достаточно:

• название, цель и кто видит (роль)
• основной сценарий: как пользователь попадает и что делает
• альтернативы: редкие переходы
• состояния: загрузка, пусто, ошибка, успех, нет прав
• действия: какие кнопки и поля доступны, что считается подтверждением

Важно описывать переходы конкретно: "Экран Заявки (список) -> нажать строку -> Экран Заявки (детали)". Тогда ИИ реже добавляет лишние шаги и не меняет порядок.

Полезно отдельно зафиксировать то, что одинаково на всех экранах: шапка, навигация, общий стиль подтверждения действий. Это снижает хаос в генерации и ускоряет сборку.

Правила UI: единый стиль и предсказуемое поведение

Без правил UI модель легко начинает "улучшать" интерфейс: менять подписи кнопок, по-разному оформлять таблицы и формы, добавлять новые варианты поведения. Чтобы этого не было, достаточно короткого документа, который отвечает на повторяющиеся вопросы.

Сфокусируйтесь на самых частых элементах и спорных местах:

• кнопки: основные и второстепенные, когда отключаем, что показываем при загрузке
• формы: обязательные поля, подсказки, автозаполнение, маски ввода
• таблицы: сортировка, пустые состояния, пагинация, действия в строке
• модальные окна: заголовок, кнопки "Отмена/Сохранить", закрытие по Esc
• уведомления: успех и ошибка, где показываем, сколько держим на экране

Отдельно закрепите тон текстов и шаблоны ошибок. Ошибка должна говорить, что не так и что сделать: не "Некорректно", а "Введите телефон в формате +7 900 000-00-00".

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

Базовая доступность тоже помогает стабильности: логичный порядок фокуса по Tab, Enter отправляет форму, у модалки есть фокус-ловушка, у полей понятные подписи.

Контракт API: чтобы данные и UI совпадали

Без четкого API-контракта быстро появляются "мелкие" расхождения: UI ожидает одно, сервер отдает другое, а ИИ каждый раз угадывает по-разному.

Описывайте API так, чтобы это читалось как правила игры: какие сущности есть, что с ними можно делать, что считается ошибкой. Тогда при генерации экранов, форм и таблиц модель будет опираться на факты.

Минимум, который чаще всего ломается:

• ресурсы и операции: list/get/create/update/delete (например, /leads)
• поля и типы: обязательность, форматы, ограничения, значения по умолчанию
• ошибки и коды: 401, 403, 404, 409, 422 и как это показываем в UI
• пагинация, фильтры, сортировка: единый подход и имена параметров
• версионирование: что считается изменением контракта и как вы его вводите

Короткий пример: если статус заявки хранится как enum (new, in_work, closed), UI не должен рисовать "Проигнорировано" без серверной поддержки. Если сервер возвращает 409 при попытке закрыть уже закрытую заявку, UI показывает понятное сообщение и предлагает обновить карточку.

Версионирование держите простым: переименование поля, смена типа или смысла значения - это изменение контракта. Надежнее добавлять новые поля и постепенно выводить старые, чем "тихо" менять поведение.

Пример: простая CRM для заявок и ее контекст

Представьте CRM: клиенты оставляют заявки, менеджеры берут их в работу, меняют статусы и фиксируют результат. Чтобы контекст не расползался, вы фиксируете несколько опор.

Словарь домена (фрагмент) может быть коротким, но строгим:

• Заявка (lead) - единица работы. Не называем ее "обращение" или "тикет".
• Клиент - человек или компания, кто оставил заявку. Не используем "контрагент".
• Менеджер - сотрудник, который обрабатывает заявку.
• Статус заявки: new, in_progress, waiting_customer, won, lost. Запрещены "в обработке", "закрыта" как свободный текст.

Дальше - 2-3 примера данных: один корректный и один проблемный, чтобы видеть границы.

{
  "ok": {
    "id": 1432,
    "client": {"name": "ООО Север", "phone": "+7 999 123-45-67"},
    "source": "site",
    "status": "in_progress",
    "assigned_manager_id": 12,
    "created_at": "2026-01-12T10:15:00+03:00"
  },
  "problem": {
    "id": "1432a",
    "client": {"name": "Север", "phone": "999123"},
    "status": "в обработке",
    "assigned_manager_id": null
  }
}

Карта экранов фиксирует границы UI. Часто хватает 5-7 страниц: список заявок, карточка, создание, редактирование, справочник статусов (только админ), пользователи и роли.

Пара правил UI закрепляет поведение: статус меняется только через выпадающий список, телефон вводим в формате +7 XXX XXX-XX-XX, а пустой менеджер означает "не назначено" и отображается бейджем.

И кусок API-контракта для заявок фиксирует ожидания между фронтом и беком:

GET /api/leads?status=in_progress&manager_id=12
PATCH /api/leads/{id}  {"status":"waiting_customer","assigned_manager_id":12}

Как собрать контекст быстро и не растянуть на месяц

Лучше собрать 80% за 2-3 коротких встречи, чем месяц полировать папку, которую никто не обновляет. Сфокусируйтесь на том, что сильнее всего влияет на точность: термины, статусы, экраны, правила, данные.

План на неделю без героизма:

• 60 минут с владельцем продукта на словарь домена: 20-40 терминов, как они называются в UI и что означают.
• Статусы и переходы: таблица "статус -> куда можно -> кто может -> какие поля обязательны".
• Карта экранов и состояния: пусто, загрузка, ошибка, нет прав, успех.
• 10-20 UI-правил, которые чаще всего ломаются: форматы дат, обязательные поля, тексты ошибок, поведение кнопок.
• API-контракт для ключевых операций: поля запроса, ответ, ошибки.

Проверка простая: попросите ИИ собрать один типовой сценарий от начала до конца. Если он путает термины или "придумывает" экран, значит где-то нет опоры.

Чтобы контекст не терялся, назначьте владельцев и ритм обновлений. Например: словарь и статусы обновляет продукт раз в 2 недели, UI-правила подтверждает дизайнер при любом изменении компонентов, API-контракт обновляет разработчик перед релизом. Добавляйте дату последнего обновления и 3-5 недавних изменений в начале документа - это резко снижает расползание.

Частые ошибки, из-за которых контекст не работает

Контекст начинает "сыпаться", когда документы разъехались с реальностью: появились новые поля, переименования, новые экраны, а артефакты остались прежними.

Самые частые ошибки:

• смешивание терминов: одна сущность называется по-разному в разных местах, и ИИ плодит лишние сущности и связи
• слишком общие UI-правила без примеров: "делаем просто" не помогает
• примеры данных не похожи на жизнь: в реальности есть пустые поля, дубляжи и разные форматы, а в примерах все идеально
• API описан словами, без точных полей, типов и ошибок, и UI начинает расходиться с сервером
• нет владельца и истории изменений, поэтому никто не поддерживает документы

Типичный сценарий: вы добавили статус "Ожидает клиента", но не обновили словарь, примеры и контракт. Через неделю ИИ снова генерирует фильтры по старым статусам и формы без нового поля.

Лекарство простое: один источник правды, дата обновления, и правило "любое изменение в продукте тянет обновление словаря, примеров, карты экранов и API-контракта".

Короткий чеклист перед новым запросом

Быстрая проверка занимает около 10 минут и заметно снижает шанс, что ИИ запутается в названиях, экранах и данных:

• цель на 1 абзац: что делаем сейчас (экран, эндпоинт, сценарий) и что считается готовым
• 5-10 ключевых сущностей: как называются в UI и в данных
• 2-3 реальных (обезличенных) примера данных, включая крайний случай
• список экранов и переходов: откуда пользователь приходит и куда уходит после действия
• 3-5 ограничений UI и 3-5 правил валидации или статусов, без двусмысленностей

Если требования поменялись, сначала обновляйте то, что влияет на смысл и совместимость: словарь домена (названия и статусы) и контракт API (поля, типы, ошибки). Потом уже правьте сценарии и UI-правила.

Понять, что артефакт устарел, легко по симптомам: ИИ предлагает несуществующие поля, возвращает старые статусы, рисует лишние кнопки, или вы все чаще пишете "не так, как в прошлый раз". Если вы два раза подряд исправляете один и тот же тип ошибки, лучше переписать артефакт, а не компенсировать подсказками.

Если вы работаете в TakProsto, полезная привычка - фиксировать изменения в режиме планирования, а перед крупной генерацией делать снимок проекта. Так проще держать единые правила в актуальном виде и быстро возвращаться к стабильной версии, если что-то поплыло.