Инженерия требований, ADR и синхронизация документации с кодом

Архитектурная база#

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

Концепция "Живых спецификаций" (Living Specifications) требует, чтобы документы (Markdown, OpenAPI, Zod, ADR) были плотно интегрированы в репозиторий и валидировались CI/CD-пайплайнами. Architecture Decision Records (ADR) выступают в роли долговременной памяти проекта, объясняя агентам почему было принято то или иное решение, исключая повторные ошибки рефакторинга.

Ментальная модель#

ADR и Живые Спецификации работают как система ограничений и компас для автономных агентов.

[Контекст Агента (Context Window)]
   │
   ├─► docs/adr/001-use-zod-for-validation.md (Ограничение стека)
   ├─► docs/specs/api-contract.yml (Ограничение интерфейса)
   └─► src/ (Кодовая база, генерируемая строго по ограничениям)

Если код меняется, спецификация должна обновиться. Если спека меняется, тесты падают.

На практике применяется#

1. Авто-генерация API клиентов: OpenAPI YAML является источником правды. При его изменении CI запускает агента, который перегенерирует TypeScript-интерфейсы и контроллеры PHP.
2. Онбординг новых агентов: При запуске новой сессии агент считывает директорию docs/adr/, мгновенно понимая, что в проекте запрещено использовать moment.js в пользу date-fns (ADR-004).
3. Continuous Documentation: Во время PR-ревью агент анализирует изменения в контрактах и предлагает обновления в файлы Markdown-спецификаций.

Как это работает#

Пример структуры ADR, которую должен понимать и соблюдать ИИ-агент.

# 12. Использование Zod для runtime-валидации DTO

Дата: 2026-10-15
Статус: Принято

## Контекст
При генерации кода ИИ-агентами часто возникает рассинхронизация между статической типизацией TypeScript и реальными данными из сети, что приводит к runtime-ошибкам.

## Решение
Мы будем использовать `zod` как единственный источник правды (Single Source of Truth) для DTO. TypeScript типы должны выводиться исключительно через `z.infer`.

## Последствия
- Положительные: ИИ имеет жесткие валидаторы, тесты легко пишутся.
- Отрицательные: Дополнительный оверхед на парсинг в runtime.

Когда агент получает задачу "создать сущность Product", он прочитает этот ADR и сгенерирует правильный код:

import { z } from "zod";

// Агент использует Zod согласно ADR 0012
export const ProductSchema = z.object({
  id: z.string().uuid(),
  price: z.number().positive(),
});

export type Product = z.infer<typeof ProductSchema>;

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

Вопросы на собеседовании#