Агентские тулзы плодят горы маркдауна: планы реализации, дизайн-доки, ресерчи. Тот же superpowers коммитит все это добро по умолчанию. И возникает вопрос - а надо ли оно в репозитории?
Я думаю, что нет. План на реализацию - это промежуточный артефакт. После мержа все его детали и так лежат в коде, а сам план начинает врать с первого же рефакторинга.
Но в чатике прозвучало справедливое возражение: по гит-дереву хочется понимать не только ЧТО сделано, но и ПОЧЕМУ. "Что" git и так покажет. А для "почему" есть инструмент получше - и придумали его задолго до LLM.
ADR - Architecture Decision Record
Короткий документ, который фиксирует ОДНО архитектурное решение: контекст, что решили, почему. Минимальный ADR - буквально три предложения. Лежат в
docs/adr/ со сквозной нумерацией. Главное правило - ADR не редактируют задним числом: решение устарело - помечаете superseded by ADR-042 и пишете новый. Получается хронология решений проекта.Заводить не на каждый чих, а когда сошлись три условия:
• решение дорого откатить
• без контекста оно выглядит странно ("какого черта тут две очереди?")
• были реальные альтернативы, и выбор - результат трейдоффов
Живой пример - NATS: у них под это отдельный репозиторий, и ADR-1 от 2020 года до сих пор объясняет, почему JetStream API построен поверх request-reply с JSON-схемами. Новый контрибутор (или автор клиентской либы) читает его и понимает дизайн, не раскапывая шесть лет git-истории😎
Причем тут LLM
ADR - идеальная память для агента:
• Агент перед изменением читает ADR и не "чинит" сознательные решения. Без этого он видит в коде "странность" и услужливо рефакторит то, что вы выбрали специально 🌚
• План на реализацию для этой задачи не годится - он несет слишком много деталей. ADR - это дистиллят: только решение и его причины, дешево по токенам
• Работает и в обратную сторону: скиллы типа grill-with-docs гриллят вас вопросами по дизайну и сами оформляют ответы в ADR. Вот такие документы коммитить можно и нужно👍
Но держать для агента прям ВСЮ историю смысла нет - поэтому я время от времени "схлопываю" ADR до текущего состояния. Да, это ломает главное правило - но агенту нужна не хронология, а понимание, почему архитектура сейчас такая. Почему бы не сэкономить контекст?
В общем, после мержа отправляем план реализации в мусорку, а все "почему" - в ADR
Ссылки:
• сборник ADR в AG2
• сборник шаблонов и гайдов по ADR
• как это выглядит у NATS
• компактный формат от Matt Pocock
А какие документы коммитите вы?
#архитектура #AI