claude-harness/global/CLAUDE.md

# Процесс разработки

## Роли инструментов
- 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 не дублировать.

## Маршрутизация
- Сообщение `[claude-harness]` в начале сессии означает, что обвязка к проекту не подключена: действовать по его инструкции до всего остального. Скрипт `~/.claude/harness/adopt-project.sh` — единственная разрешённая запись на main помимо архивации OpenSpec.
- Bounded-задача (флаг, фикс, мелкая правка): без OpenSpec change и без плана. Дизайн в чате, затем создать файл `.bounded` в корне worktree (разрешает правки в src/ без плана; файл в `.gitignore`, в коммит не попадает), TDD, коммит, PR.
- Architectural-задача: brainstorming пишет спеку не в `docs/superpowers/specs/`, а в `openspec/changes/<id>/`. В поле **Spec** плана указывается этот путь.
- Перед architectural brainstorming прочитать релевантные файлы в `openspec/specs/` и ARCHITECTURE.md, если есть.
- Карта кода — codegraph (MCP). MCP-сервер запускается в корне основного checkout и по умолчанию отвечает только по его индексу; код ветки в worktree он не видит. Поэтому сразу после создания worktree выполнить в нём `codegraph init` (индекс локальный, в git не попадает), а во всех вызовах `codegraph_explore` передавать `projectPath` = абсолютный путь worktree. Перед изменением implementer вызывает `codegraph_explore` по своей области вместо grep/Read по файлам. Если ответ всё же пуст — один раз отметить в 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. Issue закрывается (`tea issues close <id>`, комментарий со ссылкой на PR) только если все её пункты выполнены. Если PR закрывает часть пунктов (типично для follow-up issue) — issue остаётся открытой, в неё пишется комментарий: какие маркеры закрыты, каким 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, что осталось человеку.
  Пункты, не применимые к bounded-задаче (archive, SDD workspace), пропускаются с пометкой в итоговом сообщении.
  Любой другой 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 включается только по явной команде.