diff --git a/src/pages/ai/index.md b/src/pages/ai/index.md index 5b9ac96..5367e0d 100644 --- a/src/pages/ai/index.md +++ b/src/pages/ai/index.md @@ -1605,17 +1605,41 @@ tools/resources/prompts, добавьте schemas и validation, а затем **Короткий ответ** -Skills - это переиспользуемые инструкции для Codex под конкретный тип задач. Skill обычно лежит в папке с SKILL.md и -может включать references, scripts и assets. +Skills - это переиспользуемые task-specific workflows для Codex. Skill хранит инструкции в `SKILL.md` и при +необходимости добавляет references, scripts и assets, которые Codex подгружает только когда этот workflow нужен. **Полный ответ** -Skills - это переиспользуемые инструкции для Codex под конкретный тип задач. Skill обычно лежит в папке с `SKILL.md` и -может включать references, scripts и assets. +Skill нужен для класса повторяемых задач, где одного общего prompt мало, а постоянно держать подробную инструкцию в +контексте дорого. Например, команда может оформить skill для миграции Angular API, подготовки релиза, code review или +создания архитектурного документа. -Codex не загружает все skills целиком сразу. Он видит краткий список с названием, описанием и путем, а полный `SKILL.md` -читает только когда skill выбран явно или подходит по описанию. Это называется progressive disclosure и помогает не -тратить контекст на лишние инструкции. +Минимальная структура skill - отдельная директория с обязательным `SKILL.md`. В нем задаются `name`, `description` и +сама инструкция. Дополнительно рядом можно хранить: + +- `references/` - длинную справку, примеры и доменные правила; +- `scripts/` - детерминированные операции, которые надежнее выполнить кодом, чем описывать модели словами; +- `assets/` - шаблоны и другие файлы, используемые в результате; +- `agents/openai.yaml` - optional metadata для UI и зависимостей в поддерживаемых продуктах. + +Важная идея - **progressive disclosure**. Codex сначала видит компактные metadata skill, прежде всего название и +описание. Полный `SKILL.md` и дополнительные файлы читаются только после выбора skill. Поэтому десятки skills не обязаны +занимать контекст целиком с начала задачи. + +Skill можно вызвать явно через интерфейс Skills, например `/skills` или `$skill` в Codex, либо Codex может выбрать его +неявно по `description`. Из-за этого описание должно четко отвечать на вопрос, когда skill применять и когда не +применять. + +Для проекта skills можно хранить в `.agents/skills`, чтобы они версионировались вместе с репозиторием. Codex также +поддерживает user-, admin- и system-level locations. + +Skill не выдает модели новые права сам по себе. Если workflow запускает shell-script или зависит от MCP, ограничения +sandbox, approvals, credentials и review по-прежнему действуют. + +На интервью полезно сказать: Skill - это подключаемый пакет процедурного знания для определенного класса задач, а +progressive disclosure позволяет переиспользовать подробный workflow без постоянного расхода context window. + +См. [Build skills](https://learn.chatgpt.com/docs/build-skills). @@ -1627,17 +1651,42 @@ Codex не загружает все skills целиком сразу. Он ви **Короткий ответ** -Skills нужны, чтобы закрепить повторяемый рабочий процесс: как писать миграции, как готовить релиз, как проводить -дизайн-ревью, как работать с конкретным SDK, как создавать документ или как соблюдать внутренние правила команды. +Skills нужны, чтобы один раз зафиксировать качественный повторяемый workflow и затем применять его одинаково: с нужными +шагами, проверками, references и форматом результата, не копируя длинную инструкцию в каждый prompt. **Полный ответ** -Skills нужны, чтобы закрепить повторяемый рабочий процесс: как писать миграции, как готовить релиз, как проводить -дизайн-ревью, как работать с конкретным SDK, как создавать документ или как соблюдать внутренние правила команды. +Главная ценность skill - не в хранении еще одной документации, а в снижении вариативности повторяемой работы. Если +команда регулярно выполняет один класс задач, skill может закрепить порядок действий, критерии качества и способ +проверки результата. + +Хорошие кандидаты для skill: + +- миграция на новую версию framework или API; +- подготовка release notes и changelog; +- проверка Pull Request по командному checklist; +- создание однотипной документации по шаблону; +- анализ инцидента с фиксированными этапами исследования; +- работа с конкретным SDK, где важен принятый порядок вызовов и проверок. + +Например, вместо prompt «обнови dependency и ничего не сломай» skill может требовать сначала найти breaking changes, +затем обновить package и lockfile, запустить targeted tests, проверить bundle/build и отдельно описать migration risks. + +Skill полезно хранить рядом с кодом, если workflow относится к конкретному репозиторию: тогда изменение процесса +проходит обычный code review и версионируется вместе с проектом. -Хороший skill отвечает на вопрос "как именно мы выполняем этот класс задач", а не просто хранит справку. Он может -содержать порядок действий, критерии качества, ссылки на локальные reference-файлы и scripts для детерминированных -операций. +Но skill не нужен для каждой мелочи. Одноразовый вопрос дешевле решить prompt. Если процесс еще не устоялся, слишком +ранняя формализация закрепит плохие предположения. Сначала стоит несколько раз выполнить задачу вручную, понять +стабильные шаги и только затем вынести повторяемую часть. + +По возможности лучше начинать с инструкций. Script добавляют там, где нужен детерминированный результат, сложная +механическая операция или уже существует надежный tool. Это уменьшает объем кода внутри skill и его поверхность риска. + +После создания skill стоит проверить не только результат, но и **triggering**: выбирает ли Codex skill для подходящих +запросов и не активирует ли его для соседних задач. Здесь особенно важно точное `description`. + +На интервью сильный ответ: Skills превращают удачный prompt или командную процедуру в версионируемый reusable workflow, +но формализовать стоит только стабильную повторяемую работу. @@ -1649,18 +1698,49 @@ Skills нужны, чтобы закрепить повторяемый рабо **Короткий ответ** -Skill может заменить MCP, когда нужна методика, инструкция или локальный workflow без live-доступа к внешней системе. -Например: "как писать unit-тесты в этом проекте", "как оформлять changelog", "как ревьюить Angular компонент". +Skill отвечает в первую очередь на вопрос **как выполнять задачу**, а MCP - **к каким live-данным и действиям +подключиться**. Skill может убрать лишний MCP для статичной методики, но не заменит интеграцию с GitHub, Figma, Sentry +или внутренним API. **Полный ответ** -Skill может заменить MCP, когда нужна методика, инструкция или локальный workflow без live-доступа к внешней системе. -Например: "как писать unit-тесты в этом проекте", "как оформлять changelog", "как ревьюить Angular компонент". +Skills и MCP находятся на разных слоях и часто дополняют друг друга. + +**Skill подходит**, когда нужны инструкции, знания и последовательность работы: + +- как писать unit-тесты в этом проекте; +- как проводить accessibility review; +- как готовить migration guide; +- какие проверки запускать перед release; +- как анализировать Angular performance regression. + +Такой workflow может работать только с файлами репозитория и уже доступными инструментами. Поднимать отдельный MCP +server ради статичного checklist обычно лишнее. + +**MCP нужен**, когда агент должен получить актуальное состояние или выполнить действие во внешней системе: + +- прочитать свежие review comments из GitHub; +- открыть конкретный Figma-файл; +- запросить последние ошибки в Sentry; +- получить данные из внутренней базы; +- создать issue, изменить документ или вызвать корпоративный API. + +Удачная архитектура часто использует оба механизма. Например, skill `triage-production-error` описывает порядок +расследования: собрать симптомы, сгруппировать stack traces, найти подозрительный commit и подготовить вывод. MCP при +этом дает tools для Sentry и GitHub. Skill управляет workflow, MCP предоставляет capabilities. + +Не стоит путать это с security boundary. Инструкция в skill не должна быть единственной защитой от опасного MCP tool. +Authorization, schema validation, sandbox и approvals должны применяться на стороне host/server. + +Практичное правило выбора: -MCP skill не заменяет, когда нужна интеграция с живыми данными или действиями: прочитать приватный календарь, открыть -Figma-файл, получить GitHub review comments, управлять браузером, запросить Sentry logs или вызвать внутренний API. +1. Нужна только повторяемая методика - начните со Skill. +2. Нужны live-данные или side effects - нужен tool/API, часто через MCP. +3. Нужны и методика, и интеграция - Skill может оркестрировать MCP tools. +4. Контекст короткий и одноразовый - возможно, достаточно обычного prompt. -Короткое правило: **Skill учит агента как работать, MCP дает агенту куда подключиться и что вызвать**. +На интервью полезно сформулировать так: **Skill хранит процедуру, MCP дает стандартизированный доступ к внешним +возможностям; один не является новой версией другого**. @@ -1672,18 +1752,43 @@ Figma-файл, получить GitHub review comments, управлять бр **Короткий ответ** -AGENTS.md - это durable-инструкции для репозитория: стиль кода, команды проверки, правила ревью и локальные ограничения. -Skill - переиспользуемый workflow для определенного класса задач, который можно активировать только когда он нужен. +`AGENTS.md` задает постоянные правила работы в репозитории, Skill подключает подробный workflow только для подходящего +класса задач, а plugin распространяет готовый пакет capabilities и может включать Skills, MCP или оба механизма. **Полный ответ** -`AGENTS.md` - это durable-инструкции для репозитория: стиль кода, команды проверки, правила ревью и локальные -ограничения. Skill - переиспользуемый workflow для определенного класса задач, который можно активировать только когда -он нужен. +Эти механизмы решают разные задачи, поэтому выбирать между ними лучше по времени жизни и scope инструкции. -Plugin - это способ распространить набор capabilities: один или несколько skills, MCP-настройки, apps, assets и -metadata. Если нужно просто описать процесс для текущего репозитория, достаточно `AGENTS.md` или repo skill. Если нужно -поставлять интеграцию другим пользователям, лучше plugin. +**`AGENTS.md` - постоянный контекст проекта.** Codex читает instruction chain до начала работы. В файл обычно кладут +команды сборки и тестов, архитектурные границы, правила review и другие ожидания, которые должны действовать почти в +каждой задаче. + +**Skill - task-scoped workflow.** Он не обязан загружаться целиком всегда. Codex сначала видит metadata и подгружает +`SKILL.md`, references или scripts, когда skill явно выбран или подходит по описанию. Это удобно для подробных процедур, +которые нужны только иногда. + +**Plugin - единица распространения.** Plugin устанавливается как пакет и может содержать один или несколько Skills, MCP +server/configuration и связанные metadata. Если workflow нужно удобно распространять между пользователями или командами +вместе с интеграцией, plugin является более подходящим контейнером. + +Например: + +- «в этом monorepo после изменений запускай `npm run affected:test`» - `AGENTS.md`; +- «проведи миграцию Angular по нашему девятишаговому процессу» - Skill; +- «установи корпоративный набор release-workflows вместе с MCP к внутреннему release service» - plugin. + +Для Codex repo-specific skills можно хранить в `.agents/skills`, поэтому Skill тоже может жить прямо в репозитории. +Разница с `AGENTS.md` не в месте хранения, а в модели загрузки: общие правила действуют постоянно, подробный workflow +подключается по задаче. + +`AGENTS.md` и Skill не являются надежной заменой автоматическим ограничениям. Если правило можно детерминированно +проверить lint, typecheck, test или CI, лучше иметь такую проверку, а инструкцией объяснить причину и способ запуска. + +На интервью удобная модель: **AGENTS.md = always-on repo policy, Skill = on-demand procedure, plugin = installable +distribution package**. + +См. [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) и +[Build plugins](https://learn.chatgpt.com/docs/build-plugins). @@ -1695,26 +1800,44 @@ metadata. Если нужно просто описать процесс для **Короткий ответ** -Такие файлы хранят устойчивые инструкции для AI-инструмента внутри репозитория или рабочей папки. Они помогают не -повторять в каждом prompt одни и те же правила: как запускать тесты, какой стиль кода принят, какие архитектурные -границы нельзя нарушать, как оформлять PR и какие команды опасны. +Instruction-файлы хранят устойчивые правила проекта для конкретного AI-инструмента: команды, архитектурные границы, +ограничения и review policy. Формат и precedence зависят от инструмента; для Codex официальным механизмом являются +`AGENTS.md` и `AGENTS.override.md`. **Полный ответ** -Такие файлы хранят устойчивые инструкции для AI-инструмента внутри репозитория или рабочей папки. Они помогают не -повторять в каждом prompt одни и те же правила: как запускать тесты, какой стиль кода принят, какие архитектурные -границы нельзя нарушать, как оформлять PR и какие команды опасны. +Instruction-файл уменьшает необходимость повторять в каждом prompt одни и те же сведения о репозитории. Он превращает +часть командных договоренностей в machine-readable контекст: как запустить проверки, какие слои нельзя связывать, какие +файлы generated и какие действия требуют особой осторожности. + +Важно не считать все похожие filenames одним универсальным стандартом. Разные инструменты используют собственные +механизмы и правила precedence. Например: + +- Codex использует `AGENTS.md` и `AGENTS.override.md`; +- Claude Code может использовать `CLAUDE.md`; +- Gemini CLI - собственный context/instruction mechanism; +- GitHub Copilot поддерживает repository custom instructions; +- AI IDE могут иметь свои каталоги rules. + +Перед переносом правил между инструментами нужно проверить их документацию: одинаковое имя или похожая идея не +гарантируют одинаковую область действия. -Примеры: +В Codex инструкции образуют иерархию. Сначала учитывается глобальный файл пользователя, затем файлы от корня проекта к +текущей директории. Более близкие к рабочей папке инструкции добавляются позже и могут уточнять или переопределять более +общие правила. `AGENTS.override.md` имеет приоритет над обычным `AGENTS.md` в соответствующей директории. -- `AGENTS.md` - распространенный формат инструкций для coding agents, включая Codex. -- `CLAUDE.md` - project memory для Claude Code; обычно содержит команды, стиль и важные сведения о проекте. -- `GEMINI.md` - контекстный файл, который используют Gemini CLI и похожие Google AI workflows. -- `.cursorrules`, `.cursor/rules/*`, `.windsurfrules` - правила для AI IDE. -- `.github/copilot-instructions.md` - repository custom instructions для GitHub Copilot. +Это позволяет держать общую policy в корне monorepo, а рядом с frontend или backend добавить локальные команды и +ограничения. Но слишком глубокая и противоречивая иерархия усложняет понимание того, какое правило реально действует. -Эти файлы не заменяют README. README объясняет проект людям, а instruction-файл дополнительно настраивает поведение AI. -Хороший instruction-файл короткий, конкретный и проверяемый: команды, ограничения, naming, test policy, review policy. +Instruction-файл не заменяет README: README объясняет проект людям, а instruction-файл оптимизирует работу агента. Он +также не заменяет CI. Форматирование, запрещенные imports или обязательные тесты надежнее контролировать +детерминированными checks. + +Файлы инструкций сами являются частью attack surface. Изменение `AGENTS.md` в стороннем репозитории или Pull Request +нужно ревьюить как код: вредная инструкция может пытаться расширить действия агента или убедить его прочитать секреты. + +На интервью сильный ответ упоминает три свойства: **устойчивый project context, иерархический scope и необходимость +подкреплять критичные правила автоматическими проверками**. @@ -1726,22 +1849,53 @@ metadata. Если нужно просто описать процесс для **Короткий ответ** -Полезно добавлять то, что агент должен соблюдать почти в каждой задаче: +Кладите стабильные, часто применимые и проверяемые правила: команды setup/build/test, архитектурные границы, generated +files, security-ограничения и требования к review. Временные детали задачи, секреты и длинную энциклопедию лучше держать +вне instruction-файла. **Полный ответ** -Полезно добавлять то, что агент должен соблюдать почти в каждой задаче: +Хороший instruction-файл отвечает на вопрос: **что агенту нужно знать почти при любой работе в этой части репозитория, +чтобы не совершать повторяющиеся ошибки?** + +Полезно включать: + +- точные команды установки, lint, typecheck, unit/e2e tests и build; +- краткое описание архитектурных границ и запрещенных зависимостей; +- naming и conventions, которые нельзя вывести из существующего кода; +- какие файлы generated и как их правильно обновлять; +- требования к тестам и минимальные проверки перед commit/PR; +- правила работы с секретами, production-данными и destructive commands; +- dependency policy: чем разрешено пользоваться и когда нужна отдельная миграция; +- формат summary, changelog или PR, если он действительно стандартизирован командой. + +Писать лучше конкретно и императивно: «после изменения public API запусти `npm run test:types`» полезнее, чем «пиши +качественный код». Если правило можно проверить автоматически, инструкция должна указывать check, а сам invariant стоит +закрепить в CI. + +Что обычно не стоит класть: + +- документацию, которая нужна только редкому классу задач; +- временный контекст одной issue; +- длинные tutorial и справочники; +- секреты, tokens и production credentials; +- правила форматирования, полностью обеспеченные formatter/linter; +- десятки пожеланий без способа понять, выполнены ли они. + +Для monorepo полезно использовать layering: в корневом `AGENTS.md` оставить общие правила, а локальные инструкции +положить ближе к соответствующему пакету. Это уменьшает шум и делает scope правила понятнее. + +Если инструкция превращается в длинный условный workflow, ее лучше вынести в Skill. Если для выполнения нужны +live-данные или внешние действия, добавить соответствующий tool/MCP. Так `AGENTS.md` остается компактной policy, а не +энциклопедией всех процессов команды. + +В Codex также есть ограничение на суммарный размер project instructions, поэтому разрастание файлов влияет не только на +читаемость, но и на то, какой контекст реально попадет в instruction chain. -- команды установки, проверки, сборки и тестов; -- границы модулей и владельцев; -- стиль TypeScript, Angular, CSS и тестов; -- запрет на destructive commands без подтверждения; -- как работать с секретами и приватными данными; -- какие файлы generated и не должны редактироваться вручную; -- как оформлять summary, PR и changelog. +На интервью полезная формула: **instruction-файл содержит стабильные always-on правила; подробный task workflow идет в +Skill, а проверяемый invariant - в CI**. -Не стоит превращать instruction-файл в большую энциклопедию. Чем больше там общих пожеланий, тем выше шанс, что важные -правила потеряются. Для длинных workflow лучше сделать отдельный skill или documentation page и ссылаться на него. +См. [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).