AI знает твой код. Он не знает твой продукт.

Представь свой продукт: 10+ сервисов, привычный клубок. PM приносит новую фичу, и её надо выкатить.

Допустим, твои разработчики уже каждый день работают с Claude Code, и у каждого сервиса есть свой CLAUDE.md с описанием, что он делает. На уровне кода вы уже AI-assisted. Процесс:

1. Ревью PRD — разобрать требования, найти дыры, задать уточняющие вопросы, убедиться, что все одинаково поняли задачу.
2. Техдизайн — описать решение: какие сервисы меняются, как и почему.
3. Декомпозиция — нарезать задачи по сервисам, разнести по фронту и бэку.
4. Реализация — разработчики делают свои задачи.
5. QA — протестировать каждую задачу, затем прогнать полную интеграцию.
6. Релиз — выкатить.

AI помогает ровно на одном шаге — на четвёртом. Всё остальное по-прежнему едет на чистом человеческом труде. Как прокачать остальное?

В чём затык: AI не знает твой продукт

Как агент отревьюит PRD или спроектирует изменения по 10 сервисам, которых он в глаза не видел? Никак. Чего не хватает — это контекста. И не файлов CLAUDE.md по каждому сервису, которые описывают сервисы по отдельности, а понимания продукта: как сервисы стыкуются друг с другом и что уже выкачено.

Собираем контекст

Что я сделал:

• Завёл отдельный репозиторий продукта.
• Задокументировал каждый сервис, с путями до кодовых баз.
• Перенёс туда все существующие PRD и техдоки из Confluence.

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

Промпт

This repository contains the product documentation.

In /prd you'll find the existing PRDs.
In /architecture you'll find the existing technical docs, along with paths
to the service codebases that this product relies on.

Your task:
- Read the existing PRDs in /prd and the tech docs in /architecture to
  understand what is already documented.
- Analyze the codebases referenced in /architecture.
- Cross-reference the code against the existing documentation and identify
  everything that is not yet documented — frontend pages, backend handlers,
  services, jobs, integrations, and any other significant parts of the code.

End goal: a fully documented product. Produce a gap report for the PM that
clearly shows what currently has no documentation coverage.

Report format — output a Markdown document with the following sections:

1. Summary — total components found, how many are documented vs.
   undocumented, and overall documentation coverage (%).

2. Coverage table — one row per component:
   Component | Type (FE page / BE handler / service / job / integration) |
   Source path | Documented? (Yes / Partial / No) | Existing doc reference |
   Priority (High / Med / Low) | Notes

3. Undocumented items, grouped by service or domain, each with a one-line
   description of what it does (inferred from the code).

4. Recommendations — a prioritized list of what to document first and why.

For priority: user-facing and externally-exposed components rank highest,
internal/utility code lowest. If unsure whether something is documented,
mark it Partial and explain why in Notes.

Ручной проход по отчёту

Агент додумывает, что делает незадокументированный код, читая его, — и часть он понимает неправильно. Поэтому отчёт — это черновик, а не приговор. PM и тимлид проходят по нему один раз: подтверждают приоритеты, правят неверные трактовки, подписываются. Это важнее, чем кажется: исследования файлов контекста для агентов показывают, что наивный, непроверенный контекст способен снизить успешность задачи, подняв стоимость на 20%+. Плохой контекст хуже, чем его отсутствие. Закрываешь подтверждённые дыры — и у тебя полностью задокументированный продукт.

Как держать доки живыми

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

Лечится это не очередной уборкой, а правилом процесса: обновление PRD и техдоков — часть Definition of Done. Меняется поведение — в том же PR меняется и док. Gap-анализ делается один раз; дальше доки остаются актуальными, потому что поддерживать их актуальность — часть поставки.

Шаги начинают автоматизироваться сами

Когда контекст продукта на месте, шаги автоматизируются один за другим.

Начни с ревью PRD — здесь рычаг максимальный, потому что требования — самое дешёвое место поймать проблему. Дефект, пойманный здесь, чинится за минуты; тот же дефект в проде стоит на порядок дороже. PM подаёт PRD, агент ревьюит его на фоне полного контекста продукта, помечает дыры и задаёт уточняющие вопросы.

Дальше техдизайн: агент ревьюит его так же — или сам набрасывает, раз уже знает сервисы. Оттуда рычаг идёт вниз по конвейеру — декомпозиция из техдизайна, тест-кейсы из PRD. Не буду перечислять всё; суть в том, что контекст разблокирует это целиком. Без него AI помогает на шаге 4. С ним — везде.

Конкретный пример

Вот как это выглядело на одном из наших продуктов.

• Масштаб: 10 сервисов, ~40 страниц фронта, ~130 хендлеров бэка.
• Gap-анализ: агент пометил ~90 незадокументированных компонентов — около 65% продукта — ценой примерно 2 часов работы агента плюс 4 часа ревью PM и тимлида.
• Закрытие дыр: 4 дня, вшитые в обычную спринтовую работу.
• После: ревью PRD, на которое уходило полдня переписки, теперь занимает ~1 час — агент возвращает дыры и уточняющие вопросы с первого прохода. На первых 5 фичах он поймал 6 неоднозначностей или пропущенных кейсов, которые раньше всплыли бы в QA или в проде.

Сетап обошёлся примерно в неделю работы в режиме part-time. Каждый PRD с тех пор экономит примерно полдня и ловит проблемы, которые ниже по потоку стоили бы куда дороже.

Это вообще обобщается?

Исследования говорят, что да — и первым делом это срабатывает прямо на ревью PRD. Индустриальное исследование на трёх реальных датасетах требований показало, что LLM улучшают обнаружение неоднозначных требований на ~20%, а эксперты оценили объяснения ИИ на 3.84 из 5 — ровно работа ревью PRD. И прирост коррелирует с контекстом, а не с размером модели: в исследовании на пяти моделях структурированный промпт вместо голого поднял качество требований до +59%. Узкое место — редко модель. Узкое место — качество контекста.

Вывод

Прежде чем что-то автоматизировать, надо создать контекст для агентов. Это не приятная мелочь — это обязательный первый шаг AI-разработки. Сделай его правильно, держи актуальным — и каждый шаг от ревью до релиза становится тем, где AI помогает, а не только шаг 4.

Источники

• Requirements Ambiguity Detection and Explanation with LLMs: An Industrial Study (ICSME 2025) — те самые ~20% и оценка 3.84/5. ipr.mdu.se
• Exploring the Use of LLMs for Requirements Extraction from User Stories (2025) — структурированные промпты повышают качество требований. researchsquare.com
• Knowledge Activation: AI Skills as the Institutional Knowledge Primitive for Agentic Software Development (2026) — вывод про «наивный контекст снижает успешность» и устаревание спецификаций как главный режим отказа. arxiv.org
• Данные по стоимости дефектов (NIST, Capers Jones, CISQ) — contextqa.com и scopemaster.com