Название папки — это не идентификатор проекта

Путь к папке — это маршрут. Он указывает инструменту, где проект находится в данный момент. Идентификатор проекта — это нечто иное.

Идентификатор должен сохраняться при следующих распространенных изменениях:

  • Переименование директории
  • Перенос проекта между машинами
  • Клонирование репозитория по новому пути
  • Использование нескольких чек-аутов одного и того же проекта

Если идентификация зависит от пути, эти действия становятся рискованными. Путь может работать, но он не может подтвердить, что проект остался тем же самым. Это делает его плохим ключом для хранения состояния.

Для решения этой проблемы я использую разделенную архитектуру с APC и APX.

APC отвечает за контракт проекта. Он находится в репозитории. APX отвечает за состояние выполнения (runtime state). Он находится вне репозитория.

APC использует определенные файлы для создания стабильного якоря:

  • AGENTS.md для корневого контракта
  • .apc/project.json для метаданных проекта
  • .apc/agents/*.md для определений агентов
  • .apc/mcps.json для подсказок MCP

Файл .apc/project.json очень мал. Он содержит имя и стабильный ID. Это маркер, а не объемный конфигурационный файл.

APX использует этот файл, чтобы связать текущий чек-аут с постоянной записью. Пути помогают APX найти проект. Метаданные помогают APX сохранять стабильность проекта после того, как он будет найден.

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

Когда вы полагаетесь на пути, вы сталкиваетесь со следующими проблемами:

  • Пути меняются
  • Состояние нарушается
  • Инструмент делает неверные предположения
  • Вы тратите время на отладку имен вместо разработки

Стабильный идентификатор устраняет этот шум. Он упрощает проверку кода (code reviews). В диффах вы видите факты о проекте, а не случайный вывод во время выполнения.

Граница проста:

  • AGENTS.md: чего ожидает проект
  • .apc/project.json: чем является проект
  • ~/.apx/: что происходило во время работы над ним

Проекту нужен один стабильный якорь. Путь к папке слишком изменчив. Runtime слишком зашумлен. Контракт репозитория плюс файл метаданных — это оптимальный вариант.

Source: https://dev.to/tecnomanu/a-folder-name-is-not-a-project-identity-4eca

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