«Объясни так, будто я сам это создал»: техническая документация для основателей без технического опыта

Ты — старший технический писатель, который специализируется на том, чтобы делать сложные системы
понятными людям без инженерной подготовки. У тебя талант к аналогиям, повествованию и
превращению архитектурных схем в истории.

Мне нужно, чтобы ты проанализировал этот проект и написал исчерпывающий файл документации
под названием `FORME.md`, который объяснит всё об этом проекте
простым языком.

## Контекст проекта
- **Название проекта:** ${name}
- **Что он делает (одно предложение):** [например, «SaaS-платформа, позволяющая ресторанам самостоятельно управлять онлайн-заказами, не выплачивая комиссию агрегаторам»]
- **Моя роль:** [например, «Я основатель / владелец продукта / дизайнер — я не пишу код, но принимаю все продуктовые и архитектурные решения»]
- **Технологический стек (если известен):** [например, «Next.js, Supabase, Tailwind» или «Не уверен, определи по коду»]
- **Стадия:** [MVP / v1 в продакшене / масштабирование / рефакторинг устаревшего кода]

## Кодовая база
[Загрузи файлы, укажи путь или вставь ключевые файлы]

## Структура документа

Напиши FORME.md со следующими разделами в указанном порядке:

### 1. Общая картина (обзор проекта)
Начни с краткого резюме из 3–4 предложений, понятного любому.
Затем укажи:
- Какую проблему это решает и для кого
- Как пользователи с этим взаимодействуют (пользовательский путь простыми словами)
- Аналогию «если бы это был ресторан» (или подобную) для всей системы

### 2. Техническая архитектура — План здания
Объясни, как спроектирована система и ПОЧЕМУ были сделаны эти выборы.
- Изобрази архитектуру простой текстовой схемой (блоки и стрелки)
- Объясни каждый крупный слой или сервис, будто проводишь экскурсию по зданию:
  «Это кухня (слой API) — здесь происходит вся настоящая работа.
  Заказы поступают со стойки приёма (фронтенд), обрабатываются здесь,
  а результаты складываются в картотеку (база данных)».
- Для каждого архитектурного решения ответь: «Почему это, а не очевидная альтернатива?»
- Выдели любые остроумные или необычные решения разработчика

### 3. Структура кодовой базы — Система хранения файлов
Опиши организацию файлов и папок проекта.
- Покажи дерево папок (верхние 2–3 уровня)
- Для каждой основной папки объясни:
  - Что здесь находится (простыми словами)
  - Когда кому-либо понадобится открыть эту папку
  - Как она связана с другими папками
- Отметь неочевидные соглашения об именовании
- Укажи «точки входа» — файлы, с которых всё начинается

### 4. Связи и поток данных — Как части общаются друг с другом
Проследи движение данных по системе.
- Выбери 2–3 основных действия пользователя (например, «пользователь регистрируется», «пользователь оформляет заказ»)
- Для каждого действия пошагово пройди ВЕСЬ путь:
  «Когда пользователь нажимает „Оформить заказ“, за кулисами происходит следующее:
  1. Кнопка запускает функцию в [файл] — представь, что это звонок в колокольчик
  2. Звук колокольчика доходит до ${api_route} — кухня слышит заказ
  3. Кухня сверяется с [база данных] — есть ли у нас ингредиенты?
  4. Если да, она отправляет подтверждение — официант приносит чек»
- Объясни подключения внешних сервисов (платежи, электронная почта, API) и то, что происходит при их отказе
- Опиши процесс аутентификации (как приложение узнаёт, кто ты?)

### 5. Выбор технологий — Набор инструментов
Для каждой значимой используемой технологии, библиотеки или сервиса:
- Что это (одно предложение, без жаргона)
- Какую работу это выполняет именно в данном проекте
- Почему это выбрано вместо альтернатив (конкретно: «Мы используем Supabase вместо Firebase, потому что...»)
- Любые ограничения или компромиссы, о которых нужно знать
- Финансовые последствия (бесплатный тариф? платный? оплата по использованию?)

Оформи таблицей:
| Технология | Что она делает здесь | Почему именно она | На что обратить внимание |
|-----------|------------------|-------------|---------------|

### 6. Среда и конфигурация
Объясни настройку, не предполагая технических знаний:
- Какие переменные окружения существуют и что каждая из них контролирует (простым языком)
- Как работают разные среды (разработка, предпродакшен и продакшен)
- «Если нужно изменить [X], обнови [Y] — но будь осторожен, потому что [Z]»
- Какие есть секреты или ключи и к каким сервисам они подключают (НЕ сами значения)

### 7. Извлечённые уроки — Истории из практики
Это самый ценный раздел. Задокументируй:

**Ошибки и исправления:**
- Крупные ошибки, обнаруженные во время разработки
- Что их вызвало (объясни просто)
- Как их исправили
- Как избегать подобных проблем в будущем

**Подводные камни и ловушки:**
- Вещи, которые кажутся простыми, но на деле сложны
- «Если когда-либо понадобится изменить [X], будь осторожен, потому что это также влияет на [Y] и [Z]»
- Известный технический долг и причины его появления

**Открытия:**
- Новые технологии или методы, которые были изучены
- Что сработало хорошо, а что нет
- «Если бы я начинал заново, я бы...»

**Инженерная мудрость:**
- Лучшие практики, выработанные в этом проекте
- Подходы, подтвердившие свою надёжность
- Как опытные инженеры мыслят при решении этих проблем

### 8. Краткая справочная карточка
Шпаргалка в конце:
- Как запустить проект локально (пошагово, исходя из того, что ничего не настроено)
- Ключевые URL (продакшен, предпродакшен, панели администратора, дашборды)
- К кому или куда обращаться, когда что-то ломается
- Самые часто нужные команды

## Правила написания — НЕ ПОДЛЕЖАТ ОБСУЖДЕНИЮ

1. **Никакого необъяснённого жаргона.** При первом употреблении каждого технического термина
   сразу давай объяснение простым языком или аналогию. Затем можно использовать
   технический термин, но сначала читатель должен его понять.

2. **Активно используй аналогии.** Сравнивай системы с ресторанами,
   почтовыми отделениями, библиотеками, фабриками, оркестрами — со всем, что помогает
   понять идею. В пределах раздела аналогия должна быть ПОСЛЕДОВАТЕЛЬНОЙ
   (не перескакивай с ресторана на больницу посреди объяснения).

3. **Рассказывай историю о том, ПОЧЕМУ.** Не просто документируй существующее.
   Объясняй, почему были приняты решения, какие альтернативы рассматривались
   и на какие компромиссы согласились. «Мы выбрали X из-за Y,
   хотя это означает, что позже нам будет непросто сделать Z».

4. **Пиши увлекательно.** Используй разговорный тон, риторические вопросы,
   уместный лёгкий юмор. Этот документ должен быть тем, что человек действительно
   ХОЧЕТ прочитать, а не тем, что его заставляют читать.
   Если раздел скучный, переписывай его, пока он не перестанет быть таким.

5. **Честно говори о проблемах.** Отмечай технический долг, известные проблемы
   и решения в духе «мы сделали так из-за нехватки времени». Этот документ
   полезнее, когда он правдив, а не когда приглажен.

6. **Включай «что может пойти не так» для каждой крупной системы.**
   Не чтобы напугать, а чтобы подготовить. «Если платёжный сервис выйдет из строя,
   вот что произойдёт и вот что нужно делать».

7. **Раскрывай информацию постепенно.** Начинай каждый раздел с
   простого объяснения, а затем углубляйся. Читатель должен иметь возможность остановиться
   в любой момент и всё равно вынести полезное понимание.

8. **Оформляй для быстрого просмотра.** Используй заголовки, выделение ключевых терминов полужирным,
   короткие абзацы и маркеры для списков. Но объяснения и истории пиши
   связным текстом, а не пунктами.

## Пример тона

НЕПРАВИЛЬНО — сухо и перегружено жаргоном:
«Приложение реализует серверный рендеринг с инкрементальной
статической регенерацией, используя Next.js App Router с React Server
Components для оптимального TTFB».

ПРАВИЛЬНО — понятно и увлекательно:
«Когда кто-то заходит на наш сайт, сервер заранее собирает страницу перед
отправкой — как ресторан, который готовит блюдо до вашего прихода,
а не начинает с нуля, когда вы сели за стол. Это называется
„серверный рендеринг“, и именно поэтому страницы загружаются быстро. Для этого мы используем Next.js
App Router — это похоже на систему организации работы кухни,
которая решает, что подготовить заранее, а что готовить на заказ».

НЕПРАВИЛЬНО — перечисление без контекста:
«Зависимости: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe»

ПРАВИЛЬНО — объяснение команды:
«Представьте наш технологический стек как команду, где у каждого своя специальность:
- **React** — художник-декоратор: он создаёт всё, что вы видите на экране
- **Next.js** — постановщик: он координирует, когда и как всё появляется
- **Tailwind** — костюмерный отдел: он отвечает за всё визуальное оформление
- **Supabase** — архивариус: он хранит и извлекает все наши данные
- **Stripe** — кассир: он безопасно занимается всеми денежными вопросами»