urzadzeniamatter.pl // Stochastic AI

Rola: koncepcja produktu, model danych, architektura, wdrożenie, redakcja. Realizacja jednoosobowa, wspierana agentem AI prowadzonym pod ścisłą kontrolą. Stack: Python (generator statyczny), JavaScript (Cloudflare Worker), YAML jako baza, Cloudflare Workers Static Assets.

Problem

Standard Matter miał ujednolicić smart home. W praktyce przeniósł problem gdzie indziej. Kupujący widzi na pudełku logo Matter i nadal nie wie trzech rzeczy, które przesądzają o tym, czy sprzęt zadziała u niego w domu:

Czy urządzenie potrzebuje huba producenta. Sprzęt reklamowany jako „Matter” bywa bezużyteczny bez centralki za kilkaset złotych. Tej informacji nie ma ani w opisie sklepowym, ani w rejestrze certyfikacji.
Co realnie działa w danym ekosystemie. Apple Home, Google Home, Alexa, SmartThings i Home Assistant obsługują to samo urządzenie w różnym zakresie. Producent podaje listę logotypów, nie listę funkcji.
Czy to się zmieści. Moduł przekaźnika w puszce fi 60, gniazdko zasłaniające sąsiednie w podwójnej ramce, wtyczka schuko bez uziemienia w polskim gnieździe z bolcem. Karta katalogowa milczy, bo producent projektował dla całej Europy.

Rynek polski nie miał żadnego serwisu, który odpowiada na te pytania. Anglojęzyczne katalogi odpowiadają na pierwsze dwa połowicznie i nie znają polskiej dystrybucji ani polskiej instalacji elektrycznej.

Rozstrzygnięcie: dane, nie treść

Pierwszy pomiar rozstrzygnął kierunek całego projektu. Sprawdziłem, czy da się zbudować katalog z oficjalnego rejestru certyfikacji CSA (Distributed Compliance Ledger). Wynik: 58% rekordów ma nazwy nierozróżnialne w rodzaju „WiFi Smart Plug”. Rejestr nie może być kręgosłupem katalogu, bo nie odróżnia produktów, które kupujący widzi na półce jako różne.

Drugi pomiar uratował pipeline handlowy. Dopasowanie ofert sklepowych do rekordów po nazwie zawodzi z tego samego powodu, ale partNumber producenta ratuje 56% rekordów o bezużytecznej nazwie. Stąd łańcuch kluczy dopasowania: EAN, potem partNumber, dopiero na końcu producent plus model.

Wniosek strategiczny: przewagą nie jest liczba rekordów, tylko macierz zgodności ekosystemów i warstwa polska, czyli dokładnie te pola, których nie da się pobrać z żadnego feedu. To praca kuratorska, a nie import.

Architektura

Świadoma decyzja o minimalizmie. Projekt ma jedną zależność produkcyjną (wrangler). Nie ma CMS-a, nie ma bazy danych, nie ma frameworku frontendowego.

Warstwa	Rozwiązanie	Powód
Źródło prawdy	pliki YAML w repozytorium, jeden na urządzenie	Zmiana danych jest commitem: ma autora, datę i możliwość cofnięcia. Baza tego nie daje bez dodatkowej pracy
Generator	3100 linii Pythona, scalanie i renderowanie stron	Deterministyczny build, zero kodu wykonywanego u czytelnika poza filtrami tabeli
Runtime	Cloudflare Worker (350 linii)	Przekierowania afiliacyjne `/go/`, obsługa 301 po zmianie slugu, strona 404, formularz zgłoszeń
Hosting	Workers Static Assets	Strony serwowane przed uruchomieniem Workera: skrypt startuje wyłącznie przy kliknięciu afiliacyjnym

Efekt: 517 stron statycznych, w tym 467 kart urządzeń, generowanych z 542 rekordów i 465 zapisanych ofert od 30 producentów, w 38 kategoriach.

Tożsamość rekordu

Identyfikator jest własnym surogatem (u-0001), nadawanym raz przez człowieka i nigdy nieużywanym ponownie. Para VID-PID z rejestru certyfikacji nie jest kluczem, bo nie radzi sobie z produktami white-label, wariantami regionalnymi i rewizjami sprzętowymi. Numery nadaje skrypt z rejestru append-only, bo maksimum policzone z plików spada po skasowaniu rekordu, a od identyfikatora zależą zapisane linki i adresy afiliacyjne.

Jakość jako kod

Katalog handlowy psuje się cicho. Feed zmienia format, połowa ofert znika, strona nadal się buduje i przez tydzień pokazuje puste karty. Dlatego bramy jakości są częścią builda, a nie procedurą do zapamiętania.

Walidator schematu (1200 linii) z trzema poziomami surowości: błąd, ostrzeżenie i niekompletność. Tylko błąd zatrzymuje build. Niekompletność jest stanem normalnym, bo rekord w trakcie kuracji z definicji nie jest kompletny.
Utrwalenia zamiast atrap. Testy walidatora stoją na prawdziwych plikach YAML zepsutych w jeden konkretny sposób. Nowa reguła bez utrwalenia, które ją łamie, nie wchodzi.
Bezpiecznik scalania. Migawka katalogu zatrzymuje build, gdy ponad 20% wcześniej publicznych modeli znika, traci wszystkie oferty albo najniższą cenę.
Brama publikacji. Generator nie tworzy strony rekordu bez nazwy, producenta, kategorii i co najmniej jednej oferty. Niepełny rekord nie ma jak trafić na produkcję przez pomyłkę.
Domyślnie zamknięty build. Generator buduje wersję z noindex i canonical na hosta bety. Publiczny build wymaga jawnej flagi. Zapomniana flaga nie publikuje katalogu, tylko zostawia go schowanym.
Weryfikacja wdrożenia czyta strony, nie znacznik. Skrypt przed deployem sprawdza wygenerowany HTML, bo plik z zadeklarowanym trybem potrafi się rozjechać z tym, co naprawdę powstało.

Razem: 156 testów automatycznych po stronie danych plus zestaw testów runtime, wszystkie uruchamiane jedną komendą przed commitem. Bez zewnętrznego runnera: wbudowany node:test i czysty Python.

Warstwa prawna wpisana w produkt

Serwis zarabia afiliacją, więc prawo nie jest tu dodatkiem do regulaminu, tylko wymaganiem funkcjonalnym:

Oferty sortowane wyłącznie po cenie rosnąco. Kolejność wg wysokości prowizji to płatne plasowanie, zakazane bez ujawnienia. Reguła jest zaszyta w generatorze, nie w intencjach.
Znaki towarowe. Przeprowadziłem kwerendę TMView (EUIPO i UPRP): 862 rekordy dla „matter”, zero należących do Connectivity Standards Alliance, przy działającym teście kontrolnym (ZIGBEE i DOTDOT znajdują się jako znaki słowne tej organizacji). To rozstrzygnęło wybór domeny. Zakaz używania logo obowiązuje niezależnie i jest respektowany.
RODO i podmiot prowadzący. Spółka UK jako operator, przedstawiciel w Unii z art. 27 wyznaczony na dzień uruchomienia analityki, zgoda na pomiary przed załadowaniem skryptu.
Polityka bezpieczeństwa treści domknięta do default-src 'none'. Filtry katalogu siedzą w osobnym pliku właśnie po to, żeby polityka mogła obejść się bez unsafe-inline.

Konfigurator: silnik reguł, nie ankieta

Najciekawsza część produktowa. Oczywiste podejście to kreator, który pyta o metraż i filtruje katalog. Analiza danych pokazała, że metraż nie wpływa na dobór prawie wcale: ta sama żarówka pasuje do kawalerki i do domu. Decydujących zmiennych jest pięć i wszystkie siedzą w polach rekordu, które i tak kurowałem.

Odwróciłem więc kolejność prac: najpierw silnik konfliktów, potem interaktywny schemat instalacji, na końcu ankieta. Każda reguła czyta konkretne pole i mówi, dlaczego zestaw nie zadziała: brakuje routera brzegowego Thread, urządzenie deklaruje Matter albo Zigbee rozłącznie, moduł wymaga przewodu neutralnego, którego w starej instalacji schodowej nie ma. Kreator zbudowany od ankiety jest ładnym filtrem katalogu. Kreator zbudowany od reguł odpowiada na pytanie, którego nikt inny na tym rynku nie obsługuje: czy to, co mam w koszyku, w ogóle ze sobą zadziała.

Jak w tym projekcie pracowała AI

Cały kod powstał w parze z agentem (Claude Code), ale nie metodą „napisz mi serwis”. Trzy zasady, które zdecydowały o wyniku:

Dokument przed kodem. Repozytorium zawiera trzydzieści dokumentów decyzyjnych, około 83 tysięcy słów: analizy, pomiary, weryfikacje cudzych raportów, rozstrzygnięcia z datą i uzasadnieniem. Zmiana reguły zaczyna się od zmiany dokumentu, nie walidatora. Kolejność odwrotna daje narzędzie egzekwujące ustalenia, których nikt nie podjął. Dokumenty są jednocześnie kontekstem dla agenta: model dostaje wyłożone „dlaczego”, a nie zgaduje intencję z kodu.

Testy jako pas transmisyjny, nie jako formalność. Agent pisze szybko i pewnie także wtedy, gdy się myli. Utrwalenia na prawdziwych danych i jedna brama npm run sprawdz zamieniają tę prędkość w przewagę, bo błąd wychodzi w minutę, a nie po wdrożeniu.

Zero AI w runtime. Model pomógł zbudować generator, walidator i reguły. Na produkcji nie ma żadnego wywołania modelu: strony są statyczne, a decyzje deterministyczne. Katalog, który zmyśla wymiar puszki, jest gorszy od braku katalogu.

Weryfikacja cudzego researchu jako osobny etap. Zewnętrzne raporty rynkowe trafiły do repozytorium jako materiał do sprawdzenia, nie jako podstawa decyzji. Osobny dokument zapisuje, które ustalenia przeszły weryfikację, a które nadpisały wcześniejsze plany. Trzy z nich zmieniły kierunek projektu.

Rezultat

Działający serwis pod urzadzeniamatter.pl: katalog, kategorie, karty urządzeń, porównywarka, słownik jedenastu pojęć wyjaśnianych w miejscu użycia, formularz zgłoszeń urządzeń i konfigurator systemu.

Twarde liczby: 467 kart urządzeń, 465 ofert, 30 producentów, 38 kategorii, 218 commitów, 156 testów danych, jedna zależność produkcyjna, zero baz danych.

Co ten projekt pokazuje: umiejętność doprowadzenia produktu od pomiaru rynku, przez model danych i wymagania prawne, po działające wdrożenie, z tempem, które daje praca z agentem AI, i z rygorem, który sprawia, że to tempo nie kosztuje jakości.