Skip to content

Commit f09a81b

Browse files
skulidropekskulidropek
authored
Merge pull request #392 from konard/issue-390-5cc8c59392dd
docs: codify SDD development process (issue #390)
2 parents 561b6ce + bc011b1 commit f09a81b

4 files changed

Lines changed: 216 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,21 @@ const PostgresMessageRepository = Layer.effect(
237237
- Память: `O(n)` для буферизации сообщений
238238
```
239239

240+
При исправлении проблемы PR **всегда** содержит краткое доказательство фикса:
241+
242+
```markdown
243+
## Proof of fix
244+
245+
- Причина: <корневая причина, кратко>
246+
- Решение: <что изменено и почему это устраняет причину>
247+
- Доказательство: <тест/прогон, который падал до и проходит после>
248+
```
249+
250+
Фикс без воспроизводящего теста считается неполным. Дублирование кода и смысла
251+
недопустимо: перед новым кодом — Deep Research по существующим реализациям,
252+
одна единица смысла — одно место определения. Полный цикл разработки — в
253+
[`docs/process.md`](docs/process.md).
254+
240255
7. **CONVENTIONAL COMMITS С ОБЛАСТЯМИ**:
241256

242257
```bash

‎CLAUDE.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,21 @@ const PostgresMessageRepository = Layer.effect(
151151
- Память: `O(n)` для буферизации сообщений
152152
```
153153

154+
При исправлении проблемы PR **всегда** содержит краткое доказательство фикса:
155+
156+
```markdown
157+
## Proof of fix
158+
159+
- Причина: <корневая причина, кратко>
160+
- Решение: <что изменено и почему это устраняет причину>
161+
- Доказательство: <тест/прогон, который падал до и проходит после>
162+
```
163+
164+
Фикс без воспроизводящего теста считается неполным. Дублирование кода и смысла
165+
недопустимо: перед новым кодом — Deep Research по существующим реализациям,
166+
одна единица смысла — одно место определения. Полный цикл разработки — в
167+
[`docs/process.md`](docs/process.md).
168+
154169
7. **CONVENTIONAL COMMITS С ОБЛАСТЯМИ**:
155170

156171
```bash

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,11 @@ bun run docker-git apply-all --active
9494
- `apply` применяет конфиг к одному проекту. `--no-up` только обновляет файлы без `docker compose up`.
9595
- `apply-all` применяет конфиг ко всем проектам. `--active` только к запущенным контейнерам.
9696

97+
## Процесс разработки
98+
99+
Канонический цикл разработки (SDD: Spec-Driven Development) — от issue до
100+
проверяемого PR — описан в [docs/process.md](docs/process.md).
101+
97102
## Подробности
98103

99104
```bash

‎docs/process.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Процесс разработки (SDD: Spec-Driven Development)
2+
3+
Этот документ описывает канонический цикл разработки в `docker-git`: от issue до
4+
проверяемого PR. Он отвечает на вопрос «как должна проходить разработка» из
5+
[issue #390](https://github.com/ProverCoderAI/docker-git/issues/390) и связывает
6+
шаги процесса с уже существующими инструментами репозитория.
7+
8+
Базовая философия задана в [`AGENTS.md`](../AGENTS.md) и [`CLAUDE.md`](../CLAUDE.md):
9+
10+
> «Если это нельзя доказать — это нельзя доверить продакшену.»
11+
> Каждая функция — теорема, каждый тест — доказательство, каждый тип — утверждение.
12+
13+
SDD означает, что **сначала формализуем (спецификация + инварианты), потом
14+
программируем**. Спецификация и её инварианты живут вместе с кодом и проверяются
15+
автоматически.
16+
17+
## Обзор цикла
18+
19+
```text
20+
issue ──▶ clone (среда) ──▶ /plan ──▶ уточнение ТЗ + Deep Research
21+
│ │
22+
│ ▼
23+
│ Story + Prove (инварианты проверяемости)
24+
│ │
25+
│ апрув плана ──▶ plan-to-git ──▶ PR (память)
26+
│ │
27+
│ ▼
28+
└──────────────── разработка (код + тесты + Playwright MCP)
29+
│
30+
ToDos + subagents (декомпозиция)
31+
│
32+
▼
33+
CI/CD ──▶ сверка с инвариантами плана ──▶ merge
34+
```
35+
36+
## 1. Issue — источник истины
37+
38+
Разработка всегда начинается с issue. Issue фиксирует намерение и становится
39+
точкой привязки для плана, PR и итоговой проверки инвариантов.
40+
41+
## 2. Среда: клонирование с изоляцией
42+
43+
Для каждой issue поднимается отдельное Docker-окружение. Браузерная автоматизация
44+
включается флагом `--mcp-playwright` (Playwright MCP + Chromium sidecar):
45+
46+
```bash
47+
bun run docker-git clone https://github.com/ProverCoderAI/docker-git/issues/390 --force --mcp-playwright
48+
```
49+
50+
- `--force` пересоздаёт окружение и удаляет volumes проекта.
51+
- `--mcp-playwright` включает Playwright MCP для проверки кода в реальном браузере.
52+
- `--auto` (или `--auto=codex|claude|gemini|grok`) запускает агента, который сам
53+
выполнит задачу, создаст PR и очистит контейнер после завершения.
54+
55+
Подробности по флагам — в [`README.md`](../README.md).
56+
57+
## 3. Планирование: `/plan`
58+
59+
Агенту передаётся ссылка на issue и команда `/plan`. На этом этапе агент **не
60+
пишет код**, а формализует задачу:
61+
62+
1. **Задаёт уточняющие вопросы** и фиксирует ТЗ. Неоднозначности проясняются до
63+
начала разработки, а не во время неё.
64+
2. **Ведёт Deep Research.** Внутренняя формулировка из `AGENTS.md`:
65+
«I am looking for code that does `<requested functionality>`, is there existing
66+
code that can do this?» Сперва ищем переиспользуемые паттерны в репозитории,
67+
затем — внешние источники. Внешний материал цитируется дословно (`SOURCE:`),
68+
иначе `SOURCE: n/a`. Похожий подход к правилам ресёрча см.
69+
[contract-knowledge/.cursorrules](https://github.com/ton-ai-core/contract-knowledge/blob/main/.cursorrules).
70+
3. **Формирует Story** — итог плана. Story описывает поведение в терминах
71+
пользователя и завершается блоком **Prove**: инвариантами, по которым
72+
проверяется выполнение задачи.
73+
74+
### Story + Prove (инварианты проверяемости)
75+
76+
Каждая Story обязана содержать проверяемые инварианты — пред-/постусловия и
77+
свойства, которые можно подтвердить тестом, типом или прогоном CI. Это основной
78+
артефакт SDD: именно по нему сверяется результат разработки.
79+
80+
```markdown
81+
## Story: <краткое название>
82+
83+
Как <роль>, я хочу <возможность>, чтобы <ценность>.
84+
85+
### Prove (инварианты проверяемости)
86+
87+
- INV-1: ∀ вход ∈ Domain: <предусловие> → <постусловие>
88+
- INV-2: <свойство, проверяемое property-based тестом>
89+
- INV-3: <наблюдаемое поведение, проверяемое через CI / Playwright MCP>
90+
91+
### Способ проверки каждого инварианта
92+
93+
- INV-1 → unit/property тест `<имя>`
94+
- INV-2 → `bun test <путь>`
95+
- INV-3 → шаг CI `<job>` / сценарий Playwright
96+
```
97+
98+
Формат инвариантов согласован с разделом «PROOF-обязательства в PR» в
99+
[`AGENTS.md`](../AGENTS.md) и [`CLAUDE.md`](../CLAUDE.md).
100+
101+
## 4. Апрув плана → `plan-to-git` → PR
102+
103+
Когда план одобрен, он не должен теряться. Инструмент
104+
[`plan-to-git`](https://github.com/ProverCoderAI/plan-to-git) автоматически
105+
выгружает захваченные планы в комментарий PR — так план становится постоянной
106+
памятью разработки и привязывается к ветке.
107+
108+
В сгенерированных окружениях это уже подключено (см. PR #371,
109+
«feat(shell): sync agent plans to pull requests»):
110+
111+
- бинарь `plan-to-git` устанавливается в образ проекта;
112+
- managed-хук Codex захватывает явные планы (`plan-to-git hook --source codex`);
113+
- `plan-to-git sync` запускается из git post-push обёртки перед бэкапом сессии.
114+
115+
Таким образом апрувнутый план фиксируется в PR без ручных действий — память о
116+
намерении сохраняется даже при пересоздании контейнера.
117+
118+
## 5. Разработка
119+
120+
После принятия плана начинается реализация (Codex / выбранный агент):
121+
122+
- агент пишет код, **запускает тесты и проверяет работоспособность**;
123+
- при необходимости использует **Playwright MCP** для проверки написанного кода
124+
в браузере;
125+
- активно ведёт **ToDos** и использует **subagents** для декомпозиции крупной
126+
задачи на независимые проверяемые шаги.
127+
128+
Код пишется только после формального понимания задачи: типы и инварианты →
129+
архитектура (CORE/SHELL) → код → тесты. Минимальный корректный diff
130+
предпочтительнее переписывания.
131+
132+
## 6. Верификация и сверка с инвариантами
133+
134+
После реализации:
135+
136+
1. Агент проверяет **CI/CD** (сборка, типчек, тесты, линтеры).
137+
2. **Сверяет результат с инвариантами плана** (блок Prove): каждый инвариант
138+
Story должен иметь подтверждение — пройденный тест, проверку типа или зелёный
139+
шаг CI / сценарий Playwright.
140+
141+
Если любой шаг не проходит — возврат в петлю ресёрча (см. `AGENTS.md`), а не
142+
обход проверки.
143+
144+
## 7. Доказательство фикса (proof-of-fix)
145+
146+
При исправлении проблемы агент **всегда** добавляет краткое доказательство в PR:
147+
**почему возникла проблема** и **как она решена**. Кратко, по существу.
148+
149+
```markdown
150+
## Proof of fix
151+
152+
- Причина: <корневая причина, кратко>
153+
- Решение: <что изменено и почему это устраняет причину>
154+
- Доказательство: <тест/прогон, который падал до и проходит после>
155+
```
156+
157+
Фикс без воспроизводящего теста считается неполным: без воспроизведения нельзя
158+
проверить исправление, и возможна регрессия.
159+
160+
## 8. Борьба с дублированием
161+
162+
Нужны инструменты и привычки, устраняющие дублирование кода и дублирование
163+
смысла:
164+
165+
- перед написанием нового кода — Deep Research по существующим реализациям
166+
(шаг 3.2), чтобы переиспользовать, а не копировать;
167+
- одна единица смысла — одно место определения (типы, инварианты, константы);
168+
- при обнаружении дублирования — выделение общего модуля вместо копии.
169+
170+
## Чек-лист цикла
171+
172+
- [ ] Issue зафиксировала намерение.
173+
- [ ] Среда поднята (`clone`, при необходимости `--mcp-playwright`).
174+
- [ ] План уточнён вопросами и Deep Research.
175+
- [ ] Story содержит блок Prove с проверяемыми инвариантами.
176+
- [ ] План одобрен и выгружен в PR через `plan-to-git`.
177+
- [ ] Реализация ведётся через ToDos/subagents, с тестами и (при необходимости)
178+
Playwright MCP.
179+
- [ ] CI/CD зелёный; каждый инвариант Story подтверждён.
180+
- [ ] Для фикса добавлено proof-of-fix.
181+
- [ ] Дублирование кода и смысла исключено.

0 commit comments

Comments
 (0)