backend-api-design — скилл для Claude Code: RPC-API по слоям
Задаёт агенту правила проектирования RPC-API: тонкий контроллер, менеджер с бизнес-логикой, репозиторий только для доступа к данным. Пригодится при создании новых эндпоинтов и разборе чужих паттернов.
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a claude-codeЧто делает backend-api-design
Скилл описывает жёсткие правила URL: никаких path-параметров, только @QueryValue; единственный ресурс — в единственном числе (/employee), коллекция — во множественном (/employees), действия выносятся в подпути вроде /delete, /restore, /sync. Все изменения — через @Post, @Put, @Delete и @Patch не используются.
Слои расписаны по ролям. Контроллер разбирает query-параметры с значениями по умолчанию, делегирует менеджеру и разворачивает Either через .throwOrValue(). Менеджер возвращает Either<ClientException, T>, оборачивает операции с базой в transaction(db.primary) { } и проверяет бизнес-правила. Репозиторий читает с db.replica, пишет в db.primary и всегда отсекает удалённые записи через deletedAt.isNull().
Отдельный раздел про грабли. Многозначные @QueryValue требуют явного snake_case-имени: пишите @QueryValue("project_id") projectId: UUID, иначе Micronaut ищет параметр по буквальному имени, а фронтенд шлёт project_id. Второй вызов .where {} затирает первое условие — нужен .andWhere {}. И без @ExecuteOn(TaskExecutors.IO) suspend-функции могут зависнуть или уехать не в тот пул потоков, так что аннотация нужна каждому контроллеру.
Какие задачи решает
- спроектировать контракт нового эндпоинта без path-параметров
- разложить бизнес-логику по контроллеру, менеджеру и репозиторию
- вынести транзакцию и возврат ошибок в менеджер, а не в контроллер
- поймать репозиторий, заинжекченный прямо в контроллер
- собрать постраничный ответ с items, total, page, limit и hasMore
Примеры запросов агенту
- Спроектируй эндпоинты для сотрудников по правилам скилла: список, создание, удаление, восстановление
- Разбери этот контроллер и скажи, что нарушает слоистую архитектуру
- Добавь пагинацию в метод списка сотрудников, ответ собери как EmployeeListResponse
Как установить backend-api-design
1Через Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a claude-code2Вручную: положить файлы
~/.claude/skills/backend-api-design/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/backend-api-design/
1Через Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a codex2Вручную: положить файлы
.agents/skills/backend-api-design/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a cursor2Вручную: положить файлы
.cursor/skills/backend-api-design/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install c0x12c/ai-toolkit backend-api-design2Вручную: положить файлы
.github/skills/backend-api-design/SKILL.md1Через Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a gemini-cli2Командой платформы
gemini skills install https://github.com/c0x12c/ai-toolkit --path toolkit/skills/backend-api-designВручную: положить файлы
.devin/skills/backend-api-design/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о backend-api-design
Как установить backend-api-design в Claude Code?
Выполните npx skills add c0x12c/ai-toolkit --skill backend-api-design -a claude-code. Файл скилла окажется по пути ~/.claude/skills/backend-api-design/SKILL.md.
Что делает backend-api-design?
Описывает RPC-стиль API со слоями Controller → Manager → Repository: правила URL, распределение обязанностей между слоями и типичные ошибки вроде второго .where {}.
С какими инструментами работает этот скилл?
Ему разрешены Read, Write, Edit, Glob и Grep — то есть он читает и правит файлы проекта, но не запускает команды. Примеры кода построены на Micronaut и Kotlin.
