# Зачем существует этот репозиторий

## Дорогой прогон — второй

Сложную задачу сделали хорошо. Агент прочитал схему до того, как писать SQL, нашёл ту единственную
колонку, которой не было, прогнал команду, доказывающую, что выгрузка совпадает побайтово, и отдал
ответ вместе с рассуждением. Это заняло часы и много токенов — и это было оправдано.

Через три недели приходит тот же класс работы: другой эндпоинт, другой отчёт, другая выгрузка.
Открывается новое окно. В нём есть новый запрос и больше ничего. Работа выводится заново: то же
изучение схемы, те же тупики, то же «проверю, есть ли такая колонка», те же вопросы пользователю, та
же почти-ошибка. Столько же часов, столько же токенов, та же вероятность той же ошибки. Первый
прогон дал хороший ответ; он не дал ничего, с чего второй прогон мог бы начаться.

В этом вся проблема, и она не про качество модели. Она про то, что переживает сессию.

## Почему диалог это не переносит

Пять механизмов, все обычные:

| Что теряется | Почему |
|---|---|
| путь | ответ фиксирует вывод; шаги, которые к нему привели, остаются в расшифровке |
| проверка | «работает» переживает, а команда, которая это доказала, нет — её нельзя повторить |
| критерий приёмки | он жил в голове агента, поэтому следующий агент придумает другой |
| словарь | термины, на которые ушло два круга, нигде не записаны |
| отрицательный опыт | что пробовали и что не сработало — самое дешёвое знание для повторного использования, и его никогда не записывают |

Сам запрос переживает — и это наименее информативный артефакт завершённой задачи. Начинать с запроса
заново означает начинать заново.

## Что набор делает вместо этого

Три артефакта, у каждого есть место на диске:

1. **Две карточки** (M1, M2). Тема, результат, успех, неизвестное, что вне рамок; затем практик,
   словарь, навыки, факты, которые специалист никогда не станет утверждать по памяти, определение
   готовности. Двадцать минут письма, которые превращают «сделай лучше» в ограниченную работу.
2. **Окружение** (M10). Каталог: `AGENTS.md` с правилами для этого класса работы, `DOMAIN-CARD.md` с
   критерием приёмки внутри, навык с процедурой, `examples/`, `memory/` для записей. Зарегистрирован
   в рантайме, поэтому следующее окно может его увидеть.
3. **Хранилище с одной командой поиска** (M13). Прошлые задачи, рецепты, артефакты и записанные
   неудачи в виде Markdown-записей; поиск — `python tools/experience.py search "<слова задачи>"`.
   С ранжированием и с причиной каждой позиции рядом с результатом.

Решение за третьим пунктом стоит проговорить, потому что это разница между правилом и пожеланием.
«Обращайся к своему опыту» стоит модели обхода каталога и догадки. «Запусти одну команду, которая
вернёт три лучших кандидата с их применимостью» стоит одной команды. Под давлением выполняется только
второе — поэтому набор поставляет команду, а не призыв.

## Что дешевеет, а что нет

| Круг | Стоимость | Замечание |
|---|---|---|
| первый | **выше, чем у обычного ответа** | карточки, файлы окружения, одна проверенная запись |
| второй и дальше | ниже, чем выводить заново | один поиск, проверка применимости, адаптация |
| повторное использование без проверки | **дороже, чем начать заново** | устаревший рецепт в изменившемся окружении стоит переделки плюс неверного поворота |

То есть набор не бесплатен и не автоматичен. Он окупается, когда класс работы повторяется, и
проигрывает на разовой задаче — ровно поэтому M13 говорит: не ищите опыт для тривиальных запросов.

Ожидаемая экономия измеряется в вызовах инструментов, а не в прозе: поиск — одна команда, повторный
вывод — десятки. Это утверждение может проверить кто угодно, и в этом смысл следующего раздела.

## Как проверить это на своей работе

Не принимайте аргумент на веру. Проведите эксперимент на классе работы, который уже случался хотя бы
дважды:

1. **Возьмите класс**, а не задачу. «Добавить nullable-колонку в отчётный эндпоинт», а не «добавить
   `paid_at` в `orders`».
2. **Замерьте обычный круг.** Без окружения: сколько команд запущено, сколько вызовов инструментов,
   сколько вопросов задано пользователю, сколько черновиков отклонено, сколько минут прошло.
3. **Постройте окружение** по этому кругу ([Окружение](04-Environment.ru.md)), запишите один рецепт
   ([Хранилище опыта](05-Experience.ru.md)), зарегистрируйте и начните новое окно со
   стартового промпта.
4. **Замерьте те же пять чисел.** Сравните и запишите результат внутрь окружения.

Если второй круг не дешевле — это находка, а не приговор: обычно запись слишком конкретна (описывает
случай, а не класс) или её строка применимости пропускает то, что должна отклонять. Исправляйте
запись, а не вывод «подход не работает».

## Где границы

- **Это не делает модель умнее.** Меняется то, что модели дают, и то, что она обязана записать до
  того, как ответ принят.
- **Опыт — гипотеза, никогда не авторитет** (инвариант 9). Репозиторий, приложенные материалы и явное
  указание сильнее любой записи; устаревшая запись всегда проигрывает текущему свидетельству.
- **Регистрация может быть шагом человека.** В AutoClaw2 навык появляется только после перезагрузки;
  в HARNESS workspace появляется после одного клика. Набор называет этот шаг, а не делает вид, что
  каталог уже живой (проверка 12 ворот).
- **Хранилище деградирует при неверном использовании.** Записывайте всё — и поиск перестанет
  находить; записывайте секреты и машинные пути — и хранилище станет обузой. И то, и другое отклоняет
  `experience.py check`.
- **Строка ворот — не доказательство.** Это заявление агента, которое человек может проверить по
  пунктам.

## Признаки, что это нужно вам

Любые два — и окружение дешевле, чем ещё один круг вывода:

- один и тот же комментарий на ревью приходит во втором проекте;
- имя колонки или подпись функции ищут заново, потому что в прошлый раз ошиблись по памяти;
- «как мы обсуждали раньше» указывает на окно, которое никто не может открыть;
- чек-лист каждый раз выводится заново и немного по-другому;
- хороший ответ существует, и его невозможно найти.

Дальше: [Использование](01-Usage.ru.md) — как загрузить промпт, либо
[Окружение](04-Environment.ru.md), если завершённая сессия уже есть и её стоит сохранить.