.github/copilot-instructions.md: setup raz na zawsze | Kurs GitHub Copilot

Czego się nauczysz

Po co istnieje .github/copilot-instructions.md i kiedy naprawdę daje zwrot
Jakie reguły warto tam trzymać, a jakich nie warto duplikować
Jak diagnozować sytuację, w której instrukcje nie są stosowane

Najtańsza poprawa jakości odpowiedzi to nie lepszy prompt

Najtańsza poprawa jakości odpowiedzi to lepszy stan domyślny.

Dokładnie temu służy .github/copilot-instructions.md. To plik always-on, który VS Code automatycznie dołącza do wszystkich requestów chatu w danym workspace.

Jeśli dobrze go ustawisz, przestajesz za każdym razem dopisywać:

jaki macie stack
jakich bibliotek używacie
jakie są wzorce architektoniczne
czego unikać w tym projekcie

To nie jest wygoda kosmetyczna. To mniej powtórzeń, mniej dryfu i mniej szans, że agent pójdzie w styl niezgodny z repo.

Co powinno trafić do `copilot-instructions.md`

Z dokumentacji i praktyki wychodzi prosty filtr. Do tego pliku wkładaj rzeczy, które:

obowiązują w całym repo
są projektowe, nie osobiste
nie są oczywiście egzekwowane przez linter albo formatter
realnie pomagają agentowi podejmować lepsze decyzje

Dobre przykłady:

preferowane biblioteki i frameworki
zasady architektoniczne
strategia obsługi błędów
konwencje nazewnicze ważne dla całego projektu
oczekiwania wobec testów i dokumentacji

Słabe przykłady:

wszystko, co i tak wymusza Prettier albo ESLint
osobiste przyzwyczajenia jednego developera
dziesiątki ogólników bez wpływu na decyzje modelu

Ten plik ma być krótki i operacyjny

To ważny detal z docsów. Instrukcje działają najlepiej, gdy są krótkie, samowystarczalne i konkretne.

Zamiast pisać wielki esej o standardach zespołu, lepiej mieć serię prostych reguł:

używaj TypeScript strict mode
preferuj istniejące utility zamiast kopiowania logiki
nie dodawaj nowych zależności bez uzasadnienia
aktualizuj testy, gdy zmienia się zachowanie publiczne

Jeszcze lepiej, gdy dopiszesz powód przy regułach nieoczywistych. Model lepiej radzi sobie w edge case’ach, jeśli rozumie sens ograniczenia, a nie tylko jego treść.

Nie wszystko trzeba pisać od zera

Aktualna dokumentacja wspiera dwie wygodne ścieżki startowe:

/init, które generuje workspace-wide instructions
/create-instructions, gdy chcesz wygenerować konkretne instrukcje pod opisany cel

To dobry punkt wejścia, ale nie powinieneś traktować wygenerowanego pliku jako świętego tekstu. Trzeba go skrócić, odszumić i dopasować do realnych zasad projektu.

Co ten plik robi, a czego nie robi

To częsty punkt pomyłki.

.github/copilot-instructions.md wpływa na chatowe requesty, ale dokumentacja jasno mówi, że nie jest brany pod uwagę przy inline suggestions podczas zwykłego pisania w edytorze.

Czyli:

poprawi zachowanie agentów i chatu
nie zamieni nagle autouzupełniania w pełne odzwierciedlenie polityki projektu

To bardzo ważne, bo część ludzi ocenia wartość instrukcji po złym miejscu w produkcie.

Przykład minimalnego pliku

---
applyTo: "**"
---
# Zasady projektu

- Używaj istniejących utility z `src/utils`, zamiast dodawać duplikaty.
- Zakładaj TypeScript strict mode i nie obchodź typów przez `any`, chyba że kod już tego wymaga.
- Przy zmianie zachowania publicznego aktualizuj testy albo wyjaśnij, dlaczego nie są potrzebne.
- W odpowiedziach proponuj rozwiązania zgodne z Astro i Tailwind CSS v4 używanymi w repo.

Ten przykład jest krótki, ale operacyjny. Daje agentowi konkretne ramy bez zasypywania go wszystkim, co i tak wyczyta z projektu.

Gdzie ludzie najczęściej psują ten plik

Najczęstsze błędy są cztery:

wrzucanie zbyt wielu reguł naraz
opisywanie rzeczy oczywistych albo wymuszanych przez tooling
mieszanie reguł projektowych z prywatnymi preferencjami autora
brak aktualizacji pliku, gdy projekt już dawno zmienił kierunek

W praktyce copilot-instructions.md powinien być traktowany jak lekka dokumentacja operacyjna dla AI, nie jak ściana tekstu o kulturze zespołu.

Jak sprawdzić, czy instrukcje są naprawdę użyte

Docs podpowiadają kilka praktycznych ścieżek diagnostycznych:

sprawdź References w odpowiedzi chatu
użyj Diagnostics w Chat view, żeby zobaczyć załadowane instrukcje i błędy
upewnij się, że plik leży dokładnie w .github/copilot-instructions.md

Jeśli instrukcje “nie działają”, bardzo często problem nie leży w modelu, tylko w lokalizacji pliku albo w tym, że oczekiwałeś wpływu na feature, którego ten mechanizm w ogóle nie obsługuje.

Ćwiczenie praktyczne

Weź repo, nad którym pracujesz, i zrób trzy kroki:

Zapisz 5 reguł, które naprawdę zmieniają decyzje implementacyjne agenta.
Odrzuć wszystko, co i tak robi formatter, linter albo CI.
Umieść wynik w .github/copilot-instructions.md i porównaj odpowiedzi chatu przed i po zmianie.

Na końcu otwórz Diagnostics albo sprawdź References i upewnij się, że instrukcje rzeczywiście zostały dołączone.

Kluczowe wnioski

.github/copilot-instructions.md to najlepszy punkt startowy dla projektowych, always-on zasad pracy z AI.
Największą wartość dają krótkie, konkretne i nieoczywiste reguły, które wpływają na decyzje modelu.
Nie warto duplikować w nim tego, co już egzekwuje formatter, linter albo typy.
To mechanizm dla chatu i agentów, nie dla inline suggestions.
Jeśli instrukcje nie działają, najpierw sprawdź lokalizację pliku, References i Diagnostics.

Co dalej

Jeden plik globalny to dobry start, ale prawdziwy porządek zaczyna się wtedy, gdy rozbijesz zasady per folder, język i typ zadania.