---
title: "Jedno polecenie i mój agent programistyczny dostał projekt, w którym umiał się odnaleźć"
description: "Szkielet projektu z OwlMeans Common ma na start trzy workspace’y w TypeScripcie i wytyczne dla agentów dopasowane do pakietów. Funkcja z trwałymi danymi nadal wymaga konfiguracji bazy danych, walidacji i testów uprawnień."
url: "https://owlmeans.com/pl/blog/create-app/"
lang: "pl"
---

![Polecenie w terminalu prowadzące do trzech workspace’ów: common, api i web](https://owlmeans.com/_astro/hero.CpTM1Y-v_Z23pFJE.webp)

W czerwcu dodałem do OwlMeans Common polecenie `create-app`. Chciałem mieć mały projekt, który dam agentowi programistycznemu i nie będę musiał najpierw tłumaczyć mu frameworka od zera.

Common to fundament w TypeScripcie, na którym stoją projekty OwlMeans. Polecenie daje Ci punkt startowy, który od razu da się uruchomić, i wytyczne opisujące jego konwencje. Agentem nadal kierujesz Ty i to Ty przeglądasz jego zmiany.

Ten przewodnik zachowuje czerwcowy przykład i przypięte wersje z tekstu, który aktualizujemy na stronie. Opisany niżej układ wytycznych uwzględnia późniejsze przeniesienie do `.agents/`.

## Projekt na start

Wybierz jedno polecenie:

```
bun create @owlmeans/app@^0.2.0 my-app
# or
npm create @owlmeans/app@^0.2.0 my-app
# or
npx @owlmeans/create-app@^0.2.0 my-app
```

Następnie uruchom serwery deweloperskie:

```
cd my-app
bun run dev          # API on :3000, web on :3001
```

Otwórz aplikację webową i spróbuj dodawać i usuwać pozycje na ekranie Session. Demo łączy frontend z API przez wspólny kontrakt. Dane trzyma w pamięci. Wystarczy zrestartować proces, a przypomnisz sobie, dlaczego to ważne.

Szkielet ma trzy workspace’y:

-   `common` zawiera wspólne deklaracje tras, schematy walidacji i typy.
-   `api` uruchamia backend na `@owlmeans/server-app`.
-   `web` dostarcza frontend na `@owlmeans/web-panel`.

Tak wygląda minimalny szkielet z CLI. Projekty generowane w OwlMeans mogą mieć też wspólną bibliotekę backendu i workera. Przykład z CLI nie postawi za Ciebie ani ich, ani bazy danych.

## Kontrakt aplikacji

Chcę, żeby agent znajdował deklarację trasy po jej aliasie. I chcę móc sam prześledzić tę samą deklarację.

Common opisuje ten kontrakt punktami wejścia (entrypoint). Punkt wejścia łączy alias, ścieżkę, metodę i walidację:

```
entrypoint(
  route(session.add, '/:sid/items', { parent: session.base, method: RouteMethod.POST }),
  filter(params(SessionParamsSchema), body(AddItemSchema)),
)
```

Backend podpina handler przez `elevate`. Frontend podpina zachowanie ekranu i wywołuje punkt wejścia przez `ctx.entrypoint(session.add).call({ params, body })`.

Trasa i schemat to wspólny kod źródłowy. W tym wzorcu nie generuje się osobnego klienta API. Po zmianie deklaracji i tak trzeba sprawdzić miejsca wywołań i handler. Wspólne typy nie rozstrzygną, czy operację w ogóle należało dopuścić.

Z serwisami jest podobnie: każdy krok widać. Fabryka tworzy serwis, aplikacja rejestruje go pod aliasem, a kod pobiera go przez `context.service('alias')`.

Wolę kod spięty w ten sposób, bo umiem go przeczytać. Nie mierzyłem oszczędności tokenów w porównaniu z innym frameworkiem, a ten przykład żadnej nie wykazuje.

![Ilustracja zestawiająca niejawne powiązania z jawnymi deklaracjami w TypeScripcie](https://owlmeans.com/_astro/inline-1.CvMlIHE4_213Xr2.webp)

## Trwałe dane

Zasób z demo ma metody takie jak `create`, `list` i `delete`. Zasoby oparte na bazie danych korzystają z tego samego interfejsu, więc handlery zachowują znajomy kształt.

Nie znaczy to, że przejście na bazę danych sprowadza się do zmiany jednego pakietu. Nadal potrzebujesz konfiguracji połączenia, indeksów, walidacji i decyzji, co zrobić z istniejącymi danymi. Reguły dostępu też trzeba przetestować.

Jeśli dodajesz od zera funkcję notatek, przyda się taka prośba do agenta:

> Dodaj trwałe notatki zapisywane w MongoDB. Użyj `@owlmeans/mongo` i `@owlmeans/mongo-resource`. Zadeklaruj schemat i punkty wejścia w `sources/common`, zarejestruj zasób i handlery w `sources/api`, a ekran dodaj w `sources/web`. Trzymaj się zainstalowanych wytycznych dotyczących zasobów i ponownego użycia kodu.

Wywołania zasobu mogą wtedy wyglądać tak:

```
const notes = context.resource<NotesResource>(RES_NOTES)
await notes.create({ id, text, createdAt })
const { items } = await notes.list({ criteria: { ... } })
```

To fragmenty interfejsu, a nie kompletna aplikacja. Alias zasobu, schemat i połączenie trzeba zarejestrować w projekcie.

Po zmianie zrestartuj aplikację i sprawdź, czy notatka przetrwała. Wypróbuj też niepoprawne dane wejściowe i nieudane połączenie. Jeśli notatki należą do różnych użytkowników, sprawdź w testach, że jeden użytkownik nie odczyta notatek innego.

Warstwa webowa korzysta z shadcn UI i Tailwinda. Według [dokumentacji shadcn](https://ui.shadcn.com/docs) całe podejście polega na tym, że dostajesz kod źródłowy komponentów i na nim pracujesz. W tym projekcie agent może ten kod przeglądać i edytować. Sprawdzenie, jak zachowuje się gotowy interfejs, nadal należy do Ciebie.

## Wytyczne w pakietach

Wersja czerwcowa kopiowała wytyczne do osobnych katalogów dla poszczególnych agentów. Później usunęliśmy te równoległe źródła. Kanoniczne wytyczne projektu leżą w `.agents/`. W katalogu głównym jest `AGENTS.md`, a tam, gdzie trzeba, dochodzi pomost dla Claude’a.

Pakiety OwlMeans udostępniają wytyczne w katalogu `agent-meta/`. Instalator czyta te metadane i zapisuje umiejętności dla pakietów obecnych w projekcie. Umiejętność dotycząca zasobów może objaśnić framework, ale to instrukcje Twojego projektu muszą wyjaśnić, do czego służą notatki.

Po aktualizacji odpowiednich pakietów polecenie, które utrzymujemy w tym przewodniku, wygląda tak:

```
npx @owlmeans/agent-skills@^0.2.0
```

Przejrzyj to, co wypisze instalator. Zarządzane przez niego pliki, które zmieniono lokalnie, mogą wejść w konflikt, a wymuszenie nadpisania to decyzja o losie Twoich własnych zmian. Instalator służy projektom, które korzystają z pakietów; podlinkowane monorepo frameworka mają osobny proces utrzymania.

![Pierwotna czerwcowa ilustracja z osobnymi plikami wytycznych dla agentów](https://owlmeans.com/_astro/inline-2.-uzain4g_26xJMe.webp)

_Ilustracja pokazuje czerwcowy układ katalogów. W poprawionym procesie korzystaj ze wspólnego układu .agents opisanego wyżej._

Ani [AGENTS.md](https://agents.md/), ani [format Agent Skills](https://agentskills.io/specification) nie gwarantują, że każde narzędzie samo wczyta każdy plik. Zanim zaczniesz polegać na instrukcjach, sprawdź, jak agent jest zintegrowany.

## Co zostaje po Twojej stronie

`create-app` daje Ci szkielet Common. OwlMeans dokłada wokół tego fundamentu pipeline ról deweloperskich. To różne sposoby, żeby zacząć pracę z tym samym frameworkiem.

Polecenie nie ustali za Ciebie modelu danych, nie przetestuje uprawnień i nie poprowadzi Twojej usługi na produkcji. Udany build ma ograniczoną wartość: w tej konfiguracji uruchamiaj `bun run typecheck` osobno od `bun run build`.

Zbudowałem szkielet, żeby nie spinać projektu od zera za każdym razem. Zostawia mi tę część, nad którą muszę pomyśleć: czy funkcja w ogóle tam pasuje i czy działa.

_Pierwsza publikacja: 17 czerwca 2026 r. Poprawiono 15 października 2026 r.: aktualne przypięte wersje w poleceniach i wspólny układ wytycznych dla agentów._

[OwlMeans](https://owlmeans.com/pl/)
