Od modeli C4 i ADR-ów po kontrakty API
i changelog przyjazne ludziom i AI
Każdy projekt ma dokumentację.
Prawie nikt jej nie czyta.
Prawie nikt jej nie aktualizuje.
I wszyscy wiedzą dlaczego.
Kiedyś pisaliśmy dokumentację dla ludzi. Teraz piszemy ją też dla maszyn — agentów AI, których kontekstem jest właśnie nasza dokumentacja.
"Dokumentacja jest aktualna..."
(na dzień publikacji)
# docs/architecture/ADR-001.md **Status:** Accepted | **Date:** 2026-01-15 **Context:** We need persistence layer... **Decision:** PostgreSQL + Redis cache **Consequences:** +reliability, +tooling
Piszesz kod kierując się "wyczuciem" — iterujesz z AI bez planu, bez specyfikacji, bez testów. Prompt zastępuje myślenie.
Zanim napiszesz pierwszą linię kodu — masz gotową specyfikację. Kod jest implementacją specyfikacji, nie odwrotnie.
Dokument opisujący CO system ma robić i DLACZEGO — nie jak. Kontrakt między biznesem, produktem i zespołem inżynierskim, zanim powstanie pierwsza linia kodu.
Jeden dokument — jedno rozumienie. Eliminuje „ale myślałem, że..." na etapie demo.
Agent AI z pełnym PRD w kontekście generuje precyzyjny kod, nie zgaduje intencji.
Acceptance Criteria z PRD = gotowe przypadki testowe. Zero domysłów co „przechodzi".
# PRD: Sklep Online — Moduł Płatności ## Problem Statement Użytkownicy porzucają koszyk przy płatności z powodu braku popularnych metod (BLIK, PayPal). ## Business Objective Zmniejszyć porzucanie koszyka o 25% w Q3. KPI: conversion rate > 4.5%. ## Personas - **Klient detaliczny** — kupuje, oczekuje wygody - **Administrator** — konfiguruje metody płatności ## Features | Feature | Priorytet | Notes | |----------------|-----------|-----------------| | BLIK | MUST | PL-only | | PayPal | MUST | INT | | Apple Pay | SHOULD | iOS 16+ | | Krypto | WON'T | Out of scope | ## Non-Functional Requirements - Czas transakcji: < 3s (p95) - Bezpieczeństwo: PCI DSS Level 1 - Dostępność: 99.9% uptime ## Out of Scope - Waluta wielowalutowa (faza 2) - Subskrypcje (osobny PRD) ## Acceptance Criteria - [ ] Użytkownik płaci BLIKiem w < 3s - [ ] Nieudana płatność → czytelny komunikat - [ ] Admin włącza/wyłącza metodę bez deployu
System w otoczeniu — aktorzy i zewnętrzne zależności
👤 Klient, Admin
🏪 Sklep Online
🔌 PayU, SendGrid
Aplikacje, serwisy, bazy wewnątrz systemu
🌐 React SPA
⚙️ API Node.js
🗄 PostgreSQL, Redis
Moduły i serwisy wewnątrz kontenera
📦 OrderService
💳 PaymentService
🔔 NotificationSvc
Klasy, interfejsy, metody, zależności
🔷 IOrderRepository
🔶 OrderService
⚡ createOrder()
@startuml !include C4_Context.puml Person(klient, "Klient", "Składa zamówienia") Person_Ext(admin, "Admin", "Zarządza katalogiem") System(sklep, "Sklep Online", "Platforma e-commerce") System_Ext(platnosci, "PayU", "Bramka płatności") System_Ext(email, "SendGrid", "Powiadomienia email") Rel(klient, sklep, "Przeglądanie", "HTTPS") Rel(admin, sklep, "Zarządzanie", "HTTPS") Rel(sklep, platnosci, "Płatności", "REST API") Rel(sklep, email, "Potwierdzenia", "SMTP") @enduml
C4Context
title Sklep Online — C1 Context
Person(
klient, "Klient",
"Składa zamówienia")
Person_Ext(
admin, "Admin",
"Zarządza katalogiem")
System(
sklep, "Sklep Online",
"Platforma e-commerce")
System_Ext(
platnosci, "PayU",
"Bramka płatności")
System_Ext(
email, "SendGrid",
"Powiadomienia email")
Rel(klient, sklep, "HTTPS")
Rel(admin, sklep, "HTTPS")
Rel(sklep, platnosci,
"REST API")
Rel(sklep, email, "SMTP")
① Rendering
PlantUML — wymaga serwera Java lub pluginu
Mermaid — renderuje w przeglądarce; natywny w GitHub, GitLab, Notion
② Wsparcie C4
PlantUML — pełna biblioteka C4 (L1–L4, Deployment)
Mermaid — tylko C4Context / C4Container (brak L3, L4)
✏️ Excalidraw — wolny format jako kod
Whiteboard zapisany jako JSON w repozytorium.
Idealny do eksploracji pomysłów, szkiców architektury i wstępnych koncepcji — zanim powstanie formalna specyfikacja.
{
"type": "excalidraw",
"version": 2,
"elements": [
{
"type": "rectangle",
"id": "sklep-online",
"x": 100, "y": 80,
"width": 200, "height": 80,
"label": { "text": "Sklep Online" }
},
{
"type": "arrow",
"id": "rel-1",
"startBinding": { "elementId": "klient" },
"endBinding": { "elementId": "sklep-online" }
}
],
"appState": { "theme": "dark" }
}
❌ Miro / Mural — vendor lock-in, dane w chmurze dostawcy, brak wersjonowania w git
Canvas / Board jako kod (Excalidraw)
Wolny format — brak ograniczeń notacji, dowolne kształty i połączenia
JSON w repo — wersjonowany, diff w git, review w PR
AI-readable — LLM rozumie strukturę JSON, może generować i modyfikować
Offline, open-source — brak vendor lock-in, działa bez internetu
Eksploracja przed specyfikacją — szkic koncepcji zanim powstanie PRD
Diagramy jako kod (Mermaid / PlantUML)
Precyzyjny DSL — deterministyczny wynik, formalne notacje (UML, C4, sekwencje)
CI/CD integration — automatyczna walidacja i generowanie diagramów w pipeline
Czytelny diff — zmiany w architekturze widoczne jako diff tekstowy w PR
AI generuje i weryfikuje — LLM pisze Mermaid z opisu, sprawdza spójność z kodem
Natywny w GitHub/GitLab — Mermaid renderuje się w Markdown bez żadnych pluginów
Jeden plik Markdown = jedna decyzja architektoniczna.
Wersjonowany w git, review'owany w PR, czytany przez AI.
Tytuł
Krótki, jednoznaczny opis decyzji
Status
Kontekst
Dlaczego stoimy przed tą decyzją?
Decyzja
Co zdecydowaliśmy i dlaczego?
Konsekwencje
Co zyskujemy? Co tracimy?
# ADR-001: Wybór bazy danych **Status:** Accepted **Date:** 2026-01-15 **Deciders:** @backend-team ## Kontekst Potrzebujemy bazy danych dla modułu zamówień. Wymagania: ACID, 10k TPS, relacje między tabelami. ## Decyzja Wybieramy **PostgreSQL 16** jako główną bazę. Redis jako cache dla sesji i koszyka. ## Konsekwencje ✅ Silne gwarancje ACID ✅ Bogaty ekosystem narzędzi ⚠️ Wymaga doświadczenia z SQL ❌ Brak wbudowanego shardingu
Historia decyzji w git — kto, kiedy i dlaczego podjął decyzję
Onboarding — nowy developer rozumie architekturę bez "pytaj starszych"
Paliwo dla AI — LLM zna kontekst decyzji, nie tylko jej wynik
Kontrakt API to umowa — między frontendem a backendem, między mikroserwisami, między Twoim kodem a AI.
OpenAPI / Swagger — REST API — standard branżowy, tooling bogaty
AsyncAPI — Eventy i messaggi — Kafka, RabbitMQ, WebSocket
RAML — Alternatywa dla OpenAPI — mniej popularna
MCP — Model Context Protocol — Kontrakt komunikacji z agentami AI — nowy standard
🤖 MCP = AI kontrakty
Model Context Protocol — nowy sposób definiowania co AI agent może zrobić, jakie ma narzędzia i zasoby.
openapi: "3.1.0"
info:
title: Orders API
version: 2.4.1
paths:
/orders:
post:
summary: Create order
# MUST validate payment
Definiuje format pliku CHANGELOG.md i
konwencję sekcji — jeden spójny standard dla całego projektu.
# dodaj wpis do [Unreleased] changelog add \ --type added \ "Eksport zamówień do CSV" # promuj [Unreleased] → wersja changelog release 2.4.1
Co stoi na przeszkodzie, żeby rozszerzać changelog przy każdym pull-requeście?
Wersja to kontrakt z użytkownikiem. Bez SemVer changelog traci połowę sensu. semver.org
sklep-online/
│
├── AGENTS.md ← instrukcje dla agentów AI
├── CHANGELOG.md ← keep-a-changelog + SemVer
├── README.md ← opis projektu i setup
├── LLMs.txt ← kontekst dla modeli AI
│
├── docs/
│ ├── prd/
│ │ └── PRD-001-modul-platnosci.md
│ │
│ ├── adr/
│ │ ├── ADR-001-baza-danych.md
│ │ ├── ADR-002-cache-redis.md
│ │ └── ADR-003-api-rest-vs-grpc.md
│ │
│ ├── arc42/
│ │ └── architecture.md
│ │
│ ├── c4/
│ │ ├── context.puml ← L1 Context
│ │ ├── containers.puml ← L2 Container
│ │ └── components.puml ← L3 Component
│ │
│ └── api/
│ └── openapi.yaml ← API-first contract
│
├── brainstorm/
│ ├── modul-platnosci.excalidraw
│ └── onboarding-flow.excalidraw
│
└── src/
└── ...
🤖 Dla AI
AGENTS.md— role, umiejętności i instrukcje dla agentówLLMs.txt— skrócony kontekst projektu ładowany do każdego promptu📋 Wymagania
docs/prd/PRD-*.md— problem, cele, features, kryteria akceptacji🏗 Architektura
docs/adr/ADR-*.md— decyzje architektoniczne z kontekstem i konsekwencjamidocs/arc42/— całościowy opis architektury systemudocs/c4/*.puml— diagramy C4 jako kod (L1–L3)🔌 API & Release
docs/api/openapi.yaml— kontrakt API-first, źródło prawdyCHANGELOG.md— keep-a-changelog, wersjonowanie SemVerREADME.md— setup, opis, linki do dokumentacji✏️ Eksploracja
brainstorm/*.excalidraw— canvas jako kod, wersjonowany w gitBrak dokumentacji dla zmienionych plików
src/orders/ — brak wpisu w README i CHANGELOG. Zaktualizuj dokumentację lub dodaj uzasadnienie w opisie PR.
CHANGELOG.md nie zawiera wpisu dla tego PR
Wykryto zmiany w src/ bez sekcji [Unreleased]. Dodaj wpis przed mergem.
Konflikt z ADR-023: Warstwa persystencji
Zmiany w OrderRepository są niezgodne z decyzją. Zweryfikuj kod lub napisz aktualizację ADR-023.
Ładowane do KAŻDEGO promptu. Każdy token kosztuje — czas, pieniądze i uwagę modelu.
Koszt × liczba wywołań dziennie
Szybkość
Krótsze prompty = szybsze odpowiedzi = szybszy feedback loop
Dokładność
Mniej szumu = model skupia się na tym co ważne
⚠️ AI parsuje sekwencyjnie. Ważna informacja na końcu = zmarnowany budżet tokenów i słabszy wynik.
✅ Zasada: najważniejsze informacje zawsze na początku dokumentu.
Standard z 1997, używany w HTTP, TLS, OAuth. Eliminuje niejednoznaczność w specyfikacjach technicznych.
📚 Dużo przykładów kodu = najlepsza dokumentacja dla LLM. Kod jest jednoznaczny — ludzki język nie jest.
⚠️ Niejednoznaczność = halucynacja. LLM wypełnia luki "kreatywnie".
It is recommended to use PostgreSQL when possible. Redis can be used for caching if performance is needed. Consider the team's expertise.
Service MUST use PostgreSQL 16 for all persistent storage. Service MAY use Redis 7 for session cache. Service MUST NOT use MySQL or SQLite.
Handle errors appropriately and log important information for debugging.
Service MUST return HTTP 422 for
validation errors with body:
{"error":"...", "field":"..."}
Service MUST log all 5xx errors to
stdout in JSON format.
📚 RAG
Retrieval Augmented Generation
Duże bazy dokumentacji + semantic search. AI "szuka" odpowiedzi zanim odpowie.
✅ Działa dla dużych baz wiedzy
⚠️ Wymaga wektorowej bazy danych
❌ "Nie wiem czego nie wiem" problem
🔌 MCP
Model Context Protocol
Nowy sposób dostarczania kontekstu do AI. Zamiast wklejać do prompta — serwer MCP dostarcza dynamicznie.
✅ Strukturyzowany kontekst
✅ Dynamiczne aktualizacje
⚠️ Nowy ekosystem (2024+)
⚠️ Problem
"Nie wiem czego nie wiem"
LLM może nie wiedzieć jakich informacji szukać. Semantic search wymaga dobrego zapytania. Garbage in = garbage out.
RAG i MCP to narzędzia, nie rozwiązania. Dobra dokumentacja u źródła jest niezbędna.
Dokumentacja nie jest ostatnim krokiem. Jest pierwszym. Specyfikacja definiuje co budujesz — zanim to zbudujesz.
💡 Zasada: jeśli nie potrafisz opisać w 3 zdaniach co robi system — nie jesteś gotowy żeby go budować.
README.md — Cel projektu, jak uruchomić lokalnie, jak kontrybuować
docs/adr/ADR-001.md — Pierwsza decyzja architektoniczna — "dlaczego ten stack?"
openapi.yaml / asyncapi.yaml — Kontrakt API — zanim napiszesz pierwszą linię kodu
AGENTS.md — Kontekst dla AI asystentów — co mogą, czego nie mogą
⏱️ Czas: ~2 godziny. Oszczędność: tygodnie nieporozumień.
Masz istniejący projekt bez dokumentacji. AI może pomóc — ale z ważnymi ograniczeniami.
⚠️ AI nie zna historii decyzji.
ADR-y musisz napisać sam — lub odtworzyć z git log i rozmów z zespołem.
AI wygeneruje opis CZEGO kod robi.
Nigdy nie powie DLACZEGO tak jest.
🤖 Zdefiniuj agentów i skills
Co AI ma robić w tym projekcie? AGENTS.md jako punkt startowy — definiuje granice autonomii AI w legacy kodzie.
📄 Generuj pierwszy draft z AI
Użyj AI do wygenerowania pierwszej wersji README, diagramów C4, opisu API. To punkt startowy — nie finalny dokument.
🔄 Iteruj: AI generuje, człowiek weryfikuje
Każdy sprint: AI propozycja → code review dokumentacji → merge. Dokumentacja rośnie wraz z zrozumieniem systemu.
Everything as Code — w narzędziach AI-native
Dokumentacja w repo — wersjonowana, reviewowana, automatycznie walidowana. Mermaid, ADR, OpenAPI, CHANGELOG — to nie pliki, to artefakty projektowe. Narzędzia AI-native (Cursor, GitHub Copilot, Claude) rozumieją to jako kontekst, nie jako tekst.
Spec-Driven Development — najpierw specyfikacja
PRD, model C4, ADR, kontrakt API — zanim napiszesz pierwszy wiersz kodu. Specyfikacja to nie biurokracja — to projekt systemu, który AI może czytać, weryfikować i z którego generować kod.
AI nie tylko do kodowania — przez cały SDLC
Requirements → Design → Development → Testing → Release → Maintenance. AI może wspierać każdą fazę — pod warunkiem, że dokumentacja jest precyzyjna, zwięzła i w repozytorium. Dobra dokumentacja to paliwo dla AI w całym cyklu życia systemu.