Кладбище решений: почему мой AI каждую сессию начинает один и тот же спор заново

Когда AI ломает что-то - проблема почти никогда не в модели. Проблема в том, что у модели нет места, куда положить решение. Полгода практики с ForgePlan: четыре идеи, три дыры, одна звезда на GitHub.

Лид

Привет. Меня зовут Илья. Я делаю с открытым кодом инструмент для AI-агентов, и за последние полгода ловлю себя на одной и той же мысли: когда мой Claude Code что-то ломает, проблема почти никогда не в модели. Проблема в том, что у модели нет места, куда положить решение.

Пять месяцев назад у меня случился показательный диалог. Пятница - агент в одной сессии выбрал Postgres, написал миграции, всё хорошо. Понедельник - другая сессия, и агент с серьёзным лицом предлагает «а может, всё-таки Mongo? вот аргументы». Аргументы убедительные. Не потому что он плохой - просто каждая сессия начинается с нулевой памяти. У этого агента нет коллеги, которого можно дёрнуть. Нет угла в Slack, где висит «мы это уже решали в марте». Нет головы, в которой хранится «почему».

Это и есть кладбище решений. Только до AI оно было невидимым: решения умирали тихо, когда увольнялся последний инженер, который помнил. С агентами оно стало видимым каждый день. Я открываю новую сессию - и читаю спор, который мы уже один раз закрыли.

Полгода назад я начал писать инструмент, который пытается решить эту проблему - не через большие промпты и не через ещё одну цепочку из 30 шагов «как написать код с AI». А через простую идею: решение - это первоклассный артефакт, у которого есть жизненный цикл, обязательные поля и видимое доверие. Артефакт лежит в git как markdown-файл, в индекс попадает автоматически, агент видит его так же, как видите вы.

Это статья про то, что я понял за эти полгода, где промахнулся, и где всё ещё промахиваюсь. Это не реклама. Проект - открытый код, Rust, MIT, одна звезда на GitHub. Почему одна - будет в конце, и это не та история, которую я ожидал рассказывать.

Где умирают решения

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

В коде решение не написано - там написан результат решения. Файл db.py показывает, что выбран Postgres. Он не объясняет, почему не Mongo, какие были аргументы, что отвергли и зачем. Через год вы открываете db.py и видите Postgres. Хороший выбор? Плохой? Откуда я знаю.

В файлах документации решение есть, но рассинхронизировано с кодом. Документ, который мы написали при выборе Postgres, описывает архитектуру октября 2024. Сегодня октябрь 2026. За это время сменилась библиотека ORM, добавили шардирование, отказались от Redis, который тогда был в схеме. Документ формально на месте, фактически - карта местности, которой больше нет.

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

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

«Информации, которой нет в репо, для агента не существует».

walkinglabs, лекция 3

Walkinglabs - бесплатный курс на русском про инженерию обвязок для AI-агентов (12 коротких лекций, ~3 часа на всё). Цитата выше - главная мысль третьей лекции. Не «должна быть в репо», а не существует. Если знание у вас в голове или в Slack - для агента его нет. Он переоткроет вопрос, обсудит с собой, примет решение, реализует. Через неделю - следующая сессия, всё то же самое заново. Только в другую сторону.

И тут получается интересно: оба полюса документации - это про актуальность файла. А реальная проблема - про связь между файлом и решением. Документация может быть актуальной и при этом бесполезной: она описывает «что есть», но не «почему так». Решения отдельно, документация отдельно, код отдельно. Три разрозненных потока правды.

Я искал способ свести их в один.

Почему я начал делать ForgePlan

Стартовая боль была не про AI. Она была про эту самую разрозненность.

Год назад мне нужно было объяснить новому человеку, почему мы выбрали Postgres. Я открыл git log - пусто. Confluence - есть страница «Choice of database», но она с прошлой архитектуры. Slack - поиск выдал тред из 200 сообщений, половина удалена. В итоге я просто пересказал по памяти. Через три недели тот же человек предложил подумать про Mongo - потому что нигде не был зафиксирован реальный набор аргументов.

Решение есть. Обоснования нет. Через год - повтор того же разговора.

Я начал инструмент, который заставляет фиксировать решения как первоклассные артефакты. Не свободный markdown «как получится», а артефакты с обязательной структурой: обязательные секции (без которых файл невалиден), привязка подтверждений (чем доказываем), показатель надёжности R_eff (насколько решению можно верить, считается по подтверждениям).

Так появились первые типы артефактов в ForgePlan: PRD (требования к продукту), RFC (архитектурное предложение), ADR (зафиксированное решение), Spec (контракт API/данных), Evidence (подтверждение - тест, замер, ревью). Жизненный цикл: черновик → активен → заменён. Командная строка на Rust, файлы в .forgeplan/, индекс для семантического поиска рядом.

Решающий момент случился, когда я обнаружил, что наш собственный markdown был не источником правды. Артефакты сидели в LanceDB (это локальная база для эмбеддингов и быстрого поиска) как первичные данные. Markdown был экспортом из неё.

Звучало логично - база быстрая, поиск по векторам шустрый, файлы - для красоты. И это работало, пока не появились параллельные агенты в одном репозитории. Один агент видел состояние из базы, другой - из файлов, оба «правы», состояние разъезжается. Кто прав на самом деле - никто не знает, потому что источника правды нет: и база, и файлы претендуют на неё.

Я инвертировал зависимость. ADR-003 формализовал: markdown - источник правды, LanceDB - производный индекс. База упала - forgeplan scan-import восстановит за минуты. Мигрируем - забираем каталог .forgeplan/, и всё. Артефакт не зависит от инфраструктуры; инфраструктура зависит от артефакта.

Звучит как косметика. На самом деле это был переход от «у нас есть записанные решения» к «у нас есть репозиторий как единый источник правды». Это разная модель работы, и она оказалась критичной для агентов. Агент клонирует репо в новую песочницу - и сразу видит всё, без миграции данных, без отдельной базы, без вопроса «а где у вас правда лежит».

После этого ADR пришлось закрывать PROB-048: 32 места в коде, где обработчики команд напрямую писали в LanceDB, минуя markdown. Четыре раунда жёсткого ревью, 56 найденных проблем, регрессионный тест против возврата старого поведения. Полтора месяца работы. И это история, которая изменила мой взгляд не на «что я пишу», а на что вообще такое решение в системе с AI-агентом.

Дальше - четыре идеи, которые из этого выросли.

Что я понял за полгода

1. Решение - это артефакт со своим жизненным циклом

Не комментарий в коде. Не сообщение коммита. Не страница в Confluence. Файл с обязательной структурой, со ссылкой на родителя, со статусом.

В ForgePlan десять типов артефактов; на практике большинство команд использует пять-шесть: PRD, RFC, ADR, Evidence, Problem, Epic. Остальные - для конкретных сценариев. Идея жёсткая: каждый тип отвечает на один вопрос. PRD - что и зачем. RFC - как построить. ADR - почему именно так. Evidence - работает ли. Problem - что сломалось.

У каждого артефакта - жизненный цикл: draft → active → superseded | deprecated | stale. Заменяем, не удаляем. Когда через год кто-то спрашивает «мы это уже пробовали?» - superseded артефакт показывает, что пробовали, почему отказались, чем заменили. История не теряется.

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

Десять типов выглядят страшно, но никто не использует все сразу. Команды осваивают их в естественном порядке: сначала ADR (нужно где-то фиксировать решения), потом PRD (нужно отделять «что» от «как»), потом Evidence (нужно подтверждать), потом остальное по мере роста проекта.

2. R_eff - это самое слабое звено, не среднее

R_eff - показатель надёжности артефакта. Считается по подтверждениям, которые к нему привязаны (тесты, замеры, ревью). Главная идея - минимум, не среднее. Если у решения три подтверждения по 0.9 и одно по 0.1 - R_eff равен 0.1, не 0.7.

Звучит сурово. Это сделано осознанно: ваше доверие к решению не выше, чем самое слабое подтверждение. Одно слепое пятно - и всё проседает. Среднее бы скрыло это; минимум - нет.

Это место, где меня самого больно ударило. PROB-034 - отдельная история, которую я долго стеснялся рассказать.

Сам R_eff молча врал о собственной честности. Если EvidencePack (тело подтверждения) был оформлен неправильно - без явных полей verdict, congruence_level, evidence_type - парсер тихо ставил CL0 («противоречит контексту», штраф 0.9), и оценка падала почти к нулю. Агент видел R_eff = 0.10 и не понимал почему. Просто низкий балл, без объяснения. Кладбище решений внутри инструмента, который должен был кладбища решений предотвращать.

«Студенты не могут проверять свои собственные экзамены».

walkinglabs, лекция 9

Anthropic в 2025 опубликовали находку: агент, который сам себя оценивает, систематически завышает оценку. Это особенность того, как модели учили: «полезный» в их мире равно «да, готово». Просить агента «проверь, всё ли ты сделал правильно» - это дать студенту самому проверить экзамен. Он напишет «9 из 10».

Решение - отдельный проверяющий, разные контексты, в идеале разные модели. ForgePlan ставит этот блок прямо в жизненный цикл: команда activate отказывается переводить артефакт в active, если R_eff равен нулю или есть ошибки валидации. Архитектурно - а не по договорённости.

История PROB-034 закончилась двумя раундами ревью. Добавили громкое предупреждение в выводе: «EVID-091 не содержит оформленных полей → штраф CL0». Добавили красную линию в CLAUDE.md про обязательную структуру тела. Урок - не «оценка работает», а «если механизм самопроверки молчит про свои промахи, он сам становится молчаливым кладбищем решений».

3. Документация и код не должны расходиться никогда

Самый простой способ обеспечить это - не вести их отдельно.

В ForgePlan каждая команда командной строки и каждый MCP-инструмент (MCP - это протокол, через который агенты вроде Claude Code общаются с локальными программами) в своём ответе пишут ровно один машиночитаемый указатель на следующий шаг. Пять маркеров покрывают весь рабочий цикл:

$ forgeplan new prd "Auth system"
Created: prd-auth-system (predicted PRD-74?)
Next: forgeplan validate prd-auth-system

$ forgeplan validate prd-auth-system
PASS (0 MUST errors)
Next: forgeplan reason prd-auth-system

$ forgeplan score prd-auth-system
R_eff = 0  (no evidence linked)
Fix: forgeplan new evidence "PRD-074 verification"

Next: - основное действие. Or: - альтернатива. Wait: - нужно подождать. Done. - терминальный. Fix: - что делать с ошибкой. Параллельно в JSON-выводе идёт поле _next_action - агент парсит без регулярных выражений, по структуре.

В версии 0.25 такие подсказки были у 36% команд. После выверки - у 100%. Тесты следят, чтобы этот контракт не сломался незамеченным.

Что это даёт - переход от «отдельная инструкция в CLAUDE.md, как пользоваться инструментом» к «инструмент сам говорит, что делать дальше». Документация рождается в момент выполнения. Разойтись с кодом она физически не может - она и есть код, который её печатает.

Побочный эффект, который я не предсказывал: введение в курс дела новых агентов стало тривиальным. Раньше нужно было длинными инструкциями объяснять последовательность. Сейчас - запускай команду, читай Next:. Раздел в CLAUDE.md про это уменьшился с ~50 строк до ~10.

4. Рабочий цикл - это указатель, не бюрократия

Главное правило, которое я добавил последним: «цепочка артефактов - это направление, не обязательный набор».

В первой версии я думал, что для каждой задачи нужно создавать PRD → Spec → RFC → ADR. Через два месяца понял: за это вынесут. Половина задач - тривиальные правки, для них не нужен PRD. Багфикс в одну строку не требует Spec. «Обновить версию зависимости» - не повод заводить RFC.

В ForgePlan теперь есть команда route: она смотрит на формулировку задачи и говорит, какая глубина нужна.

Тактическая (быстрое, обратимое) → артефакт не нужен, иногда Note на 90 дней
Стандартная (1-3 дня, есть выбор) → PRD + RFC
Глубокая (необратимое, 1-2 недели) → PRD + Spec + RFC + ADR + обязательное рассуждение по гипотезам
Критическая (кросс-командное, стратегия) → Epic + всё перечисленное + адверсариальное ревью

Если задача обратимая и тривиальная - пишем код. Без бюрократии. Артефакты - для случаев, когда «через год кто-то спросит почему». Если ответ заведомо «никто не спросит» - артефакт не нужен.

Это пятое правило, которое освободило инструмент от собственного веса. Без него ForgePlan превратился бы во второй полюс документации: формально правильно, на практике мешает.

Чего ForgePlan ещё не делает

Раз я открыто рассказываю как делаю - значит, честно про дыры. Три, которые я вижу прямо сейчас.

Дыра 1: трассировка отдельной агентской сессии. Команды health, graph, blindspots показывают состояние репозитория - что активно, где слепые пятна. Чего нет - наблюдаемости конкретного запуска: какие инструменты агент вызвал, в каком порядке, где затупил, какой Next: проигнорировал. Walkinglabs делают это первоклассным концептом (лекция 11). У меня - на дорожной карте, без даты. Нужен сторадж трасс, просмотрщик, нужно решить вопрос приватности (в строках токенов есть пользовательский ввод).

Дыра 2: контракт на спринт. PRD слишком тяжёлый для дневной задачи (требует обязательных секций, рассуждения, привязки подтверждений). Note - слишком лёгкий, не поддерживает чек-листы требований. Промежуточного формата для «обещание на 2-3 дня» - нет. Я ловлю эту боль каждый раз, когда сажусь делать что-то на день. Это отдельный примитив, которого пока не хватает.

Дыра 3: проект только под Claude Code. Технически инструмент модель-агностичный - это CLI на Rust плюс MCP-сервер. Но я использую и тестирую его только с Claude Code. Cursor, Copilot, Windsurf могут работать, но не проверял. Это нормальная стратегия для одного человека (нельзя делать всё одновременно), но честный минус.

Цифры

Состояние на 2026-05-23 - числа из репозитория:

343 артефакта в .forgeplan/ (PRD / ADR / RFC / Spec / Epic / Evidence / Problem / Solution / Note / Refresh)
1995 тестов (cargo test, 0 падений)
76 команд в командной строке
73 MCP-инструмента
10 типов артефактов (на практике большинство команд использует 5-6)
Один бинарь, открытый код, MIT, ~41 МБ
v0.30.0
1 звезда на GitHub

Последняя цифра - главная. Описание репозитория полтора года было «Backend and ForgePlan developer tools». Это обещание, которое не сходится с реальностью. Кто ищет «инструменты разработчика» - приходит, видит жизненный цикл артефактов, оценку R_eff, контракт подсказок - и уходит, искал не это. Кто ищет инструмент для AI-агентов - не приходит, потому что в описании этого слова нет.

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

Заключение

Что я узнал за полгода - одной строкой каждое:

Когда AI ломает что-то на крупной системе, дело почти никогда не в модели. Дело в том, что у модели нет места, куда положить решение.
Документация и код расходятся всегда - кроме случая, когда документация генерируется кодом во время выполнения.
Решение - это файл с жизненным циклом, не комментарий и не сообщение коммита.
Доверие к решению равно самому слабому подтверждению, не среднему. Одно слепое пятно - и всё проседает.
Цепочка артефактов - это направление, не обязательный набор. Иначе инструмент превращается в свой собственный антипаттерн.

Три ссылки, которые могут быть полезны:

walkinglabs.github.io/learn-harness-engineering/ru/ - бесплатный курс на русском про инженерию обвязок для AI-агентов, 12 коротких лекций, ~3 часа. Концептуальный фрейм, который мне сильно помог собрать словарь.
github.com/ForgePlan/forgeplan - практическая реализация, Rust, MIT, один бинарь. brew install ForgePlan/tap/forgeplan. Документация: forgeplan.dev/docs/.

Если у вас есть обратная связь - особенно про три дыры из секции выше - пишите в issues. Честная критика строит инструмент быстрее любой правки в код.