# P2 и доработка AGENTS.md: отчёт о выполнении Дата: 2026-10-14. Исполнитель: HARNESS (агент). Основание — ТЗ `docs/TZ-2026-10-14-harness-ragraf-usage.md`: разделы P2-1…P2-4, доработка правил (`AGENTS.md`) и сверка «код ↔ база» (`db_cross`). Все числа получены запуском кода. Где замер сделан на корпусе, это сказано прямо. --- ## 1. AGENTS.md: объём, структура, вынесение ловушек **Измеренная проблема.** `AGENTS.md` занимал **74 378 байт** при бюджете инструкций агента 65 536 байт: файл обрезался при загрузке, и хвост правил (раздел 11) до агента не доходил. Половину объёма занимал раздел 5 «Traps» — **38 937 байт** на 33 ловушки. **Что сделано.** | Действие | Результат | |---|---| | Ловушки вынесены в [`AGENTS-TRAPS.md`](https://github.com/paulmann/RAGRAF/blob/main/AGENTS-TRAPS.md) | отдельный документ 44 КБ: назначение, правила чтения, оглавление из 35 ловушек, тела ловушек без изменений | | В `AGENTS.md` вместо раздела 5 — рабочий индекс | «правила, выросшие из ловушек» (что обязана сделать правка), «самые дорогие ловушки», указатель по темам | | Добавлено оглавление в начало | ссылки на 11 разделов: агент видит состав файла, а не читает его целиком | | Исправлена нумерация | в разделе 4 было ДВА пункта «13» — теперь 13 и 14 | | Ссылки на ловушки исправлены | «см. раздел 5, ловушка N» → `AGENTS-TRAPS.md`, ловушка N (прежние ссылки вели в никуда) | | Обновлён размер | **74 378 → 42 415 байт** (запас к бюджету 23 КБ) | **Зачем именно так, а не «просто сократить».** Ловушка в этом проекте — не мнение, а измеренный дефект с замером и защитой; выбросить их нельзя, а держать в файле, который обрезается, — значит потерять молча. Разделение «правила остаются в `AGENTS.md`, доказательства — рядом» сохраняет и то, и другое. **Что ещё улучшено для работы агента.** * `tools/check_all.py` — **раннер проверок**. Раньше «прогнать проверки» значило «прогнать те, которые вспомнил»: 77 файлов, единого входа нет. Раннер делит их на группы (`core` — по умолчанию, `external` — нужны чужие корпуса, `service` — нужны сервисы), печатает вердикт по каждой проверке и строку для отчёта: `python tools/check_all.py` (состав групп — `--list`). * В `docs/skills/ragraf-core/SKILL.md` обновлены действующие числа (38 и 35) и названы новые операции. --- ## 2. P2-1: сравнение ревизий (`diff`) **Что сделано.** Новый модуль [`code_diff.py`](https://github.com/paulmann/RAGRAF/blob/main/src/ragraf/code_diff.py) и операция `op_diff` (`diff` в CLI, `ragraf_diff` в MCP). Ответ содержит: | Раздел | Что отвечает | |---|---| | `files` | добавленные, удалённые, изменённые файлы (по контрольной сумме) | | `symbols` | добавленные и исчезнувшие символы (сравнение по `node_id`) | | `edges` | сколько рёбер было и стало, и по каким видам связь изменилась | | `callers_lost` | **регрессии**: символы, у которых были вызывающие и не стало ни одного | | `writes_lost` | таблицы, которые перестали заполняться (`insert`/`update`/`delete`) | | `modes` | режим (`capability`) каждой ревизии — граница доверия сравнения | **Замер на собственном корпусе** (rev-0110 → rev-0111, то есть по итогам этой же работы): файлов +2/−0/изменено 3; символов +75/−66; рёбер 37 798 → 37 895; **потеряли вызывающих 29 символов**, из них названы местами: `_table_names`, `_looks_like_graph_query`, `_graph_walk`. Сравнение нашло реальные последствия рефакторинга, а не «ничего не менялось». **Границы названы.** `removed: true` у потерявшего вызывающих означает, что и сам символ исчез из кода — это другой случай, чем «символ есть, а вызовов нет». Заглушки (`@file:`, `@ext:`) в регрессии не попадают: у них нет узла в графе, и в первом замере они давали 29 записей с пустыми полями — измерено и исправлено. --- ## 3. P2-2: ответ, а не сырые хиты (`answer=true`) **Что сделано.** Режим `answer` добавлен операциям, которые отвечают на вопрос словами: `search`, `search_multi`, `symbol`, `callers`, `impact` (в MCP — параметр `answer` у `ragraf_search`, `ragraf_search_multi`, `ragraf_symbol`, `ragraf_callers`, `ragraf_impact`). Вместо структурного результата приходит текст и ссылки: ``` **Найдено по запросу «write_check сверка плана записи»** - `src/ragraf/facade.py:3264` - `src/ragraf/facade.py:3293` … > порог достоверности связей: 0.5 ``` **Замер:** ответ на типовой вопрос — **206 символов** (требование ТЗ «≤ 1–2 КБ»); ссылки проверяемы (`файл:строка`), полное число находок названо («…и ещё N»), оболочка (`op`, `index_rev`, `capability`, `found`) остаётся — это контракт, по которому клиент понимает, на какую ревизию опирается ответ. **Полезное следствие для `callers`.** Ответ на «связей 0» больше не читается как «вызовов нет»: названы и число связей ниже порога достоверности, и вызовы, адресованные ИМЕНИ символа без доказанной привязки к определению (`name_links`). Замер: `callers cross_check` — 0 доказанных связей и **5 вызовов по имени** с местами (`src/ragraf/facade.py:927` и другие). --- ## 4. P2-3: память о решениях (`note` / `notes`) **Что сделано.** Хранилище [`notes.py`](https://github.com/paulmann/RAGRAF/blob/main/src/ragraf/notes.py) в control-хранилище корпуса (таблица `note`), операции `op_note` / `op_notes` (`note`/`notes` в CLI, `ragraf_note`/`ragraf_notes` в MCP). * запись: текст (до 4000 символов), метка задачи, метки-теги, путь, автор, ревизия; * чтение: свежие первыми, фильтр по задаче и по подстроке текста; * **границы названы**: заметка — знание АГЕНТА, а не факт индекса; в каждой записи стоит `source: "note"`, автор и время, а в ответе чтения — оговорка, что заметки не заменяют `search`/`symbol`. **Замер на живом корпусе:** запись и чтение по задаче (`task`) и по подстроке работают; `count` различает «всего» и «по задаче». --- ## 5. P2-4: метрики эффекта **Что сделано в `usage`.** Было: `hit_rate`, `calls_with_facts`, `avg_ms`, `misses`, `stale_served`. Добавлено: **`saved_calls`** — число вызовов, которые ЗАМЕНИЛИ чтение файлов или поиск по ним (операция из списка `READ_REPLACING_OPS`, вернувшая хотя бы один факт). Это измерение по журналу; оценка экономии в строках — `est_lines_not_read`. **Замер на собственном корпусе:** 668 вызовов, попаданий **63,5 %**, `saved_calls` считается по журналу, **`stale_served` = 0** (требование приёмки «ответов со stale=true быть не должно»). --- ## 6. db_cross: анализ полезности и новое решение ### 6.1 Что было не так (измерено на BWO) | Дефект | Замер | |---|---| | Имя без доказательства | ответ отдавал два списка ИМЁН: проверить, откуда имя, было нечем | | Проза становилась «таблицами» | 168 имён, среди них `all`, `and`, `al`, `access` — из комментариев и английского текста | | Пустой путь в доказательствах | у текстовых находок `path` был ПУСТ, а строка считалась от начала чанка (например `:98`) | | Мусор из чужой базы | в «неиспользуемых» попадали таблицы `bsdocs` (`domofon`, `1c`, `ozon_update`) при том, что код работает с `wizard_online` | | Скорость | **41,7 с** на вызов: полный проход 101 957 чанков текста регулярным выражением; после перехода на FTS — 72 с из-за плохого выражения разбора (34 с только на имена) | | Слепая зона не названа | место `FROM $table`, где имени нет по определению, нигде не отражалось | ### 6.2 Что сделано 1. **Факты вместо имён.** Каждое имя приходит с источником (`edge` — факт разбора языка, `text` — текстовый образец), видом доступа (`select`/`insert`/…), доказательством `path:line` и текстом конструкции. 2. **Разбор SQL переписан сканером** вместо регулярного выражения: одна линейная проверка окна вокруг ключевого слова (было 34 с на 17 944 чанка, стало ~11 с; затем дешёвая отсечка по подстроке). 3. **Отбор чанков через FTS** (`from OR insert OR update OR delete OR join`) вместо полного прохода: 101 957 → 17 944 чанка. 4. **Правила отбора имён** (каждое из замера): только полная конструкция (`SELECT … FROM`, `INSERT INTO`, `UPDATE … SET`, `DELETE FROM`, `JOIN`); не строка-комментарий; только литерал (кавычка) либо блочный литерал (`<<` покрывает все проекты сразу; теперь честно помечена «заведена, индекс не строился» — полезность такой разработки решает владелец |