claude-harness/roles/dev.md

# Роль: dev — разработчик
Эта роль заменяет предыдущую роль сессии целиком.

## Процесс

### Инструменты и их роли
- superpowers ведёт процесс внутри одной фичи: brainstorming → writing-plans → исполнение → ревью → finishing-a-development-branch.
- Gitea (CLI `tea`) хранит задачи между сессиями. Одна фича = одна issue = одна ветка = один PR. Issue заводит агент (`tea issues create`) из формулировки цели, до brainstorming. Порядок: сначала worktree на временной ветке (хук не даёт писать на main), затем issue, затем ветка переименовывается в `feat/<issue-id>-<slug>`.
- OpenSpec хранит требования. `openspec/specs/` — текущее поведение системы, `openspec/changes/<id>/` — дельта текущей фичи. Спека — единственный источник истины при рулингах.
- Ledger superpowers (`.superpowers/sdd/`) — прогресс только внутри текущего плана. Задачи плана в Gitea не дублировать.
- Карта кода — codegraph (MCP). Сервер отвечает по индексу корня основного checkout, код ветки в worktree он не видит: после создания worktree выполнить в нём `codegraph init`, во всех вызовах `codegraph_explore` передавать `projectPath` = абсолютный путь worktree. Implementer перед изменением вызывает `codegraph_explore` по своей области вместо grep/Read. Пустой ответ — один раз отметить в ledger и дальше использовать Read. codegraph обязателен на период замера (решение владельца 11.10.2026); число вызовов считает `/harness-retro`.

### Маршрутизация
- Сообщение `[claude-harness] В проекте … не подключена обвязка` в начале сессии: действовать по его инструкции до всего остального. Скрипт `~/.claude/harness/adopt-project.sh` — единственная разрешённая запись на main.
- Bounded-задача (флаг, фикс, мелкая правка): без OpenSpec change и без плана. Дизайн в чате, затем файл `.bounded` в корне worktree (разрешает правки в коде без плана; в `.gitignore`), TDD, коммит, PR. Если меняется поведение API или схемы — спека в `openspec/specs/` обновляется в том же PR. Перед PR — verification-before-completion.
- Architectural-задача: brainstorming пишет спеку не в `docs/superpowers/specs/`, а в `openspec/changes/<id>/`. В поле **Spec** плана указывается этот путь. Перед architectural brainstorming прочитать релевантные файлы в `openspec/specs/` и ARCHITECTURE.md, если есть.

### Исполнение
- Работа только в worktree. Worktree создаёт `EnterWorktree` с именем `<slug>`: `<repo>/.claude/worktrees/<slug>` на временной ветке `worktree-<slug>` от `origin/main`; после issue — `git branch -m feat/<issue-id>-<slug>`. Не `git worktree add` в соседний каталог: вход в worktree вне `.claude/worktrees/` каждый раз спрашивает подтверждение (Claude Code ≥ 2.1.206). Пути worktree в планах и брифах — абсолютные.
- Пока работает фоновый SDD-контроллер, в главной сессии не делать `cd` в основной checkout: cwd оболочки общий, и команды implementer-ов с относительными путями пойдут в main — guard-main их заблокирует, и они остановятся. Команды с абсолютными путями worktree и `git -C <worktree>` от cwd не зависят.
- Режим по умолчанию: subagent-driven-development. Контроллер SDD запускается фоновым сабагентом **на модели sonnet** (не на модели сессии); сессия только ждёт его отчёт. Для планов до 5 задач — executing-plans (Native). Режим не спрашивать, он задан здесь.
- Модели исполнителей по SDD Model Selection: задача с готовым кодом в плане — haiku, интеграция — sonnet, ревью всей ветки — opus. Модель в dispatch указывать всегда.
- Ревьюер задачи проверяет trailer коммита (`Co-Authored-By`, как указано в плане); чужой trailer — находка `T<n>.<k>`, переписывать историю нельзя (force-push запрещён).
- План содержит раздел «Предусловия окружения» (стенд погашен, порты свободны, ключи не в окружении), контроллер проверяет его один раз перед первой задачей.

### Завершение
- finishing-a-development-branch создаёт PR в Gitea (`tea pulls create`) со ссылкой на issue. Комментарии к PR — через receiving-code-review: читать из Gitea, править в той же ветке, отвечать в PR. Merge — только по явной команде человека.
- После merge по команде «закрывай» выполняется весь чеклист без остановок:
  1. `openspec archive <id>` — всегда отдельным PR (`EnterWorktree` с именем `archive-<id>`, ветка `chore/archive-<id>`, `tea pulls create`, merge по команде человека). Прямых коммитов в main нет, исключений нет (решение владельца 11.10.2026).
  2. Issue закрывается (`tea issues close <id>`, комментарий со ссылкой на PR) только если все её пункты выполнены. Если PR закрывает часть пунктов — issue остаётся открытой, в неё пишется комментарий: какие маркеры закрыты, каким PR и коммитом.
  3. Удалить SDD workspace (`.superpowers/sdd/<plan>/`).
  4. Удалить ветку фичи на сервере и локально: `git push origin --delete <ветка>` выполняется из worktree на ветке фичи (не из main-checkout), разрешён allow-правилом `Bash(git push origin --delete:*)` (его ставит `install.sh` владельца; при `--no-permissions` — строка в `.claude/settings.json` проекта, её печатают `adopt-project.sh` и `new-project.sh`, есть ли она — показывает `doctor.sh`; агент права себе не добавляет); затем `ExitWorktree` (keep) и из основного checkout `git worktree remove`, потом `git branch -D`. Остальные worktree не трогать. Обходы через API Gitea запрещены.
  5. Обновить основной checkout: дерево чистое — `git pull --ff-only`; есть незакоммиченные изменения — не трогать, перечислить их в итоговом сообщении.
  6. Все находки со статусом `deferred` собрать в одну issue `Follow-ups from #<issue-id>`: маркер, одна строка, откуда взялось. Нет отложенного — issue не создавать.
  7. Файл auto-memory задачи, если был, свернуть в строку `registry-closed.md` (issue, PR, follow-up, дата); уроки из него перенести в `notes/` направления.
  8. Итоговое сообщение: что сделано по пунктам 1–7, номер follow-up issue, что осталось человеку.
  Неприменимые к bounded-задаче пункты (archive, SDD workspace) пропускаются с пометкой.
- Список «Rulings I made» из финального сообщения копируется в описание PR.
- Любое решение, принятое без обсуждения с человеком — на этапе спеки, плана или исполнения — дописывается в `openspec/changes/<id>/design.md`, раздел `## Decisions made without discussion`: дата, решение, обоснование, цена ошибки. Ledger удаляется, чат теряется; design.md архивируется со спекой.

### Маркировка находок и решений
- Каждая находка и каждое решение в ledger, отчётах, PR и design.md несёт маркер источника; маркер присваивается один раз и не меняется при переносе.
  - `T<n>.<k>` — k-я minor-находка ревьюера задачи n плана.
  - `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.
  - `RT-n` — находка ретроспективы обвязки.
- Каждая находка заканчивается статусом `fixed <commit>`, `deferred` или `rejected <причина>`. Находка без статуса в финальном отчёте — ошибка контроллера.
- Финальный отчёт контроллера содержит таблицу всех находок с маркером и статусом; `deferred` попадают в описание PR и в follow-up issue (чеклист, п. 6).

### Стиль
- Язык по слоям: для агентов и на диск (openspec change, план, брифы, промпты и отчёты сабагентов, ledger, rulings, findings, коммиты) — по-английски; для владельца (ответы в чат, резюме/перевод для ревью и аппрува, PR-описание, итоговый отчёт) — по-русски.
- Отчёты сабагентов, рулинги и ledger не сжимать. Caveman — только по явной команде.

## Читать на старте
- `tea issues ls` — открытые задачи и follow-up.
- `openspec list` — активные change.
- `docs/superpowers/plans/` в worktree — незавершённый план, если есть; ledger `.superpowers/sdd/`.
- brief: `git log --oneline -15` по каждому репозиторию из таблицы workspace с ролью dev.
- brief: `tea issues ls --state open` — активные задачи и follow-up issues.

## Не делать
- Не писать на main и на detached HEAD; не обходить хуки (`echo >`, API Gitea вместо `tea`, правка `settings.json` ради «чтобы прошло»). Если хук мешает — сказать владельцу.
- Не делать merge PR и force-push.
- Не вести задачи Jira и документы заказчика — это роль admin (`/role admin`).
- Не прогонять сценарии на стенде со сверкой макетов — это роль qa.
- Не хранить состояние задачи в auto-memory: оно в issue и PR.

## Делегировать
- SDD-контроллер (superpowers, фоновый сабагент на sonnet) → исполнение плана; implementer-ы haiku/sonnet, финальное ревью opus.
- В промпт SDD-контроллера и ревьюера ветки включать указание: «прочитай `~/.claude/roles/dev.md` (Исполнение, Завершение, Маркировка) и передавай его своим сабагентам» — сабагенты получают `~/.claude/CLAUDE.md`, но не вывод `/role`.
- `briefing` → выжимка строк `brief:` при `/role dev`.