Jedno polecenie i mój agent programistyczny dostał projekt, w którym umiał się odnaleźć

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 my-app
# or
npm create @owlmeans/app@latest my-app
# or
npx @owlmeans/create-app@^0.1.18 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.

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 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.1.18

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.

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

Ani AGENTS.md, ani format Agent Skills 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