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

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

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

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

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

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

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

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

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

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

Записи архитектурных решений

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

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

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

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

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

Записи решений по продукту

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

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

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

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

Записи решений по дизайну

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

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

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

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

Почему записи решений важнее с ИИ

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

ИИ может возобновить решенные споры

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

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

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

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

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

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

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

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

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

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

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

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

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

Записи решений работают лучше всего, когда они следуют принципам документации как кода, что означает, что они должны храниться в том же репозитории, что и код, писаться на простом Markdown, проверяться в pull request, версионироваться с помощью Git, ссылаться на связанные проблемы и 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 перед его принятием.

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

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

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

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

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

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

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

Для работы над продуктом:

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

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

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

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

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

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

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

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

Записи решений в pull request

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Общие ошибки

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример ADR

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

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

## Контекст

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

## Решение

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

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

### DynamoDB

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

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

### MySQL

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

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

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

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 и когда оставаться с более быстрыми, менее строгими рабочими процессами
• Архитектура приложений в продакшене: Паттерны интеграции, дизайн кода и доступ к данным — домашняя страница кластера, охватывающая интеграцию, тестирование, доступ к данным и паттерны программной документации
• ИИ для управления знаниями: Реальные рабочие процессы, которые выдерживают проверку временем — практические рабочие процессы управления знаниями с дополнением ИИ, которые дополняют практику записей решений