Od pustego repozytorium do zmergowanego ticketu: cały przebieg

Co dokładnie zobaczysz w tym przebiegu?

Pozostałe wpisy opisują komendy pojedynczo. Tutaj idą po kolei, na jednym repozytorium i jednym tickecie, tak jak pierwszego dnia pracy z Monolynx.

flowchart LR
  A["git init"] --> B["Projekt i plugin"]
  B --> C["setup i project-toolchain"]
  C --> D["ticket-create"]
  D --> E["work-simple"]
  E --> F["commit, push, merge request"]
  F --> G["merge"]
  G --> H["Gotowe"]

Etap 1: repozytorium i projekt

Repozytorium jest celowo małe: jedna funkcja i jeden test.

$ mkdir sklep && cd sklep && git init -b main
$ ls -R
pyproject.toml
sklep/__init__.py
sklep/koszyk.py
tests/test_koszyk.py
$ git add . && git commit -m "Start: suma zamówienia"
$ git remote add origin git@gitlab.com:twoja-firma/sklep.git
$ git push -u origin main

def suma_zamowienia(pozycje):
    return sum(cena * ilosc for cena, ilosc in pozycje)

Na platformie zakładasz projekt o nazwie sklep, ze slugiem sklep i kodem projektu SKL. Kod jest przedrostkiem kluczy ticketów, więc pierwszy ticket dostanie klucz SKL-1. Potem w sesji Claude Code instalujesz plugin i mówisz repozytorium, z którym projektem pracuje.

/plugin marketplace add https://gitlab.com/piotrkrych/monolynx.git
/plugin install monolynx@monolynx

{
  "env": {
    "MONOLYNX_PROJECT_SLUG": "sklep",
    "MONOLYNX_AUTOTEST": "true"
  }
}

Flaga MONOLYNX_AUTOTEST to jedyna zgoda w tym przebiegu. Pozwala agentowi samodzielnie uruchamiać lint i testy. Bez niej agent wypisywałby polecenia i czekał, aż wkleisz wynik.

Etap 2: konfiguracja projektu

Komenda /monolynx:setup pokazuje, czego brakuje. W nowym projekcie brakuje prawie wszystkiego, ale do pierwszego ticketu potrzebny jest tylko punkt 2.

> /monolynx:setup

| Punkt | Stan | Skill naprawczy |
| 1. Slug projektu | OK (sklep) | - |
| 2. Strona wiki toolchain | BRAK | /monolynx:project-toolchain |
| 3. LLM Wiki | BRAK | /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 (1 jawnie ustawiona) | - |
| 7. CLI monolynx | BRAK (niezainstalowane) | - |

Które punkty naprawić?

Wybierasz punkt 2. Komenda project-toolchain wykrywa stack z pliku pyproject.toml, pokazuje proponowane komendy i po Twoim potwierdzeniu zapisuje stronę.

## Lint

komenda: ruff check .
kto odpala: agent

## Test

komenda: pytest
kto odpala: agent
testy istnieja: tak
framework: pytest
pełny przebieg: lokalnie

## Worktree

lint: jak wyzej
test: jak wyzej
izolacja testów: tak

Pełny format strony i znaczenie każdego pola opisuje wpis Strona toolchain i /monolynx:setup.

Etap 3: ticket

Komendzie ticket-create podajesz temat jednym zdaniem. Komenda czyta kod, dopytuje o szczegóły i zapisuje ticket o stałej budowie.

> /monolynx:ticket-create Rabat procentowy w sumie zamówienia

Ticket SKL-1 utworzony (2 SP, status: Backlog)
Kryteria akceptacji: 3

## Cel
Funkcja suma_zamowienia przyjmuje opcjonalny rabat procentowy.

## Zakres
- parametr rabat_procent w suma_zamowienia, domyślnie 0
- błąd ValueError dla rabatu poza zakresem 0-100

## Pliki dotykane
- `sklep/koszyk.py`
- `tests/test_koszyk.py`

## Nie ruszac
- sposób zaokrąglania kwot

## Kryteria akceptacji
- suma bez rabatu nie zmienia się
- rabat 10 zmniejsza sumę o 10 procent
- rabat spoza zakresu 0-100 kończy się błędem ValueError

Sekcja "Nie ruszac" jest dla agenta równie ważna jak zakres. Mówi, czego nie poprawiać przy okazji.

Etap 4: praca agenta

Ticket ma 2 story points, więc wystarcza work-simple: jeden programista i krytyk. Komenda zaczyna od brancha.

> /monolynx:work-simple SKL-1

Jesteś na branchu main, który jest branchem bazowym.
Proponuję nowy branch z aktualnego main:

git checkout main && git pull origin main && git checkout -b feature-1-rabat-procentowy

Po utworzeniu brancha komenda pokazuje plan i kontrakt autonomii, a ticket dostaje status W trakcie. Dalej praca idzie bez Twojego udziału.

1. Plan

   Koordynator zapisuje plan jako komentarz na tickecie.

2. Implementacja

   Programista zmienia sklep/koszyk.py i dopisuje testy w tests/test_koszyk.py.

3. Lint i testy

   Koordynator uruchamia komendy ze strony toolchain: ruff check . i pytest.

4. Ocena

   Krytyk porównuje zmianę z kryteriami akceptacji i wystawia ocenę punktową. Próg zaliczenia to 82 punkty na 100.

5. Status Review

   Po zielonych testach i zaliczonej ocenie ticket przechodzi na status Review.

ruff check .   OK
pytest         4 passed

Ticket SKL-1: status Review, ocena krytyka 93/100

Do wykonania:
git add sklep/koszyk.py tests/test_koszyk.py
git commit -m "SKL-1: rabat procentowy w sumie zamówienia"

def suma_zamowienia(pozycje, rabat_procent=0):
    if not 0 <= rabat_procent <= 100:
        raise ValueError("Rabat musi być w zakresie 0-100")
    suma = sum(cena * ilosc for cena, ilosc in pozycje)
    return suma * (100 - rabat_procent) / 100

Etap 5: commit, push i merge request

Commit, push i merge request wyglądają tak samo jak przy zmianie napisanej ręcznie.

$ git add sklep/koszyk.py tests/test_koszyk.py
$ git commit -m "SKL-1: rabat procentowy w sumie zamówienia"
$ git push -u origin feature-1-rabat-procentowy
$ glab mr create --fill --target-branch main

Merge request czytasz jak zmianę kolegi. Plan, raport programisty i ocena krytyka są w komentarzach ticketu SKL-1, więc wiesz, co i dlaczego zostało zrobione.

Etap 6: merge i zamknięcie

Po zielonym CI i zatwierdzeniu mergujesz zmianę. Zostają dwie czynności.

1. Status Gotowe

   Zmień status SKL-1 na liście backlogu, w polu statusu przy tickecie, albo poproś o to agenta. Tablica pokazuje tylko aktywny sprint, więc ticketu bez sprintu na niej nie ma. Agent nie ustawia tego statusu sam, bo "gotowe" znaczy "zmergowane".

2. Powrót na gałąź główną

   Wykonaj git checkout main i git pull, żeby następny ticket startował z aktualnego kodu.

Co zostało po całym przebiegu?

Zmiana w kodzie to tylko część wyniku. Reszta jest na platformie i przyda się przy następnym tickecie.

Co mogło pójść inaczej?

Przebieg powyżej jest prosty, bo nic go nie przerwało. Poniżej najczęstsze odchylenia i to, co wtedy się dzieje.

Objawy i naprawy zbiera wpis Gdy coś nie działa.

Najczęstsze pytania

Słownik i następny krok

Slug projektu

krótka nazwa projektu w adresach i w komendach, tutaj sklep

Klucz ticketu

prefiks projektu i numer, tutaj SKL-1

Toolchain

strona wiki z komendami lintu i testów projektu

Koordynator

sesja, która prowadzi agentów nad jednym ticketem

Krytyk

osobny agent oceniający zmianę według kryteriów akceptacji

Kontrakt autonomii

spis tego, co agent robi sam, i tego, przed czym się zatrzymuje

Każdy krok pracy ręcznej z wariantami opisuje wpis Pierwszy ticket ręcznie. Znaczenie statusów wyjaśnia wpis Statusy ticketu w Monolynx. Pracę wielu ticketów naraz prowadzi Sprint z Monolynx krok po kroku.