Инструменты Codex: поиск, терминал и работа с файлами
Автор: Казачкин Даниил Михайлович · Обновлено
Codex решает задачу не только генерацией текста. Он читает файлы, ищет символы и строки, запускает команды и анализирует их вывод. Конкретный набор инструментов зависит от поверхности, конфигурации и разрешений, поэтому надёжный агент сначала проверяет доступные возможности, а не предполагает их наличие.
Поиск строит карту, а не заменяет чтение
Быстрый поиск отвечает, где объявлен символ, кто вызывает функцию и где встречается строка ошибки. Но отдельное совпадение не показывает весь контракт. После поиска нужно прочитать:
- определение с окружающим контекстом;
- публичные типы или DTO;
- вызывающий код;
- тесты с ожидаемым поведением;
- конфигурацию, способную переопределить значение.
Для большого репозитория полезна воронка: список файлов → узкий поиск → несколько целевых чтений → проверка гипотезы. Полное последовательное чтение всех файлов расходует контекст и скрывает важные связи.
Терминал как источник доказательств
Команда должна отвечать на конкретный вопрос. Примеры:
git status --short
rg "createSession" backend/src
pnpm --filter @example/backend test -- session.service.spec.ts
pnpm --filter @example/frontend typecheckПервая команда показывает состояние, вторая находит путь вызова, третья проверяет узкое поведение, четвёртая — согласованность типов пакета. Названия команд проекта нужно брать из package.json, CI или AGENTS.md, а не переносить из другого репозитория.
Управляйте объёмом вывода
Огромный лог не равен большему знанию. Если команда возвращает тысячи строк:
- сохраните полный артефакт там, где это допустимо;
- найдите первое содержательное сообщение об ошибке;
- отделите причину от последующих каскадных падений;
- сузьте повторный запуск до одного теста или пакета;
- вернитесь к полному прогону после исправления.
Обрезанный вывод нельзя выдавать за полный. В отчёте агент должен сказать, что именно запущено и завершилась ли команда.
Выбирайте инструмент по вопросу
| Вопрос | Подход |
|---|---|
| Где используется символ? | текстовый или семантический поиск |
| Почему падает тест? | узкий запуск с полным стеком |
| Что изменено? | Git status и diff |
| Как выглядит страница? | реальный браузер |
| Актуальна ли внешняя спецификация? | официальный источник или MCP |
| Есть ли ошибка типов? | typecheck проекта |
Не проверяйте визуальный overflow только чтением CSS. Не делайте вывод о текущем API библиотеки по старому lockfile, если задача требует актуальной документации.
Инструменты и разрешения
Доступность команды не означает разрешение на любое последствие. Чтение файла и отправка данных во внешний сервис — разные действия. Запуск теста и запуск deployment-скрипта — тоже.
Перед побочным эффектом агент должен проверить область и необходимость. Если sandbox блокирует действие, корректный следующий шаг — объяснить конкретную потребность или найти безопасную альтернативу, а не пытаться обойти ограничение.
Практика: доказательство по одному инструменту
Возьмите баг «после выхода профиль остаётся на экране» и составьте цепочку:
- поиск обработчика logout;
- чтение store и route guard;
- узкий тест состояния;
- изменение;
- повторный тест;
- браузерный сценарий;
- финальный diff.
Для каждого шага запишите вопрос, на который он отвечает. Удалите шаги, которые не дают нового доказательства.
Что важно запомнить
- Сначала выясняйте доступные инструменты и правила проекта.
- Поиск находит точки входа, а чтение восстанавливает контракт.
- Каждая команда должна отвечать на конкретный инженерный вопрос.
- Не скрывайте обрезанный вывод и непроверенные предположения.
Частые вопросы
Нужно ли просить Codex показывать каждую команду заранее?
Для безопасных команд внутри согласованной области это обычно замедляет работу. Лучше заранее определить разрешения и действия, которые обязательно требуют подтверждения: сеть, публикация, удаление, production или работа вне workspace.
Может ли поиск доказать отсутствие использования?
Только в пределах выбранных файлов и вида ссылки. Динамические импорты, генерируемый код, строки конфигурации и внешние потребители могут не попасть в простой поиск. Учитывайте язык и архитектуру.
Что делать, если в проекте нет команды проверки?
Попросить Codex определить существующий способ запуска из CI и конфигурации. Если проверки действительно нет, зафиксировать ограничение и предложить минимальную воспроизводимую проверку, не выдумывая успешный результат.