Struktura projektu zoptymalizowana pod AI

Prosisz AI o dodanie nowego endpointu API. Znajduje handler route’a, ale potem spędza 8000 tokenów na czytaniu 2000-liniowego pliku “utils.ts” szukając helperów do walidacji. Są tam — obok 40 innych niepowiązanych funkcji. AI się gubi, wybiera zły helper i generuje kod, który psuje istniejącą funkcjonalność.

To samo zadanie w dobrze zorganizowanym projekcie zużywa ułamek kontekstu. AI natychmiast znajduje src/validators/user.ts, czyta 80 linii i generuje poprawny kod za pierwszym razem.

Organizacja plików to nie tylko czytelność dla ludzi. To nawigowalność dla AI. Im łatwiej twoja baza kodu jest do przejrzenia, tym mniej kontekstu AI marnuje na eksplorację i tym lepsza jest jakość wyników.

Czego się nauczysz

Wzorzec struktury projektu zoptymalizowany pod programowanie wspomagane AI
Wskazówki dotyczące rozmiaru plików, nazewnictwa i granic modułów pomagające narzędziom AI
Strategie organizacji monorepo i dużych baz kodu pod AI
Prompty do analizy i poprawy istniejącej struktury przez AI

Dlaczego organizacja plików ma znaczenie dla AI

Asystenci AI do kodowania nawigują po bazie kodu na dwa sposoby:

Czytanie plików. AI czyta pliki, aby zrozumieć kontekst. Każda przeczytana linia zużywa tokeny.
Wyszukiwanie. AI szuka po nazwie pliku, zawartości lub znaczeniu semantycznym. Jasne nazewnictwo sprawia, że wyniki wyszukiwania są trafniejsze.

Słaba organizacja szkodzi obu ścieżkom:

Gigantyczne pliki zmuszają AI do czytania tysięcy nieistotnych linii, żeby znaleźć jedną potrzebną funkcję.
Niejasne nazwy (utils.ts, helpers.ts, misc.ts) sprawiają, że wyniki wyszukiwania są niejednoznaczne i zmuszają AI do spekulatywnego czytania plików.
Głębokie zagnieżdżanie zwiększa liczbę traversów katalogów, które AI musi wykonać.
Cykliczne zależności dezorientują AI co do granic modułów i prowadzą do błędnych sugestii importów.

Zasady struktury przyjaznej AI

Małe, skupione pliki

Utrzymuj pliki poniżej 300 linii. Gdy plik przekracza ten rozmiar, AI musi czytać zawartość, której nie potrzebuje, marnując kontekst. Dziel według odpowiedzialności.

Zamiast	Użyj
`utils.ts` (800 linii, 30 funkcji)	`validators/email.ts`, `formatters/date.ts`, `parsers/csv.ts`
`api.ts` (1200 linii, wszystkie endpointy)	`routes/users.ts`, `routes/billing.ts`, `routes/notifications.ts`
`types.ts` (500 linii, wszystkie typy)	`types/user.ts`, `types/billing.ts`, `types/notification.ts`

Opisowe nazewnictwo

Nazwa pliku powinna mówić AI, co jest w środku, bez konieczności czytania. Wyszukiwanie semantyczne działa lepiej, gdy nazwy plików odpowiadają koncepcjom, które zawierają.

Niejasne	Opisowe
`helpers.ts`	`password-hashing.ts`
`index.ts` (re-eksporty)	Utrzymuj pliki index szczupłe, poniżej 20 linii
`service.ts`	`notification-service.ts`
`Component.tsx`	`UserProfileCard.tsx`

Umieszczaj powiązane pliki obok siebie

Trzymaj implementację, testy i typy razem. Gdy AI czyta twoją implementację, może natychmiast znaleźć powiązany plik testowy bez szukania.

src/services/
  notification/
    notification-service.ts
    notification-service.test.ts
    notification-types.ts
    README.md                    # Krótki opis modułu

Wyszukiwanie semantyczne Cursor indeksuje cały workspace. Ogromnie korzysta z opisowych nazw plików i kolokacji, ponieważ wyszukiwanie może znaleźć powiązany kod bez czytania nieistotnych plików.

Dodaj .cursor/rules/structure.md, żeby poinformować Cursor o twoich konwencjach:

---
description: "Project structure conventions"
alwaysApply: true
---

## File Organization
- Keep files under 300 lines
- Co-locate tests with implementations
- Use descriptive filenames (notification-service.ts not service.ts)
- Split utils by domain (validators/email.ts not utils.ts)

Claude Code nawiguje za pomocą narzędzi plikowych (Read, Glob, Grep). Opisowe nazwy sprawiają, że wzorce Glob są precyzyjniejsze, a wyszukiwania Grep bardziej celne.

Dodaj konwencje do CLAUDE.md:

## File Organization
- Files should be under 300 lines
- Tests are co-located: src/services/foo.ts -> src/services/foo.test.ts
- Types are co-located: src/services/foo-types.ts
- When creating new files, follow existing naming patterns

Auto-pamięć Claude nauczy się twojej struktury w miarę pracy. Możesz również powiedzieć wprost: “remember that we co-locate tests with implementations.”

Codex czyta AGENTS.md dla konwencji projektu. Udokumentuj swoją strukturę:

## File Organization
- Keep files under 300 lines. Split large files by responsibility.
- Tests are co-located with implementations.
- Use descriptive filenames: notification-service.ts, not service.ts.
- Group by feature/domain, not by type (routes, controllers, models).

Czytanie plików przez Codex jest wydajne, ale przejrzysta organizacja redukuje liczbę plików, które musi sprawdzić.

Analyze the file structure of this project. Identify:

1. Files over 300 lines that should be split (list them with line counts)
2. Vague filenames (utils.ts, helpers.ts, misc.ts) that should be renamed
3. Tests that are far from their implementations
4. Barrel files (index.ts) that re-export too many things

For each issue, propose a specific improvement. Do not make changes yet --
just produce the analysis so I can review your recommendations.

Organizacja monorepo

Monorepo stanowią unikalne wyzwanie dla narzędzi AI, ponieważ ogromna liczba plików może przytłoczyć wyszukiwanie i indeksowanie.

Użyj .cursorignore do wyłączenia nieistotnych pakietów z indeksowania:

packages/legacy-app/
packages/internal-tools/
node_modules/
dist/

Pracując w konkretnym pakiecie, otwieraj tylko ten pakiet jako workspace, a nie całe monorepo. To skupia wyszukiwanie semantyczne Cursor na istotnym kodzie.

Claude Code czyta pliki CLAUDE.md hierarchicznie. Umieść główny CLAUDE.md ze współdzielonymi konwencjami i pliki CLAUDE.md na poziomie pakietu ze wskazówkami specyficznymi dla pakietu:

monorepo/
  CLAUDE.md                    # Współdzielone konwencje
  packages/
    api/
      CLAUDE.md                # Komendy i wzorce specyficzne dla API
    web/
      CLAUDE.md                # Wzorce specyficzne dla frontendu

Użyj --add-dir, aby dać Claude dostęp do współdzielonych pakietów pracując w konkretnym. Claude automatycznie ładuje CLAUDE.md z katalogów nadrzędnych.

Codex używa AGENTS.md z zagnieżdżonymi nadpisaniami. Umieść globalne instrukcje w katalogu głównym i specyficzne nadpisania w podkatalogach:

monorepo/
  AGENTS.md                    # Współdzielone konwencje
  packages/
    api/
      AGENTS.md                # Nadpisania specyficzne dla API
    web/
      AGENTS.override.md       # Nadpisania frontendu (mają priorytet)

Codex łączy pliki od katalogu głównego do bieżącego, z bliższymi plikami nadpisującymi szersze wskazówki.

I'm working in the [PACKAGE] package of our monorepo. Analyze its structure:

1. Map the dependency graph within this package
2. Identify files that are too large (over 300 lines)
3. Find circular dependencies
4. Suggest a cleaner organization that would help AI tools navigate faster

Output the proposed new structure as a directory tree with brief descriptions.
Do not make changes yet.

Efekt .gitignore

Każde narzędzie używa .gitignore (i specyficznych plików ignorowania) do pomijania nieistotnej zawartości. Upewnij się, że pliki ignorowania wyłączają wszystko, czego AI nie powinno czytać:

# .gitignore (również respektowany przez narzędzia AI)
node_modules/
dist/
build/
.next/
coverage/
*.min.js
*.bundle.js

Brak ignorowania artefaktów budowania oznacza, że AI może czytać zminifikowany JavaScript lub skompilowane wyniki, marnując ogromne ilości kontekstu na nieczytelną zawartość.

Gdy coś nie działa

Zespół opiera się restrukturyzacji. Nie musisz reorganizować całej bazy kodu na raz. Zacznij od rozdzielenia najgorszych przypadków — 1000-liniowych plików i uniwersalnych utils. Użyj AI do pomocy przy restrukturyzacji: doskonale radzi sobie z ekstrakcją funkcji do osobnych modułów.

Pliki index stają się rozdęte. Pliki index, które re-eksportują wszystko z pakietu, zużywają kontekst, gdy AI je czyta. Utrzymuj pliki barrel szczupłe (poniżej 20 linii) lub wyeliminuj je na rzecz bezpośrednich importów.

Różne narzędzia indeksują inaczej. Cursor używa embeddingów semantycznych, Claude Code używa narzędzi plikowych (Read, Grep, Glob), a Codex ma własne indeksowanie. Struktura, która działa dobrze dla jednego narzędzia, generalnie działa dobrze dla wszystkich, ale zwracaj uwagę na specyficzne pliki ignorowania narzędzi.

Kolokacja nie działa dla współdzielonych narzędzi. Część kodu naprawdę jest współdzielona między wieloma funkcjami (połączenie z bazą danych, logowanie, obsługa błędów). Trzymaj je w jasno nazwanym katalogu shared/ lub lib/ z małymi, skupionymi plikami.

Co dalej

Dokumentacja jako kontekst Użyj dokumentacji projektu do wstępnego ładowania kontekstu, którego AI potrzebuje w każdej sesji.

Indeksowanie bazy kodu Jak każde narzędzie indeksuje bazę kodu i jak zoptymalizować wyniki wyszukiwania.

Okna kontekstu Zrozum matematykę tokenów stojącą za tym, dlaczego organizacja plików ma znaczenie.