Praca z agentami i praktyki inżynierskie
Przekładam wiedzę o projekcie i standardy inżynierskie na powtarzalną pracę z AI: jasne instrukcje, przydatne narzędzia i wyniki, które zespół może zweryfikować.
01 / Instrukcje projektu
Zapisz oczekiwania, które przedstawiłbyś nowemu inżynierowi: gdzie szukać informacji, jak wprowadzać zmiany i jak wykazać, że działają.
W Codex instrukcje mogą być nakładane od katalogu głównego repozytorium do katalogu roboczego. Wytyczne lokalne doprecyzowują zasady dla danego obszaru.
Treść przykładowa. Dostosuj ścieżki i ustalenia do swojego zespołu.
# Zasady pracy w projekcie
## Kontekst
- Przed zmianą granic modułów przeczytaj docs/architecture.md.
- Zachowaj istniejący format błędów API i wzorce walidacji.
## Realizacja
- Ogranicz zmiany do uzgodnionego zadania.
- Dodaj testy zmienianego zachowania.
- Uruchom odpowiednie kontrole opisane w CONTRIBUTING.md.
- Opisz zmianę zachowania, wyniki kontroli i nierozwiązane ryzyka.
## Uzgodnienia
- Zapytaj przed zmianą publicznego kontraktu API lub schematu danych.
- Wydania produkcyjne pozostaw procesowi zatwierdzania zespołu.02 / Powtarzalne procedury
Zamień powtarzalną pracę w konkretne procedury: diagnozowanie incydentu, przegląd zmiany, dodanie endpointu lub przygotowanie wyników kontroli przed wydaniem.
Skill zawiera instrukcje z nazwą i opisem oraz opcjonalne skrypty, materiały i zasoby. Opis pomaga agentowi wybrać procedurę; pełne instrukcje są wczytywane po jej wybraniu.
Określ moment użycia, dane wejściowe, kroki, oczekiwany wynik i warunki zatrzymania. Zacznij od jednego zadania, które potrafisz ocenić.
Oficjalna dokumentacja tworzenia skills ↗Przykładowy SKILL.md w katalogu procedury. Dostosuj go do używanego agenta i repozytorium.
---
name: api-change
description: Wprowadź ograniczoną zmianę endpointu API w tym projekcie. Stosuj do zachowania endpointu, walidacji i testów; pomiń zmiany infrastruktury i wydania produkcyjne.
---
1. Przeczytaj kontrakt endpointu i obowiązujące zasady projektu.
2. Znajdź istniejący endpoint stosujący te same konwencje.
3. Wprowadź najmniejszą zmianę spełniającą kryteria akceptacji.
4. Sprawdź poprawne żądanie, błędne dane i brak uprawnień.
5. Uruchom odpowiednie kontrole repozytorium i przejrzyj różnice.
6. Podsumuj zmianę i rzeczywiste wyniki; wskaż zablokowane kontrole.Przykłady wykorzystują konwencje AGENTS.md i SKILL.md obsługiwane przez Codex. Sposób wykrywania plików, priorytety i dostępne funkcje zależą od narzędzia; wdrożenie powinno odpowiadać Twojemu środowisku.
03 / Od zadania do potwierdzonych wyników
Przykładowe zadanie: dodaj endpoint pozwalający uprawnionemu użytkownikowi pobrać status dostawy zamówienia. Procedura łączy wymaganie ze standardami projektu i wykonywalnymi kontrolami.
Uzgodnij zachowanie endpointu i kryteria akceptacji.
Poznaj architekturę, konwencje i granice zmiany.
Zastosuj procedurę ograniczonej zmiany API.
Wprowadź zmianę i uruchom kontrole narzędziami repozytorium.
Sprawdź różnice, wyniki testów i otwarte pytania.
Niewielki zestaw zmian, opis zachowania, wyniki odpowiednich testów i jawną listę elementów niezweryfikowanych.
Jeśli kontrakt jest niejasny, brakuje dostępu lub potrzebna jest zmiana schematu, agent przedstawia decyzję do uzgodnienia przed kontynuowaniem zależnej pracy.
04 / Praktyki, które stosuję
Instrukcje nadają pracy kierunek. Rzetelne dostarczanie wymaga też aktualnego kontekstu, egzekwowanych uprawnień i sposobu oceny wyniku.
Opisz decyzje, polecenia i granice potrzebne agentowi. Szczegóły odsyłaj do aktualnej dokumentacji i usuwaj sprzeczne reguły.
Zacznij od właściwego kodu, kontraktów i przykładów. Sięgaj do wiedzy firmy, gdy jest potrzebna; pobrane treści traktuj jako materiał źródłowy, a nie upoważnienie do zmiany zadania.
Korzystaj z ograniczonych poświadczeń, izolacji środowiska i uprawnień narzędzi. Zapis w AGENTS.md nie blokuje technicznie nieuprawnionego działania.
Powiąż testy i kryteria akceptacji ze zmienianym zachowaniem. Zapisuj, co faktycznie uruchomiono, co się nie powiodło i co wymaga przeglądu człowieka.
Zachowuj reprezentatywne zadania, także takie, w których procedura nie powinna się uruchamiać. Porównuj skuteczność, poprawki, czas i koszty przy zmianach instrukcji.
Wersjonuj wspólne instrukcje i procedury razem z kodem. Wyznacz opiekuna i aktualizuj je wraz ze zmianami architektury, narzędzi i praktyk zespołu.
Praktyczne podejście do sprawdzania doboru procedur i ich wyników opisuje poradnik OpenAI dotyczący oceny skills.
05 / Pierwszy krok we współpracy
Wybierz powtarzalne zadanie, przy którym agenci wymagają ciągłych poprawek lub gubią konwencje projektu. Określimy zakres pilotażu i sposób oceny.
Zakres, dostępy i rezultaty uzgadniamy przed rozpoczęciem pracy.
Porozmawiajmy o pilotażu pracy z agentami ↗