DESIGN MODE — Режим проектирования

Версия: 1.0
Дата создания: 2025-11-10

ЧТО ЭТО?

Режим для работы с документацией и проектированием систем.

Когда использовать:
- Начало нового проекта
- Проектирование архитектуры
- Обновление документации
- Анализ требований
- Roadmap planning
- ADR (Architecture Decision Records)

ПРАВИЛА РЕЖИМА

✅ ЧТО ДЕЛАЕМ:

Работа с документами:
- design/PROJECT.md — описание проекта, цели, scope
- design/ROADMAP.md — план версий и фич
- design/ARCHITECTURE.md — архитектурные решения (ADR)
- design/MODELS.md — модели данных
- management/README.md — Quick Start
- management/CHANGELOG.md — история изменений

Анализ и планирование:
- Декомпозиция задач
- Анализ требований
- Проектирование БД
- API дизайн
- UX flows
- Выбор технологий

❌ ЧТО НЕ ДЕЛАЕМ:

НЕ пишем код (для этого Code Mode)
НЕ запускаем приложения
НЕ деплоим
НЕ работаем с БД напрямую

СТРУКТУРА ДОКУМЕНТАЦИИ

design/ — Проектирование

design/
├── PROJECT.md          # Главный документ проекта
├── ROADMAP.md          # План развития
├── ARCHITECTURE.md     # Архитектурные решения
├── MODELS.md           # Модели данных
├── API.md              # API спецификация
└── adr/                # Architecture Decision Records
    ├── 001-выбор-фреймворка.md
    ├── 002-структура-БД.md
    └── ...

management/ — Управление

management/
├── README.md           # Quick Start + текущее состояние
├── CHANGELOG.md        # История изменений
├── TODO.md             # Текущие задачи
└── ISSUES.md           # Известные проблемы

ПРОЦЕДУРЫ

ПРОЦЕДУРА: Начать проектирование

Вход: Идея проекта от пользователя

Шаги:

Собрать требования:
- Что делает система?
- Кто пользователи?
- Ключевые функции?
- Ограничения?
Создать PROJECT.md:
```markdown
# Проект: [НАЗВАНИЕ]

## Описание

[Краткое описание в 2-3 предложениях]

## Цель

[Зачем создаём?]

## Scope (Что включено)

Функция 1
Функция 2
Функция 3

## Out of Scope (Что НЕ включено)

Не делаем X
Не делаем Y

## Пользователи

Роль 1 — описание, потребности
Роль 2 — описание, потребности

## Метрики успеха

Метрика 1: целевое значение
Метрика 2: целевое значение

## Технологии (предварительно)

Frontend: [фреймворк]
Backend: [фреймворк]
Database: [СУБД]
Hosting: [платформа]

## Риски

Риск 1 — вероятность, влияние, митигация
Риск 2 — вероятность, влияние, митигация

## Timeline (предварительно)

Week 1-2: Проектирование
Week 3-4: MVP разработка
Week 5: Тестирование
Week 6: Деплой

## Зависимости

Внешний сервис 1
Библиотека 2

## Контакты

Product Owner: [имя]
Tech Lead: [имя]
```

Создать ROADMAP.md:
```markdown
# Roadmap: [ПРОЕКТ]

## v0.1 — POC (Proof of Concept)
Цель: Проверить основную гипотезу
Срок: 1-2 недели

Фичи:
- [ ] Базовая функция X
- [ ] Минимальный UI

## v1.0 — MVP
Цель: Запуск для первых пользователей
Срок: 4-6 недель

Фичи:
- [ ] Функция 1
- [ ] Функция 2
- [ ] Авторизация
- [ ] База данных

## v2.0 — Production
Цель: Полнофункциональная система
Срок: 3-4 месяца

Фичи:
- [ ] Расширенная функция 1
- [ ] Интеграции
- [ ] Аналитика
- [ ] API
```

Создать ARCHITECTURE.md с первым ADR:
```markdown
# Архитектура: [ПРОЕКТ]

## Общая схема

[ASCII диаграмма или описание]

## ADR (Architecture Decision Records)

### [ADR-001] Выбор основного фреймворка

Дата: 2025-11-10
Статус: Принято

Контекст:
Нам нужен фреймворк для быстрой разработки MVP дашборда.

Рассмотренные варианты:
1. Streamlit — быстрый старт, Python only
2. React + FastAPI — больше контроля, дольше разработка
3. Django — all-in-one, heavier

Решение:
Используем Streamlit для MVP.

Обоснование:
- Быстрая разработка (1-2 недели до MVP)
- Команда знает Python
- Встроенные компоненты
- Для MVP достаточно

Последствия:
✅ Плюсы:
- Быстрый time-to-market
- Простая поддержка

⚠️ Минусы:
- Ограниченная кастомизация UI
- Может потребоваться переписать для Production

Альтернативы на будущее:
- v2.0: Возможно переход на React + FastAPI
```

Создать README.md:
```markdown
# [ПРОЕКТ] — Quick Start

## Что это?

[Краткое описание]

## Статус

Версия: 0.1 (проектирование)
Последнее обновление: 2025-11-10

## Документация

design/PROJECT.md — описание проекта
design/ROADMAP.md — план развития
design/ARCHITECTURE.md — архитектура

## Начать работу

[Инструкции появятся после начала разработки]

## Контакты

[Команда]
```

Git commit:
bash git add projects/{name}/design/ git add projects/{name}/management/ git commit -m "docs: начато проектирование проекта {name}"

Выход:
- Полная структура документации
- Чёткое понимание проекта
- Готовность к Code Mode

ПРОЦЕДУРА: Добавить ADR (Architecture Decision Record)

Когда использовать:
- Принято важное архитектурное решение
- Выбрана технология
- Изменена структура БД
- Изменён подход к задаче

Шаги:

Определить номер ADR (следующий по порядку)
Создать файл design/adr/{номер}-{название}.md
Использовать шаблон:

# [ADR-{номер}] {Название решения}

**Дата:** YYYY-MM-DD
**Статус:** Предложено / Принято / Отклонено / Устарело / Заменено

**Контекст:**
[Какая проблема/ситуация требует решения?]

**Рассмотренные варианты:**
1. Вариант 1 — краткое описание
2. Вариант 2 — краткое описание
3. Вариант 3 — краткое описание

**Решение:**
[Что выбрали и почему?]

**Обоснование:**
- Причина 1
- Причина 2
- Причина 3

**Последствия:**

✅ **Плюсы:**
- Плюс 1
- Плюс 2

⚠️ **Минусы:**
- Минус 1
- Минус 2

🔄 **Требуемые изменения:**
- Изменение 1
- Изменение 2

**Альтернативы:**
[Когда может потребоваться пересмотр?]

**Связанные ADR:**
- ADR-XXX — название

Обновить design/ARCHITECTURE.md — добавить ссылку на ADR
Git commit:
bash git add design/adr/{номер}*.md git commit -m "docs: добавлен ADR-{номер} {название}"

ПРОЦЕДУРА: Обновить ROADMAP

Когда использовать:
- Завершена версия
- Изменились приоритеты
- Добавлены новые фичи
- Удалены неактуальные фичи

Шаги:

Открыть design/ROADMAP.md
Для завершённой версии:
```markdown
## v1.0 — MVP ✅ ВЫПУЩЕН
Дата выпуска: 2025-11-09
Цель: Первый запуск ✓

Фичи:
- [x] Функция 1
- [x] Функция 2
- [x] Авторизация
```

Для текущей разработки:
```markdown
## v1.1 — Улучшения 🔄 В РАБОТЕ
Цель: Улучшить UX
Планируемый срок: 2025-11-20

Фичи:
- [x] Фильтры в таблице ✓
- [ ] Экспорт в Excel 🔄 (50%)
- [ ] Push уведомления
```

Для будущих версий:
```markdown
## v2.0 — Production 📋 ЗАПЛАНИРОВАНО
Цель: Полная версия
Планируемый срок: Q1 2026

Фичи:
- [ ] API для интеграций
- [ ] Мобильное приложение
- [ ] Продвинутая аналитика
```

Git commit:
bash git add design/ROADMAP.md git commit -m "docs: обновлён roadmap - завершён v1.0"

ПРОЦЕДУРА: Синхронизация docs ↔ code

Проблема:
Документация устаревает, код расходится с планом.

Решение:
Периодическая проверка соответствия.

Шаги:

Проверить PROJECT.md:
- Scope актуален?
- Технологии соответствуют?
- Цели не изменились?
Проверить ROADMAP.md:
- Что реально реализовано в коде?
- Обновить статусы фич
- Перепланировать нереализованное
Проверить ARCHITECTURE.md:
- ADR соответствуют текущей архитектуре?
- Нужны новые ADR для новых решений?
Обновить CHANGELOG.md:
- Все изменения задокументированы?
- Версии соответствуют релизам?
Создать отчёт:
```markdown
## Аудит документации 2025-11-10

✅ Актуально:
- PROJECT.md соответствует коду
- ROADMAP.md обновлён

⚠️ Требует обновления:
- ARCHITECTURE.md: добавить ADR-005 о новой БД
- README.md: обновить Quick Start

🔄 Действия:
- [ ] Добавить ADR-005
- [ ] Обновить README
```

МНОГОСРЕЗОВЫЙ АНАЛИЗ В ДИЗАЙНЕ

При проектировании использовать 8 срезов:

1. 🏗️ СТРУКТУРНЫЙ

Из каких модулей состоит?
Как связаны компоненты?
Границы модулей?

2. ⚡ ФУНКЦИОНАЛЬНЫЙ

Какие функции система выполняет?
Use cases
User flows

3. 🔄 ПРОЦЕССНЫЙ

Как создаём?
Этапы разработки
CI/CD pipeline

4. 👥 РОЛЕВОЙ

Кто пользователи?
Роли в системе
Права доступа

5. 🔧 ТЕХНИЧЕСКИЙ

Какие технологии?
API
Интеграции

6. 📊 ИНФОРМАЦИОННЫЙ

Модели данных
Потоки данных
Хранилища

7. ⏰ ВРЕМЕННОЙ

Roadmap
История (git)
Планы

8. 🌍 ПРОСТРАНСТВЕННЫЙ

Где развёрнуто?
Серверы
Регионы

ШАБЛОНЫ ДОКУМЕНТОВ

PROJECT.md

См. "ПРОЦЕДУРА: Начать проектирование" выше

MODELS.md

# Модели данных: [ПРОЕКТ]

## Схема БД

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    status VARCHAR(50) NOT NULL,
    total DECIMAL(10, 2),
    created_at TIMESTAMP DEFAULT NOW()
);

ER диаграмма

[Текстовая ER диаграмма или ссылка на изображение]

Описание моделей

User

Назначение: Пользователи системы
Связи:
1:N → Orders

Order

Назначение: Заказы
Связи:
N:1 → User

Индексы

CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_status ON orders(status);

Миграции

История изменений схемы в /solution/mvp/migrations/

### API.md

```markdown
# API Спецификация: [ПРОЕКТ]

## Base URL

Production: https://api.example.com/v1
Staging: https://staging-api.example.com/v1

## Аутентификация

```http
Authorization: Bearer {token}

Endpoints

GET /users

Получить список пользователей.

Query Parameters:
- limit (int, optional) — количество, default: 10
- offset (int, optional) — смещение, default: 0

Response 200:

{
  "users": [
    {
      "id": 1,
      "email": "user@example.com",
      "created_at": "2025-11-10T12:00:00Z"
    }
  ],
  "total": 100
}

Errors:
- 401: Unauthorized
- 500: Internal Server Error

POST /orders

Создать новый заказ.

Request Body:

{
  "user_id": 1,
  "items": [
    {"product_id": 10, "quantity": 2}
  ],
  "total": 299.99
}

Response 201:

{
  "order_id": 42,
  "status": "created",
  "created_at": "2025-11-10T12:05:00Z"
}

---

## ИНСТРУМЕНТЫ

### Диаграммы (ASCII art)

Для визуализации использовать ASCII art:

┌─────────────┐ ┌─────────────┐
│ Frontend │────────▶│ Backend │
│ (Streamlit)│ │ (FastAPI) │
└─────────────┘ └──────┬──────┘
│
▼
┌──────────────┐
│ PostgreSQL │
└──────────────┘

### Таблицы решений

| Критерий | Streamlit | React | Django |
|----------|-----------|-------|--------|
| Скорость разработки | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| Гибкость UI | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Python only | ✅ | ❌ | ✅ |
| Production ready | ⚠️ | ✅ | ✅ |

---

## КОНФИГУРАЦИЯ

```yaml
scope: project
mode: design

loaded_files:
  - design/PROJECT.md
  - design/ROADMAP.md
  - design/ARCHITECTURE.md
  - management/README.md

cascade_enabled: true
registry_enabled: true (для выбора технологий)

actions_allowed:
  - read_docs: true
  - write_docs: true
  - read_code: true (для анализа)
  - write_code: false
  - run_commands: false
  - deploy: false

journaling: true

ПЕРЕКЛЮЧЕНИЕ РЕЖИМА

В Code Mode:

Начать разработку
→ Переключение в Code Mode

В Overview Mode:

Показать статус проекта
→ Возврат в Overview

КРИТЕРИИ ЗАВЕРШЕНИЯ ДИЗАЙНА

Дизайн завершён когда:
- ✅ PROJECT.md содержит scope, цели, метрики
- ✅ ROADMAP.md содержит план минимум на v1.0
- ✅ ARCHITECTURE.md содержит минимум 2-3 ключевых ADR
- ✅ MODELS.md (если есть БД) содержит схему
- ✅ README.md содержит Quick Start
- ✅ Всё закоммичено в git

После этого можно переходить в Code Mode.

Текущий режим: Design Mode
Фокус: Документация и планирование
Code execution: Disabled