46 lines
7.5 KiB
Markdown
46 lines
7.5 KiB
Markdown
# Процесс разработки
|
||
|
||
## Роли инструментов
|
||
- Superpowers ведёт процесс внутри одной фичи: brainstorming → writing-plans → исполнение → ревью → finishing-a-development-branch.
|
||
- Gitea (CLI `tea`) хранит задачи между сессиями. Одна фича = одна issue = одна ветка = один PR. Issue заводит агент (`tea issues create`) из формулировки цели, до brainstorming.
|
||
- OpenSpec хранит требования. `openspec/specs/` — текущее поведение системы, `openspec/changes/<id>/` — дельта текущей фичи. Спека — единственный источник истины при рулингах.
|
||
- Ledger superpowers (`.superpowers/sdd/`) — прогресс только внутри текущего плана. Задачи плана в Gitea не дублировать.
|
||
|
||
## Маршрутизация
|
||
- Bounded-задача (флаг, фикс, мелкая правка): без OpenSpec change и без плана. Дизайн в чате, затем создать файл `.bounded` в корне worktree (разрешает правки в src/ без плана), TDD, коммит, PR.
|
||
- Architectural-задача: brainstorming пишет спеку не в `docs/superpowers/specs/`, а в `openspec/changes/<id>/`. В поле **Spec** плана указывается этот путь.
|
||
- Перед architectural brainstorming прочитать релевантные файлы в `openspec/specs/` и ARCHITECTURE.md, если есть.
|
||
- Карта кода — codegraph (MCP). Перед изменением implementer вызывает `codegraph_explore` по своей области вместо grep/Read по файлам. Это инструмент внутри процесса, а не замена skill-check. В новом проекте: `codegraph init` один раз. Если `codegraph_explore` возвращает пусто (известная проблема в worktree под `.claude/worktrees/`), один раз сообщить об этом в ledger и дальше использовать Read, не тратя раунды на переиндексацию.
|
||
|
||
## Исполнение
|
||
- Работа только в worktree. Ветка называется по issue: `feat/<issue-id>-<slug>`.
|
||
- Режим по умолчанию: subagent-driven-development. Контроллер SDD запускается как фоновый сабагент **на модели sonnet** (не на модели сессии) — сессия только ждёт его отчёт. Для планов до 5 задач — executing-plans (Native).
|
||
- Модели исполнителей выбираются по SDD Model Selection: задача с готовым кодом в плане — haiku, интеграция — sonnet, ревью всей ветки — opus. Модель в dispatch указывать всегда.
|
||
|
||
## Завершение
|
||
- finishing-a-development-branch создаёт PR в Gitea (`tea pulls create`) и ссылается на issue. Комментарии к PR обрабатываются через receiving-code-review: агент читает их из Gitea, правит в той же ветке, отвечает в PR. Merge — только по явной команде человека.
|
||
- После merge по команде «закрывай» выполняется весь чеклист закрытия, без остановок между пунктами:
|
||
1. `openspec archive <id>`, коммит и push архива прямо в main (единственное разрешённое исключение из правила «в main только через PR»: хук пропускает коммиты, затрагивающие только `openspec/`).
|
||
2. `tea issues close <id>` с комментарием-ссылкой на PR.
|
||
3. Удалить SDD workspace (`.superpowers/sdd/<plan>/`).
|
||
4. Удалить ветку фичи на сервере и локально (`git push origin --delete`, `git branch -D`), удалить worktree (`git worktree remove`). Остальные worktree не трогать.
|
||
5. Обновить основной checkout: если рабочее дерево там чистое — `git pull --ff-only`; если есть незакоммиченные изменения — не трогать, а перечислить их в итоговом сообщении.
|
||
6. Все находки со статусом `deferred` (см. «Маркировка») собрать в одну issue Gitea `tea issues create` с заголовком `Follow-ups from #<issue-id>`: маркер, одна строка, откуда взялось. Если отложенного нет — issue не создавать.
|
||
7. Итоговое сообщение: что сделано по пунктам 1–6, номер follow-up issue, что осталось человеку.
|
||
Любой другой push в main — только через PR.
|
||
- Список "Rulings I made" из финального сообщения копируется в описание PR.
|
||
- Любое решение, принятое агентом без обсуждения с человеком — на этапе спеки, плана или исполнения — дописывается в `openspec/changes/<id>/design.md` в раздел `## Decisions made without discussion`: дата, решение, обоснование, что стоит ошибка. Ledger SDD удаляется, чат теряется; design.md архивируется вместе со спекой и остаётся в истории.
|
||
|
||
## Маркировка находок и решений
|
||
- Каждая находка и каждое решение в ledger, отчётах, PR и design.md несёт маркер источника. Маркер присваивается один раз и не меняется при переносе между документами.
|
||
- `T<n>.<k>` — k-я minor-находка ревьюера задачи n плана (`T4.1`, `T4.2`).
|
||
- `C-n` / `I-n` / `M-n` — critical / important / minor из финального ревью всей ветки.
|
||
- `R-n` — рулинг контроллера, сквозная нумерация в пределах фичи; рядом номер решения в design.md: `R-5 (design #33)`.
|
||
- `O-n` — наблюдение контроллера вне ревью (неточные отчёты, инструменты, окружение).
|
||
- `H-n` — замечание человека из PR, обработанное через receiving-code-review.
|
||
- Каждая находка заканчивается одним из статусов: `fixed <commit>`, `deferred`, `rejected <причина>`. Находка без статуса в финальном отчёте — ошибка контроллера.
|
||
- Финальный отчёт контроллера содержит таблицу всех находок с маркером и статусом; `deferred` попадают в описание PR и в follow-up issue при закрытии (чеклист, п. 6).
|
||
|
||
## Стиль
|
||
- Отчёты сабагентов, рулинги и ledger не сжимать. Caveman включается только по явной команде.
|