# AI-первый workflow разработки

> Основан на уроках статьи Джеймса Луана (Zilliz) о провале с Claude Code на 2M строк
> и собственном опыте MyFitCRM (двойной крах прода от `pnpm build`).

## Принцип: ИИ эффективен для малых, чётко определённых задач

ИИ генерирует "чистые" решения, которые выглядят аккуратно, но ломают смежные подсистемы.
Чем больше scope задачи — тем выше риск каскадных поломок.

**Антипаттерн:** "Сделай экран клиентов" → 100+ файлов, сломанные типы в 3 панелях.
**Паттерн:** Декомпозиция на слои, каждый проверяем отдельно.

---

## 1. Формат задачи: Ограничения ДО кода

Каждая задача (из Telegram, спринта, или ручная) должна содержать **Definition of Done** до начала работы.

### Шаблон задачи

```
📋 Задача #N: [название]

Контекст: [зачем нужно, какую проблему решает]

Scope:
- [ ] Конкретное изменение 1
- [ ] Конкретное изменение 2

Definition of Done:
- [ ] typecheck всех затронутых apps проходит
- [ ] Существующие E2E тесты не ломаются
- [ ] [специфичные критерии для задачи]

Ограничения:
- НЕ трогать: [список файлов/модулей вне scope]
- Максимум файлов: [число или "без ограничений"]
```

### Примеры хорошей vs плохой постановки

| Плохо                         | Хорошо                                                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Сделай экран клиентов"       | "Добавь GET /clients с фильтрацией по club_id. DTO: ClientListDto (page, limit, search). 3 теста: RBAC trainer видит своих, coordinator — всех в клубе, super_admin — всех. typecheck api после." |
| "Исправь баг с уведомлениями" | "В NotificationCard.tsx при status=read иконка не меняет цвет. Исправить условие в строке ~45. Проверить: typecheck mobile, визуально в Expo."                                                    |
| "Добавь SIP"                  | "Добавь SIP-модуль: 1) Prisma-модель SipAccount. 2) CRUD-эндпоинты с ModuleGuard('sip'). 3) Unit-тесты guard. DoD: migrate dev, typecheck api, test api."                                         |

---

## 2. Test-First: тесты → код → проверка

### Порядок работы

```
1. Напиши тест (что должно работать)
2. Убедись что тест падает (red)
3. Реализуй минимальный код (green)
4. typecheck + lint
5. Коммит
```

### Что тестировать в первую очередь

| Приоритет | Что                     | Как                                              |
| --------- | ----------------------- | ------------------------------------------------ |
| Критично  | RBAC (6 ролей)          | E2E: запрос от каждой роли, проверка 200/404     |
| Критично  | Multi-tenancy (club_id) | Unit: filterByRole возвращает только свои записи |
| Высокий   | API-контракты           | Supertest: статусы, формат ответа, пагинация     |
| Высокий   | Бизнес-логика           | Unit: воронка, конверсия, статусы сделок         |
| Средний   | UI-компоненты           | React Testing Library: рендер, клики, состояния  |

### Валидация результата

Проверяй **тесты**, не код. Если все тесты зелёные и typecheck проходит — код корректен.
Ревью кода глазами нужно только для:

- Безопасность (SQL-инъекции, XSS, HMAC)
- Архитектурные решения (новые зависимости, паттерны)
- Multi-tenancy (club_id в WHERE)

---

## 3. Слой за слоем: декомпозиция изменений

### Порядок слоёв (снизу вверх)

```
Слой 1: Зависимости     → package.json, pnpm-lock.yaml
Слой 2: Схема данных    → schema.prisma, миграции
Слой 3: API-контракты   → DTO, контроллеры, swagger
Слой 4: Бизнес-логика   → Сервисы, guards, pipes
Слой 5: Фронтенд API    → React Query хуки, типы
Слой 6: UI-компоненты   → Экраны, карточки, формы
Слой 7: Интеграция       → E2E тесты, typecheck всех apps
```

### Правила

1. **Один слой = один коммит** с осмысленным сообщением
2. **Проверка после каждого слоя:**

| Слой         | Проверка                                                |
| ------------ | ------------------------------------------------------- |
| Prisma-схема | `prisma validate` + `prisma generate` + `typecheck api` |
| API-эндпоинт | `test api` (unit) + `typecheck api`                     |
| Фронтенд хук | `typecheck mobile` / `typecheck web-admin` / etc.       |
| UI-компонент | `typecheck` + визуальная проверка (Expo / browser)      |
| Финал        | `pnpm typecheck` (все apps) + `test:e2e`                |

3. **Максимум 20 файлов на коммит** — если больше, декомпозируй дальше
4. **Никогда не пропускай typecheck** — это единственная защита от каскадных поломок

---

## 4. Автоматический quality gate

### Pre-merge чеклист

Перед мёрджем любых изменений в main (автоматически или вручную):

```bash
# Обязательно (блокирует merge)
pnpm --filter api typecheck          # API типы
pnpm --filter mobile typecheck       # Mobile типы
pnpm --filter web-admin typecheck    # Рецепция типы
pnpm --filter web-club-admin typecheck  # Админ клуба типы
pnpm --filter web-platform-admin typecheck  # Суперадмин типы
pnpm --filter api test               # Unit-тесты API

# Рекомендовано (предупреждение, не блокирует)
pnpm --filter api test:e2e           # E2E тесты API
pnpm lint                            # Линтинг всего
```

### НИКОГДА не запускать

```bash
pnpm build          # Удаляет .next/ — крашит dev-сервер
next build          # То же самое
```

### Интеграция с safety.md

Quality gate встроен в протокол безопасного мёрджа (safety.md, Слой 4):

- Шаг 3: `pnpm lint` → расширить до `pnpm typecheck` (все apps)
- Шаг 4: `pnpm --filter api test` → оставить
- Добавить шаг 4.5: `pnpm typecheck` — кросс-проектная проверка типов

---

## 5. Telegram-workflow: усиленный шаблон

### Получение задачи

```
Пользователь: "Добавь фильтрацию клиентов по дате рождения"

Claude отвечает:
📋 Задача #N: Фильтрация клиентов по дате рождения

План (слой за слоем):
1. 🗃 Prisma: добавить индекс на Client.birthDate
2. 🔌 API: расширить ClientListDto полями birthDateFrom/birthDateTo
3. 🧪 Тест: 2 кейса — фильтрация по диапазону, пустой результат
4. 📱 Mobile: добавить DatePicker в фильтры экрана клиентов
5. ✅ Финал: typecheck всех apps

Definition of Done:
- GET /clients?birthDateFrom=...&birthDateTo=... возвращает корректные результаты
- typecheck api + mobile проходит
- Существующие E2E тесты не ломаются

Утверждаем план?
```

### После утверждения — послойное выполнение

Каждый слой = коммит + проверка. Отчёт по завершении:

```
✅ Задача #N выполнена

Коммиты:
1. feat(prisma): индекс на Client.birthDate
2. feat(api): фильтрация клиентов по дате рождения + 2 теста
3. feat(mobile): DatePicker в фильтрах клиентов

Проверки:
✅ typecheck api
✅ typecheck mobile
✅ test api (47 passed)
✅ test:e2e (143 passed)
```

---

## 6. Антипаттерны (чего избегать)

| Антипаттерн                         | Почему плохо                                               | Что делать                                                 |
| ----------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
| Один коммит на 50+ файлов           | Невозможно откатить частично, сложно найти причину поломки | Слой за слоем, max 20 файлов                               |
| "Исправь все ошибки TypeScript"     | Каскад: фикс одной ошибки создаёт три новых                | Фиксить по одному модулю, проверять после каждого          |
| Код без тестов                      | Нет способа проверить корректность кроме ручного ревью     | Test-first: тест → код → проверка                          |
| `pnpm build` на dev-сервере         | Удаляет .next/, крашит сайт если build упадёт              | `pnpm typecheck` — безопасная альтернатива                 |
| Изменение API без обновления фронта | Фронты получают runtime-ошибки                             | Слой за слоем: API → типы → фронт, typecheck после каждого |
| "Рефакторинг заодно"                | Увеличивает scope, маскирует баги                          | Рефакторинг = отдельная задача с отдельным коммитом        |

---

## 7. Метрики качества процесса

| Метрика                 | Цель          | Как измерить                  |
| ----------------------- | ------------- | ----------------------------- |
| Файлов на коммит        | ≤ 20          | `git diff --stat HEAD~1`      |
| typecheck после коммита | 100%          | Автоматический gate           |
| Тесты перед мёрджем     | 100% passed   | CI / ручной прогон            |
| Откатов прода           | 0 в неделю    | Счётчик `pre-chatbot-*` тегов |
| Время на задачу         | Предсказуемое | Декомпозиция снижает variance |

---

## Связанные документы

- [multi-agent.md](multi-agent.md) — Мультиагентный workflow, worktrees, фазы
- [safety.md](safety.md) — Изоляция чатбота, pre-commit хуки, merge-протокол, откат
- [sprints.md](sprints.md) — Спринты и приоритеты
