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

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

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

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

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

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

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

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

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

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

Записи об архитектурных решениях (ADR)

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

Примеры решений, которые стоит зафиксировать в виде ADR, включают:

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

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

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

Записи о продуктовых решениях (PDR)

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

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

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

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

Записи о дизайнерских решениях (DDR)

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

Примеры дизайнерских решений, которые стоит зафиксировать, включают:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Большинство рабочих процессов программирования с помощью ИИ фокусируются узко на цикле генерация-проверка-фиксация:

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

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

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

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

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

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, который включает необязательный, но ценный раздел руководства для ИИ:

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

Статус: Предложено | Принято | Заменено | Устарело
Дата: ГГГГ-ММ-ДД
Тип: Архитектура | Продукт | Дизайн
Владельцы: Команда или имена

## Контекст

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

## Решение

Четко сформулируйте решение.

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

### Вариант 1

Плюсы:
- ...

Минусы:
- ...

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

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

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

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

## Ссылки

- Связанные проблемы:
- Связанные pull-запросы:
- Связанные файлы:
- Заменяет:
- Заменено:

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

Что должно быть в записи о принятом решении?

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

Хорошими кандидатами являются решения, которые:

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

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

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

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

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

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

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

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

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

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

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

Составьте черновик Записи об архитектурном решении для решения в этом pull-запросе.
Включите контекст, альтернативы, последствия и руководство для ИИ.
Сохраните как Markdown в docs/decisions/architecture.

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

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

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

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

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

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

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

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

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

Записи о принятых решениях в pull-запросах

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Распространенные ошибки

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

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

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

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

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

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

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

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

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

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

Скрытие записей за пределами репозитория

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

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

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

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

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

Пример ADR

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

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

## Контекст

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

## Решение

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

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

### DynamoDB

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

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

### MySQL

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

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

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

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

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

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

Пример PDR

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

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

## Контекст

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

## Решение

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

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

### Отправлять автоматически

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

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

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

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

Минусы:
- Все еще поощряет поверхностное ревью
- Не так хорошо соответствует существующему поведению клиента электронной почты, как черновики

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

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

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

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

Пример DDR

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

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

## Контекст

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

## Решение

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

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

### Применять предложения встроенно

Плюсы:
- Быстро
- Кажется интегрированным

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

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

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

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

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

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

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

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

Предлагаемая библиотека промптов

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

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

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

Составить новый ADR:

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

Составить новый PDR:

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

Составить новый DDR:

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

Проверить pull-запрос против существующих решений:

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

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

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

Связанное чтение

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