Research First Builder: как ИИ-агент изучает проекты до написания кода

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

Research First Builder — открытый инструмент IT Shelter, который задаёт агенту последовательность работы: изучить реальные источники, связать с ними решения, составить план, реализовать задачу и записать результаты проверок. В этой статье разберём устройство подхода на примере локального приложения и границы его проверок.

RFB состоит из скилла research-first-build и вспомогательной программы rfb.py. Скилл — папка с инструкциями и материалами для агента. Она описывает порядок исследования и разработки. Программа на Python проверяет, согласованы ли записи об источниках, решениях, плане и тестах.

Разделение важно: агент читает документацию, разбирает исходники и пишет приложение. Проверяющая программа следит за структурой сохранённых материалов. Она сама не изучает репозитории, не запускает команды из записей и не обращается к сети. Поэтому RFB не является отдельным сервисом, который самостоятельно выбирает архитектуру.

После работы в проекте остаются:

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

Рассмотрим три утверждения:

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

В RFB для таких записей предусмотрены разные категории доказательств: документация, изученная реализация, наблюдаемое поведение, вывод и пользовательское требование. У вывода указываются основания и границы. У наблюдения — то, что реально проверяли. Метка категории помогает читать отчёт, но не доказывает, что автор записи добросовестно исследовал источник.

Схема связей в материалах RFB. Условие проверки показано как пример; это не скриншот приложения или результата теста.

В репозитории есть отчёт о полном запуске на задаче Bookmarks. Задача была ограниченной: локальный менеджер для одного пользователя, URL, название, необязательные теги, поиск, редактирование и удаление. Без аккаунтов, облака, Docker и отдельной сборки фронтенда.

Агент изучал linkding, Buku и Shaarli. Результатом исследования стало несколько конкретных решений, а не перенос архитектуры одного из продуктов целиком.

ИсточникИзученное поведениеРешение для локальной задачиПарсер тегов linkdingУдаляет пустые значения, убирает дубли без учёта регистра; также преобразует пробелы внутри тегов и сортирует результатВзять удаление пустых значений и дублей. В новом приложении сохранить внутренние пробелы и первое написание тегаСхема Buku и операция вставкиИспользует SQLite с уникальным URL; в изученной операции вставки по умолчанию выполняется commitВыбрать локальное хранение и проверять, что изменения переживают перезапускСохранение ShaarliПерестраивает коллекцию, делегирует запись и сбрасывает кэшиОтказаться от этого жизненного цикла файловой коллекции для данной Python-задачи

Последнее решение не означает, что Shaarli ненадёжен. Атомарность лежащей ниже операции записи в этом исследовании не проверялась. Здесь зафиксирован отказ от переноса конкретного механизма в приложение с другим языком, масштабом и способом хранения.

В отчёте также отмечены отказ от автоматического получения метаданных и откладывание сложного языка запросов. Для этой задачи они не были необходимы. Такое ограничение объёма работы — самостоятельный результат исследования: не каждое найденное свойство аналога должно стать функцией нового продукта.

Для решения используются три понятных исхода:

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

REJECT — отклонить. Механизм рассмотрен, но не подходит: например, выходит за требования или добавляет лишние полномочия. Отказ относится к конкретной задаче, а не к качеству чужого проекта в целом.

DEFER — отложить. Сейчас механизм не нужен. В записи можно указать условие, при котором к нему стоит вернуться: например, появление нескольких независимых процессов или требования к фоновой обработке.

Если для небольшой задачи архитектурный паттерн вообще не требуется, допустим исход NO-PATTERN. В учебном примере обработки JSON Lines выбран прямой фильтр на стандартной библиотеке. RFB не требует добавлять сложность ради самого исследовательского процесса.

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

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

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

Начать можно с исследования без написания кода. Это позволяет оценить найденные источники и качество решений до большой работы.

Для установки через опубликованный пакет, из папки целевого проекта, в README приведена команда:

npx skills@1.7.0 add IT-Shelter-Labs/research-first-builder --skill research-first-build --agent codex --copy

Для этого способа нужен Node.js 22.20 или новее. Проверкам RFB нужен Python 3.11 или новее. Самому агенту требуется доступ к файлам проекта и источникам. Полная установка и варианты копирования папки описаны в русскоязычном README.

Пример первого запроса:

$research-first-build Исследуй аналоги локального менеджера закладок для одного пользователя: URL, название, теги, поиск и редактирование. Облако, аккаунты и Docker не нужны. research-only, quick depth; реализацию пока не начинай. Материалы сохраняй в docs/research-first/bookmarks.

Это пример постановки задачи, а не команда, гарантированно выдающая одинаковый результат у любого агента. После исследования стоит открыть отчёт и проверить несколько существенных мест: действительно ли источники изучены, соответствует ли вывод исходнику и не добавлены ли требования от имени пользователя.

Затем можно разрешить реализацию согласованного плана. Установка скилла и возможность выполнить весь процесс — разные вещи: доступ к модели, файлам и источникам зависит от используемой среды.

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

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

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

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

Исходники, примеры и ограничения доступны в репозитории Research First Builder. Какие решения в работе с ИИ-агентом вам чаще всего приходится просить обосновать: стек, хранение данных, зависимости или объём функций?

Разборы полезных репозиториев, инструменты и материалы о программировании и ИИ — в Telegram-канале IT_SHELTER.