Словарь терминов

Handbooks использует горстку обычных слов в особых смыслах. Если разобраться с ними сразу, каждая следующая страница станет короче.

Артефакты

Граф вызовов (call graph)

Результат Phase 1. Каждая функция и метод в вашем коде плюс каждое ребро вызова между ними, типизированное по способу разрешения. Производится парсером, никогда — моделью.

Живёт в <work>/phase1/graph.json. Всё нижестоящее читает его, и ничто не разбирает исходники заново.

Покрытие сканирования (scan coverage)

Вторая половина честности Phase 1: список файлов, которые анализатор не смог превратить в факты, у каждого — своя причина: unreadable (не удалось чтение), unparsable (упала грамматика) или partial (разобрался, но с синтаксическими ошибками, так что его факты настоящие, но неполные).

Первые два вдобавок убираются из scannedFiles в графе, поэтому ничто нижестоящее не описывает файл, которого парсер и не открывал. Пустой список — это утверждение, что разобралось всё; отсутствие самого файла таким утверждением не является. Живёт в <work>/phase1/scan-coverage.json.

Карточка (card)

Одна на каждый исходный файл. Отвечает на вопрос для чего этот файл? тремя полями — purpose, role, lifecycle — плюс, в режиме --detail deep, разбор на 120–300 слов и заметка по каждой функции.

Структурная половина карточки берётся из графа; прозаическая половина — из LLM. Если проза не получилась, карточка всё равно существует, но с пустым описанием. Живёт в <work>/phase2/cards/<path>.json.

Роль (role)

Поле role карточки берётся из закрытого словаря: entrypoint, orchestration, domain_logic, io_transport, data_model, config, util, test, generated, other. Всё прочее, что выдумает модель, схлопывается в other — творческий ответ не может расширить это множество.

Этап (stage)

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

Этапы упорядочены по жизненному циклу исполнения, а не по алфавиту или каталогам — руководство читается в том порядке, в котором система реально работает.

Скелет (skeleton)

Упорядоченный список этапов: повествовательный хребет. Либо синтезируется LLM (--strategy file), либо пишется вами (--strategy member). Живёт в <work>/phase2/skeleton.yaml.

Назначение (assignment)

К какому этапу относится каждый файл. Каждый файл получает ровно один основной этап и может перечислить дополнительные этапы, которых он тоже касается. Живёт в <work>/phase2/assignment.json.

Организация (organization)

Внутри этапа — файлы, упорядоченные по топологии графа вызовов и сгруппированные в 2–8 озаглавленных подгрупп. Живёт в <work>/phase2/organization.yaml.

Повествование (narration)

Проза: одно резюме на этап плюс обзор системы. Пишется снизу вверх — дети раньше родителей, — чтобы резюме родительского этапа писалось со знанием того, что говорят его дети. Живёт в <work>/phase3/narration.json.

Регистр (register)

Элемент состояния, который проходит сквозь этапы: пул соединений, фича-флаг, бюджет повторов, токен аутентификации. У каждого регистра есть id, одна строка семантики простым языком и список этапов, которые его касаются.

Регистры — самый полезный артефакт для веерных изменений, потому что «какие этапы касаются этого состояния» — это ровно тот вопрос, который задаёт разбросанное изменение. Живут в <work>/phase3/registers.json.

Каталоги

Рабочий каталог (--work)

Место, где живёт каждый артефакт конвейера. Один на каждый документируемый репозиторий.

<work>/
  phase1/   graph.json · functions.csv · graph.dot · dropped-calls.json · scan-coverage.json
  phase2/   cards/ · skeleton.yaml · assignment.json · organization.yaml · strategy.json
  phase3/   narration.json · registers.json · cache/
  handbook/ the rendered output, once you run `render`
  run-manifest.json

Его безопасно удалять и перегенерировать, и безопасно коммитить, если вы хотите держать руководство под версионным контролем. Генерация не изменяет ничего за его пределами.

Каталог handbook

Отрендеренный результат — markdown и, по желанию, HTML, агентский индекс и llms.txt. По умолчанию — <work>/handbook.

Каталог skill (--out у skill)

Упакованный агентский SKILL: SKILL.md плюс references/. Самодостаточен, им можно делиться; исходный код в него никогда не встраивается.

Каталог кейса (--case у resync)

То, что вы передаёте resync, чтобы описать изменение:

<case>/
  edited/       the changed source tree             REQUIRED
  plan.md       what the change was                 optional — sharpens scope
  change.diff   unified diff vs the previous tree   optional — widens scope

Команды, по одной строке на каждую

Фазы

--phase принимает all, 1, 2 (то есть 2a+2b+2c), любую отдельную фазу или список через запятую вроде 2c,3.

Две стратегии

Два слова, которые легко перепутать

Уровень достоверности (fidelity tier) — насколько хорош анализ для языка. full (написанный вручную адаптер) или generic (движок, управляемый конфигурацией). Объявляется для каждого адаптера, записывается для каждого языка и раскрывается в обзоре руководства. См. Достоверность анализа.

Детализация (detail) — насколько глубока проза. brief (purpose, role, lifecycle) или deep (плюс разбор и заметки по каждой функции). Задаётся через --detail.

Они независимы: у языка уровня generic всё равно могут быть карточки deep. Проза становится глубже; факты о вызовах твёрже не становятся.