Claude Codeдля бэкенда и API

Бэкенд — это невидимая часть проекта: то, что обрабатывает запросы, считает, проверяет права и ходит в базу. Пользователь его не видит, но именно здесь живёт логика, и здесь же ошибка стоит дороже всего: неверный расчёт, дыра в правах, потерянные данные. Claude Code пишет бэкенд-код быстро, но у него есть слепое пятно — по умолчанию он делает «счастливый путь» и забывает про крайние случаи. Этот гайд про то, как закрыть слепое пятно и получить надёжный API.

Часть 1 · Контекст

Задай контракт и образец

Расшифруем термины. API — это набор точек, через которые программы общаются: клиент шлёт запрос, сервер отвечает. Эндпоинт (endpoint) — конкретная такая точка, например POST /api/orders. Роут (route) — правило, которое связывает путь запроса с кодом-обработчиком. Контракт — это договорённость, как эндпоинт себя ведёт: что принимает, что возвращает, какие ошибки. Без контракта агент угадывает форму ответа, и фронтенд потом не стыкуется.

# Сначала покажи образец и опиши контракт
Посмотри app/api/users/route.ts — это наш стиль роутов
(Next.js, валидация через zod, ошибки в едином формате).

Сделай эндпоинт POST /api/orders:
- вход: { items: [{ productId, qty }] }
- ответ 201: { orderId, total }
- ошибки: 400 если items пуст, 401 без авторизации
Стиль и формат ошибок — как в users/route.ts.

Постоянные правила бэкенда — стек, формат ошибок, где лежат сервисы — держи в CLAUDE.md. Тогда не придётся повторять контекст в каждом промте: агент сам применяет ваши соглашения к любому новому роуту.

Часть 2 · Роуты

Роуты и эндпоинты под свой стек

Сила агента здесь — в шаблонности. Большинство роутов устроены одинаково: принять запрос, проверить вход, проверить права, сделать дело, вернуть ответ. Claude знает эти шаблоны для всех популярных фреймворков. Твоя задача — назвать фреймворк и дать соседний роут как образец стиля, чтобы новый эндпоинт был неотличим от написанного руками.

Назови стек, дай образец и контракт — роут получится «как ваш», а не как из туториала.

Дроби работу. «Сделай весь REST API для заказов» — плохой промт: агент выдаст гору кода, в которой трудно навести ревью. «Сделай эндпоинт создания заказа по контракту выше» — хороший: один роут, понятный диф, легко проверить. Как ставить такие задачи — в гайде про промптинг.

Часть 3 · Логика

Бизнес-логика через тесты

Бизнес-логика — это правила, по которым проект считает и решает: как начислить скидку, можно ли отменить заказ, кому что показывать. Это самая ценная и самая хрупкая часть бэкенда: баг здесь — это неверные деньги или сломанный сценарий. Поэтому её надёжнее всего писать через тесты.

TDD (Test-Driven Development) — это «сначала тест». Вы с агентом записываете ожидаемое поведение в виде проверки («скидка 10% при сумме от 5000»), запускаете — тест красный, кода ещё нет. Потом агент пишет минимальную реализацию, гоняет тест — зелёный. Так у логики есть объективная проверка, а не доверие на слово.

# 1. Сначала проговариваем поведение тестами
Напиши тесты на расчёт скидки:
- сумма < 5000 → скидки нет
- сумма >= 5000 → скидка 10%
- сумма >= 20000 → скидка 20%
- отрицательная сумма → ошибка
Сначала ТОЛЬКО тесты, код не трогай.

# 2. Затем — реализация под зелёные тесты
Теперь напиши функцию расчёта, чтобы все тесты прошли.

Подробный воркфлоу с циклом red-green-refactor — в гайде про тесты с Claude Code. Для бэкенд-логики это не формальность, а способ не выкатить неправильный расчёт в прод.

Часть 4 · Края

Валидация и обработка ошибок

Это главное слепое пятно бэкенда с агентом. Валидация — это проверка входных данных до того, как пустить их в логику: пришёл ли нужный формат, не отрицательное ли число, не пустое ли поле. Обработка ошибок — что вернуть, когда что-то пошло не так: понятный код и сообщение вместо падения с пятисоткой. Claude сделает и то, и другое — но только если попросить.

Удобный приём — разобрать края списком прямо в промте. Тогда агент не пропустит:

1. Пустой/неверный вход. Нет обязательного поля, не тот тип — вернуть 400 с понятным сообщением.
2. Нет прав. Не авторизован — 401, нет доступа к ресурсу — 403.
3. Не найдено. Запрошенного объекта нет — 404, а не падение.
4. Внешний сбой. База или сторонний сервис недоступны — корректная ошибка, а не зависание.
5. Не доверять клиенту. Любые данные из запроса — подозрительны, пока не проверены.

Часть 5 · Безопасность

Что оставить за собой

Бэкенд — это слой, где ошибка видна не сразу, а когда уже поздно: утёк токен, кто-то увидел чужие данные, прошёл лишний платёж. Поэтому часть вещей остаётся под контролем человека, даже если агент написал черновик.

Перед задачами, которые трогают права или контракт, включай план-режим (Shift+Tab): агент распишет, что и зачем собирается менять, ты утверждаешь — и только потом он пишет код. Для чувствительного слоя это дешевле, чем разбирать последствия.

Вопросы

Частые вопросы

Читать дальше

Соседние гайды