# claude-harness Обвязка для разработки с 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) | связи символов для сабагентов | `brew install`/`npm i -g` | | Контекст по модулям | вложенные CLAUDE.md, ARCHITECTURE.md | границы, конвенции | этот пакет | | Роль сессии | `roles/`, skill `/role`, агент `briefing`, хук `role-hint.sh` | правила, файлы и память своей роли | этот пакет | | Жёсткие правила | `guard-main.sh`, `require-plan.sh` (PreToolUse) | то, что нельзя доверять промпту | этот пакет | | Вид личных проектов | skill `aura-design` (справочники + набор `kit/`: токены, компоненты React, оболочка) | дизайн-система AURA: цвета, типографика, компоненты, раскладка | этот пакет | Что **не** входит и почему: 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 проекта-пилота install.sh установка глобальной части, идемпотентно; --check проверяет окружение new-project.sh каркас нового проекта: git, CLAUDE.md, openspec init, codegraph init, remote roles/.md общий слой ролей dev/admin/analyst/qa → ~/.claude/roles/ skills/role/SKILL.md /role : загрузить роль, память, запустить briefing → ~/.claude/skills/role/ agents/briefing.md выжимка состояния для роли (sonnet, только чтение) → ~/.claude/agents/ skills/aura-design/ дизайн-система AURA личных проектов: SKILL.md, reference/, kit/ → ~/.claude/skills/aura-design/ 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 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 (обвязка их не ставит): ```bash 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`, раздел «Роли». ## Установка ```bash # 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:// --token # scopes: read:user, write:repository, write:issue npm i -g @fission-ai/openspec # codegraph: https://github.com/colbymchenry/codegraph # 3. Глобальная часть bash install.sh --check bash install.sh # 4. Проверка хука: в любом репозитории на main запустить claude и попросить создать файл. # Ожидается BLOCKED и предложение создать worktree. # bash tests/run.sh — тесты пакета должны быть зелёными. ``` ## Новый проект ```bash bash new-project.sh ~/projects/my-app ssh://git@:2222//my-app.git ``` Заполните `{{...}}` в `CLAUDE.md`, положите фикстуры, запустите `claude` и опишите задачу своими словами. Дальше по `docs/HARNESS.md`. ## Цикл одной фичи, коротко фраза → агент заводит issue → brainstorming (вопросы, подходы, дизайн) → спека в `openspec/changes//` + раздел «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`.