Łańcuch artefaktów

Ł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

• 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?

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.

Gdzie trzymać pliki

Trzymaj jeden folder na funkcję w repozytorium produktu: intent/<feature>/intent.md, intent/<feature>/spec.md i intent/<feature>/plan.md. Z tego układu korzystają wszystkie prompty na tej stronie. Jeśli twój zespół trzyma już plany w docs/plans/, skieruj prompty tam, ale wybierz jeden układ. Osobne repozytorium intencji opłaca się dopiero wtedy, gdy jedna intencja obejmuje wiele repozytoriów.

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 Code

claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp

Potem uruchom w sesji /mcp, żeby się zalogować.

Codex

codex mcp add atlassian --url https://mcp.atlassian.com/v2/mcp

Cursor

Zainstaluj 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

Poniższe kroki prowadzą zgłoszenie o powiadomieniach z początku strony przez cały łańcuch. Każdy krok ma swój prompt.

1. Zapisz intencję. Gdy masz tylko jednolinijkowe zgłoszenie, każ agentowi przeprowadzić z tobą wywiad, zamiast pisać intencję samodzielnie. Zacommituj wynik jako intent/notifications/intent.md i daj go do akceptacji product ownerowi.

   Gotowy prompt: wywiad, który kończy się intencją

   I want to add in-app and email notifications when a teammate comments on a
   document. Interview me before writing anything. Ask one question at a time
   about users, triggers, delivery channels, opt-out, volume, edge cases, and
   constraints, and dig into the parts I have not thought about. When we have
   covered everything, write intent/notifications/intent.md with the sections
   Problem, Proposed outcome, Affected users and systems, Constraints, and Open
   questions. Put anything I could not answer under Open questions. Do not
   propose a design and do not write code.

   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).

2. Napisz specyfikację, a potem każ agentowi znaleźć w niej luki. Przygotuj spec.md wedł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.

   Gotowy prompt: zestaw specyfikację z bazą kodu

   Read intent/notifications/spec.md. Do not write or change any files.
   1. Restate each requirement in one sentence.
   2. List every ambiguity or gap, and the question that would close it.
   3. Find the existing code, tables, and API patterns this feature touches,
      with file paths.
   4. Flag every place where the spec conflicts with the current architecture,
      for example a new table where an existing one could be extended.
   5. List each requirement that has no testable acceptance criterion.

   Każdą lukę zamykaj w spec.md, nie w czacie. Decyzja, która istnieje tylko w rozmowie, znika razem z sesją.

3. 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ń.

   Gotowy prompt: szkic plan.md z zadaniami

   Using intent/notifications/spec.md and what you found in the codebase, write
   intent/notifications/plan.md with these sections:
   - Files that change, with the existing file you use as the pattern for each.
   - Decisions: every choice with a real trade-off, the options, and your pick.
   - Tasks: an ordered checklist (- [ ]). Each task fits one focused session,
     names its files, states its acceptance check, and is followed by the test
     that proves it. Order by dependency: migration, then API, then UI.
   - Risks.
   - Proof: the exact commands that show the whole change works.
   Prefer dependencies already in package.json. Do not implement anything.

   Kwestionuj plan tak, jak zrobiłbyś to na design review. Na przykład: „Plan dodaje tabelę notifications. Jakie są kompromisy względem rozszerzenia events i które rozwiązanie pasuje do naszych istniejących wzorców?”. Potem tech lead albo inżynier akceptuje plan.md i go commituje.

4. 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ę.

   Gotowy prompt: wykonaj następne zadanie

   Read intent/notifications/plan.md. Implement only the first unchecked task.
   Then run the test named in that task and the lint and type checks. If they
   pass, tick the task in plan.md and commit the code and plan.md together with
   a message that names the task. If the implementation has to depart from the
   plan, stop and tell me what and why instead of improvising. Stop after this
   one task.

5. 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.md w katalogu głównym repozytorium (szablon niżej); czyta go zarządzany Code Review w Claude Code (research preview, plany Team i Enterprise). Lokalny /code-review go 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.

   Gotowy prompt: przegląd dryfu względem specyfikacji i planu

   Compare the diff on this branch with main against intent/notifications/spec.md
   and intent/notifications/plan.md. Do not change code. Report:
   1. Files changed that plan.md does not list.
   2. Tasks ticked in plan.md without a test that exercises them.
   3. Spec requirements with no test, or with a test that cannot fail.
   4. Behaviour in the diff that the spec does not ask for.
   Tag each finding Important or Nit, and quote the spec line it relates to.

6. 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?

Ł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ę.

Claude Code

• Tryb planowania włączysz przez Shift+Tab, /plan albo claude --permission-mode plan. Od v2.1.283 (kanał latest) sesje interaktywne w terminalu i VS Code startują w trybie auto, więc na tryb planowania przełącz się świadomie; claude -p, Agent SDK, 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 pozostaje plan.md.
• claude -w notifications uruchamia pracę w nowym worktree Gita, a claude -c kontynuuje ostatnią rozmowę.

Codex

• Tryb planowania włączysz przez /plan w CLI.
• Narzędzie planowania update_plan jest od v0.152.0 domyślnie wyłączone, więc Codex nie prowadzi żywej listy kontrolnej, dopóki nie ustawisz tools.update_plan.enabled = true. Trzymaj zadania w plan.md, gdzie przetrwają każdą sesję.
• codex --worktree uruchamia sesję w nowym, zarządzanym worktree Gita (v0.157.1), a codex resume --last wznawia ostatnią sesję.
• Żeby wykonywać zadania pojedynczo bez czatu, przekaż prompt „wykonaj następne zadanie” do codex exec.

Cursor

• 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

Skopiuj te struktury do repozytorium i zastąp symbole zastępcze zapisane UPPER_SNAKE_CASE.

Szablon: intent.md

# Intent: INTENT_TITLE
Author: AUTHOR_NAME (TEAM). Status: draft | accepted. Ticket: TICKET_ID

## Problem
WHAT_IS_BROKEN_OR_MISSING

## Proposed outcome
WHAT_BETTER_LOOKS_LIKE

## Affected users and systems
USERS_AND_SYSTEMS

## Constraints
CONSTRAINTS

## Open questions
OPEN_QUESTIONS

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 design
DESIGN_DETAILS

## Out of scope
OUT_OF_SCOPE

## Skills and policies applied
- Security: POLICIES_APPLIED
- Brand and UX: GUIDELINES_APPLIED

## Flagged concerns
CONCERNS_FOR_POLICY_OWNERS

Szablon: plan.md

# Plan: PLAN_TITLE (from spec.md, accepted DATE)

## Files that change
FILE_LIST_WITH_REFERENCE_PATTERNS

## Decisions
DECISION: OPTIONS, CHOICE, REASON

## Tasks
- [ ] 1. TASK (files: FILES). Accepted when: CHECK. Test: TEST_COMMAND
- [ ] 2. TASK (files: FILES). Accepted when: CHECK. Test: TEST_COMMAND

## Risks
RISKS

## Proof
COMMANDS_THAT_SHOW_THE_CHANGE_WORKS

Gdy implementacja odchodzi od planu, aktualizuj plan.md w tym samym commicie co kod.

Szablon: REVIEW.md

# Review instructions

## Passes
Run 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)

## Exclusions
Exclude 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?

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ą.

Gotowy prompt: audyt bazy kodu zamieniony w plany

Audit this codebase for the highest-impact improvements: correctness bugs,
performance, security, missing tests, and tech debt. Do not fix anything. For
each finding, write a self-contained plan to docs/improvement-plans/NN-slug.md
with the files to change, the approach, the acceptance criteria, and the test
that proves it. Order the files by impact against effort. A separate session
will execute each plan without access to this conversation, so leave nothing
implicit.

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.md ma 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.md i plan.md oraz czy każde zadanie w plan.md jest 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ść

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?

• Potrafisz wskazać jedno miejsce dla intent.md, spec.md i plan.md.
• Każdy typ artefaktu ma jedno wskazane źródło prawdy.
• Nowa osoba w zespole znajdzie ostatni zaakceptowany intent.md oraz wyprowadzone z niego spec.md i plan.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

Plan: zapisz intent.md Pierwsze ogniwo łańcucha krok po kroku.

Wykonywalne kryteria akceptacji Zamień każde wymaganie ze spec.md w test, który najpierw nie przechodzi.

Człowiek w pętli Kiedy interweniować w trakcie wykonania, a kiedy pozwolić agentowi działać.

AI-native cykl życia oprogramowania Sześć etapów, które łączy łańcuch.