--- title: "Strona toolchain i /monolynx:setup: konfiguracja przed pierwszym ticketem" description: "Pełny format strony wiki toolchain, znaczenie każdego pola i siedem punktów, które sprawdza /monolynx:setup przed pierwszym ticketem." url: "https://monolynx.com/blog/strona-toolchain-i-monolynx-setup" lang: "pl" author: "Zespół Monolynx" published: "2026-10-09T11:36:22.505610+00:00" modified: "2026-10-09T18:11:20.038044+00:00" last_verified: "2026-10-09" tags: ["konfiguracja", "plugin", "claude-code", "agenci-ai"] translations: [] reading_time_minutes: 11 word_count: 2199 --- > [!TLDR] > - Strona wiki `toolchain` mówi agentom, jak w Twoim projekcie uruchomić lint i testy. Bez niej komenda `work` nie zna tych komend: w rozmowie pyta, czy kontynuować bez lintu i testów, a sesja w tle kończy turę. > - Strona ma sześć sekcji o stałych nagłówkach i etykietach. Komendy czytają je dosłownie, więc format jest kontraktem. > - Stronę zapisuje `/monolynx:project-toolchain`: wykrywa stack, pyta o potwierdzenie i niczego nie uruchamia. > - `/monolynx:setup` sprawdza siedem punktów konfiguracji projektu i za Twoją zgodą woła komendy naprawcze. > - Tytuł strony musi brzmieć dokładnie `Toolchain`, bo od niego zależy adres, pod którym szukają jej komendy. ## Po co agentowi strona toolchain? Agent nie zna Twojego projektu. Nie wie, czy testy idą przez `pytest`, `npm test` czy `make test`, ani czy wolno je uruchomić poza kontenerem. Strona `toolchain` jest jedynym miejscem, z którego komendy `work` i `work-simple` biorą te informacje. Zapisujesz ją raz na projekt. **Statystyki** - **6** - sekcji strony `toolchain` - **1** - strona na projekt, zawsze pod adresem `toolchain` - **7** - punktów, które sprawdza `/monolynx:setup` - **0** - komend, które `project-toolchain` uruchamia, żeby je sprawdzić **Kto zapisuje stronę toolchain i kto ją czyta** Stronę zapisuje komenda project-toolchain po Twoim potwierdzeniu. Czytają ją komendy work i work-simple przy każdym tickecie, setup przy kontroli konfiguracji, sprint-end przy testach mutacyjnych i create-mutation-ci-script przy generowaniu etapu CI. ```mermaid flowchart LR A["project-toolchain"] -- "zapis po potwierdzeniu" --> B["Strona wiki Toolchain"] B --> C["work i work-simple: lint i testy"] B --> D["setup: kontrola sekcji"] B --> E["sprint-end: testy mutacyjne"] B --> F["create-mutation-ci-script: etap CI"] ``` ## Jak wygląda cała strona toolchain? Poniżej pełna strona dla projektu w Pythonie uruchamianego w Dockerze. Nagłówki sekcji i etykiety pól są stałe. Zmieniają się tylko wartości po dwukropku. ```markdown title="Strona wiki Toolchain: projekt w Dockerze" # Toolchain projektu Stack: Python 3.12, FastAPI Uruchamianie: docker ## Lint komenda: docker compose exec app ruff check . kto odpala: agent ## Test komenda: docker compose exec app pytest kto odpala: agent testy istnieja: tak framework: pytest pełny przebieg: lokalnie ## Worktree lint: docker compose -p sklep --profile dev run --rm --no-deps -v "$PWD":/app app ruff check . test: docker compose -p sklep --profile dev run --rm --no-deps -v "$PWD":/app app pytest izolacja testów: brak ## TDD stosowac: nie ## Mutacje narzedzie: brak powod: nie zainstalowane ## Uwagi Wszystko przez docker compose exec app - nigdy lokalnie ``` > [!NOTE] > Część etykiet jest zapisana bez polskich znaków: `testy istnieja`, `stosowac`, `narzedzie`, `powod`, `jak wyzej`. Tak wygląda kontrakt i tak zapisuje je komenda. Dwie etykiety mają polskie znaki: `pełny przebieg` i `izolacja testów`. Projekt bez Dockera ma tę samą stronę, tylko krótszą. Sekcja `## Worktree` odsyła wtedy do komend z sekcji wyżej. ```markdown title="Sekcje Lint, Test i Worktree: projekt bez Dockera" ## Lint komenda: npm run lint kto odpala: agent ## Test komenda: npm test kto odpala: agent testy istnieja: tak framework: vitest pełny przebieg: lokalnie ## Worktree lint: jak wyzej test: jak wyzej izolacja testów: tak ``` ## Co znaczy każde pole? Pola dzielą się na trzy grupy: komendy, decyzje o tym, kto je uruchamia, i wiedzę o projekcie. **Porównanie** | Sekcja | Pole | Dozwolone wartości | Co z niego wynika | | --- | --- | --- | --- | | Lint, Test | `komenda` | dokładna komenda | to uruchamia agent albo wypisuje dla Ciebie | | Lint, Test | `kto odpala` | `user` albo `agent` | `user`: agent wypisuje komendę i czeka na wynik | | Test | `testy istnieja` | `tak` albo `nie` | mówi agentowi, czy projekt ma już testy | | Test | `pełny przebieg` | `lokalnie` albo `ci` | gdzie idzie pełny zestaw testów przed zamknięciem ticketu | | Worktree | `lint`, `test` | komenda albo `jak wyzej` | komendy dla kopii repozytorium, w której pracuje sesja w tle | | Worktree | `izolacja testów` | `tak` albo `brak` | czy testy z dwóch kopii mogą iść jednocześnie | | TDD | `stosowac` | `tak` albo `nie` | przy `tak` testy powstają przed implementacją | | Mutacje | `narzedzie` | nazwa z wersją albo `brak` | czy projekt ma testy mutacyjne | | Uwagi | dowolny tekst | - | reguły repozytorium, na przykład "tylko przez Docker" | > [!IMPORTANT] > Pole `kto odpala: agent` to tylko połowa zgody. Drugą jest flaga `MONOLYNX_AUTOTEST` ustawiona na `true`. Bez niej strażnik komend pyta o każde uruchomienie lintu i testów, a sesja w tle dostaje odmowę. ### Dlaczego sekcja Worktree ma osobne komendy? Sesje sprintu pracują w osobnych kopiach repozytorium, czyli w worktree. Komenda `docker compose exec` wchodzi do działającego kontenera, a ten ma zamontowany Twój główny katalog. Uruchomiona z kopii sprawdziłaby więc nie ten kod, nad którym pracuje agent. **Porównanie** | Cecha | `docker compose exec` | `docker compose run` z sekcji Worktree | | --- | --- | --- | | Który kod sprawdza | główny katalog repozytorium | bieżącą kopię, zamontowaną opcją `-v` | | Kontener | już działający | jednorazowy, usuwany po przebiegu | | Kiedy używana | praca w głównym katalogu | praca w worktree, wybierana automatycznie | | Wymaganie | działający stack | działający stack głównego katalogu | Komenda `work` sama rozpoznaje, że działa w worktree, i wtedy bierze komendy z tej sekcji. Zapis `"$PWD"` zamienia przed uruchomieniem na literalną ścieżkę kopii. > [!WARNING] > Strona bez sekcji `## Worktree` wystarcza do pracy w głównym katalogu. W worktree komenda `work` zatrzyma się i odeśle do `/monolynx:project-toolchain`. Sprint z dyspozytorem zawsze pracuje w worktree. ### Co znaczy izolacja testów? Pole odpowiada na jedno pytanie: czy dwa przebiegi testów z dwóch kopii repozytorium dzielą stan, na przykład bazę o stałej nazwie albo ten sam port. **Porównanie** | Wartość | Znaczenie | Co robi `work` | | --- | --- | --- | | `tak` | przebiegi nie dzielą stanu albo rozdziela je parametr w komendzie `test` | uruchamia testy bez kolejki | | `brak` | przebiegi dzielą stan i nie ma parametru, który by go rozdzielił | ustawia testy w kolejce, jeden przebieg naraz | Gdy projekt ma parametr izolacji, komenda `test` w sekcji Worktree zawiera znacznik ``. Sesja zamienia go na klucz swojego ticketu, więc każdy ticket dostaje własną bazę testową. ### Pełny przebieg: lokalnie czy w CI? W dużym projekcie pełny zestaw testów trwa długo. Pole `pełny przebieg` pozwala przenieść go do pipeline'u merge requesta. **Porównanie** | Cecha | `lokalnie` | `ci` | | --- | --- | --- | | Lint | pełny, w sesji ticketu | pełny, w sesji ticketu | | Testy w sesji ticketu | cały zestaw | tylko zmieniony obszar | | Pełny zestaw | w sesji, po ostatniej zmianie | w pipeline'ie merge requesta | | Wymagane flagi | brak dodatkowych | `MONOLYNX_AUTOCOMMIT`, `MONOLYNX_AUTOPUSH` i `MONOLYNX_AUTOMR` na `true` | | Kiedy ticket trafia do Review | po zielonych testach | dopiero po otwarciu merge requesta | > [!CAUTION] > W trybie `ci` błąd w obszarze, którego nie objęły lokalne testy, wyjdzie dopiero w pipeline'ie. Czerwony pipeline merge requesta naprawia wtedy kolejka `mr-queue`, a nie sesja ticketu. ## Jak powstaje strona toolchain? Stronę zapisuje komenda `/monolynx:project-toolchain`. Uruchamiasz ją w katalogu repozytorium, bez argumentów. **Kroki** 1. **Sprawdzenie stanu** Komenda szuka strony o tytule `Toolchain`. Gdy istnieje, pokazuje jej treść i pyta, czy ją zaktualizować. 2. **Wykrycie stacku** Komenda czyta pliki konfiguracyjne w repozytorium: `Makefile`, `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod` i podobne. Target z `Makefile` wygrywa z komendą domyślną. 3. **Potwierdzenie** Wykryte komendy widzisz w tabeli i odpowiadasz na pytania: czy się zgadzają, kto je uruchamia, czy stosować TDD, jak z izolacją testów i gdzie idzie pełny przebieg. 4. **Narzędzie mutacyjne** Krok opcjonalny. Komenda sprawdza, czy narzędzie jest zainstalowane, i pyta o moduły rdzenia. Niczego nie instaluje. 5. **Zapis** Strona trafia do wiki projektu z tytułem `Toolchain`. Na końcu dostajesz podsumowanie i link. **Pytanie o potwierdzenie wykrytych komend (przykład)** ```console > /monolynx:project-toolchain Wykryty stack: Python 3.12, FastAPI (docker) | | Komenda | | Lint | docker compose exec app ruff check . | | Test | docker compose exec app pytest | | Worktree | docker compose -p sklep --profile dev run --rm ... | | Izolacja testów między worktree | brak - fixture zakłada bazę o stałej nazwie | | Pełny przebieg testów | lokalnie - 14 plików testowych, brak etapu testów w CI | Testy w repo: znaleziono 14 plików 1. Komendy się zgadzają? (tak / podaj poprawne) 2. Kto uruchamia lint i testy: user czy agent? 3. Stosować TDD? (tak / nie) 4. Izolacja testów się zgadza? (tak / podaj poprawną) 5. Pełny przebieg testów: lokalnie czy ci? ``` > [!TIP] > Wykrywanie zgaduje, a Ty wiesz. Jeśli zespół uruchamia testy inną komendą niż ta z tabeli, podaj ją w odpowiedzi. Komenda zapisze dokładnie to, co potwierdzisz. > [!WARNING] > Nie zmieniaj tytułu strony ani etykiet pól przy ręcznej edycji. Adres strony powstaje z tytułu, więc tytuł inny niż `Toolchain` ukrywa ją przed komendami. Zmieniona etykieta sprawia, że komenda nie znajdzie pola. ## Co sprawdza /monolynx:setup? Komenda `/monolynx:setup` jest listą kontrolną projektu. Sprawdza siedem punktów, każdy oznacza jako OK albo BRAK i przy brakach wskazuje komendę naprawczą. **Porównanie** | Punkt | Co sprawdza | Komenda naprawcza | | --- | --- | --- | | 1. Slug projektu | czy repozytorium wie, z którym projektem pracuje | brak; ustawiasz zmienną sam | | 2. Strona `toolchain` | cztery z sześciu nagłówków (`Lint`, `Test`, `Worktree`, `Mutacje`) i pole `izolacja testów` | `/monolynx:project-toolchain` | | 3. LLM Wiki | czy metoda jest włączona w projekcie | `/monolynx:wiki-init` | | 4. Graf zależności w CI | czy CI synchronizuje graf kodu | `/monolynx:create-graph-ci-script` | | 5. Testy mutacyjne w CI | czy CI ma etap mutacji | `/monolynx:create-mutation-ci-script` | | 6. Flagi `MONOLYNX_*` | które są ustawione i gdzie | brak; to informacja, nie stan do naprawy | | 7. CLI `monolynx` | instalacja, logowanie, wersja, lista dozwolonych komend | brak; dostajesz komendy do uruchomienia | **Wynik setup w projekcie ze starszą stroną toolchain (przykład)** ```console > /monolynx:setup | Punkt | Stan | Skill naprawczy | | 1. Slug projektu | OK (sklep) | - | | 2. Strona wiki toolchain | BRAK (brakuje: ## Worktree, ## Mutacje) | /monolynx:project-toolchain | | 3. LLM Wiki | OK | /monolynx:wiki-init | | 4. Graf zależności w CI | BRAK | /monolynx:create-graph-ci-script | | 5. Testy mutacyjne w CI | BRAK | /monolynx:create-mutation-ci-script | | 6. Flagi MONOLYNX_* | INFO (3 jawnie ustawione) | - | | 7. CLI monolynx | OK (0.4.0, zalogowane, aktualne, allowlista) | - | ``` Po tabeli komenda pyta, które braki naprawić. Wybrane komendy naprawcze woła po kolei, w stałej kolejności: najpierw `project-toolchain`, potem `wiki-init`, graf i na końcu mutacje. Kolejność ma znaczenie, bo etap mutacji w CI czyta sekcję `## Mutacje` ze strony `toolchain`. > [!IMPORTANT] > Komenda `setup` niczego nie naprawia sama i nie ustawia flag autonomii. Flagi tylko pokazuje. Włączenie `MONOLYNX_AUTOPUSH` czy `MONOLYNX_AUTOMERGE` to Twoja decyzja, a nie brak w konfiguracji. **Które punkty są naprawdę potrzebne przed pierwszym ticketem?** Do pierwszego ticketu wystarczą punkty 1 i 2: slug projektu i strona `toolchain`. Punkt 3 jest potrzebny, gdy chcesz, żeby wiedza z ticketów trafiała do wiki. Punkty 4 i 5 dotyczą projektów z CI. Punkt 7 przyspiesza pracę, ale komendy działają też bez CLI, przez samo połączenie MCP. Sekcja `## Mutacje` z wartością `narzedzie: brak` ma stan OK. Liczy się obecność sekcji, bo brak narzędzia to świadoma decyzja właściciela repozytorium. ## Najczęstsze pytania **FAQ** ### Czy mogę napisać stronę toolchain ręcznie? Tak, o ile zachowasz tytuł `Toolchain`, nagłówki sekcji i etykiety pól dokładnie tak jak w przykładzie. Bezpieczniej uruchomić `/monolynx:project-toolchain` i poprawić wartości w odpowiedzi na pytania. ### Co zrobić po zmianie komendy testów w projekcie? Uruchom `/monolynx:project-toolchain` ponownie. Komenda pokaże obecną stronę, zapyta o aktualizację i zapisze nową treść pod tym samym adresem. ### Czy project-toolchain uruchomi moje testy, żeby je sprawdzić? Nie. Komenda niczego nie uruchamia poza odpytaniem narzędzia mutacyjnego o jego pomoc i wersję. Konfiguracja nie jest testem, a lint na niezapisanych zmianach dałby mylący wynik. ### Setup pokazuje BRAK przy stronie, która istnieje. Dlaczego? Strona powstała w starszej wersji pluginu i brakuje jej sekcji `## Worktree`, `## Mutacje` albo pola `izolacja testów`. Tabela wymienia brakujące elementy. Uruchom `/monolynx:project-toolchain`, żeby je dopisać. ### Jak często uruchamiać setup? Po instalacji pluginu, po jego aktualizacji i wtedy, gdy coś przestaje działać. Komenda tylko czyta, więc możesz ją uruchomić w dowolnej chwili. ## Słownik i następny krok **Słownik** - **Toolchain** - strona wiki projektu z komendami lintu i testów oraz zasadami ich uruchamiania - **Worktree** - osobna kopia repozytorium na dysku, w której pracuje sesja jednego ticketu - **Izolacja testów** - cecha projektu: czy dwa równoległe przebiegi testów nie wchodzą sobie w drogę - **Pełny przebieg** - uruchomienie całego zestawu testów, a nie tylko testów zmienionego obszaru - **Slug projektu** - krótka nazwa projektu w adresach i w komendach - **Komenda naprawcza** - komenda pluginu, która uzupełnia brak wskazany przez `setup` Założenie konta, projektu i instalację pluginu opisuje wpis [Pierwszy projekt w Monolynx](https://monolynx.com/blog/pierwszy-projekt-w-monolynx). Flagi z punktu 6 wyjaśnia wpis [Konfiguracja: które zmienne gdzie ustawić](https://monolynx.com/blog/konfiguracja-monolynx-zmienne). Gdy strona jest gotowa, przejdź do wpisu [Pierwszy ticket ręcznie](https://monolynx.com/blog/pierwszy-ticket-recznie-monolynx). **Wezwanie do działania** Chcesz zobaczyć, gdzie w projekcie mieszka strona toolchain? [Zobacz moduł Wiki w Monolynx](https://monolynx.com/features/wiki)