Przejdź do treści
← Kurs M09L02 · Instrukcje i Prompt Files ⚡
⚡ Zaawansowany M09L02 M09 · Lekcja 2 z 4 10 min Ćwiczenie

Scoped Instructions: różne reguły per folder i typ pliku

Jak tworzyć pliki .instructions.md z polem applyTo, żeby mieć inne reguły dla backendu, frontendu, testów i konfiguracji.

Czego się nauczysz

  • Jak działają pliki *.instructions.md i pole applyTo
  • Kiedy rozbijać zasady na wiele plików zamiast pakować wszystko do jednego globalnego dokumentu
  • Jak uniknąć sytuacji, w której instrukcje istnieją, ale nie są stosowane automatycznie

Jeden plik globalny szybko staje się ciężki

To naturalny etap.

Na początku .github/copilot-instructions.md wystarcza. Potem pojawiają się różne strefy repo:

  • frontend
  • backend
  • testy
  • dokumentacja
  • skrypty buildowe

I nagle jeden globalny plik zaczyna mieszać reguły, które nie powinny obowiązywać wszędzie.

Właśnie wtedy wchodzą *.instructions.md.

Czym scoped instructions różnią się od always-on instructions

To nadal są custom instructions, ale nie są automatycznie dołączane do każdej rozmowy tylko dlatego, że istnieją.

Ich zadaniem jest dopinać właściwe reguły do właściwego fragmentu pracy. Dokumentacja mówi, że agent dobiera je na podstawie:

  • wzorca applyTo
  • albo semantycznego dopasowania opisu do zadania

W praktyce oznacza to, że możesz budować AI kontekst per folder, język i rodzaj pliku, zamiast robić jeden monolit instrukcyjny.

applyTo to najważniejsze pole w praktyce

Frontmatter applyTo określa, do jakich plików instrukcja ma być stosowana automatycznie.

I tu jest bardzo ważny detal z docsów: jeśli applyTo nie istnieje, plik nie jest stosowany automatycznie. Nadal możesz go dodać ręcznie do requestu, ale nie licz, że agent sam po niego sięgnie przy zwykłej pracy.

To częsta przyczyna złudzenia, że “instructions nie działają”.

Dobry podział scoped instructions

Najpraktyczniejszy układ zwykle wygląda tak:

  • osobny plik dla TypeScript albo backendu
  • osobny plik dla UI albo frontendu
  • osobny plik dla testów
  • osobny plik dla dokumentacji

Nie chodzi o maksymalną liczbę plików. Chodzi o to, żeby agent nie dostawał zasad Reacta, gdy akurat poprawia dokumentację albo shell script.

Przykład

---
name: 'Frontend Astro Rules'
description: 'Reguly dla komponentow Astro i warstwy UI'
applyTo: 'src/**/*.{astro,ts,tsx}'
---
# Frontend


- Zachowuj istniejące wzorce komponentów Astro.
- Nie wprowadzaj nowych bibliotek UI bez wyraźnego uzasadnienia.
- Przy zmianach UI pilnuj zgodności z tokenami i klasami z globalnego systemu stylów.

I drugi plik:

---
name: 'Docs Rules'
description: 'Reguly dla dokumentacji i contentu markdown'
applyTo: 'docs/**/*.md,src/content/**/*.md'
---
# Dokumentacja


- Pisz zwięźle i konkretnie.
- Zaczynaj od decyzji albo wniosku, a nie od ogólnego wstępu.
- Unikaj marketingowego tonu.

To jest dokładnie ten poziom separacji, który daje realny zwrot.

Gdzie te pliki trzymać

Domyślna lokalizacja workspace-level to .github/instructions, a VS Code przeszukuje ją rekurencyjnie. Możesz więc grupować pliki w podfolderach według modułów, języków albo zespołów.

Dokumentacja dopuszcza też inne lokalizacje przez chat.instructionsFilesLocations, a dodatkowo wspiera zgodność z .claude/rules.

To daje sensowną elastyczność, ale nie przesadzaj z egzotyczną strukturą. Im bardziej oczywista lokalizacja, tym łatwiej zespołowi utrzymać porządek.

Parent repository discovery jest przydatne, ale nie domyślne

W monorepo to istotny detal.

Jeżeli otwierasz tylko podfolder repozytorium, instrukcje z katalogu głównego nie muszą zostać znalezione automatycznie. Dokumentacja mówi jasno, że parent repository discovery trzeba włączyć odpowiednim settingiem.

To znaczy, że w monorepo nie warto zakładać, że “przecież instrukcje są w root, więc na pewno działają”. Najpierw sprawdź, czy discovery jest włączone.

Jak dzielić instrukcje sensownie

Dobry filtr jest prosty:

  • wrzuć do globalnego pliku to, co obowiązuje wszędzie
  • wrzuć do scoped instructions to, co zależy od obszaru kodu
  • nie twórz osobnego pliku tylko dlatego, że możesz

Jeśli jakaś reguła ma sens tylko w testach, powinna żyć przy testach. Jeśli dotyczy całego repo, nie rozdrabniaj jej sztucznie na kilka plików.

Generowanie scoped instructions przez AI

Docs wspierają /create-instruction, które potrafi wygenerować targetowany plik .instructions.md z odpowiednim applyTo.

To wygodne, ale jak zwykle trzeba zweryfikować wynik. Najczęstszy problem nie leży w samej treści, tylko w zbyt szerokim albo zbyt wąskim globie.

Instrukcja może być dobra, ale jeśli applyTo nie trafia w realne pliki, agent jej nie użyje wtedy, kiedy oczekujesz.

Ćwiczenie praktyczne

Stwórz dwa pliki scoped instructions:

  1. Jeden dla kodu aplikacyjnego.
  2. Jeden dla dokumentacji albo testów.

Dla każdego ustaw applyTo, a potem wykonaj dwa requesty:

  • zmianę w kodzie
  • zmianę w markdownie albo testach

Sprawdź w References albo Diagnostics, które instrukcje zostały użyte. Jeśli agent nie dobrał właściwego pliku, popraw glob albo opis.

Kluczowe wnioski

  • *.instructions.md służą do warunkowego dołączania reguł zależnie od kontekstu pracy.
  • applyTo jest kluczowe, bo bez niego plik nie działa automatycznie.
  • Najlepiej rozdzielać instrukcje per obszar kodu, język albo typ zadania, a nie na siłę maksymalnie granularnie.
  • W monorepo trzeba świadomie ogarnąć parent repository discovery.
  • Dobre scoped instructions zmniejszają szum kontekstowy i poprawiają trafność odpowiedzi agenta.

Co dalej

Instrukcje działają automatycznie, ale nie rozwiązują wszystkiego. Do powtarzalnych workflow lepsze są prompt files, które uruchamiasz dokładnie wtedy, kiedy ich potrzebujesz.