Nazwa folderu to nie tożsamość projektu
Ścieżka folderu to trasa. Informuje narzędzie, gdzie projekt znajduje się w danej chwili. Tożsamość projektu to coś innego.
Tożsamość musi przetrwać następujące typowe zmiany:
- Zmiana nazwy katalogu
- Przenoszenie projektu między maszynami
- Klonowanie repozytorium do nowej ścieżki
- Korzystanie z wielu wersji (checkouts) tego samego projektu
Jeśli tożsamość zależy od ścieżki, działania te stają się ryzykowne. Ścieżka może działać, ale nie pozwala udowodnić, że projekt jest ten sam. To sprawia, że nie jest ona dobrym kluczem do przechowywania stanu.
Aby to rozwiązać, stosuję podział na APC i APX.
APC obsługuje kontrakt projektu. Znajduje się on w repozytorium. APX obsługuje stan runtime. Znajduje się on poza repozytorium.
APC wykorzystuje konkretne pliki, aby stworzyć stabilną kotwicę:
- AGENTS.md dla kontraktu głównego
- .apc/project.json dla metadanych projektu
- .apc/agents/*.md dla definicji agentów
- .apc/mcps.json dla wskazówek MCP
Plik .apc/project.json jest malutki. Zawiera nazwę i stabilne ID. Jest znacznikiem, a nie dużym plikiem konfiguracyjnym.
APX wykorzystuje ten plik, aby połączyć aktywną wersję (checkout) z trwałym zapisem. Ścieżki pomagają APX odnaleźć projekt. Metadane pomagają APX utrzymać stabilność projektu po jego odnalezieniu.
Taki projekt pozwala zachować czystość w repozytorium. Dane runtime, takie jak logi sesji i historia wiadomości, pozostają w pamięci APX. Nie zaśmiecają one historii git.
Polegając na ścieżkach, narażasz się na następujące problemy:
- Ścieżki się zmieniają
- Stan ulega awarii
- Narzędzie stawia błędne przypuszczenia
- Zamiast budować, tracisz czas na debugowanie nazw
Stabilna tożsamość eliminuje ten szum. Ułatwia przegląd kodu. W plikach diff widzisz fakty dotyczące projektu zamiast przypadkowych danych z runtime.
Granica jest prosta:
- AGENTS.md: czego projekt oczekuje
- .apc/project.json: czym projekt jest
- ~/.apx/: co działo się podczas pracy nad nim
Projekt potrzebuje jednej stabilnej kotwicy. Ścieżka folderu jest zbyt zmienna. Runtime jest zbyt głośny. Kontrakt repozytorium plus plik metadanych to odpowiednia skala.
Źródło: https://dev.to/tecnomanu/a-folder-name-is-not-a-project-identity-4eca
Opcjonalna społeczność edukacyjna: https://t.me/GyaanSetuAi