Практические заметки: Разработка функций с использованием подагентов Gemini CLI

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

Приложение

Этап разработки приложения работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Закрепите интерпретатор и файл блокировки зависимостей перед тем, как объяснять работу циклов. Различия в настройках между ноутбуком и системой CI являются наиболее распространенной причиной скрытых сбоев в демонстрациях API.

Запрос на новую функцию

Этап запросов на новые функции работает наилучшим образом, когда его рассматривают как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия всем элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Фиксируйте версию интерпретатора и файлы с информацией о зависимостях до того, как начнёте использовать циклы. Различия в конфигурациях между ноутбуком и средой CI являются наиболее распространённой причиной скрытых сбоев в демонстрациях API.

Пайплайн

Этап пайплайна работает наилучшим образом, когда его рассматривают как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию до расширения объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Фиксируйте версию интерпретатора и файлы блокировки зависимостей перед тем, как объяснять работу циклов. Различия между ноутбуком и средой CI являются наиболее распространённой причиной скрытых сбоев в демонах API. Этап пайплайна работает наилучшим образом, когда его рассматривают как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию до расширения объёма работ. Документируйте как успешный путь выполнения, так и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

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

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

Запуск пайплайна

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

Этап 1: архитектор

На этапе архитектуры 1 необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Разделяйте процесс создания клиента от цикла обработки сообщений, чтобы можно было заменять поставщиков без переписывания машины состояний обмена сообщениями. На этапе архитектуры 1 необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

Этап 2: разработка функций

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

Этап 3: одновременная работа над безопасностью, тестами и документацией

При работе над этапом тестирования безопасности 3-й стадии сначала запишите контракт: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успешности и не допускайте молчаливого частичного выполнения задачи. Записывайте идентификатор запроса, идентификатор модели и время задержки при каждом вызове. Без такой записи периодические ошибки поставщика будут выглядеть как баги приложения.

Этап 3.5: browser_agent

При работе над этапом Stage 3 5 browseragent сначала запишите условия взаимодействия: необходимые параметры ввода, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Записывайте время выполнения операций, стоимость токенов или запросов рядом с результатами их работы. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды. Ведите журнал с информацией об идентификаторе запроса, идентификаторе модели и времени задержки при каждом вызове. Без такой отчетности периодические ошибки поставщика могут выглядеть как баги приложения. При работе над этапом Stage 3 5 browseragent сначала запишите условия взаимодействия: необходимые параметры ввода, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Одновременно задокументируйте успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки со стороны оператора и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки.

{
  "agents": {
    "overrides": {
      "browser_agent": { "enabled": true }
    },
    "browser": {
      "sessionMode": "isolated",
      "headless": false,
      "allowedDomains": ["localhost"],
      "blockFileUploads": true,
      "confirmSensitiveActions": false
    }
  }
}

Этап 4: проверка кода

Этап проверки кода на этапе 4 работает наилучшим образом, когда его рассматривают как измеримую область. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-либо шаг срабатывает некорректно, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Закрепите интерпретатор и файл с информацией о зависимостях до того, как начнёте объяснять работу циклов. Различия в настройках между ноутбуком и системой CI являются наиболее распространённой причиной скрытых сбоев в демонстрациях API.

Что вы видели

Этот этап «То, что вы увидели», наилучшим образом функционирует, когда его рассматривают как измеримую поверхность. Соберите один пример успешного выполнения, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Фиксируйте версию интерпретатора и файлы блокировки зависимостей перед тем, как объяснять работу циклов. Различия между лаптопом и средой CI являются наиболее распространенной причиной скрытых сбоев в демонстрациях API.

Чек-лист операций

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

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

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

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

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

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

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

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

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

Деталь укрепления 0/874: измерьте время выполнения, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменение на основе фиксированного набора вопросов, а не на основе единичных примеров.

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

Деталь укрепления 0/893: измерьте время выполнения, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменение на основе фиксированного набора вопросов, а не на основе единичных примеров.

На этапе 1 процедуры укрепления безопасности необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Считайте этот этап договором между входными данными и проверенными результатами. Дайте названия создаваемым объектам, определите критерии успеха и не допускайте молчаливого частичного выполнения задачи.

Подробности укрепления безопасности 1/893: измерьте время выполнения, класс ошибок и расход токенов для данной процедуры, затем решите, следует ли сохранять изменения, исходя из установленного набора критериев, а не из единичных примеров.