Rejestrowanie intencji — tworzenie intent.md przed budowaniem

Rejestrowanie intencji (intent capture) to praktyka zapisywania problemu biznesowego i jego ograniczeń słowami inicjatora, zanim powstanie jakakolwiek architektura, plan techniczny lub kod aplikacji. Przechowywanie tego zapisu jako wersjonowanego w gicie pliku intent.md tworzy trwałą ścieżkę audytu i daje agentom AI niezbędny kontekst, aby nie rozwiązywali niewłaściwego problemu.

Pytanie w scorecardzie: W jaki sposób rejestrujesz problem biznesowy przed napisaniem jakiegokolwiek kodu lub planu (intent.md)? Maksymalna odpowiedź (3 pkt): Standaryzowany szablon intent.md w repozytorium; product owner przegląda i commituje przed Etapem 2 (Design).

Dlaczego to ważne w 2026

Gdy programiści pomijają rejestrowanie intencji, narzędzia kodowania AI natychmiast generują kod dla błędnych założeń. Tradycyjne zbieranie wymagań zajmuje tygodnie spotkań komitetów i przekazywania ticketów, tracąc niuanse na każdym kroku. W natywnym dla AI SDLC inicjator przeprowadza burzę mózgów z asystentem AI w języku naturalnym, tworząc ustrukturyzowaną proto-specyfikację intent.md w kilka godzin zamiast tygodni.

Zacommitowany plik intent.md stanowi pojedyncze źródło prawdy (single source of truth) dla product ownerów, inżynierów i agentów AI. Odpowiada na pytania: co jest potrzebne, dlaczego ma to znaczenie, kogo dotyczy i jakie ograniczenia obowiązują — zanim plan implementacji zużyje okno kontekstu lub wywoła niepotrzebne zmiany w kodzie.

Jak wygląda maksymalny wynik

Konfiguracja z maksymalnym wynikiem w Q4 spełnia cztery konkretne warunki:

1. Standardowy szablon: Repozytorium zawiera uzgodniony szablon w katalogu intent/ (lub w katalogu głównym) ze strukturą sekcji: Problem, Oczekiwany rezultat, Dotknięci użytkownicy i systemy, Ograniczenia oraz Otwarte pytania.
2. Wywiad wspomagany przez AI: Inicjator używa Claude Code, Cursora lub Codexa, aby przeprowadzić wywiad o wymaganiach, wyłonić przypadki brzegowe i zredagować plik.
3. Zatwierdzenie przez product ownera: Product owner przegląda, dopracowuje i commituje intent.md przed rozpoczęciem Etapu 2 (Design).
4. Niezależne od narzędzia przechowywanie: Plik markdown znajduje się w gicie, co zapewnia dostęp każdemu środowisku agenta bez kopiowania danych z portali webowych.

Wdrożenie krok po kroku

1. Dodaj szablon intencji do repozytorium.

   Utwórz plik intent/TEMPLATE.md w katalogu głównym repozytorium:

   # Intent: TYTUL_INTENCJI
   Autor: AUTOR (ZESPOL). Status: draft.
   
   ## Problem
   CO_JEST_ZEPSUTE_LUB_CZEGO_BRAKUJE
   
   ## Oczekiwany rezultat
   JAK_WYGLADA_POPRAWNY_STAN
   
   ## Dotknięci użytkownicy i systemy
   UZYTKOWNICY_I_SYSTEMY
   
   ## Ograniczenia
   OGRANICZENIA
   
   ## Otwarte pytania
   OTWARTE_PYTANIA

2. Przeprowadź wywiad wyjaśniający wymagania.

   Poinstruuj agenta, aby przeprowadził wywiad bez generowania kodu ani projektów technicznych:

   Claude Code

   Mam pomysł na funkcję NAZWA_FUNKCJI. Przeprowadź ze mną wywiad o problemie biznesowym,
   kogo dotyczy, jak wygląda sukces i jakie ograniczenia obowiązują.
   Po dyskusji zapisz plik intent/NAZWA_SLUG.md na bazie szablonu intent/TEMPLATE.md.
   Nie pisz żadnego kodu ani planów implementacji.

   Cursor

   Przełącz się w tryb Ask (aby nie dotykać plików kodu źródłowego) i uruchom:

   Przeprowadź ze mną wywiad dotyczący tej prośby o funkcję. Zadawaj pytania wyjaśniające
   jedno po drugim na temat użytkowników, ograniczeń opóźnień oraz elementów poza zakresem.
   Następnie wygeneruj intent/NAZWA_SLUG.md zgodnie z naszym szablonem.

   Codex

   Użyj komendy /plan w Codex CLI:

   /plan Zarejestruj to wymaganie jako intent/NAZWA_SLUG.md. Najpierw przeprowadź ze mną wywiad.
   Nie modyfikuj żadnego kodu aplikacji.

3. Przejrzyj i dopracuj przygotowany szkic intencji.

   Zweryfikuj, czy agent poprawnie uchwycił Twoją intencję i odpowiedział na otwarte pytania. Wyjaśnij wszelkie błędnie zinterpretowane ograniczenia.

4. Zacommituj zatwierdzony artefakt.

   Dodaj plik intent/NAZWA_SLUG.md do repozytorium:

   git add intent/NAZWA_SLUG.md
   git commit -m "docs(intent): rejestracja problemu biznesowego dla NAZWA_SLUG"

5. Przekaż do product ownera w celu formalnego zatwierdzenia.

   Product owner zatwierdza plik na gałęzi lub pull requeście. Po akceptacji praca przechodzi do Etapu 2: Design (spec.md).

Częste pułapki

• Natychmiastowe przejście do kodowania: Pomijanie intent.md, ponieważ funkcja wydaje się mała. Małe funkcje bez zdefiniowanych ograniczeń prowadzą do kosztownych poprawek, gdy pojawiają się przypadki brzegowe.
• Pisanie wymagań przez programistów w izolacji: Inicjator (product manager, użytkownik biznesowy, inżynier wsparcia) musi brać udział w wywiadzie, aby zachować niuanse domenowe.
• Przechowywanie intencji wyłącznie w portalach webowych: Notatki w zamkniętych dashboardach lub na Slacku odcinają agenta od pierwotnego kontekstu. Przechowuj plik markdown w repozytorium git.

Jak sprawdzić, czy już tam jesteś

• Katalog intent/ istnieje w Twoim repozytorium z ustalonym szablonem.
• Każdy nietrywialny pull request odnosi się do zaakceptowanego pliku intent.md lub z niego wynika.
• Czas od pierwszej rozmowy do zacommitowania intent.md zajmuje godziny, a nie tygodnie.
• Product owner zatwierdza intent.md przed rozpoczęciem jakiejkolwiek implementacji inżynierskiej.

Dodatkowe materiały

Etap Plan w natywnym dla AI SDLC Kompletny przewodnik po rejestrowaniu intencji jako proto-specyfikacji w cyklu wytwarzania.

Łańcuch artefaktów Dowiedz się, jak intent.md przechodzi w spec.md, plan.md i REVIEW.md.

Wypełnij Developer Scorecard Oceń swój setup inżynierski we wszystkich 25 pytaniach.