В июне я добавил в 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 года: добавлены актуальные закреплённые версии в командах и общая структура инструкций для агентов.