APC має залишатися безпечним для клонування, APX — локальним для машини

Визначте, де мають зберігатися дані, поставивши одне запитання.

Чи будуть ці дані актуальними після свіжого клонування на іншу машину?

Якщо так — кладіть у APC. Якщо ні — у APX.

Це правило робить ваш стек прозорим. APC залишається портативним. APX залишається корисним на машині, де виконується робота. Коли ці шари змішуються, проєкти стає важко поширювати та аудітувати.

APC — це контракт проєкту. APX — це середовище виконання (runtime).

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

Гарні приклади APC: • AGENTS.md для контрактів репозиторію • .apc/project.json для ідентифікації проєкту • .apc/agents/ для ролей агентів • .apc/skills/ для повторно використовуваних навичок • .apc/mcps.json для спільних підказок

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

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

Репозиторій не повинен нав'язувати локальне налаштування однієї людини всім іншим.

Коли APC залишається безпечним для клонування, ви можете переглядати структуру проєкту без прихованих файлів. Ви можете порівнювати інструкції замість того, щоб шукати побічні ефекти.

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

Перш ніж додавати новий файл, поставте собі три запитання:

  1. Чи має кожен сумісний інструмент читати це? Кладіть у APC.
  2. Чи описує це проєкт, а не машину? Кладіть у APC.
  3. Чи залежить це від локальних облікових даних або нещодавнього виконання? Кладіть у APX.

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

APC містить те, що переживає клонування. APX містить те, що має значення лише на поточній машині. Це просте правило зберігає систему в здоровому стані.

Source: https://dev.to/agentprojectcontext/apc-should-stay-clone-safe-apx-should-stay-machine-local-59n9

Optional learning community: https://t.me/GyaanSetuAi