Skip to content

process.md

Latest commit

 

History

History
181 lines (133 loc) · 11.2 KB

process.md

File metadata and controls

181 lines (133 loc) · 11.2 KB

Процесс разработки (SDD: Spec-Driven Development)

Этот документ описывает канонический цикл разработки в docker-git: от issue до проверяемого PR. Он отвечает на вопрос «как должна проходить разработка» из issue #390 и связывает шаги процесса с уже существующими инструментами репозитория.

Базовая философия задана в AGENTS.md и CLAUDE.md:

«Если это нельзя доказать — это нельзя доверить продакшену.» Каждая функция — теорема, каждый тест — доказательство, каждый тип — утверждение.

SDD означает, что сначала формализуем (спецификация + инварианты), потом программируем. Спецификация и её инварианты живут вместе с кодом и проверяются автоматически.

Обзор цикла

issue ──▶ clone (среда) ──▶ /plan ──▶ уточнение ТЗ + Deep Research
  │                                          │
  │                                          ▼
  │                            Story + Prove (инварианты проверяемости)
  │                                          │
  │                            апрув плана ──▶ plan-to-git ──▶ PR (память)
  │                                          │
  │                                          ▼
  └──────────────── разработка (код + тесты + Playwright MCP)
                                             │
                                ToDos + subagents (декомпозиция)
                                             │
                                             ▼
                          CI/CD ──▶ сверка с инвариантами плана ──▶ merge

1. Issue — источник истины

Разработка всегда начинается с issue. Issue фиксирует намерение и становится точкой привязки для плана, PR и итоговой проверки инвариантов.

2. Среда: клонирование с изоляцией

Для каждой issue поднимается отдельное Docker-окружение. Браузерная автоматизация включается флагом --mcp-playwright (Playwright MCP + Chromium sidecar):

bun run docker-git clone https://github.com/ProverCoderAI/docker-git/issues/390 --force --mcp-playwright
  • --force пересоздаёт окружение и удаляет volumes проекта.
  • --mcp-playwright включает Playwright MCP для проверки кода в реальном браузере.
  • --auto (или --auto=codex|claude|gemini|grok) запускает агента, который сам выполнит задачу, создаст PR и очистит контейнер после завершения.

Подробности по флагам — в README.md.

3. Планирование: /plan

Агенту передаётся ссылка на issue и команда /plan. На этом этапе агент не пишет код, а формализует задачу:

  1. Задаёт уточняющие вопросы и фиксирует ТЗ. Неоднозначности проясняются до начала разработки, а не во время неё.
  2. Ведёт Deep Research. Внутренняя формулировка из AGENTS.md: «I am looking for code that does <requested functionality>, is there existing code that can do this?» Сперва ищем переиспользуемые паттерны в репозитории, затем — внешние источники. Внешний материал цитируется дословно (SOURCE:), иначе SOURCE: n/a. Похожий подход к правилам ресёрча см. contract-knowledge/.cursorrules.
  3. Формирует Story — итог плана. Story описывает поведение в терминах пользователя и завершается блоком Prove: инвариантами, по которым проверяется выполнение задачи.

Story + Prove (инварианты проверяемости)

Каждая Story обязана содержать проверяемые инварианты — пред-/постусловия и свойства, которые можно подтвердить тестом, типом или прогоном CI. Это основной артефакт SDD: именно по нему сверяется результат разработки.

## Story: <краткое название>

Как <роль>, я хочу <возможность>, чтобы <ценность>.

### Prove (инварианты проверяемости)

- INV-1: ∀ вход ∈ Domain: <предусловие> → <постусловие>
- INV-2: <свойство, проверяемое property-based тестом>
- INV-3: <наблюдаемое поведение, проверяемое через CI / Playwright MCP>

### Способ проверки каждого инварианта

- INV-1 → unit/property тест `<имя>`
- INV-2 → `bun test <путь>`
- INV-3 → шаг CI `<job>` / сценарий Playwright

Формат инвариантов согласован с разделом «PROOF-обязательства в PR» в AGENTS.md и CLAUDE.md.

4. Апрув плана → plan-to-git → PR

Когда план одобрен, он не должен теряться. Инструмент plan-to-git автоматически выгружает захваченные планы в комментарий PR — так план становится постоянной памятью разработки и привязывается к ветке.

В сгенерированных окружениях это уже подключено (см. PR #371, «feat(shell): sync agent plans to pull requests»):

  • бинарь plan-to-git устанавливается в образ проекта;
  • managed-хук Codex захватывает явные планы (plan-to-git hook --source codex);
  • plan-to-git sync запускается из git post-push обёртки перед бэкапом сессии.

Таким образом апрувнутый план фиксируется в PR без ручных действий — память о намерении сохраняется даже при пересоздании контейнера.

5. Разработка

После принятия плана начинается реализация (Codex / выбранный агент):

  • агент пишет код, запускает тесты и проверяет работоспособность;
  • при необходимости использует Playwright MCP для проверки написанного кода в браузере;
  • активно ведёт ToDos и использует subagents для декомпозиции крупной задачи на независимые проверяемые шаги.

Код пишется только после формального понимания задачи: типы и инварианты → архитектура (CORE/SHELL) → код → тесты. Минимальный корректный diff предпочтительнее переписывания.

6. Верификация и сверка с инвариантами

После реализации:

  1. Агент проверяет CI/CD (сборка, типчек, тесты, линтеры).
  2. Сверяет результат с инвариантами плана (блок Prove): каждый инвариант Story должен иметь подтверждение — пройденный тест, проверку типа или зелёный шаг CI / сценарий Playwright.

Если любой шаг не проходит — возврат в петлю ресёрча (см. AGENTS.md), а не обход проверки.

7. Доказательство фикса (proof-of-fix)

При исправлении проблемы агент всегда добавляет краткое доказательство в PR: почему возникла проблема и как она решена. Кратко, по существу.

## Proof of fix

- Причина: <корневая причина, кратко>
- Решение: <что изменено и почему это устраняет причину>
- Доказательство: <тест/прогон, который падал до и проходит после>

Фикс без воспроизводящего теста считается неполным: без воспроизведения нельзя проверить исправление, и возможна регрессия.

8. Борьба с дублированием

Нужны инструменты и привычки, устраняющие дублирование кода и дублирование смысла:

  • перед написанием нового кода — Deep Research по существующим реализациям (шаг 3.2), чтобы переиспользовать, а не копировать;
  • одна единица смысла — одно место определения (типы, инварианты, константы);
  • при обнаружении дублирования — выделение общего модуля вместо копии.

Чек-лист цикла

  • Issue зафиксировала намерение.
  • Среда поднята (clone, при необходимости --mcp-playwright).
  • План уточнён вопросами и Deep Research.
  • Story содержит блок Prove с проверяемыми инвариантами.
  • План одобрен и выгружен в PR через plan-to-git.
  • Реализация ведётся через ToDos/subagents, с тестами и (при необходимости) Playwright MCP.
  • CI/CD зелёный; каждый инвариант Story подтверждён.
  • Для фикса добавлено proof-of-fix.
  • Дублирование кода и смысла исключено.