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).

Стиль

• Отчёты сабагентов, рулинги и 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.