APC должен оставаться безопасным для клонирования, APX — локальным для машины

Определите, где должны храниться данные, задав один вопрос.

Выживут ли эти данные при свежем клонировании на другую машину?

Если да, поместите их в APC. Если нет — в APX.

Это правило делает ваш стек прозрачным. APC остается переносимым. APX остается полезным на машине, выполняющей работу. Когда эти слои смешиваются, проекты становится трудно передавать и проверять.

APC — это контракт проекта. APX — это среда выполнения.

Данные APC безопасны для клонирования. Другой разработчик или машина должны иметь возможность прочитать их сразу после git checkout. Они должны быть доступны для проверки в git.

Хорошие примеры APC: • AGENTS.md для контрактов репозитория • .apc/project.json для идентификации проекта • .apc/agents/ для ролей агентов • .apc/skills/ для переиспользуемых навыков • .apc/mcps.json для общих подсказок

Данные APX локальны для машины. Эти данные остаются на машине или пересоздаются на ней. Это состояние выполнения, а не переносимый контекст.

Хорошие примеры APX: • Конфигурация среды выполнения в ~/.apx/config.json • Локальные режимы разрешений • Сессии и логи сообщений • Локальные кэши • Секреты для конкретной машины

Репозиторий не должен навязывать локальные настройки одного человека всем остальным.

Когда APC остается безопасным для клонирования, вы можете изучать структуру проекта без скрытых файлов. Вы можете сравнивать инструкции (diff), а не искать побочные эффекты.

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

Прежде чем добавить новый файл, задайте себе три вопроса:

  1. Нужно ли это читать каждому совместимому инструменту? Поместите это в APC.
  2. Описывает ли это проект, а не машину? Поместите это в APC.
  3. Зависит ли это от локальных учетных данных или недавнего выполнения? Поместите это в APX.

Примеры: • Новая роль агента? APC. • Токен Telegram-бота? APX. • Заметка о правилах проверки проекта? APC. • Лог последнего разговора? APX.

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

Источник: https://dev.to/agentprojectcontext/apc-should-stay-clone-safe-apx-should-stay-machine-local-59n9

Дополнительное обучающее сообщество: https://t.me/GyaanSetuAi