Struktura projektu dla AI

Chociaż asystenci kodowania AI są potężni, nie są magiczne. Polegają na strukturze i organizacji projektu, aby zrozumieć jego architekturę, konwencje i ograniczenia. Dobrze zorganizowany projekt jest łatwiejszy do nawigacji dla AI, prowadząc do bardziej dokładnych i świadomych kontekstu sugestii.

Ten przewodnik obejmuje najlepsze praktyki organizowania plików i konfiguracji, aby zmaksymalizować skuteczność zarówno Cursor jak i Claude Code.

Siła konfiguracji specyficznej dla AI

Zarówno Cursor jak i Claude Code wykorzystują specjalne pliki konfiguracyjne, aby dostarczyć im wysokopoziomowy, trwały kontekst o projekcie. Te pliki to najważniejszy element w strukturyzacji projektu dla AI.

Cursor: .cursor/rules/

Cursor używa katalogu .cursor/rules/ do przechowywania wytycznych specyficznych dla projektu. Te pliki .mdc mogą definiować standardy kodowania, wzorce architektoniczne i polecenia wielokrotnego użytku. Możesz mieć globalny zestaw zasad w głównym katalogu projektu i bardziej specyficzne zasady w podkatalogach (np. frontend/.cursor/rules/).

Claude Code: CLAUDE.md

Claude Code polega na plikach CLAUDE.md. Podobnie jak zasady Cursor, mogą być hierarchiczne. CLAUDE.md w głównym katalogu zapewnia globalny kontekst, podczas gdy zagnieżdżone w katalogach jak backend/ lub services/ dostarczają bardziej specyficzne instrukcje, gdy AI pracuje w tych częściach bazy kodu.

Kluczowy wniosek: Używaj tych plików konfiguracyjnych do dokumentowania “niepisanych zasad” projektu, aby AI mogło je przestrzegać.

Najlepsze praktyki organizacji plików

1. Używaj hierarchicznej konfiguracji. Dla każdego nietrywialne projektu, szczególnie monorepo, używaj zagnieżdżonych plików konfiguracyjnych.

   • Poziom główny: Zdefiniuj standardy obejmujące cały projekt, zależności i przegląd architektoniczny.
   • Poziom serwisu/modułu: W podkatalogach frontend/, backend/ lub packages/ dodaj specyficzne zasady dla tej części bazy kodu (np. “Zawsze używaj React Server Components w frontend”, lub “Backend używa wzorca Repository do dostępu do danych”).

2. Powiedz AI, co ignorować. Równie ważne jak mówienie AI, na co ma patrzeć, jest mówienie mu, co ignorować.

   • .gitignore: Oba narzędzia respektują .gitignore. Upewnij się, że jest kompletny, aby trzymać node_modules, artefakty budowania i pliki środowiskowe poza kontekstem AI.
   • Ignorowanie specyficzne dla narzędzi: Użyj .cursor/ignored-files dla Cursor lub podobnych konfiguracji, aby wprost zapobiec dostępowi AI do wrażliwych plików lub katalogów, które mogą nie być w .gitignore (jak duże pliki danych).

3. Umieszczaj dokumentację blisko kodu. Trzymaj dokumentację jak najbliżej kodu. Jeśli masz złożony moduł, README.md wewnątrz katalogu tego modułu to bezcenny kontekst dla asystenta AI. Możesz używać asystenta AI do pomocy w generowaniu i utrzymywaniu tej dokumentacji.

4. Zarządzaj projektami wielorepozytorium. Gdy pracujesz nad funkcją obejmującą wiele repozytoriów (np. serwis i współdzieloną bibliotekę):

   • Cursor: Użyj Multi-Root Workspaces, aby otworzyć wszystkie istotne repozytoria w jednym oknie.
   • Claude Code: Użyj flagi --add-dir lub polecenia /add-dir, aby wprowadzić wiele katalogów projektów do kontekstu jednej sesji.

5. Rozbijaj duże pliki. Chociaż nowoczesne AI może obsługiwać bardzo duże pliki, wydajność i dokładność poprawiają się z mniejszymi, bardziej skupionymi modułami. Jeśli masz plik liczący tysiące linii, rozważ poproszenie AI o pomoc w refaktoryzacji go na mniejsze, bardziej zarządzalne części. To nie tylko pomaga AI, ale także poprawia łatwość utrzymania kodu.

Przyjmując te strategie organizacyjne, zapewniasz jasne i ustrukturyzowane środowisko dla asystenta AI, umożliwiając mu funkcjonowanie jako prawdziwy, świadomy kontekstu członek zespołu programistycznego.