claude-skill-harness

English | 中文

Скилл для Claude Code, предназначенный для длительных многосессионных кампаний разработки.

Основан на идеях, описанных в материалах Anthropic Engineering:

• Harness Design for Long-Running Apps
• Effective Harnesses for Long-Running Agents

Что изменилось в v2

Harness v2 сохраняет интерфейс команды /harness-plan, но заменяет внутреннюю модель восстановления:

• компактное машинное состояние вместо восстановления в свободном тексте
• один активный current-contract.json на фичу
• session-summary.json как артефакт возобновления по умолчанию
• детерминированные Python-скрипты для переходов состояний
• риск-ориентированное QA вместо постоянных полных циклов ревью
• переносимые пути скриптов через ${CLAUDE_SKILL_DIR} — работает независимо от места установки
• harness_reset.py для детерминированного архивирования кампаний
• маршрутизатор команд с явной маршрутизацией: /harness-plan "goal" → INIT, /harness-plan → RESUME
• /harness-plan focus проверяет наличие конфликтов перед переключением
• при старте читается только активная фича из features.json, а не весь файл
• session-protocol.md объединён с SKILL.md для снижения расхода токенов на сессию
• эскалация повторных попыток: счётчик selftest_retries автоматически блокирует после 3 последовательных сбоев
• сигналы свежести сессии: checkpoint_writes, количество выполненных шагов и количество фич в сессии инициируют рекомендации о начале новой сессии
• руководство по параллельным подзадачам: используйте инструмент Agent для независимой работы в рамках одной фичи
• автопродвижение по умолчанию: подтверждение запрашивается только при утверждении плана INIT, деструктивных действиях и ревью QA
• обнаружение дрейфа области: checkpoint предупреждает, когда files_touched нарушают границы scope_out
• быстрая проверка: harness_checkpoint.py --quick-verify запускает test_command во время реализации для раннего обнаружения регрессий
• структурированная запись сбоев: объект last_failure в checkpoint (команда, краткое описание ошибки, затронутые файлы, временная метка)
• контекст передачи сессии: session_id, session_step_count и handoff_reason в session-summary для непрерывности между сессиями
• отслеживание ручных проверок: --manual-check-done фиксирует выполненные ручные проверки до завершения фичи
• история команд контракта: command_history отслеживает уточнения команд верификации с временными метками
• статус backlog добавлен в машину состояний с переходами в pending, in_progress и skipped
• определение платформы во время выполнения: detect_platform() / skill_home() для совместимости со средой Codex

Основные файлы

.harness/
├── campaign.json
├── features.json
├── current-contract.json
├── session-summary.json
├── features-schema.json
├── contract-schema.json
├── session-summary-schema.json
└── progress.md

Модель состояния

campaign.json

Метаданные кампании и значения по умолчанию:

• bootstrap_command
• setup_command
• default_review_policy
• baseline_status
• last_session_commit

features.json

Отслеживание фич с неизменяемыми объектами verification и структурированными объектами checkpoint. Каждая фича также содержит blocked_history (журнал блокировок/разблокировок с временными метками, ограничен 10 записями) и archived_contract (снимок контракта, сохраняемый при завершении фичи).

current-contract.json

Активный контракт фичи:

• feature_id
• goal
• scope_in
• scope_out
• verification_claims
• verification_commands
• manual_checks
• review_policy
• execution_context — рабочая директория и таймаут для команд верификации
• command_history — журнал уточнений команд верификации с временными метками

session-summary.json

Компактный артефакт возобновления, используемый новыми сессиями и хуком SessionStart:

• цель и режим кампании
• текущая фича
• счётчики прогресса
• следующие шаги возобновления
• известные сбои
• статус окружения
• session_id и session_step_count для определения границ сессии
• handoff_reason — причина завершения предыдущей сессии (свежесть, блокировка, завершение, прерывание)

Встроенные скрипты

python3 ${CLAUDE_SKILL_DIR}/scripts/harness_validate.py
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_summary.py
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_pick_next.py
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_transition.py --feature-id F007 --to in_progress
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_contract.py --feature-id F007
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_checkpoint.py --feature-id F007 --next-step "..."
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_checkpoint.py --feature-id F007 --quick-verify
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_checkpoint.py --feature-id F007 --manual-check-done "описание проверки"
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_contract.py --feature-id F007 --update-command "старая команда" "новая команда"
python3 ${CLAUDE_SKILL_DIR}/scripts/harness_reset.py --label "phase-1"

Эти скрипты работают только с директорией .harness/ и предназначены для замены ручного редактирования JSON при типовых переходах состояний. harness_contract.py и harness_checkpoint.py работают только с активной фичей в статусе in_progress, а harness_transition.py отказывается создавать вторую активную фичу.

Ключевое поведение скриптов:

• harness_validate.py проверяет дрейф git (HEAD vs последний верифицированный коммит) и обнаруживает циклические или оборванные зависимости фич.
• harness_checkpoint.py автоматически извлекает files_touched из git diff, если они не указаны явно. --quick-verify запускает test_command перед записью. --selftest-retry / --failure-command / --failure-summary фиксируют структурированную информацию о сбоях. --manual-check-done отмечает ручные проверки как выполненные.
• harness_contract.py поддерживает --update-command для уточнения команд верификации с отслеживанием истории.
• harness_transition.py архивирует активный контракт в запись фичи при завершении (вместо удаления) и добавляет записи с временными метками в blocked_history при блокировке. Поддерживает статус backlog.