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.epifantsev 1d1c70f66b feat: allow-правило git push origin --delete — строка в adopt/new-project, проверка в doctor (#22, B3) 
Решение владельца 2: удаление серверных веток (чеклист закрытия, п. 4)
разрешается allow-правилом в настройках проекта; строку добавляет
владелец, обвязка её даёт.

- doctor.sh, раздел «Проект» (git и workspace): ищет правило, покрывающее
  `git push origin --delete <любая ветка>`, в .claude/settings.json и
  settings.local.json проекта и в глобальном settings.json; ok с файлом,
  WARN с готовой строкой, битый JSON — info.
- adopt-project.sh (обычный режим) и new-project.sh (оба режима) печатают
  строку в «Дальше»; файл настроек не пишут.
- SKILL.md: пункт чеклиста для нового WARN.
- HARNESS.md: шаг 10 — 8 пунктов в roles/dev.md, рецепт п. 4.
- roles/dev.md, п. 4: кто печатает строку; worktree remove раньше
  branch -D (ветку, выведенную в worktree, git не удаляет).
- CHANGELOG 0.4.2, CLAUDE.md «Текущая работа».

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 23:39:47 +04:00

8.5 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 @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 глобальный 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 нет allow-правила для git push origin --delete → находка владельцу: готовую строку из WARN он сам добавляет в .claude/settings.json проекта (решение владельца 2, чеклист закрытия п. 4); агент 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, link-roles.sh в workspace, codegraph init в worktree, .claude/code-paths, строка в .gitignore на ветке. Всё остальное — находка пользователю: профиль shell, плагины, токены, удаление чего-либо.

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

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