> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Создавайте вместе с кодинг-агентом

Передавайте задачи кодинг-агенту: файлы, которые он читает, библиотека промптов для вставки, автономная настройка и проверка, которая оставляет контроль за вами.

## Прохождение для начинающих

Предварительные требования: прочтите два руководства для начинающих ниже, завершите локальную настройку веб-приложения и откройте этот репозиторий в редакторе с его корня. Кодинг-агент — это AI-инструмент — Cursor, Claude Code, Devin или похожий ассистент, — который читает ваш проект, редактирует файлы и выполняет команды. Всё на этой странице применимо к любому из них.

Коротко о терминах: промпт — это текст инструкции, который вы вставляете агенту. Diff — список предлагаемых им изменений файлов. Корень репозитория — верхняя папка, содержащая package.json, — агент всегда должен начинать оттуда.

1. Откройте папку `prompts/` в корне репозитория и скопируйте промпт, ближайший к вашей задаче. `new-landing-page.md` — хороший первый вариант.

2. Вставьте его своему агенту и заполните `<placeholders>`: нужный маршрут, что должна делать страница или экран, кто может её использовать и как выглядит успех. Затем добавьте одну строку: Read `llms.txt`, then `AGENTS.md`, then `.ai/PROJECT_CONTEXT.md` before touching code.

3. Пусть агент перечислит файлы, которые он изменит, и проверки, которые он запустит, прежде чем редактировать. Когда он закончит, просмотрите diff — вы утверждаете реальные изменения своего продукта.

4. Публикация, развёртывание и платные вызовы провайдеров никогда не являются частью промпта задачи. Держите их отдельными шагами, которые вы одобряете явно.

[Прежде чем начать](https://supastack.dev/ru/docs/web/before-you-start.md)

[Основные сведения о терминале](https://supastack.dev/ru/docs/web/terminal-basics.md)

[Локальная настройка веб-приложения](https://supastack.dev/ru/docs/web/ship-in-5-minutes.md)


## Файлы, которые читает ваш агент

Репозиторий поставляет небольшой набор файлов, написанных для агентов, а не только для людей. Вы никогда не вставляете этот контекст вручную — укажите агенту на `llms.txt`, и остальное он прочитает сам.

Порядок чтения важен: `llms.txt` — карта, `AGENTS.md` задаёт границы, а `.ai/PROJECT_CONTEXT.md` несёт то, что узнали предыдущие сессии. Агент, пропускающий границы, производит код, который вы не сможете выпустить.

| Файл | Что он даёт агенту |
|---|---|
| `llms.txt` | Карта входа в репозиторий — каждый документ, который стоит прочитать, плюс протоколы безопасности, в порядке чтения |
| `AGENTS.md` | Нерушимые границы: только локальная работа, пока вы не одобрите больше, ограничение по workspaceId, секреты только на сервере |
| `.ai/PROJECT_CONTEXT.md` | Память между сессиями — что недавно изменилось и почему; читается перед изменениями кода |
| зеркальные документы `.ai/` | Соответствующая заметка `.ai/<path>.md` рядом с важными файлами, фиксирующая решения по каждому файлу и открытые вопросы |
| `docs/agent-setup.md` | Сценарий автономной настройки — фазы установки, миграции и развёртывания с контрольной проверкой после каждой |
| `prompts/` | Готовые к вставке промпты задач для работ, которые владельцы запрашивают чаще всего |
| `docs/agent-security.md` | Приёмочный чек-лист — аутентификация, проверки рабочего пространства и RLS, очищенные журналы, доказательства развёртывания |
| `.env.example` | Полный перечень окружения — агент никогда не выдумывает имя переменной, отсутствующее в этом файле |


## Библиотека промптов

`prompts/README.md` — это указатель. Каждый файл — полный бриф: вставьте его, заполните `<placeholders>` — и правила комплекта, дизайн-токены вместо жёстко заданных цветов, блоки комплекта вместо выдуманных паттернов, отправятся вместе с ним.

Для пути «с нуля до запуска» вместо этого вставьте `prompts/agent-setup.md` — он управляет автономной настройкой, описанной далее.

[Позвольте агенту выполнить настройку за вас](https://supastack.dev/ru/docs/web/agent-setup.md)

- `agent-setup.md` — разверните комплект и отправьте его в эксплуатацию с помощью агента
- `pick-a-style.md` — примените стиль оформления ко всему продукту
- `new-landing-page.md` — соберите маркетинговую страницу из блоков комплекта
- `new-app-screen.md` — добавьте экран внутри оболочки приложения рабочего пространства
- `restyle-product.md` — переведите существующую страницу на токены комплекта
- `ui-audit.md` — запустите аудит визуала и доступности для маршрута


## Доверьте агенту установку и развёртывание

Комплект может в значительной степени настроить себя сам. Вставка `prompts/agent-setup.md` заставляет агента выполнить `docs/agent-setup.md` — поставляемый сценарий — фаза за фазой: предварительные проверки, файлы окружения, установка, запуск базы данных, миграции, запуск приложения и, по желанию, развёртывание на VPS. После каждой фазы он запускает её контрольную проверку и отчитывается реальным выводом, а не заявлением.

Два помощника делают это безопасным. `scripts/setup-env.mjs` создаёт файлы окружения из `.env.example`: он создаёт только отсутствующие файлы, генерирует только отсутствующие или шаблонные секреты, а его режим `--check` проверяет без записи. `docker-compose.dev.yml` — полностью контейнеризованная среда разработки, Postgres плюс dev-контейнер Node 22, — поэтому агенту не нужен Node.js, установленный на вашем компьютере.

Здесь важно, какой репозиторий вы получили. Веб-репозиторий и монорепозиторий All Platforms поставляют сценарий, compose-файлы, `scripts/setup-env.mjs` и `prompts/`. Отдельные репозитории Mobile и Desktop поставляют ограниченный `llms.txt`, `AGENTS.md`, зеркальные документы `.ai/` и отобранные документы, включая `docs/agent-security.md`, — но не сценарий настройки и compose-файлы, потому что бэкенд, с которым общаются эти приложения, живёт в веб-репозитории.

[Пройдите настройку под управлением агента](https://supastack.dev/ru/docs/web/agent-setup.md)


## Как агент помнит между сессиями

У агентов нет памяти между сессиями — папка `.ai/` и есть память. `.ai/PROJECT_CONTEXT.md` записывает, что недавно изменилось и почему. Рядом зеркальный документ, такой как `.ai/apps/web/src/reports.md`, объясняет решения за `apps/web/src/reports.ts`, которые один код не показывает.

Контракт прост: читайте зеркало файла перед его редактированием и обновляйте зеркало, когда изменение принято. Записи Open Threads фиксируют незавершённую работу, чтобы следующая сессия продолжила, а не начала заново. Устаревшее зеркало хуже его отсутствия — просматривая diff агента, проверьте, что зеркала изменённых файлов сдвинулись вместе с ним.


## Собственная поверхность запущенного приложения для агентов

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

- `GET /llms.txt` — приложение отдаёт собственный индекс llmstxt.org: руководства, публичные страницы и публичные конечные точки с абсолютными URL.
- `POST /api/mcp` — конечная точка MCP без состояния, предоставляющая инструменты приложения. Она принимает ключи `sk_` только как bearer-токены — сессии браузерных cookie никогда не применяются. Создавайте ключи в Settings → Developers.
- `GET /api/v1/openapi` — спецификация OpenAPI публичного REST API для генераторов клиентов и инструментов агентов.
- `GET /api/health` — проба живости и зависимостей, которую вызывают балансировщики нагрузки и проверки доступности; она сообщает виды конфигурации провайдеров, но никогда секреты.
- `/status` — человекочитаемая страница, сообщающая о состоянии каждой подсистемы.


## Честно проверяйте работу агента

Завершённая задача — это доказательства, а не пересказ. Прежде чем оставить работу агента, проверьте её так, как `docs/agent-security.md` проверяет развёртывание:

Когда что-то не так, отправьте diff обратно — агент исправляет свою работу быстрее всего, когда вы называете упавшую проверку. О том, что ему никогда не следовало пытаться делать в одиночку, скажите явно один раз — граница действует до конца сессии.

[Проверочные шлюзы и набор тестов](https://supastack.dev/ru/docs/web/testing.md)

- Он действительно запускал тесты, о которых заявляет, — попросите команду и её вывод, а не заключение.
- Секреты остались только на сервере — ничего нового не несёт префикс `NEXT_PUBLIC_` или `EXPO_PUBLIC_`, и ни один ключ не был напечатан в отчёт или коммит.
- Каждое чтение и запись пользовательских данных осталось ограниченным `workspaceId` — ни один запрос не доверяет id, присланному браузером.
- Зеркало `.ai/` каждого изменённого файла сдвинулось вместе с кодом.
- Публикация, развёртывание и платные вызовы провайдеров остались отдельными шагами, которые вы одобрили, — агент никогда не сливал, не пушил и не развёртывал самостоятельно.
- Если шаг упал дважды, он остановился и доложил упавшую команду вместо импровизации вокруг неё.


Чтобы продолжить настройку, прочитайте [Создайте внешние аккаунты](https://supastack.dev/ru/docs/web/external-accounts.md).


## Вперёд

[Создайте внешние аккаунты](https://supastack.dev/ru/docs/web/external-accounts.md)