# 01. Производственный процесс разработки

**Назначение:** жёстко описать, какие этапы проходит каждая единица работы (фича / задача / фаза), какие артефакты обязательны на выходе, кто (какой агент) их производит и какой Quality Gate стоит между этапами.

---

## Простым языком

Любая работа — от мелкой правки кнопки до целого нового модуля — проходит **один и тот же конвейер из 7 этапов**. Этот конвейер **не сокращается** (даже маленькая правка получает мини-ТЗ и мини-тесты), но **может масштабироваться** — для тривиальных задач этапы выполняются за минуты, для крупных фич — за часы или дни.

Аналогия: производство автомобилей. На малолитражку и на грузовик — те же 7 цехов: проектное бюро → конструкторы → дизайнеры → сборка → ОТК → испытания → отгрузка. Никто не думает «эта малолитражка простая, давайте без ОТК». В софте та же логика: пропуск этапа на «простой» задаче — главный источник техдолга.

**Семь этапов:**

1. **Постановка** — заказчик пишет, чего хочет (1–5 предложений).
2. **Анализ** — агент-аналитик расшифровывает в БТ, ТЗ, тест-кейсы.
3. **Архитектура** — агент-архитектор решает, *как* это вписывается в систему.
4. **Дизайн UI/UX** — агент-дизайнер делает макеты (если задача затрагивает интерфейс).
5. **Разработка** — агент-разработчик пишет код и unit-тесты.
6. **Code Review** — агент-ревьюер проверяет код на соответствие ТЗ и стандартам.
7. **Тестирование** — агент-тестер прогоняет автотесты, e2e, UI-тесты, регресс.
8. **Внедрение** — деплой в test → prom, smoke-тесты, подтверждение пользователя.

(Этапов фактически 8, нумерация 0…7 ниже — этап «Постановка» — единственный человеческий, остальные машинные.)

Между каждой парой этапов стоит **Quality Gate** — автоматическая проверка. Если её не проходит — задача возвращается на тот этап, где обнаружилась проблема, не дальше.

---

## Технический язык

### 0. Этап «Постановка» (Inception)

**Кто делает:** человек-заказчик (вы). Единственный неавтоматизированный этап.

**Вход:** идея, дискомфорт, наблюдение, бизнес-возможность.

**Действие:** создание Work Item в Plane через интерфейс или Plane MCP. Минимум полей:
- `title` (≤80 символов)
- `description` — свободный текст, 1–10 предложений: «что» и «зачем», без «как».
- `priority` (low / medium / high / urgent)
- `project` (выбор из существующих)
- `labels` (опционально: `area:frontend`, `area:backend`, `area:infra`, `type:feature`, `type:bug`, `type:tech-debt`)

**Артефакт на выходе:** Work Item типа **Feature** в Plane с заполненным `description`.

**QG-0 → 1 (Inception → Analysis):**
- title заполнен и ≤80 символов
- description ≥3 предложений (минимум контекст «что» и «зачем»)
- задан `project` и `priority`

При прохождении QG-0 webhook Plane → Git создаёт:
- ветку `feature/<plane-id>-<slug>`
- 6 подзадач в Plane (Анализ, Архитектура, Дизайн, Разработка, Review, Тест, Внедрение) с шаблонными описаниями
- пустую папку `docs/work-items/<plane-id>/` в репозитории
- стартовый файл `docs/work-items/<plane-id>/00-business-request.md` с копией description

> **Важное упрощение:** этап «Дизайн» создаётся в шаблоне всегда, но если ТЗ не затрагивает UI, агент-аналитик помечает его `skip:not-applicable` и архитектор автоматически закрывает его без работы.

---

### 1. Этап «Анализ» (Analysis)

**Кто делает:** агент **Analyst** (LLM: Sonnet 4.6 или Qwen 3.6+, см. `04_agents_roles.md`).

**Вход:**
- `docs/work-items/<id>/00-business-request.md` (от заказчика)
- `CLAUDE.md` проекта (стек, конвенции, ссылки)
- `docs/architecture/` (текущее состояние архитектуры — для понимания контекста)
- `docs/work-items/` (другие активные задачи — для проверки на конфликты/дубли)

**Действие:**
1. Прочитать BR и контекст проекта.
2. Сформулировать **уточняющие вопросы**, если что-то неоднозначно. Записать в `docs/work-items/<id>/01-questions.md` и поставить статус `Plane: needs-clarification`. Дальше не идти.
3. После ответов заказчика — оформить:
   - **BRD** (бизнес-требования: цель, метрика успеха, scope, out-of-scope, стейкхолдеры).
   - **ТЗ** (функциональные и нефункциональные требования, сценарии, данные, ограничения).
   - **Customer Journey / Use Cases** (для пользовательских фич).
   - **Acceptance Criteria** в формате Gherkin (Given/When/Then) — будущая основа e2e-тестов.
   - **Test Plan** — список тест-кейсов (machine-readable YAML), включая UI-тесты, если фича затрагивает UI.
   - Пометку «затрагивает UI: yes/no» — определяет, понадобится ли этап Дизайна.
4. Запросить approve у заказчика через Plane (комментарий с reaction `:approved:`).

**Артефакты на выходе:**
- `docs/work-items/<id>/01-brd.md`
- `docs/work-items/<id>/02-trz.md`
- `docs/work-items/<id>/03-acceptance-criteria.md`
- `docs/work-items/<id>/04-test-plan.yaml`
- (опц.) `docs/work-items/<id>/05-customer-journey.md`

Все — с обязательным frontmatter (см. `02_repo_structure.md`).

**QG-1 → 2 (Analysis → Architecture):**
- все обязательные файлы есть и проходят `spec-linter` (наличие секций, ссылок, версий)
- `04-test-plan.yaml` валиден по JSON-schema
- в Plane на подзадаче «Анализ» стоит reaction `:approved:` от пользователя с ролью `Stakeholder`
- ссылка `BRD ↔ ТЗ ↔ Acceptance` валидна (нет осиротевших требований)

---

### 2. Этап «Архитектура» (Architecture)

**Кто делает:** агент **Architect** (LLM: Opus 4.7).

**Вход:** все артефакты этапа 1 + полный `docs/architecture/` проекта.

**Действие:**
1. Прочитать ТЗ, текущую архитектуру (C4 Context, Container, Component), список ADR.
2. **Проверить переиспользование** — нет ли уже существующих компонентов/сервисов, которые покрывают требование. Если есть — явно записать в ADR «использовать существующий X, не создавать Y».
3. Принять архитектурные решения и записать **ADR** (по одному на каждое решение, формат Найгарда).
4. Обновить C4-диаграммы (Mermaid в Markdown), если меняется состав компонентов.
5. Сформулировать:
   - **Требования к инфраструктуре** (новые сервисы, миграции, переменные окружения).
   - **Требования к данным** (изменения схемы БД, миграции).
   - **Требования к UI** (если есть UI: что должен уметь, какие состояния, какие данные).
   - **Технические риски** и план их митигации.
6. При несогласии с ТЗ — вернуть в Анализ с конкретным комментарием. **Не править ТЗ молча.**

**Артефакты на выходе:**
- `docs/work-items/<id>/06-adr/adr-NNNN-*.md` (один или несколько)
- обновлённые `docs/architecture/c4-*.mmd` (если применимо)
- `docs/work-items/<id>/07-infra-requirements.md`
- `docs/work-items/<id>/08-data-requirements.md`
- `docs/work-items/<id>/09-ui-requirements.md` (если затрагивает UI)
- `docs/work-items/<id>/10-tech-risks.md`

**QG-2 → 3 (Architecture → Design):**
- все обязательные ADR проходят `adr-linter` (формат, наличие разделов Context/Decision/Consequences/Status)
- Mermaid-диаграммы рендерятся (CI рендерит в SVG для проверки)
- каждое требование из ТЗ имеет **архитектурное покрытие** (linker проверяет, что для каждого `REQ-XX` из ТЗ есть упоминание в ADR или явная пометка «не требует архитектурного решения»)
- если этап Дизайна неприменим — архитектор ставит лейбл `skip:not-applicable` на соответствующую подзадачу

---

### 3. Этап «Дизайн UI/UX» (Design) — опциональный

**Кто делает:** агент **Designer** (LLM: Opus 4.7 для UX-логики, опц. интеграция с Figma MCP / v0 / Vercel design tools).

**Условие применимости:** в `09-ui-requirements.md` есть содержательные требования; иначе этап автозакрывается.

**Вход:** ТЗ + UI-требования + текущая дизайн-система (`docs/design/design-tokens.json`, `docs/design/components.md`).

**Действие:**
1. Прочитать UI-требования и существующую дизайн-систему.
2. Сделать **wireframes** (low-fi) — структура экранов и переходов.
3. Сделать **mockups** (hi-fi) — финальные макеты со стилями из дизайн-системы. Не изобретать новые цвета/шрифты — использовать токены.
4. Описать **состояния**: loading / empty / error / success / disabled.
5. Описать **a11y-требования** конкретно: контраст, ARIA-роли, клавиатурная навигация.
6. Сгенерировать **HTML/JSX-прототип** (опционально) для возможности «потрогать».

**Артефакты на выходе:**
- `docs/work-items/<id>/11-design/wireframes.md` (Mermaid / SVG / ASCII-art)
- `docs/work-items/<id>/11-design/mockups.md` (изображения PNG/SVG в `assets/`)
- `docs/work-items/<id>/11-design/states.md` (описание всех состояний UI)
- `docs/work-items/<id>/11-design/a11y.md`
- `docs/work-items/<id>/11-design/prototype/` (опционально)

**QG-3 → 4 (Design → Development):**
- все требования к UI из ТЗ покрыты в `mockups.md` (linker)
- все состояния (loading/empty/error/success) описаны явно
- a11y-чек-лист заполнен
- цвета и шрифты — только из дизайн-токенов (CI-проверка)
- пользователь поставил `:approved:` в Plane на подзадаче «Дизайн»

---

### 4. Этап «Разработка» (Development)

**Кто делает:** агент **Developer** (LLM: Sonnet 4.6, опц. GLM-5.1).

**Вход:** ТЗ + ADR + UI-mockups (если есть) + Acceptance Criteria + Test Plan.

**Действие:**
1. Создать рабочую ветку (уже создана webhook'ом — переключиться).
2. Реализовать функциональность по ТЗ + ADR.
3. Написать **unit-тесты** (покрытие ≥ согласованного порога, не падать).
4. Написать **integration-тесты** для всех API-эндпоинтов.
5. Если UI — написать **компонентные тесты** (Testing Library / Vitest) и **e2e-сценарии** (Playwright) под Acceptance Criteria.
6. Обновить миграции БД (Alembic / Flyway), если меняется схема.
7. Обновить документацию: `README.md`, `CLAUDE.md`, runbook, OpenAPI (если есть API).
8. Открыть PR с лейблом `stage:dev` и шаблонным описанием (см. `07_git_workflow.md`).

**Артефакты на выходе:**
- коммиты в ветке `feature/<id>-<slug>`
- открытый PR с заполненным шаблоном (ссылка на ТЗ, ADR, чек-лист DoD)
- зелёный CI-job: lint, type-check, unit, integration, build
- обновлённые `CHANGELOG.md`, OpenAPI/JSON-Schema, миграции
- отчёт о coverage в комменте PR

**QG-4 → 5 (Development → Code Review):**
- CI зелёный (всё, что выше)
- Coverage delta ≥ 0 (не упало)
- В PR заполнен чек-лист DoD (все галочки от агента-разработчика)
- Все Acceptance Criteria имеют покрывающий тест (linker)
- Нет незакрытых TODO/FIXME, добавленных в этом PR (линтер)

---

### 5. Этап «Code Review» (Review)

**Кто делает:** агент **Reviewer** (LLM: Opus 4.7).

**Вход:** PR + ТЗ + ADR + Acceptance + diff.

**Действие:**
1. Прочитать PR-diff в контексте ТЗ и ADR.
2. Проверить:
   - **Соответствие ТЗ** — все ли требования реализованы; нет ли «изобретений» сверх ТЗ.
   - **Соответствие ADR** — выполнены ли архитектурные решения (например, использован указанный модуль).
   - **Качество кода** — naming, дублирование, сложность функций, обработка ошибок.
   - **Безопасность** — секреты в коде, SQL-инъекции, XSS, неэкранированные шаблоны.
   - **Тесты** — действительно ли тесты проверяют логику, а не «бумажные» (`expect(true).toBe(true)`).
   - **Документация** — обновлена ли.
3. Оставить комментарии в PR через GitHub/Gitea API.
4. Решение: `approve` / `request-changes` / `comment`.

**Артефакты на выходе:**
- комментарии reviewer'а в PR
- финальный review с вердиктом
- `docs/work-items/<id>/12-review.md` — короткое резюме и rationale (для будущих ретроспектив)

**QG-5 → 6 (Review → Test):**
- Reviewer поставил `approve`
- 0 unresolved review-комментариев
- 0 нарушений «P0/P1»-уровня в `12-review.md`
- (опц.) reviewer-агент явно подтвердил «соответствие ТЗ — да»

> **Защита от лояльности:** Reviewer **не должен совпадать** по экземпляру с Developer. Это разные subagent'ы с разными system prompt и разной моделью.

---

### 6. Этап «Тестирование» (Test)

**Кто делает:** агент **Tester** (LLM: Sonnet 4.6 или Qwen 3.6+).

**Вход:** PR (после approve) + Test Plan + ephemeral preview-окружение.

**Действие:**
1. Дождаться поднятия preview-окружения (Docker Compose в CI на каждый PR).
2. Прогнать **полный регресс**:
   - все unit + integration тесты (ещё раз, в чистой среде)
   - **e2e-тесты** через Playwright по Acceptance Criteria
   - **визуальная регрессия** UI (Playwright Visual Comparisons / Percy / Loki)
   - **a11y-тесты** (axe-core через Playwright)
   - **performance-тесты** для критичных путей (если в ТЗ есть NFR)
   - **security-тесты** базового уровня (Trivy / Bandit / npm audit)
3. Найденные баги — оформить как **issue в Plane** с лейблом `bug:found-by-qa`, ссылкой на PR, скриншотами и шагами воспроизведения; PR вернуть в `stage:dev`.
4. При зелёных тестах — оформить отчёт `docs/work-items/<id>/13-test-report.md`.
5. Поставить лейбл `stage:ready-to-deploy` на PR.

**Артефакты на выходе:**
- `docs/work-items/<id>/13-test-report.md` — отчёт о тестировании
- `docs/work-items/<id>/13-test-report/screenshots/` — скриншоты
- логи CI-job'ов
- (если найдены баги) — заведённые баги в Plane со ссылкой на этот PR

**QG-6 → 7 (Test → Deploy):**
- Все тесты зелёные на preview-окружении
- Visual regression: 0 нерассмотренных diff'ов
- a11y: 0 нарушений уровня A/AA
- Test coverage trend ≥ 0
- Нет открытых критичных багов на этой задаче

---

### 7. Этап «Внедрение» (Deploy)

**Кто делает:** агент **Deployer** (LLM: Sonnet 4.6) + CI/CD.

**Вход:** PR с `stage:ready-to-deploy` + зелёный QG-6.

**Действие:**
1. **Merge PR** в `main` (squash или rebase — по соглашению проекта).
2. CI автоматически:
   - бампит версию (semver на основе типа изменения)
   - создаёт git-tag `v<X.Y.Z>`
   - деплоит в `test` (полностью автоматически)
   - прогоняет smoke-тесты на `test`
3. Если smoke зелёный — открывается **release PR** или ставится approval-gate в Plane: «деплой в prom?»
4. После approval (от человека-стейкхолдера в Plane) — CI деплоит в `prom`.
5. Запускает smoke-тесты на `prom`.
6. Создаёт release notes в `CHANGELOG.md` и в Plane.
7. Закрывает Work Item в Plane.

**Артефакты на выходе:**
- merged PR
- git-tag
- запись в `CHANGELOG.md`
- `docs/work-items/<id>/14-deploy-log.md` — что, когда, кем, в какие среды
- release-комментарий в Plane Work Item с ссылкой на тег

**QG-7 → DONE (Deploy → Closed):**
- merge выполнен
- tag создан
- deploy в test и prom прошли без ошибок
- smoke-тесты на prom зелёные
- healthcheck сервиса зелёный в течение 10 минут после деплоя (по метрике)
- стейкхолдер поставил `:approved:` финальной верификации в Plane

---

## Диаграмма потока

```mermaid
flowchart TD
    Start([Заказчик создаёт BR в Plane]) --> QG0{QG-0:<br/>title/desc/<br/>project ok?}
    QG0 -->|no| Start
    QG0 -->|yes| Webhook[Webhook: создать ветку,<br/>подзадачи, папку docs/]
    Webhook --> A[1. Анализ<br/>Analyst]
    A --> QG1{QG-1:<br/>BRD/ТЗ/AC/TP<br/>+ approve}
    QG1 -->|no| A
    QG1 -->|yes| B[2. Архитектура<br/>Architect]
    B --> QG2{QG-2:<br/>ADR + покрытие<br/>требований}
    QG2 -->|no| B
    QG2 -->|yes| C{Затрагивает<br/>UI?}
    C -->|no| D[4. Разработка<br/>Developer]
    C -->|yes| C1[3. Дизайн<br/>Designer]
    C1 --> QG3{QG-3:<br/>mockups +<br/>states + a11y}
    QG3 -->|no| C1
    QG3 -->|yes| D
    D --> QG4{QG-4:<br/>CI green +<br/>coverage}
    QG4 -->|no| D
    QG4 -->|yes| E[5. Code Review<br/>Reviewer]
    E --> QG5{QG-5:<br/>approve +<br/>0 unresolved}
    QG5 -->|no| D
    QG5 -->|yes| F[6. Тестирование<br/>Tester]
    F --> QG6{QG-6:<br/>e2e + visual +<br/>a11y green}
    QG6 -->|no| D
    QG6 -->|yes| G[7. Внедрение<br/>Deployer/CI]
    G --> QG7{QG-7:<br/>deploy + smoke<br/>+ user approve}
    QG7 -->|no| F
    QG7 -->|yes| Done([Work Item closed])
```

---

## Принципы движения по конвейеру

1. **Назад можно, вперёд через QG — нельзя.** Любой этап может вернуть задачу на любой предыдущий с конкретной причиной (ссылка на пункт ТЗ/ADR). Перепрыгивать вперёд (например, «давайте сразу деплоить, потом дотестируем») запрещено git hook'ами и CI.
2. **Артефакты — единственный язык передачи между этапами.** Агенты не общаются «голосом» в чате, не помнят контекст из памяти. Всё, что нужно следующему этапу, — лежит в файлах.
3. **Время в этапе ограничено.** Каждый этап имеет SLA (по умолчанию: Анализ — 24ч, Архитектура — 24ч, Дизайн — 48ч, Разработка — пропорционально оценке, Review — 4ч, Test — 8ч, Deploy — 1ч). При превышении — эскалация в Plane на человека.
4. **Эскалация явная и формальная.** Агент, который не уверен, **обязан** написать вопрос в Plane и поставить статус `needs-clarification` — а не «угадать и продолжить».
5. **Один Work Item — один scope.** Если в ходе анализа выясняется, что задача шире — она дробится на несколько Work Item'ов через подзадачу типа `decomposition`. **Не растягиваем** scope в той же задаче.

---

## Структура задачи в Plane (типовая)

Каждый Feature-уровневый Work Item автоматически получает 6 подзадач (Дизайн опциональна — создаётся всегда, может быть автозакрыта):

| # | Subtask | Owner-агент | Лейблы | SLA |
|---|---------|-------------|--------|-----|
| 1 | Анализ | Analyst | `stage:analysis` | 24h |
| 2 | Архитектура | Architect | `stage:arch` | 24h |
| 3 | Дизайн UI/UX | Designer | `stage:design` (или `skip:not-applicable`) | 48h |
| 4 | Разработка | Developer | `stage:dev` | по оценке |
| 5 | Code Review | Reviewer | `stage:review` | 4h |
| 6 | Тестирование | Tester | `stage:test` | 8h |
| 7 | Внедрение | Deployer | `stage:deploy` | 1h |

(В Plane глубина вложенности — 1 уровень, поэтому подзадачи висят прямо на Feature.)

См. `06_plane_integration.md` — там приведён полный шаблон с описаниями подзадач.

---

## Что считается «фазой проекта»

**Фаза** — группа Work Item'ов, которые:
- логически принадлежат одному релизу или одному эпику,
- имеют общую цель и метрику успеха,
- релизятся одним тегом.

Фаза в Plane — это **отдельный Work Item с типом `Phase`** и собственными подзадачами-фичами (через `parent_id`). Глубина вложенности в Plane — 1 уровень, поэтому Phase → Feature, но не Phase → Feature → Subfeature. Подзадачи этапов производственного процесса висят на Feature, не на Phase.

Каждая Phase имеет свой artifacts-набор: `docs/phases/<phase-id>/` со сводными BRD/ADR на уровне фазы, отдельный план релиза, общие e2e-сценарии. Phase открывается → закрывается, когда все вложенные Feature закрыты + проведён релиз.

---

## Антипаттерны, которые процесс предотвращает

- ❌ «Маленькую правку — без документации» → каждая правка получает мини-ТЗ.
- ❌ «Тестирование на проме» → есть preview-окружение и обязательный QG-6.
- ❌ «Документация позже» → без обновлённой документации QG-4 не зелёный.
- ❌ «Архитектура в голове» → без ADR в репо нельзя пройти QG-2.
- ❌ «Сам себе ревьюер» → Reviewer-агент изолирован от Developer-агента.
- ❌ «Закрыл задачу — потому что считаю готовой» → закрывает CI на основе DoD.
- ❌ «UI не тестируем» → e2e + visual + a11y обязательны на QG-6.
- ❌ «Работаем напрямую на сервере» → агент не имеет доступа на запись в prom; всё через PR + tag + deploy-pipeline.