В разработке под управлением ИИ документация перестает быть просто текстом для людей — она становится исполняемым контрактом. Рассинхронизация между спецификациями и кодовой базой приводит к тому, что при последующих итерациях ИИ-агент принимает неверные решения, опираясь на устаревший контекст.
Концепция "Живых спецификаций" (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/ (Кодовая база, генерируемая строго по ограничениям)Если код меняется, спецификация должна обновиться. Если спека меняется, тесты падают.
Инженер создает ADR или OpenAPI контракт.
Агент считывает требования как системные ограничения.
Код пишется с опорой на контракты. CI проверяет типы и валидаторы.
В случае контролируемого изменения архитектуры создается новый ADR (Supersedes предыдущий).
Какую ключевую инженерную функцию выполняют файлы Architecture Decision Records (ADR) в репозитории при работе автономных AI-агентов?
docs/adr/, мгновенно понимая, что в проекте запрещено использовать moment.js в пользу date-fns (ADR-004).Пример структуры 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>;Почему в цикле разработки с участием AI-агентов подход Design-First считается единственно устойчивым, в отличие от Code-First?
Агенты не имеют стабильного доступа к внешним вики-системам. Спецификации и ADR должны лежать прямо в репозитории (docs/) в формате Markdown, чтобы всегда быть в контексте PR.
Писать эссе в ADR — антипаттерн. Агенту нужны короткие, директивные формулировки: "Контекст, Решение, Последствия". Излишняя вода тратит токены контекстного окна.
Если агент обновляет спеку под написанный им код (Code-First), система деградирует. Спецификация должна быть Design-First.