47 lines
5.8 KiB
Markdown
47 lines
5.8 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`.
|
||
|
||
**Самотест хуков** — любое `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. Не отключать хук ради того, чтобы «прошло».
|