# Универсальный стартовый шаблон документации ИИ агентов (AI)

Этот репозиторий — универсальный стартовый шаблон для проектной документации и профилей ИИ‑агентов. Используйте его как основу для новых проектов: адаптируйте структуру разделов, правила, профили агентов и технические рекомендации под ваш домен.

**Текущий статус:** Phase 0 (Planning) — стартовый шаблон (наполните деталями под ваш проект).

---

## Что входит в шаблон
- Базовая структура документации (`/docs`) и индекс навигации.
- Папка `agents/` с примерами профилей агентов (frontend/backend/code‑review/prompt‑engineer) и общими правилами (`RULES.md`).
- Рекомендации по архитектуре фронтенда/бэкенда, безопасности, API‑дизайну и оплатам (провайдер‑агностично).
- Примеры практик: мультиарендность, очереди фоновых задач, event‑лог, explainability (`reasoning_trace`) — адаптируйте под свой домен или удалите лишнее.
- Предложенный стек: Next.js (TypeScript, Tailwind, React Query/SWR) на фронте; Node.js + Express/Fastify, Prisma/Drizzle, Postgres (+опц. `pgvector`) на бэкенде; Docker для деплоя.

---

## Фазы (как основа для планирования)
- **Phase 0 — Discovery & Requirements:** зафиксируйте цели/аудиторию, требования и стек.
- **Phase 1 — Architecture & Design:** детализируйте архитектуру, API, схемы данных, очереди/события.
- **Phase 2 — MVP Implementation:** реализуйте ключевые потоки, UI/UX, интеграции, биллинг (если нужен).
- **Phase 3 — Improvements & Scaling:** качество, производительность, безопасность, наблюдаемость.
- **Phase 4 — Support & Evolution:** поддержка, релизы, эволюция фич.

---

## Навигация по документации
- **Общие документы (`/docs`):**  
  [`docs/project-overview.md`](docs/project-overview.md) — обзор проекта (шаблон); [`docs/phases-plan.md`](docs/phases-plan.md) — план по фазам; [`docs/content-structure.md`](docs/content-structure.md) — структура контента/страниц.
- **Frontend (`/docs/frontend`)** — обзор, архитектура (feature‑first), UX/UI гайды, SEO/performance.
- **Backend (`/docs/backend`)** — обзор, архитектура (модульный монолит), API design, security, payment flow (провайдер‑агностично), события и вебхуки.
- **Индексы/правила:** [`DOCS.md`](DOCS.md) — индекс документации; [`RULES.md`](RULES.md) и папка [`agents/`](agents/) — правила и профили агентов.

---

## Как использовать шаблон
- **Быстрый старт:** прочитайте `docs/project-overview.md` и `docs/phases-plan.md` — адаптируйте под ваш проект.
- **Технический дизайн:** используйте `docs/frontend/architecture.md` и `docs/backend/architecture.md`; для API и безопасности — `docs/backend/api-design.md` и `docs/backend/security.md`; оплаты — `docs/backend/payment-flow.md` (как пример/рыбу).
- **Работа с агентами:** перед задачей проверяйте `RULES.md` и профиль соответствующего агента в `agents/`.
- **Внесение изменений:** обновляйте документы при принятии решений; для новых подсистем добавляйте файлы в `docs/` (предпочтительно — английский).