Обвязка для разработки с Claude Code: superpowers как процесс, Gitea как память между сессиями, OpenSpec как библиотека спек, codegraph как карта кода, три блокирующих хука как жёсткие правила. Проверена на реальной фиче 27.09.2026 (см. docs/PILOT-2026-09-27.md).

Состав

Слой	Инструмент	Что помнит	Откуда
Процесс внутри фичи	superpowers ≥ 6.4.1	ledger плана, рулинги	плагин Claude Code
Задачи между сессиями	Gitea issues + PR (`tea`)	что делать, блокеры, human gate на merge	ваш сервер
Текущее поведение системы	OpenSpec	требования, дельты, история решений	`npm i -g @fission-ai/openspec`
Карта кода	codegraph (MCP)	связи символов для сабагентов	`npm i -g @colbymchenry/codegraph` + `claude mcp add-json`
Контекст по модулям	вложенные CLAUDE.md, ARCHITECTURE.md	границы, конвенции	этот пакет
Роль сессии	`roles/`, skill `/role`, агент `briefing`, хук `role-hint.sh`	правила, файлы и память своей роли	этот пакет
Жёсткие правила	`guard-main.sh`, `require-plan.sh` (PreToolUse)	то, что нельзя доверять промпту	этот пакет

Что не входит и почему: beads (дублирует Gitea), template-bridge (устарел, дублирует ledger), caveman по умолчанию (сжимает отчёты и рулинги; остаётся доступен по /caveman).

Файлы

global/CLAUDE.md          глобальные правила процесса → ~/.claude/CLAUDE.md
hooks/guard-main.sh       запрет изменений на main/master/detached HEAD (Edit/Write/Bash) по цели записи, без исключений
hooks/require-plan.sh     правки в src/ (или .claude/code-paths) только при плане для ветки или файле .bounded
hooks/harness_target.py   ядро обоих хуков: цели записи команды → репозиторий и ветка каждой цели
hooks/settings.hooks.json блок PreToolUse для ~/.claude/settings.json
caveman/config.json       defaultMode: off → ~/.config/caveman/config.json
project-template/         CLAUDE.md, ARCHITECTURE.md, gitignore для нового проекта
examples/                 реальный CLAUDE.md проекта-пилота
global/permissions.json   allow-правила цикла фичи (worktree, tea, push фичевых веток, удаление веток) → ~/.claude/settings.json
install.sh                установка глобальной части, идемпотентно; --check проверяет окружение; --no-permissions — без allow-правил
new-project.sh            каркас нового проекта: git, CLAUDE.md, openspec init, codegraph init, remote
roles/<r>.md              общий слой ролей dev/admin/analyst/qa → ~/.claude/roles/
skills/role/SKILL.md      /role <r>: загрузить роль, память, запустить briefing → ~/.claude/skills/role/
agents/briefing.md        выжимка состояния для роли (sonnet, только чтение) → ~/.claude/agents/
hooks/role-hint.sh        подсказка роли по заголовку сессии (SessionStart)
link-roles.sh             симлинки ролей/агентов из workspace в репозитории направлений → ~/.claude/harness/
project-template/workspace/   CLAUDE.md workspace с таблицей репозиториев, roles/dev.md
project-template/role-repo/   репозиторий направления: CLAUDE.md, ROLE.md, notes/README.md
tests/run.sh              тесты пакета (bash): bash tests/run.sh
.claude/skills/harness-retro/ проектный skill /harness-retro: ретро обвязки по транскриптам проекта (запуск из этого репозитория)
docs/retro/scripts/       retro_metrics.py (срез метрик), retro_leftovers.py (хвосты закрытия), выгрузка и разметка блокировок
docs/HARNESS.md           как это работает: слои, цикл фичи, SDD, дисциплина закрытия
docs/PILOT-2026-09-27.md  результаты пилота и находки

Существующий проект

bash ~/projects/cc-skills/claude-harness/adopt-project.sh ~/projects/foo   # [--no-merge] [--push]

Запускать из терминала, не из Claude Code: хук guard-main не даёт агенту писать на main, а бутстрап — это запись на main. Скрипт делает ветку chore/harness-init, дописывает секцию харнеса в существующий CLAUDE.md (или создаёт его из шаблона), добавляет ARCHITECTURE.md, строки в .gitignore, openspec init, codegraph init, коммитит и вливает в main fast-forward. Заполнить описание проекта в CLAUDE.md потом можно агентом bounded-задачей на ветке.

Workspace из нескольких репозиториев и роли

bash ~/.claude/harness/adopt-project.sh --workspace ~/projects/foo                      # есть каталог с репозиториями
bash ~/.claude/harness/new-project.sh --workspace ~/projects/foo --role admin --role qa # с нуля

Заполните таблицу репозиториев в CLAUDE.md workspace и перезапустите link-roles.sh. Сессии запускайте из корня workspace с ролью в заголовке: claude -n "admin спринт 3". Удобно завести алиасы в профиле shell (обвязка их не ставит):

alias cc-dev='claude -n "dev"'; alias cc-admin='claude -n "admin"'; alias cc-qa='claude -n "qa"'; alias cc-analyst='claude -n "analyst"'

В сессии: /role — текущая роль и список; /role admin — переключить. Подробности в docs/HARNESS.md, раздел «Роли».

Установка

# 1. Плагины Claude Code (внутри сессии claude)
/plugin install superpowers@claude-plugins-official
/plugin uninstall beads@beads-marketplace            # если стоит
/plugin uninstall template-bridge@template-bridge-marketplace

# 2. CLI
brew install tea && tea login add --name home --url https://<gitea> --token <token>   # scopes: read:user, write:repository, write:issue
npm i -g @fission-ai/openspec
npm i -g @colbymchenry/codegraph          # https://github.com/colbymchenry/codegraph; формулы в brew нет
claude mcp add-json -s user codegraph '{"type":"stdio","command":"codegraph","args":["serve","--mcp"],"alwaysLoad":true}'
# не `codegraph install`: он дописывает секцию в ~/.claude/CLAUDE.md, install.sh её сотрёт.
# MCP подхватится после перезапуска claude; индекс проекта — `codegraph init` в нём (new-project.sh делает сам).

# 3. Глобальная часть
bash install.sh --check
bash install.sh                 # дописывает в ~/.claude/settings.json allow-правила из global/permissions.json;
                                # чужие правила не трогает. Без них: bash install.sh --no-permissions.
                                # Нет tea pulls merge и push в main: merge — по вашей команде.

# 4. Проверка хука: в любом репозитории на main запустить claude и попросить создать файл.
#    Ожидается BLOCKED и предложение создать worktree.
#    bash tests/run.sh — тесты пакета должны быть зелёными.

Новый проект

bash new-project.sh ~/projects/my-app ssh://git@<gitea>:2222/<owner>/my-app.git

Заполните {{...}} в CLAUDE.md, положите фикстуры, запустите claude и опишите задачу своими словами. Дальше по docs/HARNESS.md.

Цикл одной фичи, коротко

фраза → агент заводит issue → brainstorming (вопросы, подходы, дизайн) → спека в openspec/changes/<id>/ + раздел «Decisions made without discussion» → ваше утверждение → план с кодом → ваше утверждение → SDD (контроллер на sonnet, implementer-ы haiku/sonnet, ревью каждой задачи, финальное ревью на opus) → PR в Gitea с рулингами → вы делаете merge → «закрывай»: archive, close issue, удаление ветки/worktree/workspace, pull main.

Ручных шагов три: два утверждения и merge. Читать обязательно: спеку один раз, раздел решений каждый раз, когда он пополняется.

Обновление

git pull && bash install.sh. Бэкапы CLAUDE.md и settings.json создаются автоматически. Раз в два месяца сверяйтесь с RELEASE-NOTES.md superpowers: семантика skills между версиями меняется.

Диагностика

bash ~/.claude/skills/harness-doctor/scripts/doctor.sh [проект] — снимок машины, самотест хуков, состояние проекта. В Claude Code тот же скилл harness-doctor агент вызывает сам при симптомах обвязки и чинит безопасное. Отчёт можно вставить в чат с Claude — чеклист прочтения в skills/harness-doctor/SKILL.md.

README.md Unescape Escape

claude-harness