claude-harness/CLAUDE.md

claude-harness

Что это

Пакет обвязки для разработки с Claude Code: глобальный CLAUDE.md с процессом, три блокирующих хука, скрипты подключения проекта и 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): проверка, что проект подключён. 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 — чеклист прочтения отчёта.
• 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 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 — статистика сессий и блокировок хуков для ретро.

Тесты

• Отдельного набора тестов нет. Единственная автоматическая проверка — самотест хуков в doctor.sh: фиктивные вызовы Write/Bash на main и на ветке, src/ с планом и без, .bounded. Прогоняется по установленным копиям, поэтому перед проверкой изменений в hooks/ сначала bash install.sh.
• Ручная проверка хука: на main в любом репозитории попросить агента создать файл, ожидается BLOCKED.
• Регрессионные тесты хуков на реальных командах из транскриптов — бэклог ретро B2, пока не сделаны.

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

Бэклог обвязки — docs/retro/2026-10-11.md, раздел 4 (B1–B12), решения владельца — раздел 5. Порядок: B1+B2 (guard-main по цели записи, тесты хуков), затем B5+B6 (роли и память, спека docs/superpowers/specs/2026-10-11-roles-and-memory-design.md), затем B3/B4/B10. Находки ретро маркируются RT-n.

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.