AI-агенты

Chef сам объясняет AI-агентам (Claude Code, Codex, Cursor и другим), как с ним работать. Объяснение печатает установленный chef, поэтому оно всегда соответствует его версии.

Справка для агента

chef help agent

Команда выводит в stdout справку в формате Markdown:

• Concepts — что такое расширение, как устроены имена, какие файлы генерирует сборка
• What chef can do — возможности chef по задачам: сборка, проверка типов, линтинг, тесты, анализ зависимостей и т.д.
• Behavior worth knowing — поведение, которое важно учитывать: что будет без указания цели, как работают glob-паттерны, что делают --force и --watch
• Commands — все команды, подкоманды и их опции
• Error codes — все коды CFxxxx
• Documentation — список страниц этой документации с путями к файлам

Справка описывает возможности и поведение chef, но не навязывает правил работы: какие опции использовать и что согласовывать перед изменением, решает проект — в своих инструкциях для агентов и в deny в chef.config.

Английская версия документации входит в npm-пакет chef (docs/en/), и справка ссылается на файлы внутри установленного пакета. Агенту не нужен доступ в интернет, и он читает документацию той версии chef, которая установлена.

Почему на английском

Справку читают агенты, а не люди. Английский текст короче в токенах и занимает меньше контекста агента.

Подключение к проекту

chef init agents

Команда добавляет в корень проекта блок, который отправляет агента к chef help agent:

Файл	Что происходит
AGENTS.md	Создаётся или дополняется блоком. Этот файл читает большинство агентов
CLAUDE.md, .claude/CLAUDE.md	Если файл есть, блок добавляется и в него: Claude Code не читает AGENTS.md, когда в проекте есть CLAUDE.md. Файл, который уже импортирует AGENTS.md (строка @AGENTS.md), не меняется

Блок ограничен маркерами <!-- chef:agent-instructions:start --> и <!-- chef:agent-instructions:end -->. Остальное содержимое файлов не меняется, повторный запуск ничего не дублирует.

Если в проекте есть только личный CLAUDE.local.md, Claude Code читает его вместо AGENTS.md. Личные файлы chef не трогает — он подскажет добавить в CLAUDE.local.md строку @AGENTS.md.

Как справка остаётся актуальной

Блок в AGENTS.md не зависит от версии chef — в нём только отсылка к chef help agent. После обновления chef запускать chef init agents повторно не нужно: справку печатает уже новая версия.

Внутри справки:

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

Справка по командам

chef help <command> показывает все опции команды, в том числе подкоманды:

chef help build
chef help test unit
chef help diag deps-tree