claude-harness/CLAUDE.md

claude-harness

Что это

Пакет обвязки для разработки с Claude Code: глобальный CLAUDE.md с процессом, три блокирующих хука и неблокирующий role-hint, скрипты подключения проекта и skill диагностики. Для одного разработчика, который ведёт фичи через superpowers, хранит задачи в Gitea и требования в OpenSpec. Главный сценарий: bash install.sh ставит глобальную часть в ~/.claude, adopt-project.sh подключает существующий проект, new-project.sh создаёт новый; дальше проект живёт по docs/HARNESS.md. Репозиторий — источник; установленные копии в ~/.claude по месту не правятся.

Стек и ограничения

• Bash (set -euo pipefail) и markdown. JSON из stdin хуков разбирается встроенным python3; других зависимостей времени выполнения нет. Внешние CLI (tea, openspec, codegraph) проверяются, но не требуются для установки.
• Хук блокирует вызов только через exit 2 с сообщением в stderr; exit 0 — пропустить. Любой сбой разбора входа должен приводить к пропуску, не к блокировке.
• install.sh идемпотентен: повторный запуск не ломает settings.json и делает бэкапы CLAUDE.md и settings.json с меткой времени.
• Хуки работают из ~/.claude/hooks/, пути в settings.hooks.json через $HOME; CLAUDE_CONFIG_DIR переопределяет ~/.claude.
• macOS и Linux; python3 должен быть в PATH сессии Claude Code.

Архитектура

• hooks/ — поведение обвязки, единственный «код» с логикой. guard-main.sh (PreToolUse на Edit/Write/MultiEdit/Bash): запрет записи на main/master/detached HEAD, исключение для openspec-only коммитов. require-plan.sh (PreToolUse на Edit/Write/MultiEdit): правки в каталогах кода только при плане для ветки или файле .bounded. harness-check.sh (SessionStart): проверка, что проект подключён. role-hint.sh (SessionStart, все источники): подсказка роли по session_title. settings.hooks.json — блок, который install.sh сливает в ~/.claude/settings.json.
• install.sh, adopt-project.sh, new-project.sh — установка и бутстрап. install.sh копирует global/, hooks/, project-template/, adopt-project.sh, new-project.sh и skills/harness-doctor в ~/.claude/{CLAUDE.md,hooks,harness,skills}. adopt-project.sh работает на ветке chore/harness-init и вливает её ff в текущую ветку; это единственная разрешённая запись на main вне PR.
• global/CLAUDE.md — глобальные правила процесса, ставятся в ~/.claude/CLAUDE.md. project-template/ — CLAUDE.md, CLAUDE.harness-section.md (секция «OpenSpec и superpowers», по ней harness-check узнаёт подключённый проект), ARCHITECTURE.md, gitignore.
• skills/harness-doctor/ — skill диагностики: scripts/doctor.sh снимает состояние машины и проекта и прогоняет самотест хуков; SKILL.md — чеклист прочтения отчёта.
• roles/ — общий слой ролей (формат: четыре раздела, см. спеку ролей), skills/role/ — skill /role, agents/briefing.md — агент выжимки, link-roles.sh — симлинки workspace → репозитории направлений. Ставятся install.sh в ~/.claude/{roles,skills/role,agents,harness}.
• tests/ — тесты пакета на bash: run.sh + test-*.sh, работают с источниками, install.sh ставят во временный CLAUDE_CONFIG_DIR.
• caveman/config.json — выключенный по умолчанию caveman. examples/ — реальный CLAUDE.md проекта-пилота.
• docs/HARNESS.md — как устроен цикл фичи, SDD, маркировка, закрытие. docs/PILOT-2026-09-27.md — пилот. docs/retro/ — ретроспектива 11.10.2026 и скрипты подсчёта по транскриптам. docs/superpowers/specs/ — спеки фич обвязки, docs/superpowers/plans/ — планы.
• Связь слоёв: хуки читают JSON вызова из stdin и состояние git проекта; скрипты бутстрапа читают project-template/; doctor.sh читает установленные копии в ~/.claude, не репозиторий.

Команды

• bash tests/run.sh [имя] — весь набор тестов. Зелёным считается только весь набор.
• bash install.sh --check — проверка окружения: бинарники, плагины, конфликты.
• bash install.sh — установка глобальной части, идемпотентно.
• bash skills/harness-doctor/scripts/doctor.sh [проект] — отчёт и самотест хуков. Только чтение.
• bash adopt-project.sh <папка> [--no-merge] [--push] — подключить существующий проект. Из терминала, не из Claude Code.
• bash new-project.sh <папка> [ssh-url] — каркас нового проекта.
• python3 docs/retro/scripts/retro_stats.py <каталог транскриптов> и retro_blocks.py — статистика сессий и блокировок хуков для ретро; hook_blocks_export.py <каталог> [...] — выгрузка блокировок в JSONL (сырьё для тестов хуков).

Тесты

• tests/run.sh — автоматические тесты источников (хуки через фиктивный JSON, скрипты во временных каталогах, размеры). Самотест хуков в doctor.sh проверяет установленные копии; перед ним bash install.sh.
• Ручная проверка хука: на main в любом репозитории попросить агента создать файл, ожидается BLOCKED.
• tests/ покрывает role-hint и скрипты install.sh, doctor.sh, link-roles.sh; регрессионные тесты guard-main и require-plan на реальных командах из транскриптов (бэклог ретро B2) пока не сделаны.

Текущая работа

Бэклог обвязки — docs/retro/2026-10-11.md, раздел 4 (B1–B12), решения владельца — раздел 5. Находки ретро маркируются RT-n.

• Сделано: B5+B6 часть 1 — слой ролей (PR #4, 0.3.0). Часть 2 (awp-ca) — issue #2, отложенные находки — issue #5.
• В работе: B1+B2 и отмена исключения openspec-only для guard-main — issue #6, ветка feat/6-guard-main-target.
• Дальше: B3/B4/B10, B12.

OpenSpec и superpowers

• Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.
• Когда brainstorming классифицировал задачу как architectural, структуру change создать через openspec new change <id> (или /opsx:propose <id>), а содержимое proposal.md, specs/ и design.md написать по итогам brainstorming. tasks.md из OpenSpec не заполнять — задачи живут в плане superpowers.
• /opsx:apply не использовать: исполнение идёт через writing-plans и SDD/executing-plans.
• openspec archive <id> — после merge PR, как часть чеклиста закрытия.
• Хук require-plan защищает любой каталог src/ на любой глубине. Если код лежит иначе — перечислить каталоги (префиксы от корня, по одному в строке) в .claude/code-paths. В этом репозитории код — hooks/ и skills/, они перечислены в .claude/code-paths.