RnD · Линия доказательств Technical R&D
Каталог и оглавление
TECH.IDX RnD/technical/README.md raw.md ->

Контракт технических исследований

Версия: 1.0
Действует с: 25 июля 2026 года

Этот контракт задаёт единый формат для технических исследований, в которых нужно не только изучить вопрос, но и предоставить исполнимое техническое решение. Его цель — сделать результат проверяемым, воспроизводимым и пригодным для продуктового решения независимо от того, подтвердилось предположение или нет.

Текущая серия по genre-neutral AI GameMaster собрана в карте исследований.

Контракт применяется ко всем новым папкам внутри RnD/technical/. Материалы в RnD/research/ и RnD/docs/ сохраняют существующий формат.

Нормативные слова#

  • Обязательно — без этого исследование не может получить финальный статус.
  • Рекомендуется — отступление допустимо, если причина записана в README.md исследования.
  • Допускается — элемент добавляется только когда он нужен конкретному исследованию.

Единица исследования#

Одно исследование отвечает на один проверяемый технический вопрос и живёт в одной папке:

RnD/technical/YYYY-MM-DD-kebab-case-slug/

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

Если вопрос нельзя оценить одним набором критериев успеха, его нужно разделить на несколько исследований. Обзор нескольких технологий допустим, если все они сравниваются для одного решения.

Обязательная структура#

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. Отрицательное или неопределённое исследование считается завершённым, если оно воспроизводимо и честно фиксирует границы знания.

Обычный переход:

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/.
  2. Переименовать копию в YYYY-MM-DD-kebab-case-slug.
  3. Заполнить вопрос, scope и критерии успеха до написания прототипа.
  4. Установить Status: active.
  5. Вести журнал по мере экспериментов, а не восстанавливать его задним числом.

Шаблон задаёт минимальный состав. Ненужные необязательные разделы можно удалить; обязательные разделы нельзя заменять ссылкой на устное обсуждение или внешний чат.