Buduję appkę o nazwie Mafiozo. To asystent prowadzącego do gry w mafię: losuje role, podpowiada kwestie i pilnuje przebiegu nocy.

W pierwszej części pokazałem w rolce, jak wygląda struktura folderów w moim projekcie. Tutaj to samo, ale z zajrzeniem do środka: co leży w każdym folderze i po co.

Teza jest prosta: żeby wypuścić aplikację mobilną, nie wystarczy sama aplikacja. Oprócz kodu potrzebuję dokumentacji, tekstów i grafik do sklepów, skryptów i strony. Kod appki to jeden folder z kilku.

Tak wygląda projekt

mafiozo/
├── docs/        dokumentacja
├── mobile/      aplikacja
├── store/       teksty i grafiki do sklepów
├── tools/       skrypty pomocnicze
├── web/         strona
├── AGENTS.md    instrukcje dla agentów AI
├── CLAUDE.md    importuje AGENTS.md
└── README.md    spis folderów

Pomijam ukryte pliki i foldery z kropką, bo nie są częścią układu.

docs/: co appka ma robić i jak ją zbudować

Zaczynam od dokumentacji, bo zanim powstanie pierwszy ekran, ktoś (ja albo agent) musi wiedzieć, co appka ma robić. Część dokumentów powstała przed kodem, część rośnie razem z projektem.

W docs/superpowers/ leżą projekt i plan, które wygenerował agent AI na podstawie moich rozmów z nim:

• specs/mafiozo-decyzje.md to dziennik decyzji. Każdy wpis ma datę, autora i powód, a założenia agenta, których nie potwierdziłem, są oznaczone słowem „domysł". Jest tam między innymi paleta kolorów (tło od #0F0F11 do #1E1B1F, akcent #A61B22) i sprawdzenie, czy nazwa „Mafiozo" nie jest zajęta.
• specs/mafiozo-projekt.md to pełny projekt: cele, nie-cele i anty-cele, a potem wieczór krok po kroku, od listy graczy po zmianę prowadzącego. Przykładowy anty-cel: „appka spowalnia wieczór: każdy krok ma być jednym dotknięciem".
• plans/mafiozo-implementacja.md to plan na 17 zadań, pisany dla agentów. Kolejność jest taka: najpierw czysta logika gry, potem teksty i grafiki, na końcu ekrany. Każde zadanie zaczyna się od padających testów:

Obok leżą cztery krótsze dokumenty:

• architektura.md: mapa plików aplikacji i decyzje warte zachowania, każda z powodem. Na przykład: wszystkie teksty interfejsu siedzą w jednym miejscu, a logika gry to czysty TypeScript, w którym każdy plik ma test.
• pierwsze-kroki.md: jednorazowa lista 18 rzeczy do wyklikania po założeniu projektu (EAS, AdMob, Firebase, Vercel, sklepy). Odhaczam, a po wszystkim usuwam plik.
• pulapki.md: pułapki, w które już wpadłem, każda z powodem. Na przykład: gdy Apple zatwierdzi wersję, jej „pociąg" jest zamknięty i nowy build pod tym samym numerem zostaje odrzucony, więc version podnoszę przed każdym buildem do sklepu.
• uruchamianie.md: jak odpalić appkę, bramka przed buildem w chmurze (najpierw lokalny xcodebuild, bo build w EAS kosztuje kolejkę) i wydanie.

mobile/: sama aplikacja

W mobile/ jest kod całej aplikacji: Expo, na iOS i Androida. To jest to, co zwykle mamy na myśli, mówiąc „appka". I to dopiero jeden z folderów. Jak jest zbudowana w środku, pokażę w innym odcinku.

store/: materiały do sklepów

Sklepy to osobna praca, więc mają osobny folder: teksty, grafiki i deklaracje.

• teksty.md to jedyne miejsce, w którym trzymam pola tekstowe: nazwę, podtytuł, opis, „Co nowego" i adresy. Każde pole ma licznik znaków i limit sklepu, który sprawdza walidator (node tools/store/build-metadata.mjs --check), bo App Store Connect nie ostrzega o za długich polach, tylko odrzuca zapis.
• Stąd nazwa „Mafiozo" i osobny podtytuł: „Mafiozo: asystent do gry w mafię" ma 32 znaki, a limit to 30. Nazwa ma 7 znaków, podtytuł 23.
• zrodla/ to surowe zrzuty z symulatora i emulatora. Z nich skrypty składają grafiki z podpisami (podpisy.json) i wyglądem (styl.json), w rozmiarach, których chcą sklepy, na przykład 1320×2868 dla iPhone'a i 2064×2752 dla iPada.
• appstore/opis.md i play/opis.md to wszystko, co nie jest polem tekstowym: deklaracje prywatności (App Privacy w App Store, Data Safety w Google Play), uwagi dla recenzenta i kategorie. Deklaracja musi się zgadzać w trzech miejscach naraz: w App Store Connect, w Data Safety i w polityce prywatności.

Tak wygląda pole w teksty.md:

Asystent do gry w mafię

tools/: skrypty pomocnicze

Skrypty są inne w każdej appce, bo każda ma swoje potrzeby. W Mafiozo duża część dotyczy sklepów (tools/store/):

• build-metadata.mjs sprawdza teksty i limity,
• compose.py i compose_play.py składają zrzuty z podpisami, a kreatywne.py grafiki do strony produktu,
• check_assets.py sprawdza gotowe grafiki: czy to PNG, czy rozmiar jest dokładny, czy nie ma kanału alfa i czy jest profil sRGB,
• asc-diff.mjs pokazuje, co jest na koncie App Store Connect (tylko odczyt).

Jest też tools/promo/ ze skryptami do 30-sekundowego filmu promocyjnego: nagrania ekranu z symulatora, podpisy w każdym języku i muzyka generowana czystym Pythonem. Reszta to drobiazgi, jak make_icons.py, który składa ikony z rysunku mafioza.

Dzięki temu limity i formaty sprawdza skrypt, a nie ja na oko.

web/: strona

Na razie to tylko tymczasowy index.html. Docelowo będzie to strona w Next.js hostowana na Vercelu, z polityką prywatności, bo Apple wymaga adresu polityki prywatności dla każdej aplikacji, więc strona jest potrzebna, zanim appka trafi do App Store. Pewnie dostanie osobny odcinek.

AGENTS.md: instrukcje dla agenta

To plik dla agentów AI, który mówi im, jak pracować w tym repo. Zaczyna się od zdania „Expo HAS CHANGED": przed pisaniem kodu agent ma przeczytać dokumentację właściwej wersji, bo to, co zna z treningu, może już nie obowiązywać. Dalej:

• Nie ma pliku ze stanem projektu. Opis stanu w .md rozjeżdża się z rzeczywistością, więc stan wyznaczają git i EAS.
• Bramki mówią, co odpalić po jakiej zmianie.
• Reguły, które łatwo złamać, każda z powodem. Na przykład: przed buildem do sklepu podnoszę version, a eas submit odpalam tylko na wyraźną prośbę, bo to zgłoszenie do recenzji.

Tak wyglądają bramki:

CLAUDE.md importuje AGENTS.md, a README.md to spis folderów.

Co z tego wynika

Żeby wypuścić appkę, potrzebuję poza samą appką:

1. dokumentacji, czyli co i jak buduję,
2. tekstów do sklepów, razem z pilnowaniem limitów,
3. grafik i zrzutów w wymaganych rozmiarach,
4. skryptów, które to składają i sprawdzają,
5. strony z polityką prywatności,
6. instrukcji dla agenta.

Jak widzisz, aplikacja to tylko jeden folder.

W kolejnych częściach pokażę, jak powstaje Mafiozo. Rolka z tej części jest na moim Instagramie: @adam_robi_appki.