Claude Code nie myśli jak inżynier. Bo Ty go tak uczysz

Większość programistów traktuje Claude Code jak rozbudowane autouzupełnianie. Otwierasz plik, wpisujesz prompt, liczysz na cud. Czasem działa świetnie. Częściej – średnio. System gubi kontekst, powtarza te same błędy, produkuje kod, który wymaga ręcznej korekty.

Problem nie leży w Claude. Leży w tym, jak strukturujesz projekt.

Dlaczego Claude Code daje niespójne wyniki?

Claude Code (podobnie jak OpenAI Codex) to model językowy trenowany na kodzie. Nie "rozumie" Twojego projektu w sensie inżynierskim – analizuje wzorce w tekście, który mu podajesz. Jeśli kontekst jest chaotyczny, output będzie chaotyczny.

Typowy scenariusz: otwierasz losowy plik, piszesz "dodaj funkcję logowania", Claude generuje kod. Ale nie wie, że masz już system autentykacji w innym module. Nie widzi architektury. Nie zna konwencji nazewnictwa, których używasz w pozostałych 40 plikach. Pracuje w próżni.

Efekt? Kod, który technicznie działa, nie pasuje jednak do reszty projektu. Musisz go przepisać, dostosować, poprawić. Claude staje się obciążeniem, nie pomocą.

Jak zbudować projekt, który Claude faktycznie zrozumie?

Klucz leży w kontekście. Claude potrzebuje trzech rzeczy, żeby myśleć jak inżynier:

1. Jawnej architektury projektu

Stwórz plik ARCHITECTURE.md w głównym katalogu. Opisz w nim:

• Strukturę folderów i ich role
• Wzorce projektowe, których używasz (MVC, MVVM, mikroserwisy)
• Konwencje nazewnictwa
• Zależności między modułami

Przykład: "Wszystkie komponenty UI znajdują się w /components. Logika biznesowa w /services. Każdy serwis eksportuje interfejs TypeScript. Nazwy plików: kebab-case, nazwy klas: PascalCase."

Kiedy Claude widzi taki plik w kontekście, generuje kod zgodny z Twoimi zasadami. Nie wymyśla własnych.

2. Dokumentacji decyzji technicznych

Programiści podejmują setki mikrodecyzji: dlaczego Redux zamiast Context API? Czemu ta biblioteka, a nie inna? Dlaczego ten endpoint zwraca JSON, a nie XML?

Claude tego nie wie. Jeśli nie zapiszesz tych decyzji, będzie proponować rozwiązania sprzeczne z Twoją architekturą.

Rozwiązanie: pliki ADR (Architecture Decision Records). Krótkie notatki w formacie:

• Decyzja: "Używamy Axios zamiast Fetch API"
• Kontekst: "Potrzebujemy interceptorów do obsługi tokenów"
• Konsekwencje: "Wszystkie zapytania HTTP przez Axios, zero natywnego fetch"

Trzymaj je w /docs/decisions. Claude będzie je czytać i respektować.

3. Przykładów kodu jako szablonów

Claude uczy się z przykładów. Jeśli pokażesz mu, jak wygląda "dobry" komponent w Twoim projekcie, będzie generować podobne.

Stwórz folder /examples z wzorcowymi plikami:

• Przykładowy komponent React z pełną dokumentacją
• Przykładowy test jednostkowy
• Przykładowy endpoint API
• Przykładowy plik konfiguracyjny

Kiedy prosisz Claude o nowy komponent, dodaj do promptu: "Wzoruj się na /examples/component-template.tsx". Output będzie spójny ze stylem projektu.

Jak podawać kontekst, żeby Claude nie gubił wątku?

Nawet najlepsza struktura projektu nie pomoże, jeśli źle formułujesz prompty. Claude ma ograniczone okno kontekstu – choć w wersji Opus 4.6 to już 200 000 tokenów, więcej niż większość projektów.

Zamiast: "Dodaj funkcję logowania"

Napisz: "Dodaj funkcję logowania w /services/auth.service.ts. Użyj wzorca z /examples/service-template.ts. Integracja z istniejącym TokenManager z /utils/token.ts. Zwróć obiekt zgodny z interfejsem AuthResponse."

Różnica? W pierwszym przypadku Claude wymyśla wszystko od zera. W drugim – pracuje w ramach Twojej architektury.

Co zrobić z błędami, które Claude powtarza?

Jeśli Claude wielokrotnie generuje ten sam błąd (np. zapomina o obsłudze błędów, używa przestarzałego API), problem leży w braku negatywnych przykładów.

Stwórz plik COMMON_MISTAKES.md:

• "NIE używaj var – tylko const i let"
• "NIE pomijaj try-catch w zapytaniach async"
• "NIE twórz komponentów bez PropTypes/TypeScript"

Dodaj ten plik do kontekstu przy każdym promptcie. Claude będzie unikać tych pułapek.

Czy to działa z innymi asystentami AI?

Tak. Ta sama logika sprawdza się z OpenAI Codex, GitHub Copilot, czy Adobe Creative Cloud z AI (jeśli pracujesz z kodem frontendowym). Każdy model językowy potrzebuje kontekstu. Różnica leży w tym, jak go podajesz.

GitHub Copilot czyta otwarte pliki w edytorze. Claude Code może analizować cały projekt. OpenAI Codex kontroluje środowisko – nadal jednak potrzebuje jasnych instrukcji.

Wspólny mianownik: im bardziej uporządkowany projekt, tym lepsze wyniki. Chaos w kodzie = chaos w outputcie AI.

Ile czasu zajmuje przygotowanie takiej struktury?

Dla nowego projektu: 2-3 godziny. Tworzysz ARCHITECTURE.md, kilka plików ADR, szablon komponentu. To jednorazowa inwestycja.

Dla istniejącego projektu: 1-2 dni. Musisz przeanalizować obecną architekturę, zapisać decyzje, które już podjąłeś (nawet jeśli były intuicyjne), stworzyć przykłady.

Zwrot z inwestycji? Natychmiastowy. Zamiast poprawiać 60% kodu generowanego przez Claude, poprawiasz 20%. Zamiast tracić czas na wyjaśnianie kontekstu w każdym promptcie, podajesz go raz – w dokumentacji.

To nie jest optymalizacja dla perfekcjonistów. To podstawowa higiena pracy z AI.

Co jeśli pracujesz w zespole?

Jeszcze ważniejsze. Jeśli każdy developer używa Claude po swojemu, dostaniecie patchwork – 10 różnych stylów kodu w jednym projekcie.

Rozwiązanie: wspólna dokumentacja. ARCHITECTURE.md staje się źródłem prawdy nie tylko dla AI, ale i dla nowych członków zespołu. ADR-y wyjaśniają, dlaczego projekt wygląda tak, a nie inaczej. Przykłady standaryzują output.

Bonus: onboarding nowego programisty skraca się z tygodni do dni. Zamiast czytać tysiące linii kodu, czyta 5 plików dokumentacji i wie, jak pisać kod zgodny z projektem.

Claude staje się narzędziem zespołowym, nie indywidualnym trickiem.

Praktyczny test: czy Twój projekt jest gotowy na AI?

Odpowiedz na trzy pytania:

• Czy nowy programista, czytając tylko dokumentację (bez rozmowy z Tobą), wie jak dodać nowy feature?
• Czy potrafisz w 3 zdaniach wyjaśnić, dlaczego wybrałeś obecną architekturę?
• Czy masz przykładowy plik dla każdego typu komponentu w projekcie?

Jeśli choć jedna odpowiedź brzmi "nie" – Claude będzie zgadywać. A zgadywanie to loteria.

Dobra wiadomość: nie musisz dokumentować wszystkiego. Wystarczy 20% struktury, która wyjaśnia 80% decyzji. Reszta wynika z przykładów.

Claude Code nie myśli jak inżynier, bo nie jest inżynierem. To narzędzie, które odwzorowuje wzorce. Jeśli dajesz mu dobre wzorce – dostaniesz dobry kod. Jeśli dajesz chaos – dostaniesz chaos z lepszą składnią.

Struktura projektu to nie biurokracja. To instrukcja obsługi dla AI. I dla każdego, kto będzie czytać Twój kod za 6 miesięcy – włącznie z Tobą.