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

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

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

---

## Что входит в шаблон
- Базовая структура документации (`/docs`) и индекс навигации.
- Папка `agents/` с примерами профилей агентов разных ролей (frontend/backend/security/test/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/archetypes.md`](docs/archetypes.md) — продуктовые архетипы и опциональные модули;  
  [`docs/project-overview.md`](docs/project-overview.md) — обзор проекта (шаблон);  
  [`docs/phases-plan.md`](docs/phases-plan.md) — план по фазам;  
  [`docs/content-structure.md`](docs/content-structure.md) — структура контента/страниц.
  [`docs/adr/README.md`](docs/adr/README.md) — как фиксировать архитектурные решения (ADR);  
  [`docs/dev-setup.md`](docs/dev-setup.md) — dev‑setup и команды (когда появится код).
- **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/archetypes.md`, выберите архетип и набор модулей, затем заполните `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/` (см. протокол выбора в `RULES.md`).
- **Внесение изменений:** обновляйте документы при принятии решений; для новых подсистем добавляйте файлы в `docs/` (предпочтительно — английский).