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 @colbymchenry/codegraph, brew install tea); не обходить, обвязка без него неполная. Формулы codegraph в brew нет.
• После установки codegraph подключить MCP: claude mcp add-json -s user codegraph '{"type":"stdio","command":"codegraph","args":["serve","--mcp"],"alwaysLoad":true}', перезапустить сессию, в проекте — codegraph init. Не codegraph install: он дописывает секцию в ~/.claude/CLAUDE.md, install.sh её сотрёт, а файл выйдет за 3 КБ.
• 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.
• MISS roles/<r>.md, MISS skill role, MISS agent briefing, MISS link-roles.sh → bash <пакет>/install.sh (версия ≥ 0.3.0).
• WARN permissions обвязки: N/M, нет: … или MISS permissions обвязки → allow-правила цикла фичи (global/permissions.json) не стоят в ~/.claude/settings.json. Это находка владельцу: bash <пакет>/install.sh запускает он сам. Агент себе права не выдаёт: так он обошёл бы отказ классификатора auto mode. Если обвязка ставилась с --no-permissions осознанно, WARN ожидаем.
• WARN глобальный CLAUDE.md > 3 КБ → в ~/.claude/CLAUDE.md дописано лишнее; процесс роли живёт в ~/.claude/roles/<r>.md, перенести туда.

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

Корпус хуков — ok корпус хуков: N/N: установленные хуки дают на реальных командах пилота те же вердикты, что размечены. WARN корпус хуков: N/M и строки над ним — расхождения: id, класс, ожидалось, получено, команда. После install.sh расхождение — регрессия пакета; разобрать одну команду: python3 ~/.claude/hooks/harness_target.py targets '<команда>' <cwd>. MISS корпус хуков — нет harness_target.py или раннера, чинится install.sh.

Проект

• 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 .claude/worktrees/ не в .gitignore → добавить строку на ветке (как .bounded), иначе worktree из EnterWorktree попадут в git status и в индекс codegraph основного checkout.
• WARN нет allow-правила для git push origin --delete → находка владельцу (чеклист закрытия п. 4). Правило ставит bash install.sh. При --no-permissions готовую строку из WARN владелец сам добавляет в .claude/settings.json проекта. Агент settings.json не правит. ok allow … называет файл, где правило найдено: проектный settings.json, settings.local.json или глобальный.
• WARN tea не отвечает → tea logins list; токен нужен со scopes read:user, write:repository, write:issue.
• «workspace (не git)» → режим нескольких репозиториев. WARN … битая ссылка → репозиторий направления переименован или файл удалён: bash ~/.claude/harness/link-roles.sh <workspace>. WARN нет <dir>/.claude/roles/<r>.md → создать проектный файл роли из ~/.claude/harness/project-template/role-repo/ROLE.md.
• WARN индекс auto-memory > 3 КБ → индекс снова стал журналом состояния; свернуть закрытое в registry-closed.md, уроки — в notes/ направления (политика памяти в глобальном CLAUDE.md).

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

install.sh --no-permissions (агент так обновляет хуки и файлы; права ставит владелец своим bash install.sh), link-roles.sh в workspace, codegraph init в worktree, .claude/code-paths, строка в .gitignore на ветке. Всё остальное — находка пользователю: профиль shell, плагины, токены, права, удаление чего-либо.

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

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