Решения при разработке программного обеспечения с использованием ИИ

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

Записи о решениях — недостающий слой памяти

Программирование на базе ИИ меняет экономику разработки ПО, делая генерацию кода дешевле, рефакторинг проще, а отказ от устаревшего кода быстрее. Это полезно. Но это также опасно, потому что, когда производить код становится легче, дефицитным ресурсом перестают быть клавиши — дефицитным ресурсом становится способность к суждению.

Почему команда выбрала PostgreSQL вместо DynamoDB? Почему продукт требует человеческого контроля перед отправкой сгенерированных ИИ писем? Почему интерфейс показывает предложения в боковой панели, а не применяет их напрямую? Почему более простой подход был отклонен шесть месяцев назад? Код может показывать то, что существует, но он редко объясняет, почему это существует.

Записи о решениях решают эту проблему, предоставляя короткий документ под контролем версий, который фиксирует важное решение, контекст за ним, рассмотренные альтернативы и последствия, которые команда приняла. В кодовой базе с поддержкой ИИ эти записи становятся чем-то большим, чем просто документацией — они становятся долговременной памятью проекта, которую и люди, и агенты кодинга на ИИ могут прочитать перед внесением будущих изменений. Практическое правило эксплуатации просто: храните записи о решениях в виде файлов Markdown в репозитории, ревьюьте их как код и позвольте будущим инструментам ИИ читать их перед предложением или реализацией изменений.

Что такое записи о решениях?

Запись о решении — это письменная запись осмысленного решения, структурированная для ответа на четыре базовых вопроса: что мы решили, почему мы это решили, какие альтернативы мы рассматривали и какие последствия мы приняли? Наиболее распространённой формой является Архитектурная Запись о Решении (Architecture Decision Record, сокращённо ADR). ADR широко используются для документирования технических решений, и эту же схему можно расширить за пределы архитектуры, включив в неё продуктовую и дизайнерскую работу.

Для программирования на базе ИИ особенно полезны три типа записей:

Вместе ADR, PDR и DDR описывают не только структуру системы, но и замысел продукта и обоснование, стоящее за пользовательским опытом. Эта комбинация важна, потому что агенты ИИ могут читать код, но одного кода недостаточно, чтобы принимать хорошие решения. Записи о решениях дают системам ИИ проверенный, долговременный, одобренный человеком источник замысла проекта.

Архитектурные записи о решениях

Архитектурные записи о решениях фиксируют технические и структурные решения. Используйте ADR, когда решение влияет на форму системы — её границы, зависимости, операционную модель или долгосрочную поддерживаемость.

Примеры решений, заслуживающих записи в ADR, включают:

• Выбор PostgreSQL в качестве основной базы данных
• Использование событийно-ориентированной архитектуры для фоновой обработки
• Сохранение приложения в виде модульного монолита
• Внедрение очереди сообщений
• Выбор REST вместо GraphQL
• Использование серверного рендеринга для веб-приложения
• Требование идемпотентности всех фоновых заданий
• Внедрение конкретной модели аутентификации и авторизации

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

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

Продуктовые записи о решениях

Продуктовые записи о решениях фиксируют поведение продукта, его масштаб и пользовательский замысел. Это встречается реже, чем ADR, но часто бывает столь же ценно — продуктовые решения часто разбросаны по тикетам, инструментам дорожных карт, чатам, заметкам встреч и памяти людей, что делает их легкими для забвения людьми и практически невозможными для надежного вывода инструментами ИИ.

Используйте PDR, когда решение влияет на то, что делает продукт, кому он служит, что намеренно выходит за рамки (out of scope) или как должна вести себя пользовательская функция. Примеры включают:

• Сообщения, сгенерированные ИИ, должны оставаться черновиками до проверки человеком
• Пользователи бесплатного тарифа могут создавать до трех проектов
• Удаленные рабочие пространства восстанавливаются в течение 30 дней
• Командная биллинговая система вне рамок версии 1
• Пользователи могут выгрузить свои данные без обращения в поддержку
• Резюме с низкой степенью уверенности ИИ показывают предупреждение, вместо того чтобы скрываться

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

Дизайнерские записи о решениях

Дизайнерские записи о решениях фиксируют решения о пользовательском опыте, взаимодействии, визуальном оформлении и контентном дизайне. Используйте DDR, когда решение влияет на то, как пользователи взаимодействуют с продуктом, как представлена информация или как дизайнерский принцип должен применяться в будущей работе.

Примеры дизайнерских решений, заслуживающих записи, включают:

• Использование инлайн-валидации вместо валидации только при отправке
• Размещение предложений ИИ в боковой панели, а не напрямую в редакторе
• Использование постепенного раскрытия (progressive disclosure) для расширенных настроек
• Требование подтверждения перед деструктивными действиями
• Использование терминов «Черновик» и «Опубликовано», а не «Неактивно» и «Активно»
• Держать основные действия видимыми на мобильных экранах

Дизайнерский замысел легко потерять при реализации. Разработчик может упростить поток, или агент ИИ может сгенерировать компонент, который технически работает, но нарушает задуманную модель взаимодействия. Например, в DDR может быть записано: «Мы показываем предложения текста ИИ рядом с документом, а не внутри него, потому что пользователям нужно сравнивать сгенерированный текст с их собственным черновиком перед принятием изменений». Эта запись дает будущим участникам принцип, который нужно сохранять, а не просто макет, который нужно копировать.

Почему записи о решениях важнее при работе с ИИ

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

ИИ может заново открыть урегулированные дебаты

Если команда уже решила использовать модульный монолит, агент ИИ все равно может предложить выделение сервиса, потому что это выглядит чисто в изоляции. Без ADR у ИИ нет надежного способа узнать, что команда уже рассматривала и отклонила этот путь, и результатом становится потраченное впустую время или тонкая деградация связности системы.

ИИ может оптимизировать локально и повредить глобально

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

ИИ может сохранить код, но потерять замысел

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

ИИ может сгенерировать правдоподобное, но неверное обоснование

ИИ может черновать записи о решениях, но он также может изобретать уверенно звучащие объяснения, которые не соответствуют реальному решению. Именно по этому человеческий контроль непостижим: ИИ может сгенерировать первый черновик записи, но человек должен убедиться, что она точно описывает фактическое решение, альтернативы и последствия, прежде чем запись будет интегрирована.

Записи о решениях как часть более широкой методологии

Записи о решениях — это не просто документация — они являются частью более широкого способа работы, который находится на пересечении легковесного архитектурного управления, подхода «документация как код», рабочих процессов управления знаниями с усилением ИИ, продуктовых исследований, обоснования дизайна, управления ИИ и ревью кода. Полезным способом описать более крупный процесс является Разработка, ориентированная на решения (Decision-Oriented Development).

Большинство рабочих процессов программирования на базе ИИ сужены до цикла «сгенерировать — отревьюить — закоммитить»:

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

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

Записи о решениях и документация как код

Записи о решениях лучше всего работают, когда они следуют принципам «документация как код», что означает, что они должны храниться в том же репозитории, что и код, писаться на чистом Markdown, ревьються в pull request’ах, версионироваться с помощью Git, иметь ссылки на связанные тикеты и pull request’ы и быть доступными для поиска как людьми, так и инструментами ИИ. Это намного надежнее, чем хранить важные решения в чатах, wiki-страницах, слайд-деках или заметках встреч — эти инструменты могут быть полезны для обсуждения, но принятое решение всегда должно жить рядом с кодом. Как держать спецификации, тесты и код в синхроне в разработке на ИИ расширяет эту же привычку «связывать с записью» в полноценную модель трассируемости, связывающую идентификаторы требований и дизайнерских решений с тестами и pull request’ами.

Хорошо организованная структура репозитория для записей о решениях может выглядеть так:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

Для меньших проектов более плоская структура работает столь же хорошо. Точная организация папок менее важна, чем консистентность — записи должны быть легко находимыми, легко ревьюемыми и легко загружаемыми инструментами ИИ как контекст перед действием над кодовой базой. Для команд на Go эта структура docs/decisions/ естественно вписывается рядом с раскладкой cmd/, internal/ и api/, описанной в Структура проектов на Go: практики и паттерны, которая рекомендует docs/ как место для архитектурных решений и описания API.

Практический шаблон записи о решении

Полезный шаблон записи о решении должен быть достаточно коротким, чтобы люди действительно им пользовались. Вот практичный шаблон Markdown, включающий необязательный, но ценный раздел по руководству ИИ:

# Решение: Короткое название

Статус: Предложено | Принято | Заменено | Устарело
Дата: YYYY-MM-DD
Тип: Архитектура | Продукт | Дизайн
Ответственные: Команда или имена

## Контекст

Опишите проблему, ограничения, цели, потребности пользователей, технические факты
и бизнес-факторы, которые привели к этому решению.

## Решение

Ясно изложите решение.

## Рассмотренные альтернативы

### Вариант 1

Плюсы:
- ...

Минусы:
- ...

## Последствия

Опишите, что станет проще, что станет сложнее и какие риски
или последующие работы это создает.

## Руководство для ИИ

Когда ассистент ИИ работает в этой области, он должен:
- Сохранять ...
- Избегать ...
- Предпочитать ...
- Просить ревью, когда ...

## Ссылки

- Связанные тикеты:
- Связанные pull request'ы:
- Связанные файлы:
- Заменяет:
- Заменено:

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

Что должно входить в запись о решении?

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

Хорошие кандидаты — это решения, которые:

• Влияют на несколько частей системы
• Кодифицируют продуктовое обещание
• Разрешают настоящую дискуссию
• Вводят долгосрочный компромисс
• Зависят от бизнес-, нормативных или операционных ограничений
• Было бы дорого заново открывать позже
• Будущие инструменты ИИ могут правдоподобно сделать неверно
• Будущие участники могут быть склонны случайно обратить

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

Значения статуса и жизненный цикл

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

Предложено — Решение рассматривается, но еще не принято. Используйте это, когда команда хочет обсудить решение в pull request перед принятием обязательств.

Принято — Решение активно и должно направлять будущую работу. Большинство полезных записей о решениях будут проводить большую часть жизни в этом состоянии.

Заменено — Решение было заменено более новой записью. Не удаляйте старые записи; храните их для истории и сделайте ссылку на новое решение, чтобы эволюция мышления оставалась видимой.

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

Важный принцип состоит в том, что записи о решениях должны быть пригодны для добавления (append-friendly). Когда команда меняет направление, создайте новую запись и сделайте ссылку на старую, а не переписывайте историю, чтобы прошлое выглядело чище.

Как ИИ должен генерировать записи о решениях

ИИ может помогать в создании записей о решениях, и это одно из лучших применений ИИ в разработке ПО — он быстро черновит структурированные документы из контекста. После обсуждения, архитектурного обзора или pull request’а вы можете попросить ассистента ИИ подготовить черновик записи:

Подготовьте черновик Архитектурной Записи о Решении (ADR) для решения в этом pull request.
Включите контекст, альтернативы, последствия и руководство для ИИ.
Сохраните его как Markdown в docs/decisions/architecture.

Для продуктовой работы:

Подготовьте черновик Продуктовой Записи о Решении (PDR), объясняющий, почему сообщения,
сгенерированные ИИ, должны оставаться черновиками до проверки пользователем.
Включите влияние на пользователя, поведение вне рамок, компромиссы и руководство для ИИ.

Однако записям, сгенерированным ИИ, нельзя автоматически доверять. Человеческий контроль должен проверить, что контекст точен, что ИИ не изобрел обоснование, что перечисленные альтернативы реальные, что последствия честны и что руководство для ИИ соответствует фактическому замыслу команды. ИИ — это ассистент по созданию черновиков — он не собственник решения.

Как ИИ должен читать записи о решениях

Другая половина практики — это указание ИИ читать записи перед действием. Перед тем как попросить ассистента ИИ реализовать изменение, включите инструкцию вроде этой:

Перед модификацией этой функции прочитайте docs/decisions.
Идентифицируйте любые Архитектурные, Продуктовые или Дизайнерские Записи о Решениях, которые применяются.
Следуйте принятым решениям. Если ваше предложенное изменение противоречит
записи о решении, объясните противоречие перед изменением кода.

Для более крупных задач подчеркните роль записей как проектной памяти:

Используйте записи о решениях как проектную память.
Не отменяйте принятые решения без предложения нового решения, заменяющего его.
Когда вы генерируете код, объясните, какие записи о решениях повлияли на реализацию.

Это изменяет роль ИИ с «предсказать правдоподобный код» на «работать внутри документированной системы ограничений» — значительное улучшение надежности для сложных или долгосрочных проектов.

Записи о решениях в pull request’ах

Записи о решениях должны быть частью обычного ревью pull request’а, а не отдельным процессом. Простая запись в чек-листе PR делает привычку видимой:

## Чек-лист записей о решениях

- [ ] Этот PR не вводит значительное архитектурное, продуктовое или дизайнерское решение.
- [ ] Этот PR вводит значительное решение и включает новую запись о решении.
- [ ] Этот PR изменяет предыдущее решение и включает заменяющую запись.
- [ ] Были рассмотрены релевантные существующие записи о решениях.
- [ ] Код, сгенерированный ИИ, следует принятым записям о решениях.
- [ ] Записи о решениях, сгенерированные ИИ, были проверены человеком.

Этот чек-лист прост, но он изменяет поведение, напоминая команде, что код — не единственный артефакт, который важен в pull request. Он также делает естественным выявление случаев, когда изменение, сгенерированное ИИ, молча нарушает предыдущее решение.

Записи о решениях и архитектурное управление

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

Они не требуют центрального архитектурного комитета для каждого изменения, и они не блокируют команды от обучения и адаптации. Вместо этого они создают след решений, которые можно ревьюить, ссылаться и строить со временем. Это поддерживает эволюционную архитектуру: архитектура может меняться, но она меняется с памятью, а не вопреки ей. Команда может пересматривать старые решения, неhaving заново открывать, почему они были сделаны, что является более здоровой и более честной формой управления:

• Малые записи вместо гигантских документов
• Ревью рядом с кодом, а не отдельное согласующее представление
• Исторический контекст вместо «племенного» знания
• Явные компромиссы вместо скрытых допущений

Записи о решениях и продуктовый менеджмент

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

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

Записи о решениях и дизайн-системы

Дизайн-системы часто документируют компоненты, токены и правила использования, но редко документируют, почему система работает именно так. Дизайнерские записи о решениях заполняют этот пробел. Библиотека компонентов может говорить «используйте диалог подтверждения для деструктивных действий», в то время как DDR объясняет обоснование: «Мы требуем подтверждения для деструктивных действий, потому что пользователи часто работают с общими командными данными, и случайное удаление имеет высокую стоимость восстановления».

Это обоснование важно за пределами конкретного компонента. Оно помогает будущим дизайнерам, разработчикам и инструментам ИИ правильно применять принцип в новых ситуациях. Без DDR агент ИИ может сгенерировать более быстрое взаимодействие, пропуская подтверждение, потому что оно кажется более эффективным. С DDR агент может распознать, что сохранение свойства безопасности намеренно и непоколебимо.

Как записи о решениях поддерживают разработку, управляемую спецификациями

Разработка, управляемая спецификациями, объясняет, что система должна делать. Записи о решениях объясняют, почему команда выбрала это направление, и это различие значительно важно для работы с поддержкой ИИ.

Спецификация функции может говорить, что письма, сгенерированные ИИ, должны сохраняться как черновики. Продуктовая запись о решении объясняет, почему автоматическая отправка была отклонена, какие риски были рассмотрены и какие будущие изменения потребуют нового решения. Дизайнерская спецификация может описывать взаимодействие боковой панели, в то время как соответствующая DDR объясняет, почему инлайн-редактирование ИИ было явно отклонено и почему сохранение контроля пользователя было оценено выше, чем скорость рабочего процесса. Архитектурная спецификация может определить границу сервиса, и ее ADR объясняет, почему команда выбрала эту границу вместо более простого или более распределенного варианта.

Спецификация направляет реализацию. Запись о решении сохраняет суждение. Вместе они дают агентам кодинга на ИИ и инструкции, и контекст — «что» и «почему» — именно это делает сочетание таким эффективным для сложных, долгосрочных систем. Когда вы принимаете инструментальный конвейер, управляемый спецификациями, сравните, как каждый вариант проявляет этот контекст; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows разбирает переносимость, контрольные точки ревью и привязку к репозиторию для основных конфигураций. Для нейтрального к инструментам процесса из пяти фаз, который реализуют эти инструменты, см. Workflow спецификационной разработки от требований до кода. Большинство SDD-инструментов чисто обрабатывают только «отправленную» половину этого цикла; Отклоненные предложения OpenSpec: конвенция памяти решений покрывает другую половину — устойчивую запись отклоненного решения, чтобы агент проверил его перед повторным предложением той же идеи.

Записи о решениях — это не спецификации

Записи о решениях связаны со спецификациями, но служат другой цели. Спецификация говорит «система должна делать Х», в то время как запись о решении говорит «мы выбрали Х вместо Y из-за этих ограничений и компромиссов». Это «вместо Y» — ценная часть. Инструменты ИИ часто генерируют решения, находя правдоподобный путь к требуемому результату, но записи о решениях сообщают им, какие правдоподобные пути уже были исследованы, оценены и отклонены — это снижает бесполезные изменения и улучшает качество работы с поддержкой ИИ.

Записи о решениях — это не замена тестам

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

Записи о решениях — это не замена комментариям в коде

Комментарии в коде объясняют локальные детали реализации, в то время как записи о решениях объясняют более широкие решения. Используйте комментарии для удивительных строк, пограничных случаев, обходных путей и функций, которые нельзя упростить. Используйте записи о решениях для того, почему существует архитектура, почему существует продуктовое поведение, почему существует паттерн взаимодействия и почему команда выбрала одно направление вместо другого. Если объяснение затрагивает только несколько строк, комментарий — правильный инструмент. Если оно затрагивает направление системы, запись о решении — правильный инструмент.

Частые ошибки

Написание записей слишком поздно

Запись о решении должна быть написана, когда решение принимается, а не через несколько месяцев, когда все забыли компромиссы. Ничего страшного, если черновик будет создан во время pull request. Еще лучше — создать его до реализации, пока решение еще активно обсуждается и альтернативы свежи.

Делание записей слишком длинными

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

Фиксация решений без последствий

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

Редактирование старых записей, будто история изменилась

Когда решение меняется, создайте новую запись и пометьте старую как «Заменено». Молчаливое переписывание старого решения, чтобы соответствовать текущему состоянию, разрушает исторический контекст, который делает записи о решениях ценными. История полезна именно потому, что показывает, как мышление эволюционировало. Скомпилированные базы знаний сталкиваются с идентичной проблемой под другим именем — Обслуживание Wiki LLM: дрейф, противоречия и ревью называет это дрейфом решений и применяет то же правило «заменять, а не переписывать» к wiki-страницам.

Позволение записям, сгенерированным ИИ, сливаться без ревью

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

Скрытие записей вне репозитория

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

Легковесная операционная модель

Практичный командный процесс, который добавляет минимальную нагрузку, выглядит так:

1. Во время планирования или реализации определите, принимается ли осмысленное решение.
2. Попросите ассистента ИИ подготовить черновик ADR, PDR или DDR на основе обсуждения.
3. Ревьюйте черновик как команда, проверяя контекст, альтернативы и последствия.
4. Закоммитьте запись как Markdown в репозитории.
5. Сделайте ссылку на нее из связанного тикета или pull request’а.
6. Укажите инструментам кодинга на ИИ читать релевантные записи перед внесением будущих изменений в области.
7. Заменяйте записи, когда решения меняются, сохраняя старую запись для истории.

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

Пример ADR

# Решение: Использование PostgreSQL для основного хранилища приложения

Статус: Принято
Дата: 2026-06-25
Тип: Архитектура
Ответственные: Команда платформы

## Контекст

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

## Решение

Мы будем использовать PostgreSQL в качестве основной базы данных приложения.

## Рассмотренные альтернативы

### DynamoDB

Плюсы:
- Операционно масштабируемая
- Хороший выбор для предсказуемых паттернов доступа ключ-значение

Минусы:
- Более сложная для реляционных запросов
- Сложнее для ad hoc отчета
- Меньше знакома текущей команде

### MySQL

Плюсы:
- Зрелая реляционная база данных
- Знакомая операционная модель

Минусы:
- Лучше соответствует потребностям команды для поддержки JSON,
  вариантов индексирования и существующей экспертизы PostgreSQL

## Последствия

PostgreSQL становится основной операционной зависимостью. Команда должна
аккуратно управлять миграциями и мониторить производительность запросов. Взамен
приложение получает сильное реляционное моделирование, зрелое индексирование
и гибкую поддержку отчетности.

## Руководство для ИИ

При модификации кода персистентности предпочитайте реляционное моделирование в PostgreSQL.
Не вводите вторую основную базу данных без заменяющего ADR.

Пример PDR

# Решение: Письма, сгенерированные ИИ, должны оставаться черновиками

Статус: Принято
Дата: 2026-06-25
Тип: Продукт
Ответственные: Продуктовая команда

## Контекст

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

## Решение

Письма, сгенерированные ИИ, должны создаваться как черновики. Человеческий пользователь
должен проверить и отправить их.

## Рассмотренные альтернативы

### Автоматическая отправка

Плюсы:
- Более быстрый рабочий процесс
- Меньше усилий со стороны пользователя

Минусы:
- Более высокий риск неправильных или неуместных сообщений
- Более низкое доверие пользователя
- Труднее восстановить из ошибок

### Запрос подтверждения только после генерации

Плюсы:
- Сохраняет простой рабочий процесс
- Предоставляет некоторый контроль пользователя

Минусы:
- Все еще поощряет поверхностную проверку
- Хуже подходит существующему поведению почтового клиента, чем черновики

## Последствия

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

## Руководство для ИИ

При создании функций генерации почты создавайте черновики по умолчанию.
Не добавляйте автоматическую отправку, пока новый принятый PDR явно не разрешит это.

Пример DDR

# Решение: Показывать предложения текста ИИ в боковой панели

Статус: Принято
Дата: 2026-06-25
Тип: Дизайн
Ответственные: Дизайнерская команда

## Контекст

Пользователям нужна помощь в улучшении письменного контента, но им также нужно
сохранять контроль над финальным текстом. Инлайн-редактирование ИИ может затруднить
различение пользовательского контента от сгенерированных предложений.

## Решение

Предложения текста ИИ будут появляться в боковой панели. Пользователи могут
принять, отклонить или скопировать предложения в основной редактор.

## Рассмотренные альтернативы

### Применять предложения инлайн

Плюсы:
- Быстро
- Ощущается интегрированным

Минусы:
- Размывает авторство
- Затрудняет проверку
- Может удивить пользователей

### Показывать предложения в модальном окне

Плюсы:
- Фокусированный опыт
- Легко реализовать

Минусы:
- Прерывает поток письма
- Труднее сравнить предложение и исходный текст

## Последствия

Боковая панель занимает больше места на экране, особенно на маленьких экранах.
Однако она сохраняет контроль пользователя и делает проверку более понятной.

## Руководство для ИИ

При добавлении функций помощи в письме сохраняйте разделение между
текстом пользователя и предложениями ИИ. Не применяйте сгенерированный текст
напрямую в документ без явного действия пользователя.

Рекомендуемая библиотека промптов

Используйте эти промпты, чтобы сделать записи о решениях частью ежедневной разработки с поддержкой ИИ.

Найти релевантные записи перед работой над функцией:

Прочитайте docs/decisions и идентифицируйте любые принятые записи о решениях, которые
применяются к этой задаче. Резюмируйте ограничения перед предложением изменений кода.

Черновик нового ADR:

Подготовьте черновик Архитектурной Записи о Решении для этого технического решения.
Включите контекст, решение, альтернативы, последствия и руководство для ИИ.
Сделайте его кратким и конкретным.

Черновик нового PDR:

Подготовьте черновик Продуктовой Записи о Решении для этого продуктового поведения.
Включите влияние на пользователя, масштаб, альтернативы, последствия и руководство для ИИ.

Черновик нового DDR:

Подготовьте черновик Дизайнерской Записи о Решении для этого паттерна взаимодействия.
Включите проблему пользователя, альтернативы, компромиссы, последствия и руководство для ИИ.

Ревью pull request по существующим решениям:

Ревью этот pull request по принятым записям о решениях в docs/decisions.
Идентифицируйте любые противоречия, отсутствующие записи о решениях или решения, которые
должны быть заменены.

Заменить решение:

Создайте новую запись о решении, которая заменяет существующую.
Сохраните историческое обоснование, объясните, что изменилось, и свяжите обе записи.

Дополнительное чтение

• Оригинальный формат ADR Майкла Ньягарда — основополагающий пост, начавший движение ADR
• Организация ADR на GitHub — инструменты, шаблоны и ресурсы сообщества для управления записями о решениях
• Что такое разработка, управляемая спецификациями? Спецификация как источник истины — каноническое определение SDD, объясняющее, как спецификации функций дополняют записи о решениях: обе делают замысел долговременным на разных уровнях системы
• Разработка, управляемая спецификациями, против Vibe Coding: Водопад? — когда использовать SDD и когда оставаться с более быстрыми, свободными рабочими процессами
• Архитектура приложений в продакшене: паттерны интеграции, дизайн кода и доступ к данным — кластер, покрывающий интеграцию, тестирование, доступ к данным и паттерны программной документации
• Отклоненные предложения OpenSpec: конвенция памяти решений — применение этого паттерна записей о решениях конкретно внутри архива изменений OpenSpec
• ИИ для управления знаниями: реальные рабочие процессы, которые работают — практичные рабочие процессы управления знаниями с усилением ИИ, которые дополняют практику записей о решениях