53 lines
7.6 KiB
Markdown
53 lines
7.6 KiB
Markdown
---
|
||
name: harness-doctor
|
||
description: Диагностика обвязки 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 — приложить строку к находке, это дефект пакета.
|
||
|
||
**Корпус хуков** — `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 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. Не отключать хук ради того, чтобы «прошло».
|