Jak pracować z Claude Code w projekcie .NET? 5 zasad: CLAUDE.md, brief zadania, małe kroki, review i decyzje

Najlepszy junior, z jakim pracowałem, nie śpi, nie bierze urlopu i czasem kłamie z pełnym przekonaniem. Potrafi napisać "Gotowe, wszystkie testy przechodzą", choć testów nawet nie uruchomił. Tak, mówię o AI - konkretnie o Claude Code, z którym pracuję codziennie w projektach .NET.

Na początku traktowałem go źle. Raz jak wyszukiwarkę, raz jak seniora: daję zadanie i idę na kawę. W obu przypadkach kończyło się tak samo - kodem, który wyglądał świetnie, i nie działał. Pomogła dopiero jedna zmiana w głowie: zacząłem zarządzać AI tak, jak tech lead zarządza juniorem.

W tym artykule dostaniesz 5 zasad, których używam na co dzień. Pokażę Ci, jak wygląda CLAUDE.md w projekcie .NET, szablon briefu zadania do skopiowania, sposób na dzielenie pracy na małe kroki i listę czerwonych flag do review kodu od AI. A na końcu tabelę: co zostaje u Ciebie, a co oddajesz AI. Na tej ostatniej zasadzie wykłada się najwięcej osób.

Przykłady pochodzą z projektu w ASP.NET Core 10 z EF Core i SQL Server (Minimal API, testy w xUnit). Narzędziem jest Claude Code, więc pojawią się CLAUDE.md, /init, Plan Mode i skille - ale brief, małe kroki, review i podział decyzji sprawdzą się przy każdym asystencie AI.

Dlaczego AI to junior, a nie senior?

Zacznijmy od tego, dlaczego w ogóle junior. Wyobraź sobie, że na Twoje biurko trafia CV kandydata o imieniu AI. Popatrz najpierw na mocne strony:

• pisze szybciej niż ktokolwiek w Twoim zespole,
• zna składnię C#, LINQ, EF Core i pół NuGeta,
• nie męczy się o 16:00,
• nie obraża się, kiedy odrzucasz mu pull requesta.

A teraz słabe strony:

• Nie zna Twojego projektu. Nie wie, że u Was walidacja jest w FluentValidation, a nie w kontrolerze.

• Kiedy czegoś nie wie, nie pyta, tylko zgaduje. I zgaduje pewnym głosem - brzmi pewnie, nawet gdy się myli.

• Lubi zrobić więcej, niż prosiłeś.

Znasz ten zestaw? To dokładnie opis zdolnego juniora. Tylko dużo szybszego.

2 błędy, które robi większość. Większość programistów popełnia jeden z 2 błędów. Pierwszy to AI jako wyszukiwarka: wklejasz kawałek kodu do czatu, bez kontekstu, i dostajesz ogólnik. Drugi to AI jako senior: piszesz "zrób moduł płatności" i idziesz na kawę. Wracasz, a tu 20 zmienionych plików i nie wiesz, od czego zacząć review.

Trzecia droga. Jest jednak trzecia droga: Ty jesteś tech leadem. AI jest juniorem. Ty decydujesz, wyznaczasz kierunek i sprawdzasz. On wykonuje. Szybko.

Jak to wygląda w praktyce? Na co dzień trzymam się 5 zasad:

1. Onboarding, czyli CLAUDE.md.
2. Brief zadania.
3. Małe kroki i commit po każdym z nich.
4. Review jak u juniora.
5. Decyzje zostają u Ciebie.

Omówmy je po kolei.

Zasada 1: onboarding juniora, czyli CLAUDE.md

Co robisz, kiedy do zespołu dochodzi nowy junior? Pokazujesz mu:

• jak zbudować projekt i odpalić testy,
• jak wygląda architektura,
• jakie macie konwencje,
• czego nie ruszać,
• kiedy zadanie jest skończone.

Z AI jest jeden problem: każda nowa sesja to jego pierwszy dzień w pracy. Nie pamięta, co mu tłumaczyłeś wczoraj. Dlatego onboarding musi być zapisany. W Claude Code służy do tego plik CLAUDE.md w katalogu głównym repozytorium. Claude czyta go na starcie każdej sesji - to po prostu onboarding na piśmie.

5 części CLAUDE.md. U mnie CLAUDE.md ma zawsze 5 części: komendy, architektura, konwencje, czego nie robić i kiedy zadanie jest gotowe. Tak to wygląda w projekcie .NET:

# OrderHub · ASP.NET Core 10 · EF Core · SQL Server

## Komendy
- Build:     dotnet build
- Testy:     dotnet test
- Migracja:  dotnet ef migrations add <Nazwa> -p src/Infrastructure

## Architektura
- src/Api            → Minimal API, tylko endpointy
- src/Application    → logika: komendy i zapytania
- src/Domain         → encje, zero zależności od EF
- src/Infrastructure → EF Core, DbContext, migracje
- tests/             → xUnit + WebApplicationFactory

## Konwencje
- Walidacja: FluentValidation, nie w endpointach
- Błędy biznesowe: Result<T>, nie wyjątki
- Metody I/O: async + CancellationToken

## Nie rób
- Nie zmieniaj testów, żeby przeszły
- Nie ruszaj istniejących migracji
- Nie dodawaj pakietów NuGet bez pytania

## Gotowe, gdy
- dotnet build bez ostrzeżeń
- dotnet test na zielono

Na górze stack i komendy: jak zbudować projekt, jak odpalić testy, jak dodać migrację. Bez tego AI zgaduje, a potem pisze "powinno działać". Dalej architektura, czyli co leży w którym projekcie. 1 linijka na projekt wystarczy.

W konwencjach zapisuję to, co u nas jest inaczej niż w tutorialu: Result zamiast wyjątków, FluentValidation, CancellationToken. Potem lista "nie rób". U mnie zawsze jest tam: nie zmieniaj testów, żeby przeszły. Uwierz mi, ta linijka nie wzięła się znikąd. Na końcu: kiedy zadanie jest gotowe. Build bez ostrzeżeń, testy zielone.

Zwróć uwagę na 2 pozostałe zakazy: nie ruszaj istniejących migracji i nie dodawaj pakietów NuGet bez pytania. To dokładnie te rzeczy, które zdolny, ale nadgorliwy junior robi "przy okazji", a potem to Ty sprzątasz. Sekcja "Gotowe, gdy" zamyka z kolei temat "powinno działać": zadanie nie jest skończone, dopóki build i testy nie przejdą.

3 zasady dobrego CLAUDE.md. Sam plik to dopiero połowa sukcesu. Druga połowa to to, jak go piszesz:

• Krótko. To nie jest wiki projektu. Dokumentacja Claude Code zaleca poniżej 200 linii. Im dłuższy plik, tym słabiej AI go przestrzega.

• Konkretnie. "Pisz czysty kod" nic nie znaczy. "Każda metoda I/O jest async i przyjmuje CancellationToken" da się sprawdzić.

• Żywy dokument. To najważniejsze. Jeśli poprawiasz AI drugi raz w tej samej sprawie, to nie jest problem AI. To brakująca linijka w CLAUDE.md.

Start w 2 minuty: /init. Nie musisz zaczynać od zera. Wpisz w Claude Code komendę /init - Claude przejrzy projekt i przygotuje pierwszą wersję CLAUDE.md. Ty dopisujesz to, czego nie wyczyta z kodu: decyzje, wyjątki i "tego nie ruszaj".

Jedno zastrzeżenie. CLAUDE.md to instrukcja, nie blokada. Junior też czasem zapomina, co mu mówiłeś. Jeśli coś ma się dziać zawsze, na przykład testy po każdej zmianie, do tego służą hooki. Ale to temat na osobny artykuł.

Zasada 2: brief zadania (szablon do skopiowania)

Junior nie czyta w myślach. AI też nie. Słaby brief to prosta droga do zgadywania - a AI, jak już wiesz, zgaduje pewnie. Potem są 3 rundy poprawek i masz wrażenie, że szybciej byłoby zrobić to samemu.

Brief w 4 częściach. Dlatego każde większe zadanie opisuję w 4 częściach:

1. Kontekst: gdzie jesteśmy, jakie pliki są ważne, jak to dziś działa.
2. Cel: co ma działać po zmianie. Opisuję zachowanie, nie implementację.
3. Ograniczenia: czego nie ruszać, jakich wzorców się trzymać.
4. Definition of Done: po czym obaj poznamy, że zadanie jest skończone.

Słaby brief. Weźmy przykład. Tak wygląda słaby brief:

"Dodaj anulowanie zamówienia."

Jedno zdanie, a w nim kilka decyzji do zgadnięcia. AI musi samo odpowiedzieć sobie na pytania:

• Kontroler czy Minimal API?
• Usunąć zamówienie czy zmienić mu status?
• Czy można anulować zamówienie, które zostało już wysłane?
• Testy? Jakie?

Każda z tych odpowiedzi może być zła.

Ten sam task, dobry brief. A tak wygląda to samo zadanie opisane w 4 częściach:

KONTEKST
Encja: Domain/Orders/Order.cs. Endpointy: Api/Endpoints/OrderEndpoints.cs.
Statusy: New, Paid, Shipped, Cancelled.

CEL
POST /orders/{id}/cancel zmienia status na Cancelled. Anulować można tylko New i Paid.
Dla Paid zapisz zdarzenie OrderRefundRequested.

OGRANICZENIA
Logika w Order.Cancel(), nie w endpoincie. Bez nowych pakietów.
Nie ruszaj istniejących migracji.

DEFINITION OF DONE
Shipped/Cancelled → 409, brak zamówienia → 404.
Testy jednostkowe Order.Cancel() + test integracyjny endpointu.
dotnet test na zielono.

Kontekst mówi, gdzie leży encja i endpointy oraz jakie są statusy. Cel: anulować można tylko nowe i opłacone zamówienia, a przy opłaconym zapisujemy zdarzenie zwrotu. Ograniczenia: logika w encji, bez nowych pakietów, bez ruszania migracji. Definition of Done: 409 dla wysłanych, 404, gdy nie ma zamówienia, testy i zielony build. AI nie musi już niczego zgadywać. Skopiuj ten szablon - możesz go od jutra używać w swoim projekcie.

Zauważ też, że brief nie powtarza tego, co jest w CLAUDE.md. Komendy, konwencje i zakazy obowiązujące w całym projekcie siedzą w CLAUDE.md, a brief opisuje tylko to jedno zadanie. Dzięki temu jest krótki, a mimo to kompletny.

Brief to nie koszt, to skrót. Napisanie takiego briefu zajmuje mi kilka minut. I to nie jest koszt. Porównaj 2 ścieżki:

• słaby brief: zgadywanie → poprawki → kolejne poprawki → ...
• dobry brief: plan → kod → review → commit. 1 przebieg.

Niech najpierw zapyta. Jeszcze jedna rzecz, którą prawie zawsze doklejam na końcu briefu:

Zanim zaczniesz:
1. Zadaj mi pytania, jeśli czegoś brakuje.
2. Pokaż plan.
3. Nie pisz kodu, dopóki go nie zatwierdzę.

Dobry junior pyta. AI trzeba o to poprosić. W Claude Code masz do tego Plan Mode: najpierw plan, potem kod.

Powtarzasz ten sam brief? Zrób skill. A jeśli piszesz ten sam brief po raz piąty, na przykład "nowy endpoint CRUD według naszych konwencji", zamień go w skill. Procedurę zapisujesz raz, w pliku .claude/skills/crud/SKILL.md, a Claude sięga po nią sam, kiedy pasuje do zadania. Twój junior dostaje instrukcję na piśmie, a Ty nie musisz jej powtarzać po raz piąty.

Zasada 3: małe zadania i commit po każdym kroku

Nie dajesz juniorowi całego modułu na tydzień, żeby potem zniknąć. Z AI jest tak samo, tylko szybciej.

Duże zadanie to 25 zmienionych plików. AI gubi kontekst, a Ty nie jesteś w stanie zrobić sensownego review. A jak coś nie działa, nie wiesz, gdzie szukać.

Małe zadanie to 1-3 pliki. Review w 2 minuty. I łatwo się cofnąć.

Anulowanie zamówienia w 5 krokach. To samo anulowanie zamówienia z poprzedniej sekcji rozbijam na 5 kroków:

1. Metoda Order.Cancel() w encji, z testami jednostkowymi.
2. Zdarzenie OrderRefundRequested.
3. Endpoint POST /orders/{id}/cancel.
4. Mapowanie błędów na HTTP 404 i 409.
5. Test integracyjny na WebApplicationFactory.

Każdy krok da się sprawdzić osobno i każdy kończy się zielonym commitem. Te kroki wynikają zresztą wprost z briefu: Definition of Done mówi o testach jednostkowych Order.Cancel(), kodach 404 i 409 oraz teście integracyjnym endpointu. Dobry brief podpowiada więc także, jak pociąć zadanie.

1 krok = 1 commit. To zasada, której się trzymam: 1 krok to 1 commit. A commit tylko wtedy, gdy build i testy są zielone.

Pętla pracy. W praktyce wygląda to tak:

plan → krok → build + testy → review diffu → commit → następny krok

Brzmi wolno? W praktyce to najszybsza droga, bo nie wracasz do rzeczy, które już działały.

Git to Twoja siatka bezpieczeństwa. Kiedy AI pójdzie w złą stronę (a pójdzie), nie kłócisz się z nim przez 20 wiadomości w stylu "napraw to", "nadal nie działa", "napraw to, co zepsułeś". Zamiast tego:

1. wracasz do ostatniego zielonego commita,
2. poprawiasz brief,
3. puszczasz zadanie jeszcze raz.

To zajmuje minutę, a nie pół godziny.

Zasada 4: review jak u juniora

To moim zdaniem najważniejsza z 5 zasad. Kod od AI czytam jak kod od juniora: z sympatią, ale bez ślepego zaufania.

Problem w tym, że ten kod zawsze wygląda profesjonalnie. Ładne nazwy, komentarze, porządek. A to, że kod wygląda dobrze, nie znaczy, że działa.

Czerwone flagi: zachowanie. Mam listę czerwonych flag, na które patrzę najpierw:

• Zrobił więcej, niż prosiłeś. Refaktor "przy okazji" w plikach, których miał nie ruszać.

• Zmienił test, żeby przeszedł. Moja ulubiona. Zmieniona asercja, dodany Skip albo usunięty test. Byle było zielono.

• Wymyślone API. Metoda albo pakiet NuGet, który nie istnieje.

• Połknięty wyjątek. Pusty catch albo catch, który zwraca null.

Czerwone flagi: typowo .NET. Druga część listy jest typowo .NET-owa:

• Async: .Result albo .Wait() zamiast await i brak CancellationToken.

• EF Core N+1: zapytanie do bazy w pętli, czyli query w foreach.

• Bezpieczeństwo: endpoint bez autoryzacji albo bez sprawdzenia, czy zamówienie należy do tego użytkownika. Do tego SQL sklejany ze stringów, czyli coś w stylu "...Id=" + id.

• Nowa zależność: pakiet NuGet (nowy <PackageReference>), o który nikt nie prosił.

Część tych flag możesz zgasić, zanim w ogóle pojawią się w kodzie. Zakaz zmieniania testów, zakaz dodawania pakietów bez pytania i konwencję async + CancellationToken masz już w CLAUDE.md z zasady 1. Review sprawdza wtedy, czy AI się ich trzymało - bo pamiętaj, CLAUDE.md to instrukcja, nie blokada.

Test: znajdź 3 problemy. Zróbmy mały test. Poniżej kod, który mógłby przyjść od AI. Kompiluje się i na pierwszy rzut oka wygląda w porządku. Zanim przewiniesz dalej, spróbuj znaleźć w nim 3 problemy.

public async Task<Order?> GetOrder(int id)
{
    try
    {
        return _db.Orders
            .FirstOrDefaultAsync(o => o.Id == id)
            .Result;
    }
    catch (Exception)
    {
        return null;
    }
}

Już? Oto rozwiązanie:

1. .Result zamiast await. Blokuje wątek w metodzie async.
2. Brak CancellationToken. Zapytania nie da się anulować.
3. catch połyka każdy wyjątek i zwraca null. Jak padnie baza, użytkownik dostanie "nie znaleziono", a Ty nie zobaczysz nic w logach.

A tak wygląda ta sama metoda po review:

public async Task<Order?> GetOrderAsync(
    int id, CancellationToken ct)
{
    return await _db.Orders
        .FirstOrDefaultAsync(
            o => o.Id == id, ct);
}

Krócej i bezpieczniej.

Każ mu się wytłumaczyć. Druga rzecz w review: po każdym kroku zadaję AI 3 pytania:

1. "Co zmieniłeś i dlaczego?"
2. "Jakie przypadki brzegowe pominąłeś?"
3. "Uruchom testy i pokaż mi wynik."

Pamiętasz, jak na początku pisałem, że AI czasem kłamie z pełnym przekonaniem? Dlatego nie wierzę na słowo w "testy przechodzą". Chcę zobaczyć wynik. Albo odpalam testy sam.

Pętla nauki. I tu zamyka się pętla z zasadą pierwszą. Każda uwaga z review, która się powtarza, trafia do CLAUDE.md:

review → powtarzający się błąd → linijka w CLAUDE.md → następna sesja bez tego błędu

Następna sesja już tego błędu nie robi. Tak junior z czasem staje się midem.

Zasada 5: decyzje zostają u Ciebie

To zasada, na której wykłada się najwięcej osób. A podział jest prosty: decyzje zostają u Ciebie, wykonanie idzie do AI.

Zwróć uwagę, że nawet w prawej kolumnie AI nie działa samopas: testy pisze dla przypadków, które Ty wypisałeś, migracje przechodzą przez Twoje review, a refaktor idzie małymi krokami pod testami.

Propozycja to nie decyzja. Czy AI może zaproponować architekturę? Jasne. Często ma dobre pomysły. Ale propozycja to nie decyzja. W git blame jest Twoje nazwisko, nie jego. I to Ty tłumaczysz się z bugów na produkcji.

Jeśli oddasz AI decyzje, to nie jesteś tech leadem. Jesteś juniorem swojego juniora.

Podsumowanie

AI to najszybszy junior, jakiego możesz mieć w zespole - pod warunkiem, że zarządzasz nim jak tech lead. Zbierzmy 5 zasad w jednym miejscu:

• Onboarding przez CLAUDE.md: komendy, architektura, konwencje, "nie rób" i "gotowe, gdy". Krótko, konkretnie i na bieżąco.
• Brief w 4 częściach: kontekst, cel, ograniczenia, Definition of Done.
• Małe kroki: 1 krok, 1 commit, zielone testy.
• Review jak u juniora: czerwone flagi, 3 pytania po każdym kroku, a powtarzające się uwagi lądują w CLAUDE.md.
• Decyzje zostają u Ciebie: AI proponuje i wykonuje, Ty decydujesz.

Jeśli chcesz zacząć jeszcze dziś, zrób 3 rzeczy:

1. Odpal /init w swoim projekcie - pierwszą wersję CLAUDE.md masz w 2 minuty.
2. Dopisz 3 rzeczy, których AI nie wyczyta z kodu: decyzje, wyjątki, "tego nie ruszaj".
3. Następne zadanie opisz w 4 częściach: kontekst, cel, ograniczenia, Definition of Done.

Różnicę zobaczysz od pierwszego taska. Bo to Ty jesteś tech leadem. AI jest juniorem. Nie odwrotnie.

Jeśli chcesz przejść to wszystko krok po kroku na własnym projekcie, zajrzyj do Szkoły 3x Dev. To szkolenie dla programistów C# i .NET, a tematowi z tego artykułu poświęciłem w nim cały moduł 02: "Promptowanie jak tech lead". Piszemy w nim CLAUDE.md dopasowany do Twojego projektu i budujemy Twój pierwszy skill, na przykład generator kontrolera CRUD zgodny z Twoimi konwencjami. A to dopiero drugi z 10 modułów - w całym szkoleniu są też projekty, mentor i grupa, a do tego 14 dni gwarancji.

Zapisy otwieram cyklicznie, więc wejdź na stronę i sprawdź, czy właśnie trwają - a jeśli nie, zostaw maila na liście oczekujących: modestprogrammer.pl/szkola-3x-dev.

Powodzenia w pracy z Twoim nowym juniorem :)