Ваше первое настоящее руководство

Это полный цикл на настоящем репозитории. Он написан так, чтобы его выполняли по порядку, и бесплатные проверки в нём намеренно стоят раньше дорогих.

alias handbook="node $(pwd)/packages/cli/dist/main.js"
export REPO=~/code/myrepo
export WORK=work/myrepo

Шаг 1 — Семь раз отмерь

handbook analyze --source $REPO --work $WORK

{
  "language": "multi",
  "files": 412,
  "functions": 3187,
  "edgesKept": 9042,
  "edgesDropped": 611,
  "filesUnparsed": 3
}

Это бесплатно, и это ваш дымовой тест. Без LLM, без ключа, без токенов.

Исправьте всё перечисленное сейчас. Каждая проблема на этом шаге позже становится более дорогой проблемой.

Шаг 2 — Сгенерируйте руководство

Это шаг, который стоит токенов. На репозитории среднего размера рассчитывайте на минуты.

Начните с дешёвого:

handbook generate --source $REPO --work $WORK

Это --detail brief и --synth-mode oneshot: короткая карточка на файл и скелет за один проход. Это самый быстрый способ увидеть, верна ли сама форма руководства.

Посмотрите на $WORK/phase2/skeleton.yaml. Похож ли список этапов на вашу систему? Если да — углубляйте:

handbook generate --source $REPO --work $WORK \
    --phase 2a --detail deep --resume

--phase 2a --resume углубляет только карточки, пропуская файлы, у которых уже есть полная. Скелет, который вы уже проверили, остаётся.

Если скелет неправильный, перезапустите 2b с циклом «актор–критик»:

handbook generate --source $REPO --work $WORK --phase 2b,2c,3 --synth-mode doctor

Шаг 3 — Отрендерите его

handbook render --work $WORK --title "MyRepo Handbook" \
    --html --html-single --agent-site --llms-txt

Без LLM. Запускайте сколько угодно — в CI, на каждом коммите.

Добавьте --source-base-url https://github.com/me/myrepo/blob/main, чтобы каждый путь к файлу в руководстве стал ссылкой на настоящий файл. Без него вывод вообще не содержит внешних URL — что важно для приватной кодовой базы.

Откройте $WORK/handbook/html/overview.html и прочитайте его. Это момент, когда нужно судить, хорошо ли получилось руководство.

Шаг 4 — Упакуйте его для вашего агента

handbook skill --handbook $WORK/handbook --out skills/myrepo \
    --name myrepo --project "MyRepo" \
    --work $WORK --source $REPO \
    --agent-dir $WORK/handbook/agent

--work + --source вместе порождают coverage.json: хеш содержимого для каждого файла. Именно это делает дрейф руководства обнаружимым, а не молча неверным позже.

--agent-dir включает в пакет индекс для агента и его таблицы фактов и даёт протоколу маршрутизации SKILL grep-рецепты — так что агент превращает имя символа в path:startLine-endLine одной командой, вместо того чтобы читать прозу и догадываться.

Шаг 5 — Провалидируйте его

handbook validate --skill skills/myrepo --source $REPO

Проверяет структуру, контракт frontmatter, согласованность «индекс ↔ страницы этапов» и заново хеширует исходники, чтобы сообщить об отставших страницах. Завершается с кодом 2 при неудаче, поэтому именно эту команду стоит поставить в CI.

Шаг 6 — Спланируйте настоящее изменение

handbook plan --source $REPO --handbook skills/myrepo/references \
    --request "Retry failed uploads three times before giving up" \
    --out plan.md

Агентный цикл только для чтения: он листает, читает и делает grep — инструмента записи у него нет вовсе, — маршрутизируется по руководству, сверяется с настоящими исходниками и записывает plan.md.

Прочитайте план. Действительно прочитайте. Он заканчивается машиночитаемым блоком деклараций:

### EDIT 1

- file: `src/upload.py`
- where: `Uploader.send (~88)` — wrap the request in the retry helper

```old
    response = self._client.put(url, data)
```

```new
    response = self._retry(lambda: self._client.put(url, data), attempts=3)
```

```json
{ "will_modify": ["Uploader.send"], "will_add": ["Uploader._retry"], "will_remove": [] }
```

Шаг 7 — Примените его, оставив путь назад

handbook apply --source $REPO --plan plan.md --dry-run   # verify only, never writes
handbook apply --source $REPO --plan plan.md             # for real

Пробный прогон по духу не является необязательным. Он разрешает каждый якорь по текущему содержимому файлов и говорит вам ровно, какие правки лягут.

Применение печатает каталог резервной копии. Скопируйте его куда-нибудь до того, как он понадобится:

handbook rollback --backup $REPO/.handbook-patches/2026-08-08T14-05-11-204Z

Откат отказывается трогать любой файл, изменившийся после патча, если не передан --force, — потому что его восстановление молча уничтожило бы эту работу. Все четыре правила безопасности — в Применении изменений.

Шаг 8 — Прокатите руководство вперёд

Код сдвинулся. Не перегенерируйте — сделайте resync.

Кейс — это каталог, который вы собираете сами:

cases/upload-retry/
  edited/       copy of the repo after the change   (required)
  plan.md       the plan from step 6                (optional — sharpens scope)
  change.diff   unified diff of the change          (optional — widens scope)

mkdir -p cases/upload-retry
cp -R $REPO cases/upload-retry/edited
cp plan.md cases/upload-retry/
handbook resync --case cases/upload-retry --work $WORK

Resync заново анализирует изменённое дерево, сравнивает старый граф с новым и перегенерирует только то, что изменилось. Уже отрендеренные результаты в $WORK/handbook обновляются автоматически.

Нет под рукой конечной точки? --no-llm обновляет структурные факты и помечает прозу устаревшей, вместо того чтобы делать вид, что она актуальна.

Если ваш репозиторий очень большой

Подробнее — в Стоимости и производительности.

Дальше