Команда Codex CLI /init: создание файла AGENTS.md

Слеш-команда Codex CLI /init применяется для быстрой подготовки проекта к работе с ИИ-агентом: она создаёт в текущей директории файл инструкций AGENTS.md, где можно описать правила, структуру, команды, ограничения и особенности репозитория. Благодаря этому Codex получает постоянный контекст и не вынужден каждый раз угадывать, как устроен проект и какие требования нужно соблюдать.

/init превращает неформальные договорённости о проекте в понятный для Codex документ. Это не просто создание пустого файла, а первый шаг к предсказуемой и безопасной работе с кодовой базой.

Команда особенно полезна в новых или незнакомых проектах, где важно заранее объяснить агенту, как запускать тесты, какие каталоги не следует изменять, какой стиль кода использовать и какие действия требуют осторожности. При этом /init не устанавливает зависимости, не запускает миграции и не исправляет код автоматически: она подготавливает основу для дальнейшего взаимодействия.

Как использовать /init

Команда используется внутри интерактивной сессии Codex CLI. Обычно нужно открыть терминал, перейти в корневую папку проекта, запустить Codex, а затем ввести слеш-команду /init. После этого инструмент анализирует содержимое рабочей директории и предлагает или создаёт файл AGENTS.md с инструкциями для агента.

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

Базовый сценарий выглядит так:

cd my-project
codex
/init

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

Шаг	Что сделать	Зачем это нужно
1	Открыть терминал	Получить доступ к командной строке и рабочей директории
2	Перейти в корень проекта	Создать инструкции в правильном месте
3	Запустить Codex CLI	Открыть интерактивную сессию
4	Ввести /init	Сформировать или подготовить AGENTS.md
5	Проверить файл	Убедиться, что правила точны и не противоречат проекту
6	Сохранить изменения в Git	Сделать инструкции частью общей истории проекта

Что происходит после запуска

После выполнения /init Codex обычно изучает доступные признаки проекта: файлы конфигурации, исходный код, документацию, сценарии сборки и тестовые команды. На основании этого он формирует содержимое AGENTS.md либо предлагает пользователю подтвердить создание файла. Конкретное поведение может зависеть от версии Codex CLI и текущих настроек.

Важно понимать разницу между анализом проекта и изменением проекта. Команда не превращает агент в безусловно компетентного разработчика и не гарантирует, что все рекомендации будут идеальными. Она лишь создаёт место, где эти рекомендации и явные правила можно закрепить.

Элемент	Что может попасть в инструкции	Пример
Структура	Назначение основных каталогов	src содержит приложение, tests — тесты
Запуск	Команды разработки	npm run dev
Проверки	Тесты, линтер, форматтер	npm test, npm run lint
Стиль	Правила оформления кода	Использовать TypeScript strict mode
Ограничения	Что нельзя менять без согласования	Не редактировать сгенерированные файлы
Процесс	Порядок проверки изменений	Сначала тесты, затем линтер и сборка

Где должен находиться AGENTS.md

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

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

Расположение	Типичная область действия	Когда использовать
Корень репозитория	Весь проект	Общие правила, архитектура, базовые команды
apps/web/	Веб-приложение	Особые правила интерфейса и сборки
services/api/	Серверный сервис	API, миграции, интеграционные тесты
packages/ui/	Общая библиотека	Правила публичных компонентов и обратной совместимости

Как подготовить хороший файл

После запуска /init стоит открыть AGENTS.md и проверить его так, будто это инструкция для нового сотрудника. Удалите догадки, устаревшие команды и слишком общие формулировки. Хорошее правило должно помогать принять решение, а не просто звучать солидно.

Обычно полезно включить в документ следующие сведения:

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

Неудачная формулировка	Улучшенный вариант	Почему второй вариант лучше
Пиши хороший код	Для новых функций добавляй типы и избегай any	Есть конкретный критерий
Всегда тестируй изменения	После изменений запускай npm test -- --runInBand	Понятно, какую команду выполнить
Не трогай конфигурацию	Не изменяй файлы CI без отдельного согласования	Ограничение имеет ясную область
Соблюдай архитектуру	Бизнес-логику размещай в src/domain, HTTP-обвязку — в src/api	Правило можно применить на практике

Когда применять /init

/init особенно полезна в начале работы с репозиторием, когда Codex ещё не знает его устройство и внутренние договорённости. Однако запускать её можно не только один раз: если проект сильно изменился, правила устарели или к команде присоединились новые разработчики, файл имеет смысл пересмотреть и обновить.

Инструкции должны отражать текущий рабочий процесс, а не исторический музей команд, которыми когда-то пользовались. Устаревший AGENTS.md способен навредить сильнее, чем его отсутствие.

Новый проект

В новом проекте /init помогает быстро сформировать минимальный контекст. Пока структура ещё небольшая, инструкции можно сделать короткими: указать используемый стек, основные команды и ожидаемый стиль изменений. По мере развития проекта документ расширяется вместе с реальными потребностями.

mkdir shop-api
cd shop-api
git init
codex
/init

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

Незнакомый существующий репозиторий

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

cd legacy-billing
codex
/init
Открой AGENTS.md и проверь команды запуска перед первой задачей.

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

Ситуация	Польза от /init	Что проверить вручную
Новый проект	Фиксирует базовые договорённости	Корректность структуры и команд
Унаследованный проект	Помогает собрать первичный контекст	Актуальность найденной информации
Монорепозиторий	Создаёт основу для общих и локальных правил	Границы разных пакетов
Командная разработка	Снижает количество повторяющихся объяснений	Согласие команды с правилами

Перед передачей проекта другому разработчику

Файл AGENTS.md удобно использовать как технический слой онбординга. Он не должен заменять полноценную документацию для людей, но способен быстро ответить на практические вопросы: какую команду запустить, где находится тест, какие каталоги генерируются автоматически и какие изменения требуют особого внимания.

cd mobile-app
codex
/init
Добавь в инструкции порядок запуска Android-тестов и укажи, что каталог build генерируется автоматически.

При этом не стоит помещать в файл пароли, токены, приватные ключи и другие секреты. AGENTS.md часто хранится в Git и доступен всем, кто имеет доступ к репозиторию.

После смены технологического стека

Миграция с одного инструмента на другой — хороший повод проверить инструкции. Например, проект мог перейти с npm на pnpm, с одного тестового фреймворка на другой или с Docker Compose на иной способ локального запуска.

cd analytics
codex
/init
Сравни текущие команды из package.json и CI с существующим AGENTS.md. Удали устаревшие инструкции и добавь актуальные.

Изменение в проекте	Какие инструкции обновить	Риск при игнорировании
Смена пакетного менеджера	Установка, скрипты, lock-файл	Агент предложит несуществующие команды
Новая структура каталогов	Описание модулей и точек входа	Изменения попадут не в тот слой
Изменение CI	Проверки и порядок сборки	Локальная проверка будет неполной
Переезд базы данных	Миграции и локальный запуск	Можно случайно повредить окружение

Примеры использования /init

Сама команда короткая, но её практическая ценность проявляется в том, что происходит после создания инструкций. Ниже приведены ситуации, в которых /init помогает получить более предсказуемые ответы и безопаснее организовать работу Codex.

Пример 1. Инициализация Python-проекта

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

cd data-service
codex
/init
Проверь, что инструкции указывают использование .venv, pytest и ruff. Не предлагай устанавливать зависимости глобально.

Правило	Пример значения	Практический эффект
Окружение	.venv	Зависимости не смешиваются с системными
Тесты	pytest	Агент знает основной способ проверки
Линтер	ruff check .	Единый контроль качества
Форматирование	ruff format .	Стабильный стиль файлов

Пример 2. Инициализация фронтенд-проекта

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

cd customer-portal
codex
/init
Добавь правила: новые компоненты размещать в src/components, состояние не хранить в глобальном сторе без необходимости, перед завершением запускать lint и build.

Такая запись не заставляет Codex писать идеальный интерфейс, но направляет его к принятому в проекте способу работы.

Пример 3. Монорепозиторий

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

cd company-platform
codex
/init
Создай общие инструкции для монорепозитория. Отдельно укажи, что apps/admin и services/payments имеют собственные правила.

Уровень	Что описывать	Пример
Корень	Общие команды и зависимости	Установка, сборка всех пакетов
Приложение	Локальный запуск и UI-правила	apps/admin
Сервис	API, БД, миграции	services/payments
Пакет	Публичный контракт	packages/design-system

Пример 4. Проект с базой данных

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

cd orders-api
codex
/init
Не выполняй миграции на production. Для локальной проверки используй Docker и тестовую базу.

Полезно также указать, где находятся схемы, как создаётся тестовая база и какие команды сбрасывают данные.

Пример 5. Генерируемые файлы

Во многих проектах часть кода создаётся генераторами: клиент API, ORM-модели, типы GraphQL или файлы локализации. Агенту нужно явно сообщить, что ручное редактирование таких файлов нежелательно.

cd reporting
codex
/init
Не редактируй src/generated вручную. После изменения схемы запускай npm run generate и проверяй результат тестами.

Тип файла	Правильное действие	Неправильное действие
Сгенерированный клиент	Изменить исходную схему и запустить генератор	Править итоговый файл вручную
Lock-файл	Обновлять согласованным менеджером пакетов	Редактировать текстом без понимания последствий
Миграция	Создать новую миграцию	Переписывать применённую миграцию
Сборочная папка	Пересоздать через build-команду	Вносить изменения непосредственно в неё

Пример 6. Подготовка к исправлению бага

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

cd payment-gateway
codex
/init
В инструкции добавь: сначала воспроизвести ошибку тестом, затем исправить код, после этого запустить unit- и integration-тесты.

Такой подход помогает не ограничиться косметическим изменением, которое скрывает симптом, но не устраняет причину.

Пример 7. Подготовка CI-проверок

Если проект имеет строгий CI, AGENTS.md должен объяснять, какие проверки обязательны до создания pull request. Это экономит время: агент не будет считать задачу завершённой сразу после локальной компиляции.

cd platform
codex
/init
Укажи обязательный порядок: format, lint, unit tests, build. Если проверка не запускалась, явно сообщай об этом.

Пример 8. Ограничение опасных операций

В инструкциях можно закрепить запреты на удаление файлов, изменение секретов, работу с production и переписывание истории Git. Это не заменяет технические права доступа, но создаёт дополнительный уровень предосторожности.

В AGENTS.md: не выполняй git reset --hard, git push --force и удаление данных без явного подтверждения пользователя.

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

Пример 9. Локальные инструкции для пакета

Вложенный AGENTS.md имеет смысл, когда один пакет отличается от остальных. Например, библиотека может требовать сохранения обратной совместимости, тогда как внутреннее приложение допускает более быстрые изменения.

cd packages/public-sdk
codex
/init
Добавь локальное правило: изменения публичных типов должны сопровождаться обновлением документации и тестами обратной совместимости.

Пример 10. Актуализация существующих инструкций

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

cd product
codex
/init
Не удаляй существующие командные правила. Сравни их с текущим package.json, Makefile и CI, предложи только подтверждённые изменения.

Чем /init отличается от похожих команд

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

/init — это команда подготовки инструкций, а не универсальная кнопка «разберись во всём проекте». Она задаёт основу, но не заменяет постановку конкретной задачи.

/init и обычный текстовый запрос

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

Критерий	/init	Обычный запрос
Цель	Подготовить правила проекта	Решить конкретную задачу
Результат	AGENTS.md или его черновик	Ответ, план или изменение кода
Срок действия	Долгосрочный, пока файл актуален	Обычно ограничен текущим контекстом
Лучшее применение	Онбординг и стандартизация	Исправление, анализ, разработка функции

/init и /help

/help предназначена для получения информации о доступных командах и возможностях текущей версии Codex CLI. Она помогает понять синтаксис и функции интерфейса, но не создаёт инструкции для конкретного репозитория.

Команда	Основной вопрос	Результат
/init	Как объяснить Codex правила этого проекта?	Инструкции в AGENTS.md
/help	Какие команды доступны?	Справка по интерфейсу

/init и просмотр Git-изменений

Просмотр состояния Git или diff отвечает на вопрос «что изменилось?». /init отвечает на другой вопрос: «какие правила нужно соблюдать в этой кодовой базе?». Эти действия хорошо дополняют друг друга, но не являются взаимозаменяемыми.

git status
git diff

После создания или изменения AGENTS.md полезно как раз посмотреть Git-изменения и убедиться, что в файл не попали случайные секреты или лишние детали.

/init и запуск проекта

Команда запуска проекта, например npm run dev или docker compose up, меняет состояние окружения или запускает сервис. /init лишь подготавливает инструкции и обычно не должна рассматриваться как замена запуску, сборке или тестированию.

Действие	Назначение	Меняет код?
/init	Создать инструкции проекта	Может создать или изменить AGENTS.md
npm test	Проверить поведение кода	Обычно нет
npm run build	Собрать приложение	Создаёт артефакты
docker compose up	Запустить окружение	Может создать контейнеры и данные

Типичные ошибки при использовании /init

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

Ошибка 1. Запуск не из корня проекта

Если выполнить /init в неправильном месте, Codex увидит неполную структуру. В результате инструкции могут описывать только один подкаталог или, наоборот, сразу несколько несвязанных проектов.

cd ~/projects
codex
/init

Правильнее:
cd ~/projects/store-api
codex
/init

Перед запуском проверьте наличие признаков корня: .git, package.json, pyproject.toml, go.mod, Makefile или другого главного файла проекта.

Ошибка 2. Слепое доверие автоматически созданному тексту

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

Что проверить	Как проверить	Признак проблемы
Команды	Сверить с package.json, Makefile и CI	Команда отсутствует или имеет другой синтаксис
Каталоги	Сопоставить с фактическим деревом файлов	Описана удалённая папка
Тесты	Запустить ключевую проверку	Тестовый сценарий завершается ошибкой
Ограничения	Обсудить с владельцами проекта	Правило мешает нормальной работе

Ошибка 3. Слишком общие инструкции

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

Плохо: пиши чистый код и всё тестируй.

Лучше: новые сервисы размещай в src/services, для unit-тестов используй Vitest, перед завершением запускай npm run lint и npm test.

Ошибка 4. Хранение секретов в AGENTS.md

Инструкции часто попадают в Git, поэтому API-ключи, пароли, токены и приватные сертификаты нельзя включать в этот файл. Даже если репозиторий закрытый, секрет может случайно попасть в резервную копию, pull request или другой канал распространения.

Плохо:
DATABASE_URL=postgres://admin:password@host/db
OPENAI_API_KEY=sk-example-secret

Лучше:
Для локальной базы используй переменную DATABASE_URL из .env.
Секреты не добавляй в Git и не печатай в отчётах.

Ошибка 5. Попытка описать абсолютно всё

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

Стоит включить	Лучше не включать без необходимости
Нестандартные команды проверки	Очевидные правила вроде «сохраняй файлы»
Опасные операции	Большую историю архитектурных решений
Границы ответственности каталогов	Полный список всех файлов
Требования к публичному API	Повтор всей пользовательской документации

Краткая памятка по /init

Команда /init нужна для того, чтобы подготовить проект к последовательной работе с Codex CLI. Она создаёт или помогает сформировать AGENTS.md — документ с правилами, которые агент должен учитывать при анализе и изменении кода.

Сначала правильная директория, затем /init, после этого — обязательная ручная проверка файла. Именно такой порядок превращает короткую слеш-команду в полезный рабочий процесс.

Вопрос	Краткий ответ
Где запускать?	В корне нужного проекта или подходящего подкаталога
Что создаётся?	Файл инструкций AGENTS.md или его заготовка
Нужно ли проверять результат?	Да, обязательно
Запускает ли команда тесты?	Нет, если только пользователь отдельно не попросит об этом
Устанавливает ли зависимости?	Нет
Можно ли использовать вложенные файлы?	Да, если части проекта имеют разные правила
Можно ли хранить секреты?	Нет
Когда обновлять инструкции?	После изменений в стеке, структуре, CI или процессе разработки

Перед началом работы с новым репозиторием используйте следующий минимальный чек-лист:

1. Перейдите в фактический корень проекта.
2. Убедитесь, что это нужный Git-репозиторий.
3. Запустите Codex CLI.
4. Выполните /init.
5. Откройте созданный или обновлённый AGENTS.md.
6. Проверьте команды установки, тестирования и сборки.
7. Удалите предположения и устаревшие сведения.
8. Добавьте опасные операции и ограничения.
9. Не включайте секреты.
10. Сохраните подтверждённые изменения в репозитории.

В итоге /init лучше воспринимать не как магическую настройку Codex, а как инструмент документирования рабочей среды. Чем точнее описаны структура, команды и ограничения проекта, тем меньше лишних уточнений потребуется в дальнейшем и тем предсказуемее будут действия ИИ-агента.