Łańcuch artefaktów

Łańcuch artefaktów zmienia pomysł w sześć kontrolowanych przekazań: intent.md, spec.md, plan.md, diff z dowodami testów, wyniki review oraz incydent lub kolejną intencję. Jedno nazwane źródło prawdy utrzymuje ludzi i agentów na tym samym zaakceptowanym stanie oraz zachowuje audytowalną historię.

Łańcuch

Każdy etap kończy się zapisaniem jednego artefaktu do kontroli wersji. Następny etap zaczyna się od jego odczytania.

Etap	Artefakt	Kto go akceptuje
Plan	`intent.md`	Product owner
Design	`spec.md`	Product owner, z tech leadem przy pracy wyższego ryzyka
Build	`plan.md`, potem diff i jego testy	Inżynier (rutyna); tech lead lub architekt (wyższe ryzyko)
Test	Output testów, log builda lub screenshot diff dołączony do sesji lub PR	Code owner recenzujący PR
Deploy	Pull request z findings z review	Code owner; release manager na bramce produkcji
Maintain	Rekord incydentu, potem nowy `intent.md`	Service owner lub on-call, potem product owner dla findings produktowych

Na wczesnych etapach markdown jest dominującym artefaktem, bo product owner i agent mogą oboje czytać i działać na tym samym pliku. Od builda wzwyż artefaktem jest kod i jego rekordy.

Nazwij jedno źródło prawdy

Istniejące procesy SDLC już śledzą artefakty, tylko nie jako pliki markdown. Work itemy mogą żyć w Jira, wymagania w narzędziu z regulatoryjną traceability, designy w Figmie, a akceptacje zmian w change boardzie. Te systemy trudno wyprzeć, bo auditorzy już je akceptują.

Dla każdego artefaktu, który proces produkuje, nazwij jeden system jako źródło prawdy. Wszystko inne trzyma kopię lub link.

Poniższe konfiguracje działają. Wybierz jedną per artefakt:

Repo jako źródło prawdy. Pliki markdown są autorytatywnym rekordem. Legacy system odwołuje się do plików w commitach. To najczystszy setup dla organizacji prowadzonych przez engineering: jedno narzędzie, jeden autorytet timestampów.

Legacy system jako źródło prawdy. Jira, ServiceNow lub narzędzie wymagań trzyma autorytatywny rekord. Pliki markdown są kopiami roboczymi. Agent czyta rekord na starcie sesji i zapisuje wynik z powrotem przez konektor MCP w tej samej sesji, która wyprodukowała spec lub plan.

Linkage jako minimum. Każdy plik markdown notuje ID rekordu. Każdy legacy rekord zawiera commit SHA pliku markdown. Zacznij tutaj, gdy jeszcze nie możesz wybrać jednego źródła prawdy.

Szablony

Użyj poniższych kształtów. Zastąp placeholdery wartościami dla swojej zmiany.

Szablon: intent.md

# Intent: INTENT_TITLE
Author: AUTHOR_NAME (TEAM). Status: draft.

## 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 DATE)
Status: ready-for-plan

## Wymagania
REQUIREMENTS_LIST

## Architektura i projekt
DESIGN_DETAILS

## Zastosowane polityki i skills
- Security: POLICIES_APPLIED
- Brand i UX: GUIDELINES_APPLIED

## Zgłoszone wątpliwości (Flagged Concerns)
CONCERNS_FOR_POLICY_OWNERS

Szablon: plan.md

# Plan: PLAN_TITLE (from spec.md DATE)

## Files that change
FILE_LIST

## Order of work
1. FIRST_STEP
2. SECOND_STEP

## Risks
RISKS

## Proof
HOW_YOU_WILL_KNOW_IT_WORKED

Szablon: REVIEW.md

# Instrukcje recenzji (Review instructions)

## Przejścia (Passes)
Uruchom trzy osobne przejścia i oznacz każde znalezisko kategorią:
- Błędy (Bugs): błędy logiki, nieobsłużone edge cases, subtelne regresje
- Bezpieczeństwo (Security): podatności na injection, luki autoryzacji, PII w logach
- Zgodność (Compliance): dopasowanie do spec.md, plan.md i standardów projektu

## Kryteria ważności (Severity criteria)
- Ważne (Important): zepsute działanie, wyciek danych, luka bezpieczeństwa, złamanie polityki
- Drobiazg (Nit): formatowanie, nazewnictwo, kosmetyka (maksymalnie 5 nits łącznie)

## Wykluczenia
Pomiń kod generowany w src/gen/, dist/ oraz rzeczy sprawdzane automatycznie przez CI.

Gdy implementacja odbiega od planu, zaktualizuj plan.md w tym samym commicie.

Praktyki zapisu artefaktów per harness

Przechowuj artefakty w miejscach dostępnych dla wszystkich narzędzi:

Cursor: Cursor Plan mode domyślnie zapisuje szkice w .cursor/plans/. Skopiuj lub zapisz ostateczny zatwierdzony plan jako plan.md w głównym katalogu repozytorium lub w docs/plans/, aby zewnętrzne narzędzia, CI i reviewerzy mieli do niego dostęp.
Codex: Użyj /plan w CLI i zapisz zaakceptowany wynik jako plan.md. Do izolacji użyj worktree aplikacji Codex lub zwykłego git worktree add; CLI nie ma flagi --worktree.
Claude Code: Użyj Shift+Tab albo uruchom claude --permission-mode plan, zapisz wynik jako plan.md, a osobny checkout utwórz przez claude -w BRANCH_NAME.

Verify

Potwierdź wszystkie poniższe:

Potrafisz wskazać jeden dom dla intent.md (folder w repo produktu lub dedykowane repo).
Każdy typ artefaktu ma nazwane źródło prawdy.
Nowy contributor znajduje ostatni zaakceptowany intent.md oraz spec.md / plan.md z niego wyprowadzone bez pytania na Slacku.

Wprowadź łańcuch do pracy

Zapisz pierwszy pomysł jako intent.md — zobacz Plan.
Zmapuj te same pliki na Cursor, Claude Code i Codex — zobacz mapę narzędzi.