Адна каманда — і мой агент для працы з кодам атрымаў праект, у якім ён не губляецца

У чэрвені я дадаў у OwlMeans Common каманду create-app. Мне хацелася мець невялікі праект, які можна аддаць агенту для працы з кодам, каб не тлумачыць яму спачатку фрэймворк з нуля.

Common — аснова на TypeScript, на якой стаяць праекты OwlMeans. Каманда дае табе гатовы да запуску пачатковы праект і інструкцыі, якія апісваюць яго пагадненні. Кіраваць агентам і правяраць яго змены будзеш усё ж ты.

У гэтым разборы застаўся чэрвеньскі прыклад, а зафіксаваныя версіі пакетаў узятыя з тэксту на сайце, які мы трымаем актуальным. Структура інструкцый ніжэй ужо ўлічвае пазнейшы пераезд у .agents/.

Пачатковы праект

Выберы адну з каманд:

bun create @owlmeans/app my-app
# or
npm create @owlmeans/app@latest my-app
# or
npx @owlmeans/create-app@^0.1.18 my-app

Потым запусці серверы распрацоўкі:

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

Адкрый вэб-застасунак і паспрабуй дадаваць і выдаляць элементы на экране Session. Дэманстрацыйны застасунак звязвае фронтэнд з API праз агульны кантракт. Даныя ён трымае ў памяці. Перазапусці працэс — і адразу ўспомніш, чаму гэта важна.

Каркас мае тры працоўныя прасторы:

• common змяшчае агульныя дэкларацыі маршрутаў, схемы валідацыі і тыпы.
• api запускае бэкэнд на @owlmeans/server-app.
• web дае фронтэнд на @owlmeans/web-panel.

Гэта мінімальны каркас з CLI. Праекты, якія генеруе OwlMeans, могуць мець яшчэ агульную бібліятэку для бэкэнда і воркер. Ні іх, ні базы даных прыклад з CLI за цябе не стварае.

Кантракт застасунку

Я хачу, каб агент знаходзіў дэкларацыю маршруту па яе псеўданіме. А яшчэ хачу, каб па той жа дэкларацыі мог прайсці і я сам.

Для гэтага кантракта Common выкарыстоўвае кропкі ўваходу (entrypoints). Кропка ўваходу звязвае псеўданім, шлях, метад і валідацыю:

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

Бэкэнд далучае апрацоўшчык праз elevate. Фронтэнд далучае паводзіны свайго экрана і выклікае кропку ўваходу праз ctx.entrypoint(session.add).call({ params, body }).

Маршрут і схема — агульны зыходны код. Асобнага згенераванага API-кліента ў гэтым падыходзе няма. Калі мяняеш дэкларацыю, усё роўна трэба праверыць месцы выкліку і апрацоўшчык. Агульныя тыпы не могуць вырашыць, ці трэба было дазваляць аперацыю.

Сэрвісы праходзяць такі ж празрысты шлях. Фабрыка стварае сэрвіс, застасунак рэгіструе яго па псеўданіме, а код атрымлівае яго праз context.service('alias').

Мне такая звязка больш даспадобы, бо я магу яе прачытаць. Наколькі яна эканоміць токены ў параўнанні з іншым фрэймворкам, я не вымяраў, і гэты прыклад такой эканоміі не даказвае.

Захоўванне даных

Дэманстрацыйны рэсурс мае метады накшталт create, list і delete. Рэсурсы на базе даных карыстаюцца тым жа інтэрфейсам, таму апрацоўшчыкі захоўваюць знаёмую форму.

Але пераход на базу даных ад гэтага не становіцца справай аднаго пакета. Табе яшчэ спатрэбяцца налады падключэння, індэксы, валідацыя і рашэнне наконт наяўных даных. Правілы доступу таксама трэба пакрыць тэстамі.

Для новай функцыі нататак агенту карысна даць такі запыт:

Дадай нататкі, якія захоўваюцца ў MongoDB. Выкарыстай @owlmeans/mongo і @owlmeans/mongo-resource. Аб’яві схему і кропкі ўваходу ў sources/common, зарэгіструй рэсурс і апрацоўшчыкі ў sources/api і дадай экран у sources/web. Прытрымлівайся ўсталяваных інструкцый пра рэсурсы і паўторнае выкарыстанне кода.

Тады выклікі рэсурсу могуць выглядаць так:

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

Гэта ўрыўкі інтэрфейсу, а не гатовы застасунак. Псеўданім рэсурсу, схему і падключэнне трэба зарэгістраваць у праекце.

Пасля змены перазапусці застасунак і пераканайся, што нататка нікуды не знікла. Паспрабуй таксама некарэктны ўвод і збой падключэння. Калі нататкі належаць розным карыстальнікам, правер тэстам, што адзін карыстальнік не можа прачытаць нататкі іншага.

Вэб-пласт пабудаваны на shadcn UI і Tailwind. Дакументацыя shadcn апісвае падыход бібліятэкі так: ты атрымліваеш зыходны код кампанентаў і працуеш з ім. У гэтым праекце агент можа вывучаць і правіць гэты код. А правяраць, як у выніку паводзіцца інтэрфейс, — па-ранейшаму твая справа.

Інструкцыі ў пакетах

Чэрвеньская версія капіявала інструкцыі ў асобныя тэчкі для кожнага агента. Пазней мы прыбралі гэтыя паралельныя крыніцы. Кананічныя інструкцыі праекта жывуць у .agents/: у корані ляжыць AGENTS.md, а там, дзе трэба, ёсць мост для Claude.

Пакеты OwlMeans распаўсюджваюць свае інструкцыі праз agent-meta/. Усталёўшчык чытае гэтыя метаданыя і запісвае навыкі для пакетаў, якія ёсць у праекце. Навык пра рэсурсы можа растлумачыць фрэймворк, а вось навошта патрэбныя твае нататкі, павінны тлумачыць інструкцыі твайго праекта.

Калі абновіш патрэбныя пакеты, актуальная каманда для гэтага разбору такая:

npx @owlmeans/agent-skills@^0.1.18

Прагледзь, што выведзе ўсталёўшчык. Файлы, якімі ён кіруе, але якія ты правіў лакальна, могуць канфліктаваць, а прымусовы перазапіс — гэта рашэнне пра лёс тваіх уласных змен. Усталёўшчык прызначаны для праектаў, якія выкарыстоўваюць пакеты; звязаныя манарэпазіторыі фрэймворка маюць асобны працоўны працэс падтрымкі.

Ілюстрацыя паказвае чэрвеньскую структуру тэчак. Для абноўленага працоўнага працэсу карыстайся агульнай структурай .agents, апісанай вышэй.

Ні AGENTS.md, ні фармат Agent Skills не гарантуюць, што кожны інструмент аўтаматычна загрузіць кожны файл. Перш чым спадзявацца на інструкцыі, правер, як з імі інтэграваны твой агент.

Што застаецца табе

create-app дае табе каркас Common. OwlMeans дабудоўвае вакол той жа асновы канвеер роляў распрацоўкі. Гэта розныя спосабы пачаць працу з адным і тым жа фрэймворкам.

Каманда не вызначыць за цябе мадэль даных, не пратэстуе дазволы і не будзе абслугоўваць твой сэрвіс у вытворчым асяроддзі. Паспяховая зборка — абмежаваны вынік: у гэтай канфігурацыі запускай bun run typecheck асобна ад bun run build.

Я стварыў каркас, каб больш не паўтараць пачатковую звязку. Мне застаецца тое, над чым і трэба думаць: ці месца там гэтай функцыі і ці працуе яна.

Упершыню апублікавана 17 чэрвеня 2026 г. Перагледжана 15 кастрычніка 2026 г.: актуальныя версіі ў камандах і агульная структура інструкцый для агентаў.

OwlMeans