feat: initial commit
This commit is contained in:
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: merge-request-authoring
|
||||
description: Redagowanie tytułu i opisu merge requesta dla zmiany wykonanej przez agenta - struktura opisu, informacja o ryzyku, ślad audytowy i lista kontrolna dla recenzenta. Użyj na końcu przebiegu, gdy zmiana jest gotowa do publikacji.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
owner: pubi-platform
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Opis merge requesta
|
||||
|
||||
Odbiorcą jest **człowiek, który bierze odpowiedzialność za merge**. Opis ma mu pozwolić
|
||||
podjąć decyzję bez czytania całego diffa.
|
||||
|
||||
## Tytuł
|
||||
|
||||
Conventional Commits, tryb rozkazujący, bez kropki na końcu, maks. 72 znaki:
|
||||
`build(deps): podniesienie acme-sdk 1.4.2 -> 2.1.0 wraz z migracją API`
|
||||
|
||||
## Struktura opisu
|
||||
|
||||
```markdown
|
||||
## Co i dlaczego
|
||||
2-4 zdania. Cel zmiany i skąd przyszło zadanie (issue / harmonogram / audyt zależności).
|
||||
|
||||
## Zakres zmian
|
||||
- `ścieżka/pliku.py` - co konkretnie zmienione
|
||||
(tylko pliki realnie w diffie)
|
||||
|
||||
## Weryfikacja
|
||||
Komenda, wynik, liczba testów. Wklej istotny fragment logu.
|
||||
|
||||
## Ryzyko i ograniczenia
|
||||
Co może się zepsuć na produkcji, czego agent NIE zweryfikował,
|
||||
elementy oznaczone jako `requires_human`.
|
||||
|
||||
## Ślad audytowy
|
||||
ID przebiegu, wersje pakietów kontekstowych (apm.lock.yaml), użyte modele, liczba iteracji.
|
||||
|
||||
## Lista kontrolna dla recenzenta
|
||||
- [ ] Diff nie zawiera zmian spoza zakresu
|
||||
- [ ] Brak zmian w testach maskujących błąd
|
||||
- [ ] Wersja zależności zgodna z zadaniem
|
||||
```
|
||||
|
||||
## Zasady
|
||||
|
||||
- **Zero marketingu.** Bez "successfully", "seamlessly", "comprehensive".
|
||||
- **Nie zgaduj wyników.** Cytuj wyłącznie realny log weryfikacji.
|
||||
- **Nazywaj to, czego nie wiesz.** Sekcja o ryzyku jest ważniejsza niż lista zmian.
|
||||
- **Nigdy nie cytuj sekretów** ani fragmentów danych produkcyjnych z logów.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
name: repo-recon
|
||||
description: Rozpoznanie repozytorium przed zmianą - ustalenie systemu budowania, menedżera zależności, komendy testowej, miejsc użycia biblioteki i realnego promienia rażenia zmiany. Użyj zawsze jako pierwszy krok migracji, upgrade'u SDK lub większego refaktoru.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
owner: pubi-platform
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Rozpoznanie repozytorium
|
||||
|
||||
Celem jest **fakt, nie domysł**. Każde stwierdzenie w raporcie musi wynikać z odczytanego pliku
|
||||
lub wyniku wyszukiwania.
|
||||
|
||||
## Procedura
|
||||
|
||||
1. **System budowania i menedżer zależności** - sprawdź w tej kolejności:
|
||||
`pyproject.toml`, `requirements*.txt`, `setup.cfg`, `pom.xml`, `build.gradle*`, `package.json`,
|
||||
`go.mod`. Zanotuj plik, który realnie deklaruje wersję biblioteki (może być więcej niż jeden -
|
||||
np. `pyproject.toml` + `constraints.txt`).
|
||||
2. **Aktualna wersja pakietu** - odczytaj dosłownie zapis wersji (`==`, `~=`, `^`, zakres).
|
||||
Zapis ma znaczenie: `~=1.4` migruje się inaczej niż `==1.4.2`.
|
||||
3. **Miejsca użycia** - `search_repo` po nazwie modułu importu (uwaga: nazwa pakietu
|
||||
dystrybucyjnego bywa inna niż nazwa modułu, np. `acme-sdk` -> `import acme`).
|
||||
Zbierz: pliki, symbole (klasy, metody), liczbę wystąpień.
|
||||
4. **Komenda weryfikacji** - znajdź jak repozytorium się testuje: sekcja `[tool.pytest.ini_options]`,
|
||||
`Makefile`, `tox.ini`, `.gitlab-ci.yml` (tylko do odczytu!). Jeśli brak - zaraportuj brak,
|
||||
nie wymyślaj komendy.
|
||||
5. **Promień rażenia** - oceń, czy użycia są skupione w warstwie adaptera (niskie ryzyko),
|
||||
czy rozlane po kodzie domenowym (wysokie ryzyko).
|
||||
|
||||
## Wynik
|
||||
|
||||
Zwróć strukturę zgodną ze schematem `RepoProfile`. Pola, których nie udało się ustalić,
|
||||
oznaczaj jako `null` i wypisz w `gaps` - to sygnał dla planisty, że potrzebna jest decyzja człowieka.
|
||||
|
||||
## Antywzorce
|
||||
|
||||
- Zgadywanie komendy testowej ("pewnie pytest") - jeśli nie ma dowodu, wpisz `gaps`.
|
||||
- Pomijanie plików lock (`poetry.lock`, `package-lock.json`) - one też pinują wersję.
|
||||
- Raportowanie użyć na podstawie samej nazwy pakietu bez sprawdzenia aliasów importu.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: safe-code-edit
|
||||
description: Technika bezpiecznej edycji cudzego kodu przez agenta - minimalny diff, zasady użycia narzędzi plikowych, weryfikacja po każdej zmianie i postępowanie przy nieudanej edycji. Użyj przy każdej modyfikacji plików w repozytorium.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
owner: pubi-platform
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Bezpieczna edycja kodu
|
||||
|
||||
## Twarde zasady
|
||||
|
||||
1. **Czytaj przed pisaniem.** Nigdy nie wywołuj `replace_in_file` na pliku, którego nie odczytałeś
|
||||
w tym przebiegu. Treść z planu nie jest dowodem na aktualny stan pliku.
|
||||
2. **Najmniejszy możliwy diff.** Zmieniaj wyłącznie linie, które muszą się zmienić.
|
||||
`write_file` (nadpisanie całości) jest dozwolone tylko dla plików, które sam utworzyłeś.
|
||||
3. **Jedna intencja na edycję.** Nie łącz migracji API z poprawą literówki w komentarzu.
|
||||
4. **Weryfikuj natychmiast.** Po zmianie pliku uruchom `run_verification`.
|
||||
Jeśli wynik jest czerwony, napraw przyczynę zanim dotkniesz kolejnego pliku.
|
||||
5. **Nie walcz z narzędziem.** Jeśli `replace_in_file` dwa razy nie znajdzie dopasowania -
|
||||
odczytaj plik ponownie i dopasuj dokładny fragment ze spacjami. Trzecia porażka = zgłoś
|
||||
`requires_human` z treścią fragmentu, zamiast nadpisywać plik w całości.
|
||||
6. **Nie dotykaj plików spoza planu.** Rozszerzenie zakresu wymaga nowego planu.
|
||||
|
||||
## Gdy weryfikacja jest czerwona
|
||||
|
||||
- Przeczytaj **pełny** komunikat błędu, nie tylko ostatnią linię.
|
||||
- Zlokalizuj plik i linię z traceback; napraw przyczynę, nie objaw.
|
||||
- Nie modyfikuj testów, żeby przeszły. Test jest kontraktem.
|
||||
- Jeśli po trzech próbach ten sam błąd - zatrzymaj się i zgłoś `requires_human` z pełnym logiem.
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: sdk-version-upgrade
|
||||
description: Podniesienie wersji SDK lub biblioteki wraz z migracją wywołań API - planowanie zmiany, kolejność edycji, obsługa breaking changes i kryteria akceptacji. Użyj gdy zadanie mówi o bumpie wersji, upgradzie SDK, migracji do nowego major release lub usunięciu deprecated API.
|
||||
license: Apache-2.0
|
||||
allowed-tools:
|
||||
- read_file
|
||||
- search_repo
|
||||
- list_files
|
||||
- write_file
|
||||
- replace_in_file
|
||||
- run_verification
|
||||
metadata:
|
||||
owner: pubi-platform
|
||||
version: "1.0.0"
|
||||
references: acme-sdk-2.x-migration.md
|
||||
---
|
||||
|
||||
# Upgrade wersji SDK
|
||||
|
||||
## Zasada nadrzędna
|
||||
|
||||
Upgrade to **dwie rozłączne zmiany**: (a) deklaracja wersji w pliku zależności,
|
||||
(b) dostosowanie kodu do nowego API. Deklarację wersji ustawia deterministycznie silnik pipeline'u -
|
||||
Twoim zadaniem jest wyłącznie (b). Nie edytuj ręcznie plików zależności, chyba że plan mówi inaczej.
|
||||
|
||||
## Kolejność pracy
|
||||
|
||||
1. Przeczytaj notatkę migracyjną dla docelowej wersji z katalogu `references/` tego skilla.
|
||||
Jeśli brakuje notatki dla danej biblioteki - **zatrzymaj się** i zgłoś `requires_human`.
|
||||
Nie migruj API "z pamięci modelu".
|
||||
2. Zbuduj mapę zmian: `stary symbol -> nowy symbol -> plik(i) do zmiany`.
|
||||
3. Edytuj plik po pliku, najmniejszą możliwą zmianą (`replace_in_file`, nie przepisywanie pliku).
|
||||
4. Po każdym pliku uruchom weryfikację (`run_verification`). Czerwony wynik naprawiaj natychmiast,
|
||||
zanim przejdziesz dalej - kumulowanie błędów uniemożliwia ustalenie przyczyny.
|
||||
5. Na koniec sprawdź, czy nie zostały użycia starego API: `search_repo` po każdym symbolu z mapy.
|
||||
|
||||
## Breaking changes - reguły decyzyjne
|
||||
|
||||
| Sytuacja | Działanie |
|
||||
|---|---|
|
||||
| Zmiana nazwy klasy/metody, ta sama semantyka | Migruj bezpośrednio |
|
||||
| Zmiana nazw parametrów | Migruj, zachowując wartości wywołań 1:1 |
|
||||
| Zasób wymaga teraz zamknięcia / context managera | Użyj `with`, nie dodawaj ręcznego `close()` |
|
||||
| Nowy wymagany parametr bez sensownej wartości domyślnej | `requires_human` - to decyzja biznesowa |
|
||||
| Usunięta funkcjonalność bez zamiennika | `requires_human`, nie obchodź problemu własną implementacją |
|
||||
|
||||
## Kryteria akceptacji
|
||||
|
||||
- Wszystkie testy repozytorium zielone.
|
||||
- Zero wystąpień starych symboli poza plikami changelog/dokumentacji.
|
||||
- Diff nie zawiera zmian niezwiązanych z migracją.
|
||||
- Deklarowana wersja zależności odpowiada wersji docelowej z zadania.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Maszynowo wykonywalna wersja notatki migracyjnej acme-sdk-2.x-migration.md.
|
||||
#
|
||||
# Zasada architektoniczna: co da się zmigrować deterministycznie, migrujemy regułą,
|
||||
# a nie modelem. LLM jest od reszty - od przypadków, których reguła nie obejmuje,
|
||||
# i od oceny, czy wynik ma sens. Reguły są częścią pakietu APM, więc podlegają
|
||||
# temu samemu wersjonowaniu i przeglądowi co skill.
|
||||
package: acme-sdk
|
||||
applies_to: ">=2.0.0,<3.0.0"
|
||||
file_glob: "*.py"
|
||||
rules:
|
||||
- id: import-client
|
||||
description: "Client -> AcmeClient w imporcie"
|
||||
pattern: '\bfrom acme import Client\b'
|
||||
replacement: 'from acme import AcmeClient'
|
||||
- id: constructor
|
||||
description: "Konstruktor: nowa nazwa klasy, endpoint -> base_url"
|
||||
pattern: '\bClient\(\s*api_key=(?P<key>[^,]+),\s*endpoint=(?P<endpoint>[^)]+)\)'
|
||||
replacement: 'AcmeClient(api_key=\g<key>, base_url=\g<endpoint>)'
|
||||
- id: send-message
|
||||
description: "send() -> messages.create() z nowymi nazwami parametrów"
|
||||
pattern: '\.send\(\s*to=(?P<to>[^,]+),\s*body=(?P<body>[^)]+)\)'
|
||||
replacement: '.messages.create(recipient=\g<to>, content=\g<body>)'
|
||||
- id: drop-close
|
||||
description: "Klient 2.x zwalnia zasoby automatycznie - close() usunięte z API"
|
||||
pattern: '^[ \t]*[A-Za-z_][A-Za-z0-9_]*\.close\(\)[ \t]*\n'
|
||||
replacement: ''
|
||||
multiline: true
|
||||
- id: response-attribute
|
||||
description: "Odpowiedź jest obiektem Message, nie słownikiem"
|
||||
pattern: '(?P<var>\b[a-z_][a-z0-9_]*)\[[''"]id[''"]\]'
|
||||
replacement: '\g<var>.id'
|
||||
@@ -0,0 +1,27 @@
|
||||
# acme-sdk: migracja 1.x -> 2.x
|
||||
|
||||
> Przykładowa notatka migracyjna. W realnym wdrożeniu ten katalog zasila pakiet APM
|
||||
> utrzymywany przez zespół właściciela SDK (np. `pubi/apm-packages/acme-sdk-migrations`),
|
||||
> a `apm install` dostarcza go do joba CI z pinem po tagu.
|
||||
|
||||
## Zmiany łamiące kompatybilność
|
||||
|
||||
| 1.x | 2.x | Uwagi |
|
||||
|---|---|---|
|
||||
| `from acme import Client` | `from acme import AcmeClient` | zmiana wyłącznie nazwy |
|
||||
| `Client(api_key=..., endpoint=...)` | `AcmeClient(api_key=..., base_url=...)` | `endpoint` -> `base_url` |
|
||||
| `client.send(to=..., body=...)` | `client.messages.create(recipient=..., content=...)` | wysyłka przez sub-resource |
|
||||
| `client.close()` | `with AcmeClient(...) as client:` | klient jest context managerem |
|
||||
| zwracany `dict` z kluczem `id` | obiekt `Message` z atrybutem `.id` | dostęp `msg["id"]` -> `msg.id` |
|
||||
|
||||
## Bez zmian
|
||||
|
||||
- `AcmeError` pozostaje w `acme.errors`.
|
||||
- Format kluczy API i semantyka retry są niezmienione.
|
||||
|
||||
## Kolejność migracji
|
||||
|
||||
1. Import i konstrukcja klienta.
|
||||
2. Wywołania wysyłki.
|
||||
3. Zarządzanie cyklem życia (`close()` -> `with`).
|
||||
4. Odczyt pól odpowiedzi.
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
#!/usr/bin/env bash
|
||||
# Znajduje użycia modułu w repozytorium wraz z kontekstem.
|
||||
# Użycie: find_usages.sh <katalog-repo> <nazwa-modulu>
|
||||
set -euo pipefail
|
||||
repo="${1:?podaj katalog repozytorium}"
|
||||
module="${2:?podaj nazwę modułu importu}"
|
||||
rg --line-number --with-filename \
|
||||
-e "^\s*import\s+${module}\b" \
|
||||
-e "^\s*from\s+${module}\b" \
|
||||
-e "\b${module}\." \
|
||||
--glob '!**/.git/**' --glob '!**/node_modules/**' \
|
||||
"$repo" || echo "brak użyć modułu ${module}"
|
||||
Reference in New Issue
Block a user