Prywatna konfiguracja agenta

Nie ma się co oszukiwać. Niemal każdy z nas korzysta, lub skorzystał już z dobrodziejstw sztucznej inteligencji. Jeśli jesteś programistą to z pewnością też używasz agenta do pracy nad swoim programem. Wiesz pewnie także, że lepiej sobie radzi gdy opiszesz mu jak wygląda twój projekt. Jak jednak trzymać taką konfigurację jeśli nie możemy jej zapisać bezpośrednio w repozytorium?

tl;dr

• Agenty AI mogą być konfigurowane za pomocą plików AGENTS.md znajdujących się w kodzie
• Narzędzie stow umożliwia linkowanie plików i katalogów do struktury innego repozytorium
• Używamy .git/info/exclude aby ignorować linkowane pliki
• Inne pomysły na użycie konfiguracji stow tutaj

Konfiguracja AI

Dzięki agentom AI jesteśmy w stanie lepiej zarządzać swoim kodem. Są one w stanie przeanalizować projekt i dodać zmiany, właśnie tam, gdzie są akurat potrzeba. Jednak nie zawsze taka wiedza jest dostępna na pierwszy rzut oka. Agent nie zawsze jest w stanie domyślić się, jak powinien poruszać się po naszym kodzie.

Aby pomóc agentom w poprawnej edycji naszego kodu, warto dodać im kilka informacji na temat architektury używanego rozwiązania. Dane te najczęściej zapisywane są do plików AGENTS.md znajdujących się w repozytorium. Plik ten dla wielu modeli może przybierać różną nazwę, najczęściej jest on jednak zestawem instrukcji doklejanych do głównego zapytania.

Innym źródłem danych mogą być też narzędzia zwane skils lub agents (w zależności od używanego serwisu). Dodają one nam dodatkowe instrukcji dla konkretnego działania które chcemy podjąć. Może to być np. code review, tworzenie dokumentacji czy sprawdzanie poprawności kodu. Wyglądają one podobnie do wyżej wymienionych plików AGENTS.md, ale są dodawane na żądanie dewelopera. Copilot na przykład, lokalizuje je w folderze .github/agents.

Pliki z konfiguracją mogą być dołączone do głównego repozytorium z kodem i w ten sposób udostępnione wszystkich użytkownikom. Co jednak gdy nie chcemy włączać tych plików do oficjalnego kodu, ale chcielibyśmy zachować je w zewnętrznym repozytorium, które będzie odpowiednio połączone z głównym kodem?

Konfiguracja w zewnętrznym repo

Chcąc synchronizować pliki agentów w prywatnym repozytorium warto zadbać o to, aby proces wgrywania nowych zmian był jak najbardziej automatyczny.

Używam do tego narzędzia stow. Jest to prosty program, który tworzy linki dla konfiguracji z wewnętrznego repozytorium, do wybranego miejsca w strukturze plików, co pozwala na ich szybkie edytowanie w głównym repo. Innymi słowy jeśli stworzymy plik z konfiguracją w swoim prywatnym repozytorium to zlinkujemy je z pracowym. Możemy w ten sposób edytować plik konfiguracyjny na poziomie firmowego repo i zapisywać zmiany w prywatnym repozytorium.

Warto odnotować że narzędzie to zostało stworzone do synchronizacji konfiguracji w linuxowych plikach /home co ułatwiało przenoszenie ich pomiędzy urządzeniami użytkownika.

Stwórzmy zatem prywatne repozytorium, w którym będziemy trzymali swoją konfigurację. Repozytorium powinno zawierać folder z nazwą naszej konfiguracji. Dzięki temu w jednym repo będziemy mogli trzymać ustawienia dla wielu projektów, lub wiele konfiguracji, które będziemy wybierać.

mkdir private-config && cd private-config
git init
mkdir main-config

Teraz w katalogu z konfiguracją (w naszym przykłądzie main-config) tworzymy strukturę odpowiadającą naszemu projektowi i dodajemy tam wybrane pliki.

touch main-config/AGENT.md ## AGENT.md znajdzie się w głównym katalogu

mkdir main-config/.github/agents && touch main-config/.github/agents/pull-request.md ## pull-request będzie utworzony w katalogu .github/agents

Teraz wystarczy użyć narzędzia stow do zlinkowania naszej konfiguracji:

stow --target <path_to_workspace> main-config

Teraz stow automatycznie doda linki symboliczne do plików z main-config i będą one widziane w głównym repozytorium. W przypadku folderu .github/agents jeśli istniał wcześniej dodane pliki znajdujące się w nim. Jeśli takiego katalogu nie było wcześniej, zostanie on dołączony w całości, przez co nowo dodane pliki automatycznie trafią do repozytorium z prywatną konfiguracją.

Ukrywanie konfiguracji w repo

Wadą naszego rozwiązania może być fakt, że system kontroli wersji będzie proponował dodanie naszych plików do kontroli wersji. Można je zatem zapisać w naszym .gitignore znajdującym się w repozytorium. Co jeśli nie chcemy zostawiać śladów w głównym repozytorium?

Świetną alternatywą jest plik .git/info/exclude. Odgrywa on taką samą rolę jak .gitignore ale nie podlega wersjonowaniu. Może zatem posłużyć do zapisywania plików, które mają być “niewidzialne” dla systemu kontroli wersji.

Przykładowa treść pliku dla naszego przypadku:

AGENTS.md
/.github/agents

Można się w tym miejscu pokusić o dodanie tego pliku do prywatnego repo z konfiguracją, jednak w tym przypadku zalecam ostrożność. Jeśli zechcemy dodać kilka różnych konfiguracji (profili), mogą wystąpić konflikty, a narzędzie nie będzie wiedziało na którym pliku exclude bazować.

To może skonfigurujmy coś jeszcze

Za pomocą narzędzi które wymieniłem można wrzucać nie tylko konfigurację agentów, ale również innego rodzaju ustawienia. Poniżej kilka przykładów:

• Globalne ustawienia narzędzi. (linki do pliku /home)
• Konfiguracja ulubionego IDE (np link issue w inteliJ)
• Dodanie repozytorium z dokumentacją bezpośrednio w repozytorium kodu
• Dodanie prywatnych skryptów wewnątrz repo
• Dodatkowy system budowania ułatwiający nawigowanie po repozytorium np Taskfile
• Rozbudowa kodu aplikacji o dodatkowe pliki z narzędziami do szybkiego debugowania (np customowy logger zdefiniowany w dodatkowym pliku)

Bibliografia

1. https://www.gnu.org/software/stow/manual/stow.html - Dokumentacja stow
2. https://git-scm.com/docs/gitignore - Dokumentacja gitignore