claude-harness/global/CLAUDE.md

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

Роли инструментов

• 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 включается только по явной команде.