Что такое Handbooks?
Один код на входе, два справочника на выходе — повествовательный сайт документации для команды и индекс местоположений для кодинг-агента. Из одной распарсенной карты, всегда в ногу с кодом.
Один код на входе. Два справочника на выходе.
Handbooks записывает одну и ту же карту вашего кода дважды, потому что у неё два совсем разных читателя:
📖 Справочник для людей
Документационный сайт с повествованием по этапам — поиск, тема, глубокие ссылки — сгенерирован из кода и открывается прямо из file://. Его читаете вы.
🤖 Справочник для ИИ
Машинный индекс местоположений: таблицы маршрутизации файл→этап, факты вызовов по функциям, llms.txt и устанавливаемый пакет SKILL. Его читает ваш кодинг-агент.
В основе — одни и те же факты (граф вызовов, построенный парсером), поэтому они никогда не разойдутся. Один оптимизирован под повествование и навигацию, другой — под маршрутизацию и обнаружение устаревания.
Проблема, сформулированная прямо
У вас есть репозиторий. Он слишком велик, чтобы держать его в голове, и слишком велик, чтобы уместить его в контекстное окно.
Попросите кодинг-агента «повторять неудавшиеся загрузки три раза» — и он уверенно исправит ту единственную функцию загрузки, которую нашёл, пропустив константу с политикой повторов, зеркальную реализацию в batch-воркере, метрику, считающую попытки, и тест, который проверяет старое поведение.
Это не сбой рассуждения. Это сбой маршрутизации. Агент просто никогда не видел карту.
Версия в одно предложение
Handbooks читает ваш код настоящим парсером, строит по нему карту, передаёт эту карту агенту как индекс местоположений — не как сводку — и поддерживает карту в актуальном состоянии по мере изменения кода.
Попробуйте, прежде чем читать дальше
Всё написанное ниже не имеет значения, если оно не запускается. Это занимает около тридцати секунд, не тратит ни одного токена и не требует API-ключа:
git clone <this repo> && cd handbooks
pnpm install && pnpm build
pnpm demopnpm demo прогоняет весь тулчейн на встроенном образце проекта с использованием
встроенного mock-сервера LLM. Когда он завершится, у вас на диске будут отрендеренное
руководство, HTML-сайт, индекс-локатор для агентов и провалидированный SKILL-пакет.
Три идеи, на которых это построено
1. Факты берутся из парсера, а не из модели
Handbooks разбирает каждый исходный файл с помощью tree-sitter
и строит типизированный граф вызовов: функции, методы, рёбра вызовов, разрешённые через
self/атрибуты/параметры/импорты, вызовы, покидающие ваш код, и вызовы, которые
разрешить не удалось — они помещаются в карантин в отдельном файле и никогда не
угадываются.
Файлы, которые не удалось прочитать или разобрать вовсе, помещаются в карантин точно так же — этот пробел можно перечислить, а не обнаружить задним числом по его отсутствию.
Этот слой никогда не касается LLM. Запустите его дважды — получите один и тот же граф дважды.
2. Проза накладывается поверх фактов и помечается
LLM пишет человекочитаемую часть: для чего нужен файл, как устроена подсистема, какое состояние проходит через какие этапы. Она всегда привязана к графу, а там, где она не получилась, структура всё равно выпускается — с пустым описанием.
Отсутствующее предложение лучше выдуманного.
3. Карта построена для маршрутизации, а не для чтения
Результат — это не сводка вашего кода. Это индекс, отвечающий на вопрос «какие файлы, функции и состояние должно затронуть это изменение?» — включая разбросанные и неочевидные. Планировщик затем использует этот индекс, читает реальные исходники по каждому найденному адресу и выдаёт план правок, побайтово точный настолько, что его можно применить механически.
Что даёт один запуск
| Результат | Для кого |
|---|---|
| Markdown-руководство — обзор, индекс этапов, страница на каждый этап, таблица регистров состояния | люди |
Многостраничный HTML-сайт — закреплённое оглавление, хлебные крошки, переключатель темы, работает по file:// | люди |
| Одна самодостаточная HTML-страница, которую можно отправить по почте | люди |
Индекс для агентов — символ → path:line-line, таблицы файлов и вызовов, рецепты grep | агенты |
llms.txt + llms-full.txt | агенты |
| SKILL-пакет с хешем содержимого для каждого файла, чтобы дрейф был обнаружим | агенты |
Для кого это
| Вы… | Вы получаете… |
|---|---|
| Инженер, только что унаследовавший сервис на 200 тыс. строк | Поэтапный разбор, который действительно можно прочитать, плюс HTML-сайт, которым можно поделиться |
| Тот, кто запускает кодинг-агента на большом репозитории | SKILL-пакет, который избавляет агента от угадывания, где что лежит |
| Тимлид, вводящий людей в проект | Документация, которая перегенерируется вместо того, чтобы гнить |
| Тот, кто поддерживает полиглотный монорепозиторий | Один проход по 18 языкам с раскрытием достоверности анализа для каждого языка |
Чего это вам стоит
- Node.js ≥ 20.11 и pnpm. Это вся установка. Никакой нативной компиляции, никакого
Python, никакого
node-gyp— парсеры представляют собой WebAssembly. - OpenAI-совместимая конечная точка для LLM-фаз. Хостинговый OpenAI, Azure, vLLM,
Ollama, LiteLLM, внутренний прокси — всё, что говорит на
/v1/chat/completions. Это может быть модель, работающая на вашей собственной машине. - Совсем ничего для
handbook analyze— команды, которую стоит запустить первой.
Покидает ли мой код мою машину?
Phase 1 выполняется полностью локально. Phase 2 и Phase 3 отправляют содержимое файлов на ту конечную точку,
которую настроили вы, — а это может быть localhost. Больше ничего наружу не уходит, а
--max-chars-per-file ограничивает, сколько из любого отдельного файла вообще может быть отправлено. См.
модель доверия.
Куда идти дальше
Зачем это существует
Проблема маршрутизации и почему сводка по кодовой базе её не решает.
Как работает генерация
Пять фаз, сколько стоит каждая и что деградирует при сбое одной из них.
Конфигурация
Флаги, переменные окружения, каскады .env и handbook.config.yaml — один реестр.
Устранение неполадок
То, что действительно идёт не так, и что с этим делать.