# Заметки о дизайне

Почему промпт устроен именно так и какие альтернативы отвергнуты. Прочтите до правки модуля:
большинство «улучшений» промптов — это снятие ограничения, которое работало.

## Постановка задачи

У переносимого промпта четыре требования, и они тянут в разные стороны:

| Требование | Напряжение |
|---|---|
| Универсальность — работает для любой темы | универсальный промпт сползает в размытость |
| Специализация — отвечает как практик | специализированный промпт нельзя переиспользовать |
| Проверяемость — ревьюер может проверить | проверка стоит токенов и терпения |
| Переносимость — без имён инструментов | переносимость убирает крючки, делающие промпт конкретным |

Решение — **разделить промпт на инварианты и переменную часть**: то, что верно в любом домене,
живёт в M3–M8; то, что меняется per domain, — в M2, M10 и примерах. Новый домен правит только
переменную часть.

## Решение с двумя карточками

Всё начинается с двух карточек:

- **Карточка задачи (M1)** — что просят, для кого, с какими ограничениями и что явно вне рамок.
- **Карточка домена (M2)** — кто практик, какой словарь и навыки нужны, что обязательно проверить и
  что значит «готово».

Отвергнутые альтернативы:

| Альтернатива | Почему отвергнута |
|---|---|
| Один длинный чек-лист | агент его пропускает; чек-лист без точки решения — украшение |
| «Думай пошагово» | улучшает беглость, не корректность; уверенные ошибки появляются быстрее |
| Ролевой абзац («ты инженер мирового класса») | меняет тон, не поведение; непроверяемо |
| Роутер доменов с фиксированным списком | список устаревает в момент появления новой темы |
| Только few-shot примеры | примеры учат поверхности; карточки учат решению |

Карточки работают потому, что это **выходы, которые агент обязан произвести до действия**, а не
инструкции, которые надо помнить. Записанную карточку можно проверить, опровергнуть и
версионировать; внутреннее намерение — нет.

## Почему три метки

Две метки (`факт` / `догадка`) схлопываются под давлением: всё становится «фактом с оговоркой». Три
метки заставляют принять решение, потому что `[предположение]` обязано назвать последствие, а
`[вывод]` — посылки.

Метки лечат реальный отказ: агент говорит «тесты проходят, значит функция работает» — это вывод,
посылка которого (что тесты покрывают функцию) не проверена. По M4 это `[вывод]`, и посылка
становится видимой.

## Почему журнал контекста, а не «используй контекст»

«Используй весь доступный контекст» даёт сразу два отказа: безграничное поглощение и утверждения
без источника. Журнал из пяти колонок — источник, тип, утверждение, уверенность — делает видимыми
оба. Он достаточно мал, чтобы вести его внутри ответа, и достаточно точен, чтобы ревьюер заметил
утверждение, которое источник не поддерживает.

Порядок приоритета (текущее сообщение > вложения > прошлые ходы > другие переписки > дерево >
публичные источники) кодирует одно правило: **намерение приходит только от пользователя,
свидетельства — откуда угодно**.

## Почему цикл заканчивается записью

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

## Почему результат — окружение, а не роль

Первая версия набора говорила «работай старшим специалистом до конца сессии». Фраза верна и почти
бесполезна: она меняет то, как агент говорит, а не то, что остаётся после окна. Измеренное
последствие: законченная работа ничего не оставляла после себя, и следующий круг того же класса
начинался с нуля в чистой сессии, агентом, который об этом ничего не знал.

В версии 1.2.0 результат переехал. Специализация даёт артефакт — зарегистрированный Workspace или
сохранённого агента — из пяти частей: правила, карточка домена с проверяемым критерием приёмки,
разобранные примеры вместе с провалом, хранилище прежней работы и стартовый промпт. Роль стала
побочным режимом, и промпт говорит это прямо (M10, режим отказа 18).

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

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

## Почему ворот двенадцать, а не сорок

Ворота длиннее двенадцати пунктов не прогоняют. Двенадцать ещё помещаются на экран и сообщаются одной строкой
(`ворота 12/12`). Два пункта, проваливающихся чаще всего — покрытие свидетельствами и проверка, —
и есть причина, по которой остальных десяти недостаточно.

## Почему есть таблица режимов отказа

Таблица в M9 — единственная часть промпта, называющая собственные трюки агента. Каждая строка
соединяет узнаваемый симптом с конкретным противоядием, поэтому ревьюер может сказать «это режим
отказа 4» вместо спора о вкусе. Промпт, не называющий своих режимов отказа, оптимизирован под
случаи, где он уже работает.

## Почему нет имён инструментов

Имя инструмента привязывает промпт к рантайму и версии. Имя **класса возможности** позволяет
рантайму сопоставить её и заставляет промпт определить, что происходит при отсутствии возможности —
а именно этот случай и ломает рабочие процессы агентов. Колонка деградации в M6 — прямое следствие.

## Что этот дизайн не решает

| Ограничение | Почему остаётся |
|---|---|
| Настойчивый агент всё равно может пропустить ворота | промпт делает пропуск видимым, но не невозможным |
| Суждение «что важно пользователю» не механизируется | поле `Результат` в M1 сужает его, ничто не убирает |
| Длинные задачи расходятся за много ходов | стоп-условия M5 ловят часть дрейфа; для остального нужен файл состояния задачи |
| Качество карточки домена зависит от автора | пятнадцать минут в M10 задают пол, а не потолок |

Называть ограничения — часть дизайна: промпт, обещающий решить всё перечисленное, сам является
примером режима отказа 11 (театр авторитета).

## Почему появился модуль про повторную работу

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

Поэтому M13 построен на асимметрии: **доставание обязано стоить одну команду, запись — проверяться
машиной, а переиспользование — обосновываться шестью вопросами.**

| Решение | Отвергнутая альтернатива | Почему |
|---|---|---|
| Хранилище Markdown-записей плюс CLI | векторная база или «модель помнит» | проверяемо, диффаемо, работает офлайн, нет индекса для поддержки |
| Поиск печатает причину каждой позиции | голый список top-5 | ранжирование без причин нельзя отвергнуть по свидетельству |
| Применимость — шесть вопросов | «проверь, что подходит» | невысказанная проверка — пропущенная проверка |
| Записи помечаются устаревшими, не удаляются | удалить устаревшее | след аудита и есть причина доверять хранилищу |
| Одно хранилище, одна схема | заметки на каждого агента | два хранилища — две истины, одна устарела |
| Опыт ниже репозитория | опыт как полноценное свидетельство | уверенно применённый устаревший рецепт — самый дорогой провал в наборе |

## Почему ворот стало двенадцать

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

## Что этот дизайн не решает

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

## Проверка дизайна

Структурные контракты проверяет `tools/prompt_lint.py`: полнота модулей, строки самопроверки, число
инвариантов, парность переводов, целостность ссылок, согласие версий. Поведенческие утверждения —
что карточки снижают дрейф, что метки снижают количество выдуманных фактов — из документа
машинно не проверяются, и `docs/VALIDATION.ru.md` прямо говорит, какие из них остаются
предположениями.