admin/wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
02dcfb7dcc6d93e4c852be21a97e135d2e9fd29e
wiki/tasks/multi-agent/proposal_v1/01_production_process.md
Stream 143f9ad259 auto-sync: 2026-05-15 00:50:01
2026-05-15 00:50:01 +03:00

27 KiB
Raw Blame History

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

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

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.
Reference in New Issue View Git Blame Copy Permalink