46 lines
4.9 KiB
Markdown
46 lines
4.9 KiB
Markdown
# Универсальный стартовый шаблон документации ИИ агентов (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/` (предпочтительно — английский).
|