claude-harness/skills/harness-doctor/SKILL.md

name, description

name	description
harness-doctor	Диагностика обвязки Claude Code (claude-harness) — когда хук сработал не так, codegraph пустой, агент пишет в main, тесты не видят ключ, обвязка «не подключена» или просто непонятно, что установлено. Запускает doctor.sh, читает отчёт по чеклисту, чинит то, что чинится безопасно, остальное формулирует как находку.

harness-doctor

Один прогон → один отчёт → одинаковое прочтение агентом и человеком.

Когда запускать

• Любой симптом про обвязку: «хук отбрил/пропустил», «codegraph возвращает пусто», «agent запушил в main», «SessionStart ругается», «tea не отвечает», «тесты делают платные запросы».
• Перед первой фичей в новом или только что подключённом проекте.
• По просьбе пользователя «продиагностируй обвязку» / «doctor».

Как

1. bash ~/.claude/skills/harness-doctor/scripts/doctor.sh [папка проекта] — только чтение, ничего не меняет. Отчёт целиком показать пользователю без сокращений.
2. Прочитать по чеклисту ниже. Каждую строку MISS/WARN либо починить (если в списке «чинится само»), либо назвать находкой с маркером O-n и предложить действие.
3. Если отчёт нужен человеку вне Claude Code — он вставляет его как есть; тот же чеклист.

Чеклист прочтения

Машина

• MISS бинарник → установить (npm i -g @fission-ai/openspec, brew install codegraph tea); не обходить, обвязка без него неполная.
• MISS plugin superpowers → /plugin install superpowers@claude-plugins-official. WARN plugin beads/template-bridge → удалить, конфликтуют со skills superpowers.
• MISS/WARN hook … → bash <пакет>/install.sh; «не зарегистрирован» — settings.json правился руками, тот же install.sh сольёт заново.
• WARN в окружении есть *_API_KEY → ключ виден всем сабагентам и делает интеграционные тесты платными при каждом npm test. Убрать из профиля shell, передавать только в строке запуска. Это находка для пользователя, агент сам профиль не правит.
• Глобальный CLAUDE.md без «маркировка: да» или «projectPath: да» → старая версия, install.sh.

Самотест хуков — любое WARN … (ожидалось N) означает, что хук установлен, но не делает того, что должен. Причины по убыванию частоты: правлен руками; python3 не в PATH сессии; settings.json зовёт другой путь. Чинится install.sh; если и после него WARN — приложить строку к находке, это дефект пакета.

Проект

• MISS CLAUDE.md/openspec//.codegraph/ или WARN без секции → обвязка не подключена: bash ~/.claude/harness/adopt-project.sh <root> (сам делает ветку и ff-merge; дерево должно быть чистым).
• «worktree; основной: …» + «MCP смотрит на индекс основного checkout» → в вызовах codegraph_explore передавать projectPath=<root worktree>; если индекса в worktree нет — codegraph init там.
• «ветка: detached» → не работать, вернуться на ветку; guard-main блокирует detached HEAD намеренно.
• «чистое дерево: НЕТ» в основном checkout при закрытии → git pull --ff-only не делать, перечислить файлы пользователю.
• «планы: 0» и нет .bounded при правке кода → require-plan заблокирует; это не ошибка хука, нужен brainstorming или .bounded.
• «code-paths: умолчание» при коде вне src/ → создать .claude/code-paths.
• «SDD workspace: …» при отсутствии активной фичи → хвост незакрытой фичи; проверить чеклист закрытия.
• WARN .bounded не в .gitignore → добавить строку, иначе уедет в main.
• WARN tea не отвечает → tea logins list; токен нужен со scopes read:user, write:repository, write:issue.

Чинится само (без вопроса)

install.sh, codegraph init в worktree, .claude/code-paths, строка в .gitignore на ветке. Всё остальное — находка пользователю: профиль shell, плагины, токены, удаление чего-либо.

Чего не делать

Не «улучшать» хуки по месту: их источник — пакет claude-harness, правка идёт туда и ставится install.sh. Не отключать хук ради того, чтобы «прошло».