Слеш-команда Codex CLI /agent применяется для переключения на ветку агента и работы с созданными субагентами: она помогает отделить самостоятельную линию выполнения задачи от основного диалога и не смешивать несколько направлений работы в одну бесконечную переписку. Это особенно полезно, когда нужно поручить агенту исследование, анализ кода, подготовку изменений или проверку гипотезы, а самому сохранить контроль над основной задачей.
Ветка агента — это не просто новый экран чата. Она представляет отдельный контекст работы, в котором агент может сосредоточиться на конкретной подзадаче, не перегружая главный сеанс лишними деталями.
На практике /agent удобна в проектах, где одна большая задача распадается на несколько независимых частей: например, один агент изучает структуру репозитория, второй анализирует тесты, а основной сеанс занимается планированием изменений. При этом важно понимать разницу между веткой субагента, копией или ответвлением чата и восстановлением уже сохранённого сеанса: внешне эти действия могут казаться похожими, но предназначены они для разных рабочих сценариев.
- Как использовать /agent в Codex CLI
- Базовый порядок действий
- Как формулировать задачу для субагента
- Как контролировать изменения
- Когда применять /agent
- Когда ветка агента действительно экономит время
- Когда лучше не использовать /agent
- Примеры работы с /agent
- Пример 1. Исследование незнакомого репозитория
- Пример 2. Поиск причины ошибки
- Пример 3. Подготовка тестов без изменения производственного кода
- Пример 4. Сравнение вариантов реализации
- Пример 5. Безопасная подготовка массового изменения
- Чем /agent отличается от других команд
- Команда /subagents
- Команда /fork
- Команда /resume
- Ветка субагента, ответвление чата и сохранённый сеанс
- Как выбрать правильную команду
Как использовать /agent в Codex CLI
Этот раздел важен потому, что правильное применение команды начинается не с запоминания одной комбинации символов, а с понимания её модели работы. Сначала нужно определить, какую часть задачи следует вынести в отдельную ветку, затем выбрать существующего субагента или создать рабочий контекст, передать ему понятную цель и после этого использовать полученный результат в основном процессе.
Хорошая работа с агентами начинается с чётко ограниченной задачи: чем понятнее границы поручения, тем полезнее результат и тем меньше времени уйдёт на исправление недоразумений.
Обычно команду вызывают непосредственно в интерактивной сессии Codex CLI, вводя /agent в строке команд. Конкретный экран выбора, список доступных агентов, названия пунктов меню и дополнительные параметры могут зависеть от версии CLI, настроек проекта и включённых возможностей. Поэтому при расхождении интерфейса следует проверить встроенную справку командой /help или документацию именно той версии, которая установлена в окружении.
| Элемент работы | Что означает | Практический вопрос |
|---|---|---|
| Основной сеанс | Главный контекст, в котором пользователь формулирует общую цель и принимает решения | Какой результат нужен проекту целиком? |
| Ветка агента | Отдельная линия выполнения, связанная с конкретным субагентом или задачей | Что можно исследовать независимо? |
| Субагент | Исполнитель, которому поручается ограниченная подзадача | Какие действия агент должен выполнить? |
| Результат | Выводы, найденные файлы, предложения, изменения или отчёт | В каком виде нужно вернуть итог? |
| Слияние решения | Использование выводов агента в основном рабочем процессе | Что из результата действительно стоит принять? |
Базовый порядок действий
Перед запуском агента полезно сформулировать задачу в одном-двух предложениях. Поручение «разберись с проектом» слишком расплывчато: агент может потратить время на обзор файлов, который не поможет решить проблему. Гораздо лучше указать конкретную область, ожидаемый результат и ограничения.
- Откройте нужный проект и убедитесь, что Codex CLI работает в правильном каталоге.
- Определите отдельную подзадачу, которую не обязательно выполнять в основном диалоге.
- Введите
/agent. - Выберите подходящую ветку или субагента, если интерфейс показывает список доступных вариантов.
- Передайте задачу с указанием контекста, файлов, ограничений и формата результата.
- Проверьте вывод агента и решите, какие предложения использовать в основной ветке.
Если команда открывает меню, не следует выбирать первый пункт автоматически. Сначала посмотрите, какие ветки уже существуют, какие из них активны и не выполняют ли они похожую работу. Два агента, одновременно анализирующие один и тот же файл, редко ускоряют процесс: чаще они создают два отчёта с частично совпадающими, а иногда противоречивыми выводами.
| Часть поручения | Слабая формулировка | Более полезная формулировка |
|---|---|---|
| Цель | Посмотри авторизацию | Найди причину отказа при обновлении access-токена |
| Область | Проверь backend | Изучи src/auth и связанные тесты |
| Ограничения | Исправь как-нибудь | Не меняй публичный API и не добавляй новые зависимости |
| Результат | Напиши, что думаешь | Составь список причин, укажи подтверждающие файлы и предложи минимальный патч |
Как формулировать задачу для субагента
Субагенту особенно полезны указания о том, что нужно делать, а чего делать не нужно. Если требуется только исследование, это следует написать прямо: «не изменяй файлы, подготовь отчёт». Если нужен патч, стоит указать, какие тесты запустить и как сообщить о результатах.
- Контекст: название проекта, модуль, проблемный сценарий.
- Цель: вопрос, на который требуется ответ, или изменение, которое нужно выполнить.
- Границы: файлы, каталоги, запреты и допустимый масштаб изменений.
- Проверка: тесты, линтер, сборка или ручной сценарий.
- Формат ответа: краткий вывод, подробный отчёт, список файлов или готовый патч.
Полезно также просить агента отделять подтверждённые факты от предположений. Например, найденная строка в трассировке — факт, а гипотеза о том, почему она появилась, требует проверки. Такое разделение делает отчёт заметно надёжнее и помогает не принять красивое объяснение за доказанную причину.
| Тип указания | Пример | Зачем нужен |
|---|---|---|
| Только анализ | Не редактируй файлы, подготовь отчёт | Предотвращает неожиданные изменения |
| Разрешение на изменения | Измени только тесты в tests/api |
Ограничивает область действия |
| Критерий готовности | Запусти тесты для модуля и укажи результат | Помогает проверить итог |
| Формат ответа | Верни три причины по степени вероятности | Упрощает последующее принятие решения |
Как контролировать изменения
Ветка агента не отменяет обычные инженерные привычки. Перед поручением, связанным с редактированием кода, полезно проверить состояние рабочего дерева, понять текущую ветку Git и убедиться, что незакоммиченные изменения не будут случайно смешаны с результатом агента.
Если агент предлагает существенные изменения, рассматривайте их как предложение к проверке, а не как автоматически правильное решение. Просмотрите diff, проверьте тесты, оцените обратную совместимость и отдельно убедитесь, что в проект не попали временные файлы, отладочные сообщения или изменения, которых не было в задаче.
| Проверка | Что искать | Когда выполнять |
|---|---|---|
| Рабочее дерево | Существующие незакоммиченные изменения | До запуска агента |
| Границы diff | Файлы вне заявленной области | После работы агента |
| Тесты | Новые падения и нестабильные сценарии | После изменения кода |
| Секреты | Ключи, токены, локальные конфигурации | Перед публикацией результата |
Когда применять /agent
Команда полезна тогда, когда задачу можно разделить на самостоятельные направления, а результаты этих направлений не требуют постоянного пошагового согласования. Это не означает, что агент должен работать полностью бесконтрольно. Скорее, он получает собственную рабочую область внимания, пока пользователь занимается архитектурой, приоритетами или другой частью проекта.
Параллелить стоит не всё подряд, а независимые вопросы. Если одна задача постоянно зависит от промежуточного решения другой, разделение на агентов может не ускорить работу, а добавить координационные расходы.
Хорошие кандидаты для /agent — исследование незнакомого кода, сравнение вариантов реализации, подготовка тестов, поиск связанных мест в репозитории, анализ миграции или проверка документации. Менее удачны задачи, где требуется непрерывный диалог и частое подтверждение каждого действия: например, тонкая правка пользовательского интерфейса по визуальному результату или изменение критического кода без заранее известных критериев проверки.
| Сценарий | Почему подходит | Ожидаемый результат |
|---|---|---|
| Исследование репозитория | Можно выполнить независимо от написания кода | Карта модулей и список точек изменения |
| Анализ ошибки | Агент может собрать факты и гипотезы | Причина сбоя и способы воспроизведения |
| Подготовка тестов | Цель легко описать через сценарии | Набор тестов и объяснение покрытия |
| Сравнение решений | Можно задать единые критерии | Таблица плюсов, минусов и рисков |
| Механическое изменение | Повторяющиеся операции удобно делегировать | Изменённые файлы и отчёт о проверке |
Когда ветка агента действительно экономит время
Экономия появляется, когда агенту не приходится каждый раз спрашивать о базовых деталях. Перед запуском соберите минимальный пакет контекста: название ошибки, пример входных данных, ожидаемое поведение, важные файлы и ограничения. Это дешевле, чем несколько циклов уточнений после неудачного старта.
Ещё один хороший сценарий — параллельное получение независимых мнений. Например, один агент ищет техническую причину проблемы, а другой оценивает риски предложенного исправления. Основной сеанс затем сравнивает результаты, а не ждёт завершения одной длинной цепочки рассуждений.
| Признак подходящей задачи | Что это даёт |
|---|---|
| Есть чёткая граница | Агент не распыляется на весь проект |
| Результат можно описать | Проще оценить качество работы |
| Задача допускает независимость | Можно работать параллельно с основным сеансом |
| Есть проверяемые критерии | Меньше риска принять ошибочный вывод |
Когда лучше не использовать /agent
Не всякая задача выигрывает от дополнительной ветки. Если проблема маленькая и требует одной очевидной команды, создание отдельного контекста может быть сложнее, чем непосредственное выполнение. То же относится к задачам, где результат зависит от постоянно меняющихся решений пользователя.
- Не выносите в отдельную ветку задачу, которую быстрее решить одной короткой инструкцией.
- Не поручайте агенту изменение критической инфраструктуры без ограничений и проверки.
- Не запускайте много агентов на один и тот же файл без понятного плана координации.
- Не передавайте секреты и чувствительные данные без необходимости.
- Не считайте успешное завершение команды доказательством корректности результата.
Отдельная осторожность нужна при массовых изменениях. Если агент переименовывает десятки файлов, обновляет зависимости или меняет формат данных, необходимо заранее определить процедуру отката. В таких случаях полезнее сначала попросить подготовить план и список затрагиваемых мест, а уже потом разрешать редактирование.
| Риск | Как проявляется | Мера снижения |
|---|---|---|
| Размытая цель | Агент исследует всё подряд | Задать вопрос и область поиска |
| Конфликт изменений | Несколько веток редактируют одни файлы | Разделить области или работать последовательно |
| Ложная уверенность | Гипотеза представлена как факт | Потребовать ссылки на файлы и проверки |
| Потеря контекста | Результат нельзя применить в основном сеансе | Заранее указать формат отчёта |
Примеры работы с /agent
Примеры ниже показывают не только сам вызов команды, но и способ постановки задачи. В реальной сессии синтаксис выбора ветки или субагента может отличаться в зависимости от версии Codex CLI, поэтому воспринимайте эти фрагменты как практические сценарии и шаблоны формулировок, а не как обещание единственного интерфейса.
Пример 1. Исследование незнакомого репозитория
Такой сценарий подходит, когда нужно быстро понять устройство проекта, но не хочется перегружать основной диалог перечислением всех найденных файлов. Агент должен исследовать структуру и вернуть карту проекта без внесения изменений.
$ codex > /agent Задача для субагента: Изучи репозиторий и подготовь краткую карту архитектуры. Покажи: 1. точку входа приложения; 2. основные модули; 3. место, где обрабатываются HTTP-запросы; 4. расположение тестов; 5. файлы конфигурации. Не изменяй файлы. В отчёте укажи пути и кратко объясни назначение каждого важного каталога.
Ценность такого поручения в том, что результат можно использовать как справочную записку для дальнейшей работы. Если агент обнаружит несколько возможных точек входа, попросите его сравнить их и указать, какая из них используется при обычном запуске.
Ожидаемый формат результата: - Точка входа: src/main.ts - HTTP-слой: src/api - Бизнес-логика: src/services - Тесты: tests/ - Неопределённость: найдены два конфигурационных файла, требуется проверить сценарий запуска
Пример 2. Поиск причины ошибки
Здесь агенту поручается не немедленное исправление, а диагностика. Такой порядок полезен, когда ошибка может быть вызвана несколькими слоями: конфигурацией, сетью, сериализацией или логикой повторных запросов.
$ codex > /agent Проанализируй ошибку: "401 Unauthorized возникает при обновлении access-токена после истечения срока действия". Изучи только: - src/auth; - middleware авторизации; - тесты обновления токена; - конфигурацию времени жизни токена. Не вноси изменения. Найди подтверждённые факты, перечисли гипотезы по вероятности и укажи, какие тесты помогут отличить одну причину от другой.
Особенно полезно попросить агента не ограничиваться первым найденным совпадением. Хороший отчёт связывает симптом с конкретным потоком выполнения и показывает, где именно появляется неверное значение.
Попросите вернуть: 1. место возникновения ошибки; 2. значение, которое ожидалось; 3. фактическое значение; 4. минимальный способ воспроизведения; 5. безопасное исправление; 6. тест, который не даст ошибке вернуться.
Пример 3. Подготовка тестов без изменения производственного кода
Этот сценарий удобен, когда логика уже существует, но её поведение недостаточно зафиксировано тестами. Ограничение «не менять production-код» помогает сосредоточить работу на проверяемых сценариях.
$ codex > /agent Добавь тесты для функции normalizeUserProfile. Изучи реализацию и существующий стиль тестов. Покрой случаи: - отсутствующие необязательные поля; - пустые строки; - неизвестные дополнительные поля; - корректную локаль; - ошибочный тип входных данных. Не меняй код приложения и не добавляй зависимости. После изменений запусти только тесты соответствующего модуля и сообщи результат.
При проверке результата важно посмотреть, действительно ли тесты проверяют поведение, а не просто повторяют внутреннюю реализацию. Если тест ломается после безвредного рефакторинга, он может быть слишком привязан к деталям.
Проверка результата: 5 новых сценариев добавлено локальный набор тестов: PASS полный тестовый набор не запускался Решение: запустить полный набор отдельно перед слиянием изменений.
Пример 4. Сравнение вариантов реализации
Иногда ещё неизвестно, какой путь выбрать: добавить кэш, изменить запросы к базе или пересмотреть формат данных. В этом случае субагент может подготовить исследование, но окончательное архитектурное решение должно оставаться за пользователем и командой.
$ codex > /agent Сравни три варианта уменьшения времени ответа endpoint /reports: 1. кэширование результата; 2. оптимизация SQL-запроса; 3. предварительный расчёт агрегатов. Изучи текущую реализацию и миграции базы. Для каждого варианта укажи: - ожидаемый выигрыш; - сложность; - риски устаревших данных; - влияние на инфраструктуру; - необходимые изменения; - способ измерить эффект. Код не меняй. Верни сравнительную таблицу и рекомендацию с оговорками.
В таком задании особенно важно требовать критерии измерения. Фраза «этот вариант быстрее» мало полезна без уточнения: быстрее на каких данных, при какой нагрузке и с каким уровнем актуальности результата.
Минимальный план измерений: - базовый p50 и p95; - размер выборки; - число запросов к базе; - доля попаданий в кэш; - поведение при устаревших данных; - результат после нагрузки, близкой к production.
Пример 5. Безопасная подготовка массового изменения
Массовое изменение лучше начинать с инвентаризации. Сначала агент находит все места использования старого API, затем формирует план миграции, и только после проверки списка можно поручать ему механическую замену.
$ codex > /agent Подготовь миграцию с функции legacyParseDate на parseDate. Сначала ничего не меняй: - найди все вызовы; - раздели их по форматам входных данных; - отметь места, где поведение может отличаться; - составь список файлов для изменения; - предложи порядок миграции. Особое внимание удели часовым поясам и обработке null. Верни отчёт, не редактируй файлы.
После изучения отчёта можно запустить второй этап в отдельной ветке. Такой двухшаговый подход снижает риск того, что автоматическая замена изменит смысл кода там, где старые вызовы использовались нестандартно.
После проверки плана: > Продолжи миграцию только в файлах из согласованного списка. > Не меняй публичную сигнатуру parseDate. > После замены запусти линтер и тесты дат. > Покажи diff и отдельно перечисли места, пропущенные намеренно.
Чем /agent отличается от других команд
Похожие команды часто путают, потому что все они связаны с переходом между контекстами работы. Однако /agent, /subagents, /fork и /resume решают разные задачи: первая связана с веткой агента, вторая — с управлением субагентами, третья — с созданием ответвления чата, а четвёртая — с возвращением к сохранённому сеансу.
| Команда | Главное назначение | Что меняется | Типичный результат |
|---|---|---|---|
/agent |
Переключение на ветку агента | Рабочий контекст субагента | Отдельная линия выполнения подзадачи |
/subagents |
Просмотр или управление субагентами | Список и состояние исполнителей | Выбор, контроль или координация агентов |
/fork |
Создание ответвления чата | История диалога копируется в новый путь | Независимое продолжение беседы |
/resume |
Возобновление сохранённого сеанса | Загружается ранее сохранённое состояние | Продолжение старой работы с прежним контекстом |
Команда /subagents
/subagents следует воспринимать как инструмент управления набором субагентов, а не как синоним переключения в одну конкретную агентскую ветку. В зависимости от версии Codex CLI она может показывать активные и завершённые задачи, их состояние, доступные роли или средства контроля. Для точного набора действий используйте встроенную справку установленной версии.
Практическая разница проста: /agent отвечает на вопрос «в какую ветку агента перейти?», а /subagents — «какие субагенты существуют и что с ними происходит?». Если работа ведётся параллельно, сначала удобно получить обзор через /subagents, а затем открыть нужную линию с помощью /agent.
| Задача пользователя | Более подходящая команда | Почему |
|---|---|---|
| Посмотреть активные агентские работы | /subagents |
Нужен обзор состояния |
| Перейти к конкретной ветке | /agent |
Нужен рабочий контекст выбранного агента |
| Понять, завершена ли подзадача | /subagents |
Нужно проверить статус |
| Продолжить работу внутри ветки | /agent |
Нужно открыть соответствующий контекст |
Команда /fork
/fork обычно используется для создания ответвления текущего чата. Это похоже на копирование точки разговора: новая линия получает историю, которая уже была накоплена, но затем может развиваться самостоятельно. Здесь необязательно появляется отдельный субагент — пользователь может продолжать диалог сам, проверяя альтернативный подход.
Представьте развилку: в одном варианте вы выбираете PostgreSQL, в другом — Redis. /fork позволяет сохранить общий исходный контекст и продолжить обсуждение двух решений отдельно. /agent имеет другой акцент: она направляет работу в ветку, связанную с агентом и его самостоятельной подзадачей.
| Критерий | /agent |
/fork |
|---|---|---|
| Кто продолжает работу | Субагент или агентская ветка | Пользователь или другой участник чата |
| Основная цель | Делегирование подзадачи | Изучение альтернативного пути |
| Контекст | Специализированная линия агента | Ответвление текущей истории |
| Пример | Исследовать причину сбоя | Сравнить две архитектуры в отдельных диалогах |
Команда /resume
/resume предназначена для возвращения к сохранённому сеансу. Она не создаёт новую агентскую подзадачу и не обязательно создаёт новую копию текущего диалога. Её смысл — снова открыть уже существующую работу, чтобы продолжить её с прежнего места.
Это удобно после закрытия терминала, перерыва в работе или переключения между несколькими проектами. Если /fork похожа на создание новой дороги от текущего перекрёстка, то /resume больше похожа на возвращение к уже проложенной дороге, включая сохранённые указания и историю.
| Ситуация | Что выбрать | Логика выбора |
|---|---|---|
| Нужно продолжить вчерашний сеанс | /resume |
Сеанс уже существует и его нужно восстановить |
| Нужно проверить другой вариант решения | /fork |
Нужна независимая ветка разговора |
| Нужно делегировать исследование | /agent |
Нужен отдельный исполнитель |
| Нужно увидеть список активных исполнителей | /subagents |
Нужен контроль агентских задач |
Ветка субагента, ответвление чата и сохранённый сеанс
Эти понятия удобно сравнить через три разных действия. Ветка субагента нужна для делегирования: агент выполняет порученную работу в специализированном контексте. Ответвление чата нужно для альтернативного продолжения: история берётся за основу, но дальнейшее обсуждение может пойти в другом направлении. Возобновление сеанса нужно для восстановления: пользователь возвращается к уже существующей работе без намерения создавать новую линию.
| Свойство | Ветка субагента | Ответвление чата | Возобновление сеанса |
|---|---|---|---|
| Зачем используется | Делегировать подзадачу | Проверить альтернативу | Продолжить сохранённую работу |
| Кто выполняет работу | Субагент | Пользователь или выбранный собеседник | Пользователь в восстановленном контексте |
| Создаётся ли новая линия | Да, агентская | Да, чатовая | Нет, открывается прежняя |
| Нужна ли координация | Да, нужно принять результат | Да, нужно сравнить варианты | Обычно нет, контекст уже накоплен |
| Главный риск | Плохо поставленная задача | Разброс вариантов и дублирование | Забытый контекст или устаревшее состояние |
Есть и ещё одно практическое отличие — отношение к результату. Работа субагента обычно требует этапа проверки и принятия: вывод агента может быть полезным, но не обязан автоматически становиться частью основного решения. В ответвлении чата пользователь сам ведёт альтернативный сценарий. При возобновлении сеанса задача обычно остаётся той же, просто работа продолжается после паузы.
Как выбрать правильную команду
Если сомневаетесь, задайте себе один вопрос: вы хотите делегировать, разделить варианты, посмотреть состояние агентов или вернуться к старой работе? Ответ почти всегда подсказывает нужную команду.
- «Пусть отдельный исполнитель исследует модуль» — используйте
/agent. - «Покажи, какие агенты уже запущены» — используйте
/subagents. - «Хочу проверить другой вариант, не ломая текущий разговор» — используйте
/fork. - «Нужно продолжить вчерашний сеанс» — используйте
/resume.
Быстрая памятка: /agent — перейти к работе агента /subagents — посмотреть и контролировать субагентов /fork — создать независимое ответвление чата /resume — восстановить сохранённый сеанс
Наконец, не забывайте о версии инструмента. Названия команд и детали поведения могут развиваться: интерфейс меню, способы выбора ветки, отображение статусов и правила хранения контекста способны отличаться. Если команда не распознаётся или ведёт себя иначе, сначала проверьте /help, затем документацию и настройки конкретной установки Codex CLI.
| Проверочный вопрос | Если ответ «да» | Следующий шаг |
|---|---|---|
| Нужно поручить работу отдельному исполнителю? | Да | Рассмотрите /agent |
| Нужно увидеть состояние параллельных задач? | Да | Откройте /subagents |
| Нужно сохранить исходный разговор и попробовать иной путь? | Да | Используйте /fork |
| Работа уже была начата ранее? | Да | Проверьте /resume |
| Есть риск изменения важных файлов? | Да | Сначала запросите план и проверьте рабочее дерево |