Łańcuch artefaktów
ENŁańcuch artefaktów to ciąg commitowanych plików, który prowadzi zmianę od pomysłu do produkcji: intent.md, spec.md, plan.md z listą zadań, diff z dowodami testów, wyniki review oraz rekord incydentu, z którego powstaje kolejna intencja. Każdy etap czyta poprzedni artefakt, a wskazana osoba akceptuje go, zanim ruszy następny etap.
Masz zgłoszenie „Dodaj powiadomienia dla użytkowników” z terminem na piątek. Wklejasz je agentowi, a on pisze 400 linii kodu, które wyglądają wiarygodnie, ale pomijają połowę wymagań, wymyślają tabelę notifications kolidującą z twoją tabelą events i ignorują konwencje twojego API. Agent nie zawiódł. Podjął decyzje architektoniczne, o które nikt go nie prosił, i nic zapisanego nie mówiło mu, że ma postąpić inaczej.
Ta strona jest dla deweloperów, którzy uruchamiają agentów przy prawdziwych funkcjach, i dla tech leadów, którzy chcą, żeby każda zmiana zostawiała ten sam ślad. Zastępuje starszą na tej stronie metodę „PRD → plan → lista zadań”: PRD stał się plikami intent.md i spec.md, plan — plikiem plan.md, a lista zadań — sekcją zadań w plan.md.
Co łańcuch artefaktów da ci przy następnej funkcji
Dział zatytułowany „Co łańcuch artefaktów da ci przy następnej funkcji”- Sześć artefaktów, każdy z szablonem, osobą, która go akceptuje, i dowodem, który mu towarzyszy.
- Sześć gotowych promptów: wywiad, który zamienia pomysł w intencję, przegląd specyfikacji pod kątem luk, szkic planu, wykonanie jednego zadania, kontrola dryfu diffa i audyt bazy kodu zamieniony w plany.
- Polecenia trybu planowania w Claude Code, Codeksie i Cursorze oraz miejsce, w którym musi wylądować ich wynik.
- Sposób sprawdzania każdego przekazania testami, kryteriami akceptacji i przeglądem dryfu — bez czytania każdej linii, którą pisze agent.
Z jakich plików składa się łańcuch artefaktów?
Dział zatytułowany „Z jakich plików składa się łańcuch artefaktów?”Każdy etap kończy się commitem jednego artefaktu. Następny etap zaczyna się od jego przeczytania.
| Etap | Artefakt | Kto go akceptuje | Co dowodzi, że jest gotowy |
|---|---|---|---|
| Plan | intent.md | Product owner | Problem, rezultat i ograniczenia są opisane; otwarte pytania są wypisane, a nie zgadnięte |
| Design | spec.md | Product owner, przy pracy wyższego ryzyka także tech lead | Każde wymaganie ma kryterium akceptacji, które test może sprawdzić |
| Build | plan.md z listą zadań, potem diff | Inżynier (praca rutynowa); tech lead lub architekt (wyższe ryzyko) | Każde zadanie wskazuje swoje pliki i polecenie, które potwierdza jego wykonanie |
| Test | Wynik testów, log builda lub diff zrzutów ekranu dołączony do PR | Code owner recenzujący PR | Polecenia z sekcji Proof planu przechodzą w CI |
| Deploy | Pull request z wynikami review | Code owner; release manager na bramce produkcyjnej | Brak otwartych uwag oznaczonych jako Important |
| Maintain | Rekord incydentu, potem nowy intent.md | Właściciel serwisu lub dyżurny, potem product owner | Następna intencja linkuje incydent |
Aż do planu artefaktem jest markdown, bo product owner i agent mogą czytać ten sam plik i działać na jego podstawie. Od etapu build artefaktem jest kod wraz z dowodami: wynikami testów, logami i uwagami z review. Pełną procedurę dla każdego pliku znajdziesz na stronach etapów: Plan dla intent.md, Design dla spec.md i Build dla plan.md.
Wskaż jedno źródło prawdy dla każdego artefaktu
Dział zatytułowany „Wskaż jedno źródło prawdy dla każdego artefaktu”Twój proces już śledzi te artefakty, tylko nie jako markdown. Zadania żyją w Jirze, wymagania w narzędziu z regulacyjną identyfikowalnością, projekty w Figmie, a zgody na zmiany — w komitecie zmian (change board). Audytorzy akceptują te systemy, więc trudno je wyprzeć.
Dla każdego artefaktu wskaż jeden system jako źródło prawdy. Wszystko inne trzyma kopię albo link. Wybierz jedną z poniższych konfiguracji dla każdego artefaktu:
| Konfiguracja | Rekord wiążący | Jak agent z nim pracuje | Wybierz, gdy |
|---|---|---|---|
| Repozytorium | Plik markdown | Czyta i edytuje plik; zgłoszenie linkuje commit | Proces należy do inżynierii i chcesz jednego źródła znaczników czasu |
| System zastany | Rekord w Jirze, ServiceNow lub narzędziu do wymagań | Czyta rekord na starcie sesji i zapisuje wynik przez serwer MCP w tej samej sesji | Audytorzy lub regulator już akceptują ten system |
| Samo powiązanie | Oba, z odsyłaczami | Każdy plik zapisuje ID rekordu; każdy rekord zawiera SHA commita pliku | Nie możesz jeszcze wybrać jednego źródła — zacznij od tego |
Konfiguracja „system zastany” wymaga serwera MCP dla tego systemu. Dla Jiry użyj serwera Atlassian Rovo MCP pod adresem https://mcp.atlassian.com/v2/mcp; dla zgłoszeń w GitHubie — serwera GitHub MCP. Dodaj serwer Atlassian w swoim narzędziu:
claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcpPotem uruchom w sesji /mcp, żeby się zalogować.
codex mcp add atlassian --url https://mcp.atlassian.com/v2/mcpZainstaluj wtyczkę Atlassian z marketplace’u Cursora albo dodaj serwer do mcp.json:
{ "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } }Opcje uwierzytelniania i inne systemy zgłoszeń opisują strony Atlassian MCP, serwery do zarządzania projektami dla Lineara i innych oraz serwery kontroli wersji.
Przeprowadź jedną funkcję przez cały łańcuch
Dział zatytułowany „Przeprowadź jedną funkcję przez cały łańcuch”Poniższe kroki prowadzą zgłoszenie o powiadomieniach z początku strony przez cały łańcuch. Każdy krok ma swój prompt.
-
Zapisz intencję. Gdy masz tylko jednolinijkowe zgłoszenie, każ agentowi przeprowadzić z tobą wywiad, zamiast pisać intencję samodzielnie. Zacommituj wynik jako
intent/notifications/intent.mdi daj go do akceptacji product ownerowi.W Claude Code agent może pytać przez narzędzie
AskUserQuestion, które zamiast ściany tekstu daje ci pytania wielokrotnego wyboru (obecne w v2.1.283). -
Napisz specyfikację, a potem każ agentowi znaleźć w niej luki. Przygotuj
spec.mdwedług strony Design. Zanim powstanie jakikolwiek plan, otwórz nową sesję i każ agentowi zestawić specyfikację z kodem. Ten krok wyłapuje kolidującą tabelę, zanim ktokolwiek ją napisze.Każdą lukę zamykaj w
spec.md, nie w czacie. Decyzja, która istnieje tylko w rozmowie, znika razem z sesją. -
Naszkicuj plan w trybie planowania. Tryb planowania pozwala agentowi czytać kod bez zmieniania go. Poproś o plan, który wykorzystuje to, co już istnieje, i kończy się listą zadań.
Kwestionuj plan tak, jak zrobiłbyś to na design review. Na przykład: „Plan dodaje tabelę
notifications. Jakie są kompromisy względem rozszerzeniaeventsi które rozwiązanie pasuje do naszych istniejących wzorców?”. Potem tech lead albo inżynier akceptujeplan.mdi go commituje. -
Wykonuj jedno zadanie na turę. Każde zadanie jest na tyle małe, że da się je sprawdzić i wyrzucić. Gdy agent pomyli się przy zadaniu 7, tracisz zadanie 7, a nie całą funkcję.
-
Sprawdź diff względem łańcucha. Zanim pull request trafi do człowieka, uruchom przegląd, który porównuje to, co zbudowano, z tym, co zaakceptowano. Ten sam przebieg umieść w
REVIEW.mdw katalogu głównym repozytorium (szablon niżej); czyta go zarządzany Code Review w Claude Code (plany Team i Enterprise; ogólnie dostępny według Anthropic, sprawdzone 2026-10-16). Lokalny/code-reviewgo nie czyta, więc uruchom poniższy prompt dryfu jako zwykły prompt. W Codeksie przekaż go jako prompt:codex review "Follow REVIEW.md. Compare this branch with main against intent/notifications/spec.md and plan.md.". Własnego promptu nie da się połączyć z--base(sprawdzone w v0.157.1), więc gałąź nazwij w samym prompcie. -
Zmerguj i domknij pętlę. Pull request niesie wyniki review i dowody testów. Gdy funkcja wywoła incydent albo ujawni brakujące wymaganie, rekord staje się nowym
intent.md— zobacz Maintain.
Jak włączyć tryb planowania w Claude Code, Codeksie i Cursorze?
Dział zatytułowany „Jak włączyć tryb planowania w Claude Code, Codeksie i Cursorze?”Łańcuch jest taki sam w każdym narzędziu. Różni się to, jak utrzymujesz agenta w trybie tylko do odczytu podczas planowania i gdzie ląduje plan. We wszystkich trzech plan liczy się dopiero jako zacommitowany plik: to on jest czytany przez CI, agentów recenzujących i następną sesję.
- Tryb planowania włączysz przez Shift+Tab,
/planalboclaude --permission-mode plan. Od v2.1.283 (oba kanały wydań na 2026-10-12) sesje interaktywne w terminalu i VS Code startują w trybie auto, więc na tryb planowania przełącz się świadomie;claude -pi Agent SDK (poza zewnętrznymi dostawcami i wyłączoną telemetrią, gdzie od v2.1.285 startują w trybie auto), sesje, w których ustawienia włączajądisableAutoMode, oraz sesje na modelu nieobsługiwanym przez tryb auto nadal startują w trybie Manual. - Ctrl+G otwiera proponowany plan w zewnętrznym edytorze, żebyś mógł go poprawić przed akceptacją.
- Ctrl+T przełącza wbudowaną listę zadań. Ustaw
CLAUDE_CODE_TASK_LIST_ID, żeby dzielić jedną listę między sesjami. Traktuj ją jako widok roboczy; zapisem pozostajeplan.md. claude -w notificationsuruchamia pracę w nowym worktree Gita, aclaude -ckontynuuje ostatnią rozmowę.
- Tryb planowania włączysz przez
/planw CLI. - Narzędzie planowania
update_planjest od v0.152.0 domyślnie wyłączone, więc Codex nie prowadzi żywej listy kontrolnej, dopóki nie ustawisztools.update_plan.enabled = true. Trzymaj zadania wplan.md, gdzie przetrwają każdą sesję. codex --worktreeuruchamia sesję w nowym, zarządzanym worktree Gita (v0.157.1), acodex resume --lastwznawia ostatnią sesję.- Żeby wykonywać zadania pojedynczo bez czatu, przekaż prompt „wykonaj następne zadanie” do
codex exec.
- Wybierz Plan w selektorze trybu agenta. Według dokumentacji Cursora Plan Mode „creates detailed implementation plans before writing any code” (sprawdzone 2026-08-28).
- Zanim zaczniesz budować, zapisz zaakceptowany plan w repozytorium jako
plan.md, żeby recenzenci, CI i pozostałe narzędzia czytały ten sam plik. - Prompt przeglądu dryfu z kroku 5 uruchom w nowym czacie Agenta, żeby recenzent nie dziedziczył kontekstu, który napisał kod.
- Worktrees „let Agent work in isolated Git checkouts” (dokumentacja Cursora, sprawdzone 2026-08-28), dzięki czemu równoległe zadanie nie dotyka twojej gałęzi roboczej.
Pełne mapowanie każdego etapu na narzędzia znajdziesz w mapie narzędzi.
Szablony artefaktów
Dział zatytułowany „Szablony artefaktów”Skopiuj te struktury do repozytorium i zastąp symbole zastępcze zapisane UPPER_SNAKE_CASE.
Szablon: intent.md
Dział zatytułowany „Szablon: intent.md”# Intent: INTENT_TITLEAuthor: AUTHOR_NAME (TEAM). Status: draft | accepted. Ticket: TICKET_ID
## ProblemWHAT_IS_BROKEN_OR_MISSING
## Proposed outcomeWHAT_BETTER_LOOKS_LIKE
## Affected users and systemsUSERS_AND_SYSTEMS
## ConstraintsCONSTRAINTS
## Open questionsOPEN_QUESTIONSSzablon: spec.md
Dział zatytułowany „Szablon: spec.md”# Spec: SPEC_TITLE (from intent.md, accepted DATE)Status: ready-for-plan
## Requirements and acceptance criteria- R1: REQUIREMENT. Accepted when: CHECKABLE_CRITERION
## Architecture and designDESIGN_DETAILS
## Out of scopeOUT_OF_SCOPE
## Skills and policies applied- Security: POLICIES_APPLIED- Brand and UX: GUIDELINES_APPLIED
## Flagged concernsCONCERNS_FOR_POLICY_OWNERSSzablon: plan.md
Dział zatytułowany „Szablon: plan.md”# Plan: PLAN_TITLE (from spec.md, accepted DATE)
## Files that changeFILE_LIST_WITH_REFERENCE_PATTERNS
## DecisionsDECISION: OPTIONS, CHOICE, REASON
## Tasks- [ ] 1. TASK (files: FILES). Accepted when: CHECK. Test: TEST_COMMAND- [ ] 2. TASK (files: FILES). Accepted when: CHECK. Test: TEST_COMMAND
## RisksRISKS
## ProofCOMMANDS_THAT_SHOW_THE_CHANGE_WORKSGdy implementacja odchodzi od planu, aktualizuj plan.md w tym samym commicie co kod.
Szablon: REVIEW.md
Dział zatytułowany „Szablon: REVIEW.md”# Review instructions
## PassesRun four passes and tag each finding with its pass:- Bugs: logic errors, broken edge cases, subtle regressions- Security: injection risks, authentication gaps, PII in logs- Compliance: the change matches spec.md, plan.md, and design principles- Drift: files changed outside plan.md, ticked tasks without tests
## Severity criteria- Important: broken behaviour, leaked data, security vulnerability, policy breach- Nit: formatting, naming, cosmetic refactors (cap at 5 nits total)
## ExclusionsExclude generated code under src/gen/, dist/, and checks already enforced by CI.Jeśli wolisz przyjąć łańcuch jako gotowy framework, GitHub Spec Kit prowadzi tę samą sekwencję przez polecenia /speckit-specify, /speckit-plan, /speckit-tasks i /speckit-implement (github/spec-kit, sprawdzone 2026-09-26). Strony Spec Kit i spec-driven development pomogą ocenić, kiedy wystarczy zwykły markdown.
Czy planować mocniejszym modelem niż ten, którym wykonujesz?
Dział zatytułowany „Czy planować mocniejszym modelem niż ten, którym wykonujesz?”Planowanie i wykonanie nagradzają co innego. Plan wymaga od modelu szerokiego czytania, ważenia kompromisów i dostrzegania przypadków brzegowych. Dobrze opisane zadanie jest w porównaniu z tym dość mechaniczne. Trzymaj się zasady obowiązującej w całym serwisie: zacznij od domyślnego modelu narzędzia, przy planowaniu najpierw podnieś poziom rozumowania (effort), a model zmień dopiero wtedy, gdy twoje własne ewaluacje pokażą zysk.
Jeśli jednak rozdzielasz pracę, Claude Code ma do tego wbudowany alias: opusplan używa Opusa w trybie planowania i Sonneta przy wykonaniu. W każdym narzędziu podział umożliwia zacommitowany plan.md, bo sesja wykonująca czyta plik, a nie rozmowę z planowania. O wyborze modelu przeczytasz w routingu modeli i w przeglądzie modeli.
Ten sam podział skaluje się na cały backlog. Jedna dokładna sesja audytuje bazę kodu i pisze plany. Późniejsze sesje — albo równoległe, w osobnych worktree — je wykonują.
Jak sprawdzić każde przekazanie bez czytania każdej linii?
Dział zatytułowany „Jak sprawdzić każde przekazanie bez czytania każdej linii?”Każdy artefakt niesie dowody dla następnej bramki, więc recenzent sprawdza dowody, a nie każdą linię diffa.
- Od specyfikacji do testów. Każde wymaganie w
spec.mdma kryterium akceptacji. Zamień każde kryterium w test, który na razie nie przechodzi (czerwony), zanim zacznie się implementacja — zobacz wykonywalne kryteria akceptacji i programowanie sterowane testami. - Od planu do dowodu. Każde zadanie wskazuje swój test, a sekcja Proof — polecenia. CI je uruchamia; człowiek czyta wynik, nie kod.
- Od diffa do planu. Przegląd dryfu z kroku 5 wyłapuje pliki spoza planu i odhaczone zadania bez testów. Uruchamia go agent, a człowiek czyta tylko uwagi oznaczone jako Important.
- Od pull requesta do produkcji. Code owner akceptuje wyniki review i dowody testów; release manager odpowiada za bramkę produkcyjną. Zobacz review pull requestów od agentów.
- Kompletność łańcucha. Przed merge’em sprawdź, czy pull request linkuje
intent.md,spec.mdiplan.mdoraz czy każde zadanie wplan.mdjest odhaczone albo jawnie odłożone.
Osoby akceptujące się nie zmieniają — wskazuje je kolumna „Kto go akceptuje” w tabeli na początku strony. Agent może przygotować każdy artefakt i przejrzeć każdy diff, ale nie akceptuje własnej pracy.
Kiedy łańcuch artefaktów się sypie i jak z tego wyjść
Dział zatytułowany „Kiedy łańcuch artefaktów się sypie i jak z tego wyjść”Intencja jest zbyt mglista, żeby planować. Z „popraw powiadomienia” nie powstanie specyfikacja. Uruchom prompt z wywiadem, a wszystko, na co zgłaszający nie umie odpowiedzieć, wpisz w Open questions. Nie zaczynaj specyfikacji, dopóki product owner ich nie zamknie.
Plan jest za duży. Plan z 40 lub więcej zadaniami to kilka funkcji. Podziel go na kamienie milowe, z których każdy dostarcza coś widocznego dla użytkownika, i wdróż pierwszy, zanim zaplanujesz drugi.
Agent odpływa od planu w długiej sesji. Rozmowa z planowania wypada z okna kontekstu i agent zaczyna improwizować. Podawaj plik planu w każdym prompcie, czyść kontekst między zadaniami (/clear w Claude Code, /new w Codeksie, nowy czat w Cursorze) i wznawiaj pracę od plan.md, nie od czatu. Zobacz okna kontekstowe.
Kod i plan się rozjeżdżają. Ktoś naprawił błąd, którego plan nie przewidział, i nie zaktualizował plan.md. Następna sesja ufa wtedy nieaktualnemu planowi. Wpisz do REVIEW.md zasadę „aktualizuj plan.md w tym samym commicie”, a przegląd dryfu wyłapie przeoczenia.
Plan nigdy nie opuścił narzędzia. Zaakceptowany plan istnieje tylko jako szkic trybu planowania albo w czacie, więc agenci recenzujący i CI nie mogą go przeczytać. Zacommituj go jako plan.md, zanim ruszy pierwsze zadanie.
Dwa źródła prawdy sobie przeczą. Zgłoszenie w Jirze mówi jedno, a spec.md drugie. Sprawdź, który system twoja konfiguracja wskazuje jako wiążący, popraw drugi i zapisz SHA commita albo ID rekordu w obu.
Pomijasz łańcuch „tylko ten jeden raz”. Zmiana w jednym pliku może trafić prosto do zadania. Wszystko, co dotyka schematu, publicznego API albo więcej niż jednej warstwy, dostaje co najmniej spec.md i plan.md, bo właśnie tam wyłapuje się błędy w rodzaju kolidującej tabeli.
Lista kontrolna: czy łańcuch artefaktów działa w twoim repozytorium?
Dział zatytułowany „Lista kontrolna: czy łańcuch artefaktów działa w twoim repozytorium?”- Potrafisz wskazać jedno miejsce dla
intent.md,spec.mdiplan.md. - Każdy typ artefaktu ma jedno wskazane źródło prawdy.
- Nowa osoba w zespole znajdzie ostatni zaakceptowany
intent.mdoraz wyprowadzone z niegospec.mdiplan.md, nie pytając nikogo. - Każdy pull request zmergowany w ostatnim miesiącu linkuje swój
plan.md, a jego zadania są odhaczone albo odłożone.
Co dalej po wdrożeniu łańcucha artefaktów
Dział zatytułowany „Co dalej po wdrożeniu łańcucha artefaktów”Czy ten artykuł Ci pomógł?
Jedno kliknięcie, bez logowania.
Co z tym zrobisz?
Jak się czytało?
Co przeszkadzało? Możesz zaznaczyć kilka
Twoja rola?
Dzięki. Czytam każdą odpowiedź. Michał Jaskólski
Pomógł Ci ten artykuł?
Każde to jedno kliknięcie. Zamknij, kiedy chcesz.
bez logowania