aep/claude-harness
1
0
Fork 0
Code Issues 13 Pull Requests 3 Actions Packages Projects Releases Wiki Activity
claude-harness/skills/harness-doctor/SKILL.md
Andrey Epifancev 0e984a096e feat(doctor): проверки ролей, самотест role-hint, режим workspace, размеры 
Refs #2

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MzkPQWjfA7RpqYWkjnqJwt
2026-10-12 00:35:45 +04:00

6.9 KiB
Raw Blame History

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.
  • MISS roles/<r>.md, MISS skill role, MISS agent briefing, MISS link-roles.sh → bash <пакет>/install.sh (версия ≥ 0.3.0).
  • WARN глобальный CLAUDE.md > 3 КБ → в ~/.claude/CLAUDE.md дописано лишнее; процесс роли живёт в ~/.claude/roles/<r>.md, перенести туда.

Самотест хуков — любое 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.
  • «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, link-roles.sh в workspace, codegraph init в worktree, .claude/code-paths, строка в .gitignore на ветке. Всё остальное — находка пользователю: профиль shell, плагины, токены, удаление чего-либо.

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

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