# Контракт технических исследований Версия: **1.0** Действует с: **25 июля 2026 года** Этот контракт задаёт единый формат для технических исследований, в которых нужно не только изучить вопрос, но и предоставить исполнимое техническое решение. Его цель — сделать результат проверяемым, воспроизводимым и пригодным для продуктового решения независимо от того, подтвердилось предположение или нет. Текущая серия по genre-neutral AI GameMaster собрана в [карте исследований](STUDY-MAP.md). Контракт применяется ко всем новым папкам внутри `RnD/technical/`. Материалы в `RnD/research/` и `RnD/docs/` сохраняют существующий формат. ## Нормативные слова - **Обязательно** — без этого исследование не может получить финальный статус. - **Рекомендуется** — отступление допустимо, если причина записана в `README.md` исследования. - **Допускается** — элемент добавляется только когда он нужен конкретному исследованию. ## Единица исследования Одно исследование отвечает на **один проверяемый технический вопрос** и живёт в одной папке: ```text RnD/technical/YYYY-MM-DD-kebab-case-slug/ ``` Дата — день начала исследования. Имя папки после создания не меняется: оно служит стабильным идентификатором для ссылок из PRD, задач и других исследований. Если вопрос нельзя оценить одним набором критериев успеха, его нужно разделить на несколько исследований. Обзор нескольких технологий допустим, если все они сравниваются для одного решения. ## Обязательная структура ```text YYYY-MM-DD-kebab-case-slug/ ├── README.md ├── RESEARCH.md ├── SOLUTION.md ├── VALIDATION.md └── prototype/ ├── исходный код ├── тесты └── файлы запуска и зависимостей ``` Допускаются дополнительные каталоги: - `artifacts/raw/` — неизменённые ответы, логи, трассы и исходные измерения; - `artifacts/derived/` — вычисленные таблицы, отчёты и графики; - `fixtures/` — безопасные тестовые входные данные; - `docs/` — дополнительные схемы или объёмные заметки, если четырёх основных документов недостаточно. Не нужно создавать пустые дополнительные каталоги «на будущее». ## Назначение обязательных файлов ### `README.md` — паспорт и решение Содержит: - статус, исход и даты; - проверяемый вопрос; - границы и явно исключённые задачи; - критерии успеха, зафиксированные до реализации; - ссылки на остальные документы и основной код; - краткий итог, ограничения и следующий продуктовый шаг. `README.md` должен позволять понять итог исследования без чтения полного журнала, но каждый существенный вывод в нём должен ссылаться на доказательство в `RESEARCH.md` или `VALIDATION.md`. ### `RESEARCH.md` — метод и доказательства Содержит: - исходное состояние и baseline; - метод исследования; - реестр источников и измерений; - журнал экспериментов, включая неудачные попытки; - факты, измерения, выводы, гипотезы и неизвестные; - рассмотренные альтернативы и причины отказа. ### `SOLUTION.md` — техническое решение Содержит: - выбранный подход и его границы; - архитектуру или поток данных; - структуру прототипа; - точные команды установки, запуска и тестирования; - конфигурацию без секретов; - известные ограничения; - условия, при которых прототип можно переносить в production-код. ### `VALIDATION.md` — проверка результата Содержит: - окружение и версии; - соответствие каждого критерия успеха фактической проверке; - точные команды и наблюдаемый результат; - baseline и candidate-метрики, если исследование измерительное; - ошибки, нестабильность и ограничения воспроизводимости; - финальный исход с обоснованием. ### `prototype/` — исполнимое доказательство Прототип обязан проверять главный технический риск, а не имитировать готовый продукт. Он должен запускаться из чистого checkout по инструкции в `SOLUTION.md`. Прототип: - использует минимальный объём кода и зависимостей, достаточный для проверки; - содержит поведенческую проверку основного утверждения; - не содержит ключей, токенов, персональных данных и других секретов; - фиксирует зависимости стандартным для выбранного стека способом; - не импортируется в production-код молча: перенос требует отдельного решения и обычного production-review. Если решение невозможно выразить кодом, вместо `prototype/` допускается другой исполняемый артефакт — например, конфигурация инфраструктуры, benchmark harness или схема с валидатором. Причина и команда проверки обязательны в `SOLUTION.md`. ## Статусы и исходы Поле `Status` принимает только одно из значений: | Status | Значение | |---|---| | `proposed` | вопрос и критерии ещё формируются | | `active` | исследование и прототипирование идут | | `blocked` | продолжение зависит от явно записанного внешнего условия | | `complete` | документы и код готовы, проверки выполнены | | `archived` | исследование заменено или утратило актуальность | Поле `Outcome` принимает только одно из значений: | Outcome | Значение | |---|---| | `pending` | финального вывода ещё нет | | `pass` | все обязательные критерии выполнены | | `partial` | решение полезно, но часть критериев не выполнена | | `fail` | подход не справился с обязательными критериями | | `inconclusive` | данных недостаточно для решения | `complete` не означает `pass`. Отрицательное или неопределённое исследование считается завершённым, если оно воспроизводимо и честно фиксирует границы знания. Обычный переход: ```text proposed -> active active <-> blocked active -> complete complete -> archived ``` ## Контракт доказательности Каждое существенное утверждение помечается одним из типов: - **Fact** — подтверждено первичным источником, спецификацией или наблюдаемым свойством системы; - **Measurement** — получено указанной командой в записанном окружении; - **Inference** — аналитический вывод из перечисленных фактов или измерений; - **Hypothesis** — проверяемое предположение; - **Unknown** — данных пока нет или они недостаточны. В `RESEARCH.md` каждому источнику или измерению присваивается стабильный ID `E-001`, `E-002` и так далее. Итоговые выводы ссылаются на эти ID. Для внешнего источника обязательны URL, дата доступа и применимая версия. Для локального доказательства обязательны путь, команда или commit SHA, если результат зависит от конкретного состояния кода. Нельзя: - выдавать отсутствие данных за отрицательный результат; - выдавать единичный успешный запуск за надёжность; - заменять измерение оценкой «на глаз»; - удалять неудачные попытки из журнала; - менять критерии успеха после получения результата без отдельной записи с причиной и временем изменения. ## Контракт воспроизводимости До начала реализации в `README.md` фиксируются критерии успеха и способ их проверки. После реализации другой разработчик должен суметь: 1. установить зависимости по `SOLUTION.md`; 2. запустить прототип одной основной командой; 3. выполнить проверки из `VALIDATION.md`; 4. получить тот же качественный вывод в заявленных допусках. Обязательно записываются: - OS, runtime, ключевые версии библиотек и внешних сервисов; - необходимые аппаратные и сетевые условия; - seed и число прогонов для стохастических экспериментов, если применимо; - входные данные и способ их получения; - фактический вывод команд, метрики или ссылки на локальные artifacts; - допустимый диапазон отклонения для нестабильных измерений. Для AI/model-экспериментов дополнительно записываются model ID, системная инструкция или её локальный путь, параметры генерации, число прогонов, latency/token/cost measurements и сырые ответы, если их сохранение допустимо. Секреты и чувствительные пользовательские данные в artifacts не сохраняются. ## Как изменять исследование - Существенное изменение вопроса создаёт новое исследование. - Новый способ проверить тот же вопрос добавляется в текущую папку и журнал. - Повторная проверка после обновления модели, библиотеки или инфраструктуры добавляется отдельным разделом с новой датой и окружением. - Устаревшее исследование не переписывается под новый результат: оно получает `archived` и ссылку на замену. - Синхронизированные материалы в `RnD/sources/` не изменяются. Нужные локальные evidence artifacts сохраняются внутри папки исследования, если это разрешено лицензией и политикой данных. ## Definition of Done Исследование может получить `Status: complete`, только если: - [ ] вопрос, scope и критерии успеха сформулированы; - [ ] все четыре обязательных Markdown-файла заполнены; - [ ] основной технический риск проверяется исполнимым артефактом; - [ ] установка, запуск и проверки описаны точными командами; - [ ] каждый критерий успеха имеет результат и evidence-ссылку; - [ ] неудачные попытки и ограничения сохранены; - [ ] секреты и чувствительные данные отсутствуют; - [ ] `Outcome` обновлён и не равен `pending`; - [ ] следующий шаг сформулирован как решение, а не как расплывчатое «исследовать дальше»; - [ ] из корня репозитория проходит `npm run check`. ## Начало нового исследования 1. Скопировать каталог [`_template/`](_template/). 2. Переименовать копию в `YYYY-MM-DD-kebab-case-slug`. 3. Заполнить вопрос, scope и критерии успеха до написания прототипа. 4. Установить `Status: active`. 5. Вести журнал по мере экспериментов, а не восстанавливать его задним числом. Шаблон задаёт минимальный состав. Ненужные необязательные разделы можно удалить; обязательные разделы нельзя заменять ссылкой на устное обсуждение или внешний чат.