# AI Setup Apm > Настройка, проверка и диагностика APM: публикуемый пакет (`apm.yml`, `.apm/*`, выпуск) или зависимости потребителя (`apm.lock.yaml`, `apm audit`), включая восстановление установки. - Skill: `mekras/ai-setup-apm` (Agent Skill, multi-file: 36 files) - Install (CLI): `npx skillmds@latest add mekras/ai-setup-apm` - Raw SKILL.md: https://api.skillmd.com/api/skills/mekras/ai-setup-apm/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: mekras (https://skillmd.com/u/mekras) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mekras/ai-setup-apm --- # ai-setup-apm Перед существенным изменением публикуемого источника истины получи `ai-work-control/full`; продолжай по его результату без повторения контроля. ## Переносимость P0 выполняет настройку и проверку через файловые операции агента и доступные команды самой целевой задачи. До запуска поставляемого скрипта проверь Python 3 или POSIX-среду по его shebang. Если среда недоступна, выполни соответствующие изменения по этой процедуре и сообщи, что автоматическая проверка не выполнена. Не устанавливай интерпретатор или пакет без явного решения пользователя. Защищай от Python-байткода все процессы, которые читают, импортируют, исполняют или копируют файлы из `.apm`, `.agents`, `.claude`, `.codex` и поставляемой оснастки. Для наследуемой защиты предпочитай `PYTHONDONTWRITEBYTECODE=1`, а ключ `-B` используй для одного подтверждённого процесса. Ни один из способов не останавливает явные `py_compile` и `compileall`. Не применяй эти компиляторы к защищённым деревьям. Проверяй синтаксис в памяти либо поставляемым `validate-python-syntax.py`. До и после тестов, установки и аудита проверяй физические деревья и `apm.lock.yaml` через `validate-python-artifacts.py`. Работай с любым проектом, использующим APM. Сначала определи тип проекта, затем веди его по своей ветке. Публикуемый пакет настраивай так, чтобы его можно было установить, проверить и выпустить повторяемо: актуальный `apm.yml`, переносимый детерминированный контроль качества `apm run tests` без вызовов модели и сети, отдельный опциональный модельный прогон `apm run evals` и явная структурная приёмка, а не только исправление первого найденного локального дефекта. Проект- потребитель приводи к понятному состоянию зависимостей: раздельное описание прямых зависимостей, разрешённого графа и предупреждений `apm audit` с безопасной рекомендацией, а не правка манифеста под содержимое файла блокировки. ## Режим работы - `setup` — пользователь просит настроить, создать, обновить или исправить настройки APM. В этом режиме меняй файлы. - `audit` — пользователь просит проверить пакет, манифест, выпуск или причину сбоя. В этом режиме сначала верни выводы и меняй файлы только по явному запросу или если пользователь уже попросил исправить. ## Обязательный порядок 1. Определи корень проекта и его тип по APM. Наличие `apm.yml`, `apm.lock.yaml`, `dependencies.apm` или `devDependencies.apm` само по себе не задаёт тип. Различай три типа: - публикуемый пакет — есть признаки публикации: `.apm/skills/**`, `.apm/agents/**`, публикуемые `.apm/instructions/**`, `type` или `includes` в `apm.yml`, описывающие пакет проекта, `scripts.tests` для коллекции либо явный запрос настроить пакет APM; - проект-потребитель — есть зависимости APM, но признаков публикации нет; - смешанный проект — есть и признаки публикации, и потреблённые зависимости. 2. Маршрутизируй задачу по типу: - публикуемый пакет или часть смешанного проекта про публикацию → ветка «Публикуемый пакет»; - проект-потребитель или часть смешанного проекта про зависимости и установку → ветка «Проект-потребитель»; - настройка клиентского контура (подключение агента, `AGENTS.md`, `CLAUDE.md`, правила проекта) → не выполняй здесь, верни в `ai-setup-project`, `ai-agents-md-maintenance` или клиентские инструкции проекта. Прежде чем менять файлы, прочитай `references/apm-collection-settings.md`; если задача доставляет оснастку в целевой проект — дополнительно `references/tooling-installers.md`. ## Ветка: публикуемый пакет 3. Прочитай существующие `apm.yml`, `README.md`, списки `.apm/skills/**`, `.apm/agents/**`, `.apm/instructions/**`, возможный корневой `skills/**` и доступные тестовые команды. 3а. Если задача создаёт или меняет файлы `.apm/skills/**`, используй вместе с этой веткой `ai-skill-development`. Подключи оба навыка до первого запуска Python или APM: содержательная проверка навыка и защита самоприменения должны действовать в одном рабочем цикле. 3б. Отдели публичный договор коллекции от контекста её разработки. Во всех поставляемых файлах — инструкциях, справках, метаданных, примерах, сценариях, скриптах и проверках — оставляй только сведения и зависимости, нужные пользователю коллекции или проекту-потребителю. Не переноси пути, данные, настройки, процессы, средства и историю проекта-разработчика. Материал разработки преобразуй в самостоятельное правило, вымышленный пример или проверку. Если конкретная точка интеграции нужна потребителю, сначала явно опиши её назначение в публичном договоре коллекции. 4. Если `apm.yml` уже есть, обновляй его с сохранением `name`, `version`, `description`, `author`, `license`, `target`, `targets`, `dependencies` и явного `includes`, если пользователь не попросил изменить эти поля. 5. Если `apm.yml` отсутствует, создай минимальный манифест коллекции навыков: `type: "skill"`, `includes: auto`, `targets` из запроса или текущего проекта, `dependencies.apm: []`, `dependencies.mcp: []`. 6. Если в `target` или `targets` есть `claude`, считай это признаком того, что проект использует Claude как одну из обвязок. В ветке настройки пакета не создавай и не редактируй `CLAUDE.md` сам, но в отчёте явно зафиксируй, что клиентскому маршруту настройки нужно проверить наличие `CLAUDE.md` и при необходимости создать его как `@AGENTS.md` или символьную ссылку на `AGENTS.md`. 7. Если исходные навыки лежат в корневом `skills/**`, а `.apm/skills/**` отсутствует, считай это расхождением со структурой APM-пакета. Перенеси или предложи перенести исходники в `.apm/skills/**`; корневой `skills/**` оставляй только для плагинового пакета, сгенерированного пакета или явно выбранной совместимой схемы. 8. Раздели проверки на две цели и не смешивай их в одной команде: - `scripts.tests` — детерминированный контроль качества P1. Только проверки проверки (скрытые Unicode-символы в исходниках, структура `triggers.json` и `result-scenarios.json`, бюджет `description`, а при доставке оснастки — её совпадение с источником, отсутствие скомпилированных Python-артефактов и исполнимые контракты публичных Python-скриптов P1), без вызовов модели, сети и внешнего инструмента командной строки. Запускатель использует Python 3 и не зависит от синтаксиса POSIX-оболочки. Если Python отсутствует, выполни доступную структурную проверку P0 и пометь автоматическую проверку как невыполненную. Не помещай модельный прогон в `tests`. - `scripts.evals` — опциональный модельный прогон, который запускают отдельно командой `apm run evals`. Это измерение качества, а не условие приёмки. Команда должна поддерживать выборочный запуск хотя бы для одного каталога навыка и отдельного сценария через переменную среды. Не записывай команды, которые ссылаются на отсутствующие файлы; сначала найди существующие проверки либо создай недостающий скрипт в рамках задачи. Если команда использует поставляемые `tools/run-collection-checks.py` или `tools/run-skill-evals.py`, в том же подтверждённом шаге установи оснастку командой `scripts/install-eval-tools <корень-проекта>` и проверь запуск `apm run tests` либо самой Python-команды. Установка навыка через APM доставляет источник установщика, но не создаёт рабочие копии в `tools/`. 9. Для коллекции с исходниками в `.apm/skills` используй две команды P1. Подставь доступную в целевой среде команду Python 3, например `python`, системный вариант с суффиксом версии или `py -3`. Не закрепляй один вариант как универсальный. Контроль качества без модели: ```text <команда Python 3> tools/run-collection-checks.py ``` Опциональный модельный прогон: ```text <команда Python 3> tools/run-skill-evals.py [путь-к-навыку] ``` Модельный прогон вызывает модель через адаптер по переносимому контракту: вызов `<команда адаптера> <модель>`, запрос на стандартном вводе, текст ответа на стандартном выводе. Адаптеры, список моделей и модель-судью задаёт локальный файл настроек `evals.local.yml`, который не попадает в Git: средство запуска создаёт его из образца `evals.sample.yml` при первом запуске и добавляет в `.git/info/exclude`. Модели и судью указывают в формате `адаптер:модель`, поэтому один прогон может сочетать модели от разных адаптеров; каждая запись проверяется по одинаковым критериям. Имена моделей в `apm.yml` и навыках не фиксируй. Для проверки одного навыка добавь `APM_EVAL_PATH=.apm/skills/`, для отдельного сценария — `APM_EVAL_CASE_ID=`. Канонический источник этой оснастки — `scripts/eval-tools/` этого навыка; рабочие копии в `tools/` ставит установщик `scripts/install-eval-tools` по `references/tooling-installers.md`. Целевому проекту-издателю не переписывай адаптеры и средство запуска вручную, а установи их: `install-eval-tools .`. Чтобы рабочие копии не разошлись с источником, в контроль качества `tests` входит детерминированная проверка `scripts/eval-tools/check-eval-tools-drift.py`; при расхождении правь источник в `eval-tools` и переустанавливай оснастку. Проверка скрытых Unicode-символов сканирует исходники пакета, а не только выбранный `APM_EVAL_PATH`, потому что `apm install` предупреждает именно об исходном дереве пакета. Если навык содержит Python-скрипт первого уровня в `scripts/`, контроль качества требует `evals/script-contract-tests.json` с реалистичной фикстурой и запуском поставляемой команды. В нём нельзя подменять проверку сценария импортом внутренней функции, `--help` или ожидаемым отказом. В `operations` контракта перечисли обязательные операции скрипта и укажи `covers` успешного сценария. Для каждой операции обязателен успешный рабочий сценарий с совпадающим префиксом команды. Команды из процедуры навыка должны быть сопоставлены с `operations` контракта. Для сохранённого JSON рабочий сценарий выполняет запись и повторно читает созданный файл. Контроль качества обязан отклонять `__pycache__`, `.pyc` и `.pyo` в защищённых деревьях и семантических путях `apm.lock.yaml`. Он запускает этот барьер до и после остальных проверок. Для синтаксиса используй `validate-python-syntax.py`, а не `py_compile` или `compileall`. 9а. Для самоприменения коллекции используй поставляемый безопасный цикл: ```text <команда Python 3> tools/run-apm-safe.py ``` Он выполняет предварительную проверку, `apm install --frozen`, повторную проверку, `apm audit --ci` и итоговую проверку в среде с запретом записи байткода. Локальный запускатель аудита можно передать через `--audit-runner`. Если предварительный барьер нашёл запись только в `apm.lock.yaml`, не правь файл вручную: сохрани производное состояние и пересоздай lock-файл из чистого исходного дерева по процедуре восстановления. 10. До полного модельного прогона выбирай самый узкий достаточный цикл: контроль качества `tests` и валидаторы изменённого навыка, затем `apm run evals` для затронутого навыка или сценария, затем полный прогон перед выпуском, изменением общей инфраструктуры или правкой нескольких навыков. 11. Для механического создания нового базового `apm.yml` можно применить P1 `scripts/setup-apm-collection`. Скрипт использует только стандартную библиотеку, устанавливает поставляемую оснастку проверок в `tools/` и намеренно отказывается менять существующий YAML. Существующий манифест обновляй по процедуре P0, затем установи оснастку отдельным установщиком, проверь diff и разбери итоговый файл доступным YAML-средством. В манифесте должны остаться по одному `scripts` и `includes`, а `.apm/skills/**`, `includes` и команда тестов должны соответствовать реальным файлам проекта. 12. После правки запусти доступные детерминированные проверки: синтаксис `apm.yml`, валидаторы тестов навыков, повторную проверку упаковки после изменения публикуемого состава, `apm audit` или `apm view`, если они доступны локально и не требуют неподходящего окружения. 13. Перед завершением режима `setup` закрой явный чек-лист готовности: `apm.yml`, исходное дерево `.apm/skills/**`, `includes`, `scripts.tests`, граница публичного договора, публикуемый состав после правок и различие между подтверждёнными и непроверенными свойствами установки, упаковки и аудита. Если `scripts.tests` ссылается на `tools/`, отдельно подтверди, что все нужные файлы созданы установщиком и команда запускается. Для границы проверь всё поставляемое дерево, а не только `SKILL.md`: известные внутренние маркеры должны блокироваться автоматической проверкой, а в чистом проекте-потребителе без материалов разработчика должны проходить установка и детерминированный контроль качества. 14. Не завершай `setup` выводом вида «больше править нечего» только потому, что найден один локальный дефект упаковки, один мусорный артефакт или прошла отдельная команда APM. Если часть структурной приёмки недоступна, явно назови, что не проверено, почему и какой остаточный риск остаётся. 15. В отчёте назови изменённые файлы, итоговую команду `apm run tests`, выполненные проверки и оставшиеся ограничения. ## Ветка: проект-потребитель 15. Веди `apm.yml` как декларацию прямого намерения проекта: `dependencies.apm` и `devDependencies.apm` — это пакеты, которые проект сам подключает. Различие секций: `devDependencies` исключаются из вывода `apm pack` и нужны для оснастки и тестов; обе секции — прямые декларации. `apm.lock.yaml` генерируется командой `apm install`, записывает весь разрешённый граф, включая транзитивные пакеты, и его нельзя править руками. Подробности — в `references/apm-collection-settings.md`. 16. При диагностике раздели слои и не смешивай их: прямые зависимости из `apm.yml`; транзитивно установленные пакеты из файла блокировки и развёрнутого дерева (`apm_modules/**`, `.agents/skills/**`); предупреждения инструмента. Транзитивный пакет в файле блокировки — это норма, а не повод добавлять его в прямые зависимости. 17. Трактуй `apm audit` по его реальным категориям расхождения установки: `unintegrated` (есть исходник, нет развёрнутого файла), `modified` (развёрнутый файл отличается от результата установки), `orphaned` (развёрнутый файл без источника). Штатное исправление всех трёх — `apm install` или возврат правки в источник, а не правка `apm.yml`. Правку `apm.yml` предлагай только как новое решение проекта подключить пакет напрямую, а не чтобы повторить файл блокировки или скрыть предупреждение. 18. Если повтор установки или `apm audit --ci` сообщает, что выпуск обязан поставить конкретный файл, но этот файл отсутствует в полученном пакете, не считай это обычным `unintegrated`, `modified` или `orphaned` и не повторяй `apm install` без изменения состояния. Сначала выполни процедуру восстановления из `references/apm-collection-settings.md`: сохрани проверяемую копию состояния, пересоздай только производные APM-файлы из `apm.yml`, затем снова проверь установку. Не удаляй рекурсивно `apm.lock.yaml`, `apm_modules`, `.agents`, `.codex` или `.claude`; не затрагивай отслеживаемые Git и неидентифицированные пользовательские файлы. Если чисто пересозданное состояние воспроизводит тот же отсутствующий путь, это дефект выпуска или его метаданных. Сообщи пакет, версию и путь, сохрани резервную копию и запроси исправленный выпуск либо решение человека о временном обходе. 19. В отчёте по потребителю раздели прямые зависимости, разрешённый граф и предупреждения `apm audit`; назови безопасное исправление и отдельно — решения, которые требуют человека. ### Граница проекций зависимостей и Git Если проект-потребитель использует APM и Git, предложи включить в его обязательные детерминированные проверки поставляемый валидатор: ```text <команда Python 3> <путь-к-ai-setup-apm>/scripts/validate-apm-git-boundary.py ``` Валидатор требует APM и Git. Он сопоставляет `git ls-files` с владельцами, которых для каждого пути сообщает `apm find` по `apm.lock.yaml`. Он завершится с ошибкой для отслеживаемой проекции и назовёт файл, пакет и действие: удалить файл из индекса Git и добавить правило в `.gitignore`. Скрипт не изменяет индекс, рабочее дерево или `.gitignore`. Не определяй проекцию по имени каталога: отслеживаемый проектный файл в `.agents/`, `.claude/` или `.codex/` допустим, если его нет в реестре развёртывания зависимости. Не передавай валидатору собственное исходное дерево `.apm/` проекта как проекцию зависимости. ## Ограничения - Не подменяй настройку APM обычной документацией в README. - Не считай `apm.yml`, `apm.lock.yaml`, `dependencies.apm` или `devDependencies.apm` достаточным признаком того, что проект публикует коллекцию APM. - Не превращай проект-потребитель в producer-пакет без явных признаков публикации или отдельного запроса человека на настройку пакета APM. - Не трактуй `orphaned` в `apm audit` как транзитивный пакет в файле блокировки: это категория расхождения развёрнутых файлов без источника, штатно лечится `apm install`. - Не лечи отсутствующий в самом выпуске заявленный файл многократным `apm install`, ручной правкой `apm.lock.yaml` или рекурсивным удалением рабочих каталогов. До пересоздания производного состояния сохрани его и проверь, что не будут затронуты отслеживаемые Git или неидентифицированные пользовательские файлы. - Не копируй содержимое `apm.lock.yaml` в прямые `dependencies.apm`, чтобы убрать предупреждение `apm audit`; меняй прямые зависимости только как новое смысловое решение проекта. - Не перезаписывай существующие метаданные пакета без причины. - Не фиксируй конкретные модели в переносимом навыке, манифесте коллекции или контроле качества `tests`. Модели задают только локальные настройки модельного прогона вне Git. - Не помещай модельный прогон в `scripts.tests`: контроль качества обязан выполняться без ошибок без модели, сети и внешнего инструмента командной строки. - Не считай один найденный артефакт упаковки или один успешный запуск команды достаточным доказательством, что вся структура коллекции APM восстановлена. - Не считай `apm compile` обязательным для коллекции только из `.apm/skills/**`; используй его для `instructions` или когда проект явно публикует соответствующие примитивы APM. - Не используй `hooks` и `commands` как основной переносимый механизм, если задачу можно решить через `skills`, `prompts`, `instructions` или `agents`. ## Формат результата Если задача относится к настройке клиентского контура и маршрутизирована дальше, укажи: - какие найденные APM-файлы относятся только к клиентскому подключению; - есть ли в `target` или `targets` признак `claude` и что это означает для `CLAUDE.md`; - куда перенаправлена задача: `ai-setup-project`, `ai-agents-md-maintenance` или клиентские инструкции проекта; - почему эта часть не выполняется внутри `ai-setup-apm`. Для ветки «Проект-потребитель» укажи: - список прямых зависимостей из `apm.yml` (`dependencies.apm`, `devDependencies.apm`); - что относится к разрешённому графу: транзитивно установленные пакеты из файла блокировки и развёрнутого дерева; - как разобраны предупреждения `apm audit` по категориям `unintegrated`, `modified`, `orphaned`; - если воспроизведение установки остановилось на отсутствующем заявленном файле — какие производные данные сохранены и пересозданы, чем подтверждён дефект выпуска и какое решение остаётся за человеком; - безопасное исправление и отдельно — решения, которые требуют человека. Для ветки «Публикуемый пакет» в режиме `setup` укажи: - что было создано или обновлено в `apm.yml`; - какие команды стоят в `scripts.tests` и `scripts.evals`; - чем подтверждена структурная готовность `apm.yml`, `.apm/skills/**`, `includes` и публикуемого состава; - чем подтверждено, что контроль качества `apm run tests` проходит без модели, а `apm run evals` запускается отдельно; - какие проверки выполнены; - что не проверено и какой риск остался; - что осталось проверить человеку перед публикацией. Для ветки «Публикуемый пакет» в режиме `audit` укажи: - найденные расхождения по манифесту, тестам и процессу APM; - риск каждого расхождения; - достаточное изменение для восстановления работоспособной коллекции.