---
title: "Лучшие практики написания спецификаций: от PRD и RFC до спецификаций для LLM-агентов"
slug: "specification-writing-practices"
participant: fable
model: "claude-fable-5-1"
effort: "max"
date: 2026-09-21
cutoff: 2026-09-21
language: ru
sources_read: 108
status: complete
summary: "Спецификация — документ, по которому исполнитель делает работу без уточнений, а приёмщик принимает её по записанным критериям; у продуктовой, технической и задачной форм одно ядро: цель, границы, требования, критерии и процедура приёмки, владелец, статус. Форму выбирают по исполнителю, обратимости и цене ошибки; для LLM-агента обязательна проверка, которую он запускает сам, для подрядчика — испытания и акт. Ключевое ограничение: контролируемых исследований связи «качество спецификации → результат агента» нет, а LLM-автор выявляет меньше половины неявных требований."
---

# Лучшие практики написания спецификаций: от PRD и RFC до спецификаций для LLM-агентов

## 0. Вердикт {#verdict}

**Спецификация** — документ, по которому исполнитель делает работу без уточнений, а приёмщик принимает её по записанным критериям; действующий стандарт задаёт для требований характеристики от unambiguous до verifiable, а для набора — полноту и непротиворечивость {факт} [S1]. Для продукта управления компанией нужны три уровня — продуктовый, технический и задача исполнителю, и у всех трёх одно ядро: цель, границы, требования, критерии приёмки, проверка, процедура приёмки, владелец и статус. Главный вывод: форму выбирают по исполнителю, обратимости и цене ошибки, а не по привычке; для агента это task spec с проверкой, которую он запускает сам, для сотрудника — task brief с критерием «сделано», для подрядчика — ТЗ с испытаниями и актом, для клиента — бриф и SLA.

**Инструменты spec-driven development** дали рабочие шаблоны — критерии в EARS, маркеры неопределённости, гейты одобрения {вендор} [S2, S3], но их процессы многословны и плохо масштабируются по размеру задачи {мнение} [S4]. Ключевое ограничение: контролируемых исследований связи «качество спецификации → результат агента» на продуктовых задачах нет, есть только косвенная эмпирика. LLM как автор надёжен в структуре и формулировках и ненадёжен в полноте: рекомендуемый порядок — интервью с записью спецификации и проверка, которую агент может запустить сам {вендор} [S5], при этом интервьюер-модель выявляет меньше половины неявных требований, поэтому обязательны доменный чек-лист, маркеры неопределённости и ревью человеком {эмпирика} [S6]. LLM как исполнитель чувствителен к неоднозначности: на бенчмарке она ухудшает все модели и даёт расходящиеся реализации, а сами модели её не выявляют {эмпирика} [S7].

**Самая сильная альтернатива** — разговор с приёмочными тестами без документа; она выигрывает, когда заказчик и исполнитель доступны друг другу и работа обратима, и проигрывает для агентов, подрядчиков и сотрудников в поле. Уверенность средняя: анатомия форм и требования к приёмке подтверждены первичными шаблонами, дерево решений и машиночитаемая структура — авторские построения, долгосрочный эффект не измерен.

## 1. Что это и как работает {#basics}

### 1.1 Определение, уровни и границы понятия

**Спецификация** в этом отчёте — документ, который фиксирует ожидаемый результат работы так, что исполнитель выполняет её без уточнений, а приёмщик принимает по заранее записанным критериям. ISO/IEC/IEEE 29148 задаёт для отдельного требования характеристики necessary, appropriate, unambiguous, complete, singular, feasible, verifiable, correct, conforming, а для набора требований — complete, consistent, feasible, comprehensible, validatable {факт} [S1, S8]. Тот же стандарт различает документы уровня бизнеса (BRS), заинтересованных сторон (StRS), системы (SyRS) и программного обеспечения (SRS) {факт} [S8]. Для продукта управления компанией эта лестница сводится к трём уровням из задания.

| Уровень | Вопрос | Типичные формы | Кто принимает результат |
|---|---|---|---|
| Продуктовый | Зачем и что | PRD, one-pager, PR/FAQ, pitch | Владелец продукта, руководитель |
| Технический | Как | design doc, RFC, ADR, контракт API | Инженеры, ревьюеры |
| Задача исполнителю | Что сделать, как проверить, как принять | user story с критериями, task brief, work instruction, ТЗ подрядчику, бриф клиенту | Постановщик задачи |

**Границы понятия.** Спецификация не совпадает с регламентом или SOP (описывают повторяемый процесс, а не результат конкретной работы), с планом или графиком (когда, а не что), с дизайн-макетом (одно из решений, а не требование) и с договором (юридическая обёртка, внутри которой спецификация — приложение). Чаще всего путают три пары:

- **Критерии приёмки истории и Definition of Done.** Cohn описывает DoD как «резиновый штамп», который ставится на каждую карточку, а conditions of satisfaction — как надпись на обороте конкретной карточки {мнение} [S9].
- **SLA и SLO.** По книге Google SRE признак SLA — явные последствия нарушения: «если явных последствий нет, вы почти наверняка смотрите на SLO» {факт} [S10].
- **PRD и техническая спецификация.** PRD HashiCorp содержит требования и критерии приёмки по фазам и прямо отсылает вопросы реализации в RFC {факт} [S11].

**Механизм.** Любая работающая форма содержит одну цепочку звеньев: цель → границы (что внутри и что снаружи) → требования → критерии приёмки → процедура проверки → процедура приёмки → владелец и статус. Формы отличаются тем, какие звенья развёрнуты и насколько; отсутствие любого звена даёт предсказуемую поломку: без границ растёт объём, без критериев приёмка превращается в переговоры, без владельца документ умирает {гипотеза}.

### 1.2 Анатомия по типам

#### Продуктовый уровень

**PRD.** Шаблон HashiCorp: summary с метаданными (дата, статус, владелец), background, problem («сердце документа»), personas, requirements and phases, user research («самый важный раздел»), approvals; внутри каждой фазы — требования, критерии приёмки «written like test cases» и considerations для авторов RFC {факт} [S11]. Шаблон Confluence добавляет таблицу требований со ссылками на задачи Jira, таблицу открытых вопросов с датами решения и раздел «Not doing» {факт} [S12]. Intercom вместо PRD использует Intermission: постановка проблемы со ссылками на исследования, job stories «When ___, I want to be able to ___, so I can ___», критерии успеха, scope по релизам; документ обязан помещаться на одну страницу A4, «иначе у вас нет достаточно ясного взгляда на проблему», и намеренно не содержит дизайна решения {факт} [S13, S14]. Сборник примеров PRD у Lenny Rachitsky платный, его содержание проверить не удалось [S15].

**PR/FAQ.** Amazon Working Backwards: пресс-релиз из шести частей (заголовок, подзаголовок, резюме, проблема, решение, цитаты и «как начать»), затем внешние FAQ (вопросы клиентов) и внутренние (рынок, экономика, зависимости, риски) {факт} [S16]. Пресс-релиз «всегда меньше одной страницы», FAQ «пять страниц или меньше»; на встрече все читают молча, старшие высказываются последними; результат документа — решение go/no-go {факт} [S16, S17].

**Pitch по Shape Up.** Пять ингредиентов: problem, appetite (бюджет времени), solution, rabbit holes, no-gos {факт} [S18]. Уровень детализации задан принципом «wireframes слишком конкретны, слова слишком абстрактны»: решение показывают breadboards и fat marker sketches, а сама работа должна быть rough, solved, bounded {факт} [S18, S19].

#### Технический уровень

**Design doc.** По описанию практики Google: context and scope, goals and non-goals, the actual design с акцентом на trade-offs, system-context diagram, APIs, data storage, alternatives considered, cross-cutting concerns; объём 1–3 страницы для инкрементальной работы и 10–20 для крупных проектов; писать только там, где решение неочевидно или нужен консенсус {факт} [S20].

**RFC.** Шаблон HashiCorp: overview (1–2 абзаца), background (до страницы: «новичок должен восстановить контекст по ссылкам»), proposal, abandoned ideas, свободные разделы implementation, UX, UI; метаданные — status (WIP, In-Review, Approved, Obsolete), owner, approvers, ссылка на PRD {факт} [S21]. В Uber план утверждали «несколько избранных людей» до начала работ, затем документ рассылали всей инженерной организации, а рост шума от рассылки признавался издержкой {факт} [S22]. Публичные шаблоны RFC или design doc есть более чем у 80 компаний {факт} [S23].

**ADR.** Формат Nygard: title, context, decision («We will…»), status (proposed, accepted, deprecated, superseded), consequences; одна-две страницы, полные предложения, записи не удаляются, а помечаются superseded {факт} [S24]. MADR добавляет decision drivers, considered options и confirmation — способ проверить, что решение соблюдено {факт} [S25].

#### Инженерия требований

**SRS по 29148.** Структура: purpose, overall description (product perspective, constraints, user characteristics), specific requirements (interfaces, functions, performance, database, attributes); IEEE 830 заменён на 29148 в 2011 году, текущая редакция 2018 {факт} [S1].

**EARS.** Пять шаблонов Mavin плюс составной: ubiquitous «The <system> shall <response>», state-driven «While <state>, the <system> shall …», event-driven «When <trigger>, the <system> shall …», optional «Where <feature>, the <system> shall …», unwanted behaviour «If <trigger>, then the <system> shall …», complex — комбинация While и When {факт} [S26]. Признанные ограничения: более трёх предусловий дают громоздкие предложения, часть требований лучше выражать таблицами решений или диаграммами состояний, нефункциональные требования ложатся плохо {факт} [S27].

**User story.** INVEST (Wake): Independent, Negotiable, Valuable, Estimable, Small, Testable; карточка несёт «неявное обещание: я понимаю, чего хочу, достаточно, чтобы написать тест» {мнение} [S28]. Три C Jeffries: card — напоминание, а не требование; conversation — обмен; confirmation — приёмочные тесты, желательно автоматические {мнение} [S29].

**Use case (Cockburn).** Поля: goal in context, scope, level, preconditions, success end condition, failed end condition, primary actor, trigger, main success scenario, extensions («что может пойти не так на каждом шаге»), sub-variations, open issues, schedule {факт} [S30].

**Gherkin и specification by example.** Ключевые слова Feature, Rule, Example/Scenario, Given, When, Then, Background, Scenario Outline; шаги описывают поведение, а не интерфейс («представьте, что сейчас 1922 год»), проверяют наблюдаемые исходы, а не состояние базы данных {факт} [S31]. Adzic по материалам более чем 50 проектов выделил паттерны: deriving scope from goals, specifying collaboratively, illustrating using examples, refining the specification, automating validation without changing specifications, validating frequently, evolving a documentation system {эмпирика} [S32]. Fowler предупреждает, что примеры «не могут быть единственной техникой требований», но дают двойную проверку: требование выражено и тестом, и кодом {мнение} [S33].

#### Контракты как спецификация

**OpenAPI 3.1** — «независимое от языка описание интерфейса HTTP API», позволяющее «людям и компьютерам понять возможности сервиса без доступа к исходному коду»; верхний уровень: openapi, info, servers, paths, webhooks, components, security; схемы совместимы с JSON Schema 2020-12 {факт} [S34]. JSON Schema — декларативный язык структуры и ограничений JSON для валидации, документации и контрактов обмена данными {факт} [S35]. AsyncAPI 3.0 переносит тот же подход на message-driven API: channels, operations, components, независимо от протокола {факт} [S36]. Контракт — единственная форма спецификации, для которой проверка исполнения автоматизирована по построению {гипотеза}.

#### Спецификации для LLM-агентов

**Kiro.** Три файла: requirements.md (user stories с критериями приёмки в EARS вида «WHEN a user submits a form with invalid data THE SYSTEM SHALL display validation errors next to the relevant fields»), design.md (архитектура, sequence diagrams), tasks.md (дискретные задачи со ссылками на требования); два маршрута — requirements-first и design-first; quick spec без гейтов одобрения {вендор} [S2, S37]. Для исправления ошибок рекомендуется явно фиксировать сохраняемое поведение формулой «WHEN [condition] THEN system SHALL CONTINUE TO [existing behavior]» {вендор} [S38].

**Spec Kit.** Философия «код служит спецификации»; constitution с неизменяемыми принципами, затем specify → plan → tasks → implement; неоднозначности помечаются «[NEEDS CLARIFICATION: конкретный вопрос]», чек-лист требует, чтобы «маркеров не осталось»; тесты утверждаются человеком и должны сначала падать {вендор} [S3]. Шаблон spec.md: истории с приоритетами P1–P3 и полем «Independent Test», сценарии Given/When/Then, edge cases, требования FR-001 «System MUST …», ключевые сущности, критерии успеха SC-001 с измеримыми величинами, допущения; ИИ предписано «WHAT и WHY, не HOW» {вендор} [S39]. Команда clarify задаёт «до пяти целевых вопросов» и записывает ответы в spec.md; checklist — «unit tests for your requirements»; analyze — проверка согласованности spec, plan и tasks «пока артефакты ещё дёшево править»; converge — проверка кода против всех трёх {вендор} [S40].

**OpenSpec.** Разделяет openspec/specs (текущая истина) и openspec/changes (предложения); изменение состоит из proposal, дельт спецификаций, design и tasks; при архивировании дельты сливаются в спецификации {вендор} [S41]. Требования пишутся ключевыми словами RFC 2119 (SHALL, MUST), сценарии — Given/When/Then, дельты помечаются «ADDED / MODIFIED / REMOVED Requirements», чтобы ревьюер видел только изменение {вендор} [S42].

**AGENTS.md и файлы правил.** «README для агентов»: обычный Markdown без обязательных полей; ближайший к редактируемому файлу AGENTS.md побеждает, явный промпт пользователя перекрывает всё {факт} [S43]. Codex склеивает файлы от глобального к вложенным и перестаёт добавлять их при достижении лимита project_doc_max_bytes, по умолчанию 32 KiB {вендор} [S44]. Cursor советует держать правила короче 500 строк, крупные разбивать на составные и приводить примеры вместо копирования кода {вендор} [S45].

**Model Spec как спецификация поведения.** Цепочка полномочий root → system → developer → user → guideline; «предполагай добрые намерения»; при неясности «формулируй допущения и задавай уточняющие вопросы»; цитируемый текст, JSON и выводы инструментов «не имеют полномочий по умолчанию»; каждое правило иллюстрировано парами compliant и violation; текст в общественном достоянии CC0 {вендор} [S46]. Для внутреннего стандарта это образец того, как спецификация поведения задаёт приоритет инструкций и правило разрешения конфликтов {гипотеза}.

**Рекомендации вендоров моделей по инструкциям.** Anthropic: «правильная высота» инструкций — не хрупкие жёсткие правила и не туманные указания, минимальный набор высокосигнальных токенов, канонические примеры, подгрузка контекста just-in-time {вендор} [S47]. OpenAI для GPT-4.1: модель следует инструкциям «буквальнее предшественников», при конфликте побеждает инструкция ближе к концу промпта, правила «always» провоцируют лишние вызовы инструментов {вендор} [S48]; для GPT-5 противоречия в инструкциях (пример: «никогда не назначать приём без согласия пациента» рядом с «автоматически назначать ближайший слот») ощутимо ухудшают результат {вендор} [S49]. Anthropic для промптов: «покажи промпт коллеге без контекста; если он запутается, запутается и модель», объясняй мотивацию правил, давай 3–5 примеров, размечай разделы XML-тегами {вендор} [S50].

#### Спецификации для людей вне разработки

**Work instruction.** Элементы: идентификация задачи, цель, последовательные шаги с визуальными подсказками, ответственные за каждый шаг, ресурсы и инструменты, контрольные точки качества, ссылки на нормативы {мнение} [S51].

**Задание подрядчику: SOW и ТЗ.** Разделы SOW: цели, scope, задачи, график и вехи, deliverables, стандарты качества, критерии приёмки «с тестированием, инспекциями и формальным sign-off» до оплаты, условия оплаты, допущения, ограничения, управление изменениями {мнение} [S52]. Критерии приёмки дают заказчику право отказать в приёмке и запускают процедуру доработки {мнение} [S53]. Приёмочное тестирование по ISTQB — «формальное тестирование относительно потребностей и требований для определения, удовлетворяет ли система критериям приёмки»; процесс: критерии → выполнение → сравнение с ожидаемым → pass/fail → sign-off {факт} [S54]. ГОСТ 34.602 задаёт разделы ТЗ (общие сведения, назначение и цели, характеристика объекта автоматизации, требования к системе, состав и содержание работ, порядок контроля и приёмки, подготовка объекта, документирование) и три вида испытаний по ГОСТ 34.603: предварительные, опытная эксплуатация, приёмочные {факт} [S55]; результаты оформляются протоколом приёмочных испытаний и актом о вводе в действие {факт} [S56].

**Бриф.** Девять разделов: название и описание, цели и метрики успеха, аудитория, сообщение и тон, deliverables, стейкхолдеры, бюджет, сроки, дистрибуция; бриф «живой документ», но обязан достичь ясности до старта работ {вендор} [S57].

**SLA.** Компоненты: описание услуги, целевые показатели, мониторинг и отчётность, порядок обращения и эскалации, сроки реакции и решения, последствия нарушения {факт} [S58]; SRE советует немного SLO, без абсолютов и с бюджетом ошибок {мнение} [S10].

**Функциональная спецификация Spolsky.** Разделы: disclaimer, единственный автор, scenarios, nongoals, overview, details («самое важное»), open issues, side notes; спецификация живёт до завершения кода, а устаревание — «следствие плохого ухода, а не порок формы» {мнение} [S59].

### 1.3 Анатомия по аудиториям

| Аудитория | Что обязано быть | Чего не писать | Детализация | Где ломается |
|---|---|---|---|---|
| LLM-агент, кодирование | Самодостаточный текст с именами файлов и интерфейсов, явный out of scope, финальный e2e-шаг проверки; проверка, которую агент может запустить сам: тест, сборка, скриншот {вендор} [S5] | То, что агент выведет из кода; длинные объяснения; часто меняющееся {вендор} [S5] | Уровень задачи с критериями-тестами | Контекстное окно: качество падает по мере заполнения {вендор} [S5]; противоречивые инструкции {вендор} [S49]; правило теряется в раздутом файле {вендор} [S5] |
| LLM-агент, операционные и аналитические задачи | Иерархия инструкций и правило конфликтов, допущения и вопросы при неясности, формат вывода, примеры, критерий остановки {вендор} [S46, S48, S50] | Инструкции, чей смысл зависит от недоверенных данных {вендор} [S46] | Уровень задачи | Данные инструментов приняты за инструкции {вендор} [S46] |
| Разработчик | Контекст, goals и non-goals, рассмотренные альтернативы {факт} [S20]; разговор как часть требования {мнение} [S29] | Дизайн решения за инженера в продуктовом документе {факт} [S13, S18] | Design doc 1–3 страницы, задача — конкретная работа с исходом {факт} [S20, S60] | User story как ритуал вместо задачи {мнение} [S60] |
| Сотрудник подразделения | Шаги, инструменты, контрольные точки, ответственные {мнение} [S51]; простой язык без кодовых слов {факт} [S13] | Обоснования и история решений | Пошаговая инструкция | Нет критерия «сделано» для шага {гипотеза} |
| Партнёр, подрядчик | Deliverables, критерии приёмки, процедура и сроки приёмки, действия при отказе {мнение} [S52, S53]; виды испытаний и акт {факт} [S55, S56] | Внутренние мотивы и политика заказчика | ТЗ с разделом приёмки | Субъективные критерии → спор о приёмке {гипотеза} |
| Клиент | Ожидаемый результат, критерии успеха, сроки, что требуется от клиента {вендор} [S57]; для сервиса — SLA с последствиями {факт} [S58] | Внутренняя терминология исполнителя | Бриф на страницу, SLA на несколько показателей | Ожидания без измеримых показателей {гипотеза} |

### 1.4 Борьба с неоднозначностью

Наборы правил, применимые к любой форме, сводятся к четырём инструментам.

- **Запретный словарь.** Requirements smells: subjective language, ambiguous adverbs and adjectives, loopholes, open-ended non-verifiable terms, superlatives, comparatives, negative statements, vague pronouns; автоматический детектор Smella показал среднюю точность 59 % при полноте 82 % {эмпирика} [S61]. Для user stories QUS задаёт 13 критериев: well-formed, atomic, minimal, conceptually sound, problem-oriented, unambiguous, conflict-free, full sentence, estimatable, unique, uniform, independent, complete {эмпирика} [S62].
- **Шаблон предложения.** EARS фиксирует порядок «условие → система → отклик» и набор ключевых слов [S26]; Given/When/Then делает то же для примеров [S31].
- **Пример вместо абстракции.** Конкретный пример показывает границу правила там, где общая формулировка её скрывает {мнение} [S33].
- **Явная неопределённость.** Маркер «[NEEDS CLARIFICATION]» в тексте и запрет закрывать спецификацию с маркерами [S3, S39]; ограниченный список вопросов с записью ответов в документ [S40]; у агента — обязанность формулировать допущения и спрашивать {вендор} [S46].

Цена невыполнения измерена для агентов: на бенчмарке Orchid неоднозначность ухудшает результат всех моделей, модели дают функционально расходящиеся реализации одного требования и не выявляют неоднозначность самостоятельно {эмпирика} [S7].

### 1.5 Проверки, критерии и процедура приёмки как обязательная часть

**Правило трёх частей.** Для каждого требования спецификация отвечает на три вопроса: что должно быть истинно (критерий), как это узнать (проверка), кто и когда решает (приёмка). Общий для всех работ уровень качества выносится в Definition of Done — «формальное описание состояния инкремента, когда он отвечает мерам качества продукта»; не-Done «нельзя выпускать и даже показывать на Sprint Review» {факт} [S63]; частные критерии остаются в самой задаче {мнение} [S9].

| Форма | Как встроены критерии | Процедура приёмки |
|---|---|---|
| PRD HashiCorp | Критерии приёмки по фазам «как тест-кейсы» {факт} [S11] | Чек-лист approvals, предпосылки: согласованный timeline и достаточная ясность для RFC {факт} [S11] |
| PR/FAQ | Внутренние FAQ о рисках и допущениях {факт} [S16] | Молчаливое чтение, обсуждение, go/no-go {факт} [S16, S17] |
| Design doc, RFC | Goals и non-goals; approvers в метаданных {факт} [S20, S21] | Ревью с утверждением статуса Approved {факт} [S21] |
| ADR (MADR) | Раздел confirmation {факт} [S25] | Смена статуса proposed → accepted {факт} [S24] |
| User story | Conditions of satisfaction на карточке {мнение} [S9] | Confirmation через приёмочные тесты {мнение} [S29] |
| Gherkin, SbE | Сценарии сами являются тестами {факт} [S31] | Автоматический прогон, «живая документация» {эмпирика} [S32] |
| Контракт API | Схемы и типы {факт} [S34, S35] | Валидация и контрактные тесты по построению {гипотеза} |
| Kiro, Spec Kit, OpenSpec | Критерии в EARS или Given/When/Then, FR-/SC-идентификаторы {вендор} [S37, S39, S42] | Гейты одобрения фаз, analyze и converge {вендор} [S2, S40] |
| Task для агента | Тест, сборка, скриншот как проверка {вендор} [S5] | Агент показывает вывод проверки, человек подтверждает {вендор} [S5] |
| SOW, ТЗ | Критерии приёмки на deliverable {мнение} [S52] | Испытания → протокол → акт; право отказа и доработка {факт} [S53, S55, S56] |
| Work instruction | Контрольные точки качества {мнение} [S51] | Проверка на контрольной точке ответственным {гипотеза} |
| Бриф | Метрики успеха {вендор} [S57] | Согласование до старта, живой документ {вендор} [S57] |
| SLA | Целевые показатели с методом измерения {факт} [S58] | Отчётность и последствия нарушения {факт} [S10, S58] |

### 1.6 Где ломается

| Форма | Типичная поломка | Механизм |
|---|---|---|
| PRD | Документ разрастается и не читается | «Чем длиннее документ, тем меньше его читают и помнят» {мнение} [S13] |
| PR/FAQ | Слишком много определённости заранее для исследовательских проектов | Требует ответов о рынке и экономике до первых экспериментов {мнение} [S16] |
| Pitch | Замена pitch на wireframe сковывает команду | Высокая детализация «загоняет дизайнеров в коробку» {факт} [S18] |
| Design doc | Пишется там, где решение очевидно | Издержки создания без выгоды консенсуса {факт} [S20] |
| RFC | Рассылка всем создаёт шум | Признано в Uber, лечится фильтрами {факт} [S22] |
| ADR | Решение без confirmation не проверяется | Нет способа узнать, соблюдается ли решение {факт} [S25] |
| EARS | Громоздкие предложения при многих предусловиях | Признанное ограничение синтаксиса {факт} [S27] |
| User story | Карточка принята за полное требование | Card — напоминание, требование рождается в разговоре {мнение} [S29] |
| Gherkin | Сценарии, написанные после кода или в одиночку, случайные детали | Теряется общее понимание, сценарии превращаются в скрипты {мнение} [S31] |
| Kiro, Spec Kit | Малая задача раздувается в десятки критериев | Небольшой баг превращён в 4 истории с 16 критериями {мнение} [S4] |
| AGENTS.md, CLAUDE.md | Правила игнорируются | Раздутый файл, важное тонет в шуме {вендор} [S5] |
| SOW, ТЗ | Приёмка превращается в спор | Субъективные критерии и отсутствие процедуры отказа {мнение} [S53] |
| SLA | Абсолютные обещания | «Всегда доступно» нереалистично и дорого {мнение} [S10] |

## 2. Актуальность и доказательная база на дату среза {#evidence}

### 2.1 Распространённость по сегментам и тренд

| Сегмент | Состояние на 2026-09-21 | Тренд | Основание |
|---|---|---|---|
| Инженерные культуры: RFC, design doc, ADR | Публичные шаблоны более чем у 80 компаний; Meta отмечена как исключение, избегающее тяжёлой документации {факт} [S23] | Стабилен | Список Pragmatic Engineer, обновление 2024 |
| Файлы инструкций для агентов | AGENTS.md принят более чем 60 тыс. open-source проектов с августа 2025 и передан в Agentic AI Foundation под Linux Foundation вместе с MCP и goose {факт} [S64]; поддержка Codex, Cursor, Copilot, Jules, VS Code и других {факт} [S43] | Растёт быстро | Пресс-релиз Linux Foundation 2025-12-09 |
| Spec-driven development для агентов | Spec Kit: 138,2 тыс. звёзд GitHub на дату доступа, лицензия MIT {факт} [S65]; OpenSpec: 69,8 тыс. звёзд {факт} [S41]; Kiro анонсирован 2025-07-14 {факт} [S66]; Thoughtworks поместил практику в кольцо Assess (выпуск за ноябрь 2025); в текущем выпуске радара на дату среза блип отсутствует {мнение} [S67] | Растёт, зрелость низкая | Звёзды измеряют интерес, не внедрение {гипотеза} |
| LLM как автор продуктовых документов | В опросе Productboard среди 379 продуктовых специалистов компаний от 500 человек 94 % используют ИИ ежедневно или часто, PRD в числе главных задач {вендор} [S68] | Растёт | Вендорский опрос, октябрь 2025 |
| ИИ в разработке в целом | DORA 2025: около 5 000 респондентов, 90 % используют ИИ; положительная связь с пропускной способностью и отрицательная со стабильностью поставки {эмпирика} [S69] | Растёт | Опросное исследование, не эксперимент |
| Конфигурация агентов в репозиториях | В выборке 2 853 репозиториев контекстные файлы часто единственный механизм, AGENTS.md складывается как интероперабельный стандарт, skills и subagents редки {эмпирика} [S70] | Растёт | Разведочное исследование 2026 |
| Классическая инженерия требований (29148, EARS, use cases) | Стандарт действует в редакции 2018 {факт} [S1]; EARS внедрён в Airbus, Bosch, Dyson, Honeywell, Intel, NASA, Siemens {факт} [S26] и встроен в Kiro с 2025 {факт} [S27] | Стабилен, второе дыхание через агентов | Официальные страницы |

### 2.2 Научная и эмпирическая база

**Проблемы требований в практике.** Семейство опросов NaPiRE (228 компаний, 10 стран) фиксирует неполные и скрытые требования как самую частую проблему, рядом — коммуникационные сбои, движущиеся цели и слишком абстрактные требования {эмпирика} [S71]. Автоматическая проверка формулировок работает частично: детектор запахов требований дал точность 59 % при полноте 82 % с большим разбросом по контекстам {эмпирика} [S61]; инструмент AQUSA на более чем 1 000 историй из 18 компаний не достиг целевой полноты {эмпирика} [S62]. Для EARS количественной эмпирики об уменьшении дефектов в открытых источниках не найдено: описаны «документированные преимущества» и «уроки промышленного применения» {факт} [S27].

**BDD и примеры.** Систематическое картирование 166 работ 2006–2021 годов отмечает «острую нехватку метрик» качества BDD-спецификаций и «скудость исследований с индустриальными данными» {эмпирика} [S72]. Разработчики Cucumber описывают типичные провалы: сценарии после кода, аналитик пишет в одиночку, случайные детали, несколько правил в одном сценарии {мнение} [S73]. База Adzic — интервью и кейсы более чем 50 проектов без контрольных групп {эмпирика} [S32].

**LLM как интервьюер и автор требований.**

| Исследование | Дизайн | Результат | Ограничение |
|---|---|---|---|
| LLMREI [S74] | Чат-бот для интервью, 33 симулированных интервью, zero-shot и least-to-most | Число ошибок сопоставимо с интервьюером-человеком, извлекает «большую часть требований» {эмпирика} | Симулированные, а не реальные стейкхолдеры |
| Генерация уточняющих вопросов [S75] | Два контролируемых эксперимента, вопросы LLM против человеческих | Не хуже по ясности и релевантности; лучше, если подсказаны типы ошибок интервьюера {эмпирика} | Размер выборки в аннотации не раскрыт |
| ReqElicitGym [S6] | 101 сценарий, симулированный пользователь-оракул, семь моделей | Модели выявляют менее половины неявных требований, слабы в стилевых требованиях, полезные вопросы приходят поздно {эмпирика} | Веб-сайты как домен |
| Редакции формулировок LLM [S76] | 26 участников, 130 формулировок, оценка собственных и переписанных | Переписанные оценены выше по соответствию замыслу, читаемости и однозначности {эмпирика} | Самооценка, автор в контуре валидации |
| Оценка качества по 29148 [S77] | LLM оценивает, объясняет и предлагает улучшение; валидация с инженерами | «Потенциал для улучшения качества требований» {эмпирика} | Числа в аннотации отсутствуют |
| DeepQuali [S78] | GPT-4o, две малые компании, сверка с экспертами | Эксперты в целом согласны с оценками и объяснениями, недовольны интеграцией в процесс {эмпирика} | Малая выборка |
| Human-LLM defect prediction [S79] | Бенчмарк QuRE, 1 266 требований Mercedes-Benz | Быстрый прирост от 20 проверенных человеком примеров, высокая полнота {эмпирика} | Один тип дефекта (слабые слова) |
| Детекция неоднозначности в индустрии [S80] | Три железнодорожных набора, in-context learning, 8 экспертов | +20,2 % к классификации при 10 примерах; объяснения оценены на 3,84 из 5 {эмпирика} | Индустриальный трек, средняя оценка объяснений |
| SpecFix [S81] | Автопочинка неоднозначных описаний задач, HumanEval+, MBPP+, LiveCodeBench | Изменено 43,58 % описаний, Pass@1 на изменённых +30,9 %, по бенчмарку +4,09 % {эмпирика} | Функции-задачи, не продуктовые требования |
| Orchid [S7] | 1 304 задачи с четырьмя типами неоднозначности | Ухудшение у всех моделей, расходящиеся реализации, модели не выявляют неоднозначность сами {эмпирика} | Функциональный уровень |
| Генерация Gherkin [S82] | GPT-3.5, GPT-4, Llama-2, PaLM-2; zero- и few-shot | GPT-семейство даёт синтаксически чистые тесты при few-shot; человек в контуре обязателен {эмпирика} | 2024 год, устаревшие модели |

**Агенты и исход работы.** Единственное рандомизированное исследование — METR: 16 опытных open-source разработчиков, 246 задач, доступ к ИИ замедлил выполнение на 19 % при ожидании ускорения на 24 %; среди причин названы неявные требования репозиториев (документация, тесты, форматирование) {эмпирика} [S83]. Анализ около 400 тыс. сессий Claude Code показывает, что люди принимают около 70 % решений «что строить», а агент — около 80 % решений «как»; верифицированный успех у экспертных сессий выше 28 % против 15 % у новичков, и экспертность выражается в точной постановке задачи {эмпирика} [S84]. Мультивокальный обзор 67 источников 2022–2026 годов формулирует тезис «дисциплина спецификации, а не способности модели — ограничивающий фактор надёжности», но без контролируемого эксперимента {эмпирика} [S85]. Таксономия шести фреймворков SDD (Spec Kit, OpenSpec, BMAD, GSD, Spec Kitty, Reversa) находит сходимость к «устойчивым артефактам, рабочим контрактам, трассируемости и человеческому ревью» и называет главные риски: дрейф спецификации и кода, чрезмерное доверие сгенерированному, привязка к платформе {эмпирика} [S86].

**Качество файлов инструкций.** Из 34 публичных AGENTS.md 37 % оказались ниже порога структурной полноты, чаще всего отсутствуют классификация данных и рубрики оценки {эмпирика} [S87]. Файлы правил «пассивны»: не видно, применяются ли они; активная проверка соблюдения повышает следование правилам {эмпирика} [S88].

### 2.3 Практическая база

- **Кейсы с числами от практиков.** Böckeler опробовала Kiro, Spec Kit и Tessl: Spec Kit сгенерировал избыточный повторяющийся Markdown («я бы лучше ревьюила код, чем все эти markdown-файлы»), Kiro превратил мелкий баг в 4 истории с 16 критериями, агенты игнорировали или перетолковывали инструкции {мнение} [S4]. Thoughtworks: процессы «многословны и своевольны», неустойчивы к размеру задачи, «длинные spec-файлы трудно ревьюить» {мнение} [S67].
- **Вендорские данные.** Kiro и Spec Kit описывают процесс, но не публикуют измерений эффекта {вендор} [S2, S3]. Пересказ поста OpenAI о «harness engineering»: команда сначала тратила пятницы на уборку «AI-slop», затем перенесла правила в линтеры и архитектурные проверки; принцип «чего нет в контексте агента — не существует» {вендор} [S89]. Первоисточник на openai.com недоступен (403), число строк и PR не проверено.
- **Работающие ограничения длины.** Intercom — одна страница A4 {факт} [S13]; Amazon — пресс-релиз меньше страницы, FAQ до пяти {факт} [S17]; Google — 1–3 или 10–20 страниц по масштабу {факт} [S20]; Cursor — до 500 строк правил {вендор} [S45]; Codex — 32 KiB по умолчанию {вендор} [S44].

### 2.4 Мнение отрасли и главные споры

- **«SDD — новый водопад».** Кент Бек: описания SDD «предполагают, что при реализации вы не узнаете ничего, что изменило бы спецификацию»; Фаулер добавляет, что «обучающий цикл экспериментов необходим для построения модели в основе любой стоящей спецификации» {мнение} [S90]. Yeret с позиции продуктовой разработки: SDD — «язык программирования более высокого уровня», но большие спецификации до старта возвращают хэндоффы и глушат обучение; спецификацию нужно писать во время исполнения силами команды {мнение} [S91].
- **Ответ сторонников.** Spec Kit заявляет, что при генеративной связи «пивоты становятся системной регенерацией, а не ручной переписью» {вендор} [S3]; Kiro продаёт «спецификации, синхронные с кодом» {вендор} [S66]. Ни одно из утверждений не подкреплено измерениями.
- **User stories как ритуал.** Linear называет user stories «карго-культом» и пишет задачи как конкретную работу с исходом {мнение} [S60]; Cohn и Jeffries защищают историю как повод для разговора с подтверждением тестами {мнение} [S9, S29].
- **Стоимость раннего дефекта.** Популярный аргумент «дефект в требованиях стоит в 100 раз дороже» Bossavit разобрал как «лепрекона»: исходные данные Boehm не выдерживают проверки, одно из исследований даёт обратное соотношение {мнение} [S92]. Обосновывать спецификации этой кривой нельзя.
- **PR/FAQ и неопределённость.** Критика: слишком много определённости заранее, плохо для исследовательских проектов; ответ — использовать документ как начальную гипотезу и обновлять {мнение} [S93].

### 2.5 Что изменилось за 2023–2026 и как это влияет на выводы

1. **Появился новый класс исполнителей.** Kiro (июль 2025) и Spec Kit (сентябрь 2025) сделали спецификацию входом для агента: «модели превосходны в завершении паттернов, но не в чтении мыслей» {вендор} [S94]. Следствие: критерии приёмки, которые агент может выполнить сам, стали обязательным полем, а не украшением [S5].
2. **Появились измерения неоднозначности для машин.** Orchid и SpecFix показывают, что неоднозначность напрямую снижает корректность кода и что её частично чинит переписывание требований {эмпирика} [S7, S81]. Это первая количественная связь «качество формулировки → результат», которой у классической RE не было.
3. **Спецификация поведения стала публичным жанром.** Model Spec в CC0 задал образец: приоритеты инструкций, допущения, парные примеры {вендор} [S46].
4. **Эмпирика об ИИ-продуктивности противоречива.** RCT METR показывает замедление у экспертов [S83], опросы DORA — рост пропускной способности при падении стабильности [S69]. Вывод отчёта: спецификация и проверки нужны именно как стабилизатор, а не как ускоритель {гипотеза}.
5. **Инструкционные файлы стали стандартом де-факто** и одновременно предметом критики за низкое структурное качество [S64, S87].

## 3. Где применимо и где нет, плюсы и минусы {#fit}

### Подходит, когда
- **Исполнитель не может задать вопрос в момент работы.** Агент в автономной сессии, подрядчик, сотрудник в поле: всё, что не записано, будет додумано; Claude Code рекомендует после интервью запускать «свежую сессию» с готовой спецификацией {вендор} [S5], а SOW требует критериев и процедуры приёмки до начала работ {мнение} [S52].
- **Цена ошибки высока или результат необратим.** Миграция данных, договор, изменение на критическом пути: Kiro советует полноценную bugfix-спецификацию для «критических путей, прошлых регрессий и требований комплаенса» {вендор} [S38]; ГОСТ вводит трёхступенчатые испытания перед вводом в действие {факт} [S55].
- **Решение затрагивает многих.** HashiCorp пишет RFC, «если изменение затронет многих стейкхолдеров», ради ясности и консенсуса {факт} [S21]; Google — там, где нужен консенсус и ревью старших {факт} [S20].
- **Работа повторяется и результат должен быть одинаков.** Work instruction с шагами и контрольными точками фиксирует «как» для каждого исполнителя {мнение} [S51].
- **Есть приёмка третьей стороной или оплата по результату.** Критерии приёмки дают заказчику право отказа и запускают доработку {мнение} [S53]; SLA без последствий — не SLA {факт} [S10].
- **Проверку можно автоматизировать.** Контракт API валидируется по построению {факт} [S34], сценарии Gherkin исполняются {факт} [S31], а тест для агента закрывает цикл «сделал → проверил → поправил» {вендор} [S5].

### Не подходит, когда
- **Работа исследовательская с высокой неопределённостью.** Требование ответить о рынке и экономике до первых экспериментов делает PR/FAQ преждевременным {мнение} [S93]; Бек: детальная спецификация до реализации отрицает обучение по ходу {мнение} [S90].
- **Изменение описывается одной фразой.** «Если вы можете описать diff одним предложением, пропустите план» {вендор} [S5]; опечатки и однострочные правки — в чат, а не в спецификацию {вендор} [S38]; для очевидных решений design doc не пишут {факт} [S20].
- **Заказчик и исполнитель могут разговаривать.** Карточка плюс разговор плюс приёмочный тест дешевле документа {мнение} [S29]; Linear заменяет истории короткими задачами {мнение} [S60].
- **Нет владельца, готового обновлять.** Устаревание — следствие отсутствия ухода {мнение} [S59]; дрейф спецификации и кода назван главным риском SDD-фреймворков {эмпирика} [S86].
- **Форма не соответствует размеру задачи.** Мелкий баг, превращённый в 4 истории и 16 критериев, дороже самого исправления {мнение} [S4].

### Плюсы
- **Однократная коммуникация.** По Spolsky спецификация экономит время, потому что «как должна работать программа» объясняется один раз, а не в каждом разговоре {мнение} [S95].
- **Приёмка без спора.** Критерий с pass/fail и sign-off превращает приёмку в процедуру, а не переговоры {факт} [S54]; DoD делает состояние «сделано» прозрачным для всех {факт} [S63].
- **Закрытый цикл для агента.** Проверка, которую агент запускает сам, заменяет человека в роли «цикла верификации» {вендор} [S5]; снятие неоднозначности уменьшает расходящиеся реализации {эмпирика} [S7].
- **Память организации.** ADR сохраняет мотивы решений, которые иначе «теряются» {мнение} [S24]; design doc служит документом для инженеров сопровождения {факт} [S20].
- **Стабилизатор скорости.** При росте объёма изменений без проверок падает стабильность {эмпирика} [S69]; спецификация с критериями и есть такая проверка {гипотеза}.

### Минусы
- **Стоимость написания и ревью.** Генерируемые спецификации многословны и «трудны для ревью» {мнение} [S4, S67]; RFC-рассылка увеличивает шум {факт} [S22].
- **Дрейф от реальности.** Код меняется, спецификация нет; расхождение невидимо до дорогого момента {эмпирика} [S86].
- **Иллюзия полноты.** Скрытые требования — главная проблема практики {эмпирика} [S71]; LLM-интервьюер выявляет меньше половины неявных требований {эмпирика} [S6].
- **Сковывание исполнителя.** Детальные wireframes «загоняют в коробку» тех, кто будет делать {факт} [S18].
- **Подмена разговора документом.** Спецификация как замена conversation теряет то, что рождается в диалоге {мнение} [S29, S90].

## 4. Альтернативы и дерево решений {#alternatives}

### 4.1 Прямые альтернативы

Предмет сравнения — **письменная спецификация с критериями и процедурой приёмки** (PRD, design doc, task spec, ТЗ). Альтернативы того же класса — другие способы передать исполнителю «что сделать и как проверить».

| Способ | Однозначность | Проверяемость | Стоимость создания | LLM-исполнитель | Человек вне разработки | Устойчивость к изменениям |
|---|---|---|---|---|---|---|
| Письменная спецификация с критериями приёмки (предмет) | Высокая при шаблонах EARS или Given/When/Then [S26, S31] | Высокая: критерии + процедура [S54] | Средняя; растёт с объёмом [S4] | Подходит: самодостаточный текст с проверкой [S5] | Подходит: ТЗ, бриф, инструкция [S51, S52] | Требует владельца; риск дрейфа [S86] |
| Разговор + приёмочные тесты (3C, SbE) | Средняя: детали в диалоге [S29] | Высокая, если тесты автоматизированы [S32] | Низкая на старте, требует доступности заказчика | Не подходит без записи: агент не участвует в разговоре {гипотеза} | Подходит для сотрудника рядом | Тесты — живая документация [S32] |
| Прямой промпт без артефакта («vibe coding») | Низкая: модель «не читает мысли» [S94] | Низкая, если нет теста [S5] | Минимальная | Только для однострочных правок [S5, S38] | Не применимо | Нулевая: намерение живёт в истории чата [S41] |
| Исполняемый контракт (OpenAPI, JSON Schema, AsyncAPI) | Высокая для интерфейсов [S34, S35] | Автоматическая [S34] | Средняя, окупается инструментами | Отлично: машиночитаемо | Не применимо | Версионируется как код |
| Spec-as-source (Tessl) | Высокая заявлена | Тесты привязаны к спецификации [S96] | Высокая; закрытая бета [S96] | Целевая аудитория | Не применимо | Код регенерируется; параллель с неудачами MDD [S4] |
| Формальная спецификация (TLA+) | Максимальная | Модельная проверка TLC [S97] | Высокая, редкая компетенция | Референс | Не применимо | Стабильна для протоколов |
| Breadboard или fat marker sketch (Shape Up) | Средняя намеренно [S19] | Через appetite и no-gos [S18] | Низкая | Слабо: нужны слова для агента {гипотеза} | Нет | Меняется в ходе цикла |
| Work instruction, SOP | Высокая для шагов [S51] | Контрольные точки [S51] | Средняя | Подходит как steering для рутинных задач {гипотеза} | Основная форма | Ревизии по номеру версии |

### 4.2 Когда альтернатива целесообразнее предмета

- **Разговор + тесты** — когда заказчик и исполнитель доступны друг другу ежедневно и работа обратима; плюс: дешевле и живее, минус: не переносится на агента и подрядчика без записи [S29, S32].
- **Прямой промпт** — когда изменение описывается одной фразой и есть автоматическая проверка; плюс: нулевые издержки, минус: намерение не сохраняется [S5, S41].
- **Контракт** — когда работа сводится к интерфейсу между системами или командами; плюс: проверка по построению, минус: не описывает «зачем» [S34].
- **Spec-as-source** — когда организация готова к тому, что код становится производным артефактом; минус: инструмент в бете и повторяет риски MDD [S4, S96].
- **TLA+** — когда ошибка в протоколе или распределённом алгоритме катастрофична; минус: компетенция и время [S97].
- **Breadboard** — когда важнее дать команде свободу решения внутри appetite [S18, S19].
- **Work instruction** — когда работа повторяемая и исполнители меняются [S51].

### Дерево решений

Дерево строится по осям: исполнитель, тип работы, обратимость, цена ошибки. Связка с классификатором типов работы из исследования по методологиям доставки предполагается по типам «повторяемая», «проектная с известным решением», «исследовательская», «инцидент», «подрядная», «сервисная» {гипотеза}.

- Если исполнитель — LLM-агент →
  - Если изменение описывается одной фразой и обратимо → прямой промпт с проверкой (тест или сборка), без спецификации [S5, S38]
  - Если задача затрагивает несколько файлов или подход неясен → task spec для агента: цель, файлы и интерфейсы, out of scope, критерии как тесты, финальная e2e-проверка, свежая сессия [S5]
    - Если это новая функциональность с продуктовой неопределённостью → сначала one-pager по образцу Intermission [S13], затем spec в стиле Kiro или Spec Kit с критериями EARS или Given/When/Then и clarify до нуля маркеров [S3, S37, S40]
    - Если это баг на критическом пути → bugfix spec с фиксацией сохраняемого поведения «SHALL CONTINUE TO» [S38]
    - Если задача — интерфейс между сервисами → контракт OpenAPI или AsyncAPI первым, задача агенту ссылается на него [S34, S36]
  - Если задача операционная или аналитическая → инструкция по образцу Model Spec: иерархия инструкций, допущения и вопросы, формат вывода, 3–5 примеров, критерий остановки [S46, S50]
- Если исполнитель — разработчик или команда →
  - Если решение неочевидно или затрагивает несколько команд → design doc или RFC на 1–3 страницы с goals, non-goals, alternatives и approvers [S20, S21]
    - Если фиксируется одно архитектурное решение → ADR по MADR с полем confirmation [S24, S25]
  - Если решение очевидно → задача с критериями приёмки в Given/When/Then и общий DoD [S31, S63]
  - Если нужен API между командами → contract-first: OpenAPI, затем задачи [S34]
- Если исполнитель — сотрудник подразделения →
  - Если работа повторяемая → work instruction: шаги, инструменты, контрольные точки, ответственный [S51]
  - Если работа разовая → task brief: результат, срок, критерий «сделано», кому и как сдать (шаблон в разделе 6)
- Если исполнитель — подрядчик или партнёр →
  - Если оплата по результату или цена ошибки высока → ТЗ или SOW с deliverables, критериями приёмки, программой испытаний и актом [S52, S55, S56]
  - Иначе → бриф с deliverables и критериями приёмки без формальных испытаний [S57]
- Если аудитория — клиент →
  - Если продаётся услуга с обязательствами → SLA: SLI, целевые значения, измерение, последствия [S10, S58]
  - Если делается проект для клиента → бриф с ожидаемым результатом, критериями успеха и тем, что требуется от клиента [S57]
- Если решается «строить ли вообще» →
  - Если рынок и экономика понятны → PR/FAQ до пяти страниц FAQ и go/no-go [S16]
  - Если важнее ограничить вложение времени → pitch с appetite и no-gos [S18]
- Если работа исследовательская с высокой неопределённостью → one-pager с гипотезой, критерием остановки и сроком эксперимента; полная спецификация только после результата [S90, S93]
- Если ошибка в протоколе или распределённом алгоритме катастрофична → к технической спецификации добавить модель TLA+ как референс [S97]

## 5. Практическое применение {#practice}

### 5.1 Порядок внедрения стандарта

1. **Зафиксировать ядро полей** для всех форм: цель, границы, требования, критерии приёмки, проверка, приёмка, владелец, статус (раздел 1.1, структура в разделе 6).
2. **Выбрать формы по дереву** раздела 4 и завести по одному шаблону на аудиторию; лишние формы не заводить.
3. **Определить общий Definition of Done** организации, чтобы частные критерии не повторяли общие требования качества {факт} [S63], и словарь запрещённых слов по списку запахов требований {эмпирика} [S61].
4. **Подготовить среду для агентов:** короткий AGENTS.md или CLAUDE.md с тем, что агент не выведет из кода {вендор} [S5, S43]; детерминированные проверки как хуки, потому что инструкции в файле «совещательны», а хуки «гарантируют действие» {вендор} [S5]; contract-first для интерфейсов {факт} [S34].
5. **Ввести жизненный цикл и хранение:** спецификации рядом с кодом под контролем версий {вендор} [S38, S41], статусы и журнал изменений (раздел 6).
6. **Через месяц провести ревизию** по метрикам раздела 8 и удалить формы, которые никто не читает.

### 5.2 Жизненный цикл спецификации, которую пишет LLM под руководством человека

| Шаг | Что происходит | Опора в источниках |
|---|---|---|
| 1. Интервью | Человек даёт краткое описание; LLM «интервьюирует подробно, не задавая очевидных вопросов, копая в трудные места», затем пишет SPEC.md {вендор} [S5]. Вопросы LLM не хуже человеческих и лучше при подсказке типичных ошибок интервьюера {эмпирика} [S75] | Ограничение: без доменных чек-листов LLM выявит меньше половины неявных требований {эмпирика} [S6] |
| 2. Черновик | Заполнение шаблона формы; всё неизвестное помечается «[NEEDS CLARIFICATION]» вместо додумывания {вендор} [S3, S39] | Правило: «WHAT и WHY, не HOW» на продуктовом уровне {вендор} [S39] |
| 3. Проверка полноты и противоречий | До пяти уточняющих вопросов с записью ответов в документ {вендор} [S40]; кросс-артефактный анализ spec, plan, tasks {вендор} [S40]; прогон по запахам требований {эмпирика} [S61]; LLM-оценка по характеристикам 29148 с объяснением {эмпирика} [S77] | Золотое правило: документ понятен коллеге без контекста {вендор} [S50] |
| 4. Ревью человеком | Молчаливое чтение и обсуждение, старшие говорят последними {факт} [S17]; утверждающие названы в метаданных {факт} [S21]; тесты утверждаются человеком до реализации {вендор} [S3] | Ревью — единственный этап, где ловятся ошибки замысла {гипотеза} |
| 5. Статусы и версии | Draft → In review → Approved → In progress → Accepted → Obsolete; набор объединяет статусы шаблонов Spec Kit, HashiCorp и ADR {факт} [S21, S24, S39] | Изменения — как дельты ADDED / MODIFIED / REMOVED с последующим слиянием {вендор} [S42] |
| 6. Трассируемость | Требование прослеживается вперёд к задачам, проверкам и приёмке и назад к источнику потребности {факт} [S98]; задачи ссылаются на требования {вендор} [S2]; таблица требований связана с задачами трекера {факт} [S12]; идентификаторы FR-/SC- {вендор} [S39]; converge сверяет код с документом {вендор} [S40] | Полная трассируемость дорога; в медицинском ПО FDA фиксирует разрыв между предписанной и фактической {факт} [S98] |
| 7. Поддержание | Обновлять спецификацию при изменении кода с пересинхронизацией задач {вендор} [S38]; замораживать только при завершении кода {мнение} [S59]; «устаревшее в контексте агента неотличимо от истины» — нужны фоновые проверки дрейфа {вендор} [S89] | Без владельца шаг не выполняется {мнение} [S59] |

### 5.3 Сквозные примеры

Все числа ниже — иллюстрация, а не измерение.

**Пример A. Спецификация для агента кодирования.** Задача: экспорт отчёта по сменам в CSV в продукте управления компанией.

- **Интервью и черновик.** Владелец продукта 20 минут (иллюстрация) отвечает на вопросы LLM, LLM пишет SPEC.md на полторы страницы: цель; затрагиваемые файлы и интерфейсы; out of scope (без планировщика рассылок); шесть требований в EARS, например «When пользователь нажимает «Экспорт» с фильтром по датам, the система shall сформировать файл CSV в UTF-8 с BOM и заголовком колонок»; критерии приёмки как список тестов, включая граничный случай пустого периода; команда сквозной проверки; ссылка на CLAUDE.md с правилами репозитория.
- **Исполнение.** Агент запускается в свежей сессии, реализует, прогоняет тесты и показывает вывод; субагент-ревьюер сверяет diff со спецификацией и сообщает только пробелы, влияющие на требования {вендор} [S5].
- **Приёмка.** Человек принимает по чек-листу раздела 6 за 10 минут (иллюстрация).
- **Точка поломки.** Если в спецификации нет команды проверки, «выглядит готовым» становится единственным сигналом {вендор} [S5].

**Пример B. Задание сотруднику в поле.** Агропроизводство: проверить капельное орошение на поле № 7. Task brief, написанный LLM по шаблону раздела 6 и утверждённый агрономом: результат — заполненный чек-лист с фотографиями каждого узла; шаги (12 линий, порядок обхода, что считать дефектом); инструменты (манометр, приложение); критерии приёмки — все линии отмечены, давление в заданном диапазоне или отмечено отклонение, фото каждого фильтра; срок — до 14:00; приёмщик — агроном; способ сдачи — форма в приложении. Приёмка: агроном проверяет полноту по критериям; отсутствие фото возвращает задание. Основание формы — элементы work instruction {мнение} [S51] и простой язык без кодовых слов {факт} [S13].

**Пример C. ТЗ подрядчику с приёмкой.** Интеграция кассового ПО с учётной системой. Разделы: цели; scope и out of scope; deliverables (коннектор, документация, обучение); требования с идентификаторами; критерии приёмки на каждый deliverable с pass/fail; программа испытаний — предварительные испытания по методике, опытная эксплуатация две недели (иллюстрация) с журналом замечаний, приёмочные испытания с протоколом и актом {факт} [S55, S56]; оплата привязана к акту; процедура отказа и доработки с сроком {мнение} [S52, S53]; управление изменениями. Точка поломки: критерий «система работает стабильно» без метрики превращает приёмку в спор {гипотеза}.

**Пример D. Бриф для клиента.** Сервисный бизнес внедряет систему задач для сети ресторанов. Бриф на одну страницу: ожидаемый результат (описано словами клиента), критерии успеха (например, все смены планируются в системе к концу второго месяца — иллюстрация), что требуется от клиента (доступ, ответственный, данные), сроки и встречи приёмки, что не входит {вендор} [S57]. После запуска — SLA поддержки: показатели, окно измерения, порядок эскалации, последствия нарушения {факт} [S58].

### 5.4 Типичные ошибки первого применения

- **Шаблон инструмента принят за норму размера.** Мелкий баг оформлен как четыре истории с 16 критериями {мнение} [S4]; лечится выбором формы по дереву раздела 4.
- **Нет проверки у агента.** «Trust-then-verify gap»: правдоподобная реализация без граничных случаев {вендор} [S5].
- **Раздутый файл правил.** Важные правила теряются в шуме; сигнал — агент задаёт вопросы, ответ на которые есть в файле {вендор} [S5].
- **Критерии без pass/fail.** «Частичная приёмка» и споры о трактовке {мнение} [S53].
- **Сценарии после кода и в одиночку.** Теряется общее понимание, сценарии не отражают согласия команды {мнение} [S73].
- **Спецификация без владельца и статуса.** Документ невозможно ни обновить, ни закрыть {мнение} [S59].

### 5.5 Что происходит через месяцы

Источники показывают три траектории.

- **Дрейф.** Код меняется, документ нет, расхождение невидимо до дорогого момента {эмпирика} [S86]; ответы — пересинхронизация задач при правке спецификации {вендор} [S38] и фоновые агенты, открывающие PR с исправлением дрейфа {вендор} [S89].
- **Накопление памяти.** ADR-лог растёт, устаревшие записи остаются с пометкой superseded {факт} [S24]; design docs служат инженерам сопровождения {факт} [S20].
- **Уборка.** Команда OpenAI перешла от еженедельной ручной уборки к правилам в линтерах {вендор} [S89].

Лонгитюдных измерений эффекта стандарта спецификаций за год и более не найдено; вывод о **долгосрочной пользе** остаётся гипотезой {гипотеза}.

### 5.6 Стоимость входа

| Статья | Оценка |
|---|---|
| Время на первый черновик | PR/FAQ: «несколько часов, а не несколько дней» {факт} [S16]; design doc 1–3 страницы {факт} [S20]; one-pager Intercom — одна страница A4 {факт} [S13] |
| Время на уточнение | До пяти вопросов за цикл clarify, циклы повторяются {вендор} [S40] |
| Инструменты | Spec Kit и OpenSpec бесплатны, MIT {факт} [S65, S41]. Kiro: Free 0 $, Pro 20 $, Pro+ 40 $, Pro Max 100 $, Power 200 $ за пользователя в месяц {вендор} [S99]. Cursor: Hobby 0 $, индивидуальный тариф от 20 $, Teams 40 $ за пользователя в месяц {вендор} [S100]. Claude: Pro 20 $ в месяц, Max от 100 $, Team 20–25 $ за место; Claude Code во всех платных планах {вендор} [S101]. Цены проверены 2026-09-21 |
| Компетенции | Написание требований в EARS и Given/When/Then [S26, S31]; дизайн проверок; для агентов — context engineering {вендор} [S47]; для людей вне разработки — простой язык {факт} [S13] |

## 6. Артефакты {#artifacts}

### 6.1 Ядро полей, общее для всех форм

| Поле | Назначение | Обязательность | Основание |
|---|---|---|---|
| id, title | Уникальная ссылка для трассировки | Всегда | Нумерация ADR монотонна, номера не переиспользуются {факт} [S24] |
| owner | Один ответственный за содержание | Всегда | «Единственный автор» {мнение} [S59]; owner и approvers в метаданных {факт} [S21] |
| status | Draft, in_review, approved, in_progress, accepted, obsolete | Всегда | Статусы шаблонов [S21, S24, S39] |
| goal, context | Зачем и для кого | Всегда | Problem — «сердце документа» {факт} [S11] |
| scope, non_goals | Что внутри и что снаружи | Всегда | Non-goals и «Not doing» {факт} [S12, S20] |
| requirements[] | Атомарные требования с идентификаторами | Всегда | Singular и verifiable по 29148 {факт} [S1]; FR-001 {вендор} [S39] |
| acceptance_criteria[] | Что должно быть истинно, pass/fail | Всегда | «Как тест-кейсы» {факт} [S11] |
| verification | Как проверяется каждый критерий: тест, инспекция, измерение | Всегда | Виды испытаний {факт} [S55]; проверка для агента {вендор} [S5] |
| acceptance_procedure | Кто, когда, по какому протоколу принимает и что при отказе | Всегда | Sign-off после сравнения с ожидаемым {факт} [S54]; право отказа и доработка {мнение} [S53] |
| open_questions[] | Явная неопределённость | Пока есть | Маркеры и запрет закрывать с ними {вендор} [S3] |
| assumptions[] | Принятые допущения | По необходимости | Раздел Assumptions {вендор} [S39] |
| changelog[] | Дельты и версии | С первого изменения | Дельты ADDED / MODIFIED / REMOVED {вендор} [S42] |
| links | Родительская спецификация, задачи, проверки, акты | По мере появления | Трассируемость вперёд и назад {факт} [S98] |

### 6.2 Шаблоны по аудиториям

**Task spec для агента кодирования** (владелец: постановщик; живёт до приёмки, затем архив).

```markdown
SPEC-042: Экспорт отчёта по сменам в CSV
owner: ivanova | status: approved | parent: PRD-007
### Цель
Руководитель смены выгружает отчёт за период для бухгалтерии.
### Контекст для агента
Файлы: src/reports/shift_report.py, src/api/reports.py. Паттерн экспорта: src/reports/export_orders.py.
### Out of scope
Рассылка по расписанию; форматы кроме CSV.
### Требования
FR-1 When пользователь запрашивает экспорт с фильтром по датам, the система shall вернуть CSV в UTF-8 с BOM.
FR-2 If период пуст, then the система shall вернуть файл только с заголовком и код 200.
### Проверка
Тесты: tests/reports/test_shift_export.py (написать до реализации, убедиться, что падают).
Сквозная проверка: make e2e-export возвращает 0.
### Приёмка
Приёмщик: ivanova. Критерий: все тесты зелёные, вывод команды приложен, diff не выходит за scope.
```

Основания: самодостаточность, файлы, out of scope, e2e-шаг {вендор} [S5]; шаблоны EARS {факт} [S26]; тесты до реализации {вендор} [S3].

**Task brief для сотрудника** (владелец: руководитель; живёт до сдачи).

| Поле | Пример |
|---|---|
| Результат | Заполненный чек-лист орошения поля № 7 с фото каждого узла |
| Шаги | Обход 12 линий по схеме, замер давления, фото фильтра |
| Инструменты | Манометр, приложение, схема поля |
| Критерии «сделано» | 12 отметок, давление в диапазоне или отклонение отмечено, 12 фото |
| Срок | 14:00 сегодня |
| Приёмщик и способ сдачи | Агроном, форма в приложении |
| Что делать при отклонении | Позвонить агроному, не устранять самостоятельно |

Основания: элементы work instruction {мнение} [S51], простой язык {факт} [S13].

**Work instruction** (владелец: руководитель подразделения; ревизии по версии): идентификатор и версия, цель, область, ответственные, ресурсы и инструменты, безопасность, пронумерованные шаги с иллюстрациями, контрольные точки качества с критерием, записи, история изменений {мнение} [S51].

**ТЗ подрядчику** (владелец: заказчик; живёт до акта): цели; scope и out of scope; требования с идентификаторами; deliverables с критериями приёмки; программа и методика испытаний (предварительные, опытная эксплуатация, приёмочные), протокол и акт {факт} [S55, S56]; сроки приёмки, порядок отказа и доработки, оплата по акту, управление изменениями {мнение} [S52, S53].

**Бриф клиенту** (владелец: менеджер; согласован до старта): проблема словами клиента; ожидаемый результат; критерии успеха с измерением; что требуется от клиента; сроки и точки приёмки; что не входит; бюджет {вендор} [S57].

**SLA** (владелец: сервис; пересмотр по календарю): услуга; SLI и целевые значения; метод и окно измерения; отчётность; порядок обращения и эскалации; сроки реакции и решения; последствия нарушения; исключения {факт} [S10, S58].

**Продуктовый one-pager** (владелец: владелец продукта; живёт до решения «строить ли»): проблема со ссылками на исследования; job stories; критерии успеха; scope по релизам; open questions; одна страница {факт} [S13, S14].

**Design doc и ADR** — по шаблонам источников: context and scope, goals и non-goals, design, alternatives, cross-cutting concerns {факт} [S20]; ADR: context, decision, status, consequences, confirmation {факт} [S24, S25].

### 6.3 Чек-лист качества перед статусом approved

1. Каждое требование атомарно, проверяемо и не содержит слов из списка запахов: субъективных оценок, неопределённых наречий, «и т. д.», превосходных и сравнительных степеней, отрицаний, неясных местоимений {эмпирика} [S61].
2. Требования записаны по шаблону EARS или Given/When/Then; условие, система и отклик различимы {факт} [S26, S31].
3. У каждого требования есть критерий приёмки с pass/fail и способ проверки {факт} [S54].
4. Есть out of scope и non-goals {факт} [S20].
5. Маркеров «[NEEDS CLARIFICATION]» не осталось; открытые вопросы либо закрыты, либо отнесены к допущениям {вендор} [S3].
6. Документ понятен коллеге без контекста; для агента — не содержит того, что он выведет из кода {вендор} [S5, S50].
7. Нет противоречий между требованиями и между спецификацией, планом и задачами {вендор} [S40, S49].
8. Названы владелец, приёмщик и утверждающие {факт} [S21].
9. Размер соответствует форме: one-pager — страница, design doc — 1–3 страницы {факт} [S13, S20]; файл правил — короче 500 строк {вендор} [S45].
10. Для подрядчика и клиента: процедура отказа и доработки записана {мнение} [S53].

### 6.4 Протокол приёмки

| Поле | Содержание |
|---|---|
| spec_id, version | Что принимается |
| Дата, приёмщик, исполнитель | Кто участвует |
| Таблица критериев | id критерия → метод проверки → ожидаемое → фактическое → pass/fail → доказательство (вывод теста, фото, документ) |
| Решение | accepted, accepted_with_notes, rejected |
| Замечания и срок доработки | Для rejected и accepted_with_notes |
| Подписи или подтверждения | По правилам организации |

Пример строки: «AC-3 → прогон tests/reports → все зелёные → 14 passed → pass → лог прикреплён». Основания: процесс UAT «критерии → выполнение → сравнение → pass/fail → sign-off» {факт} [S54], протокол и акт по ГОСТ {факт} [S56].

### 6.5 Журнал изменений

Запись: version, date, author, kind (ADDED, MODIFIED, REMOVED), requirement_ids, reason, approved_by. Пример: «1.2 → 2026-09-21 → LLM-черновик, утвердила ivanova → MODIFIED FR-2 → по результату опытной эксплуатации → petrov». Дельта-формат заимствован у OpenSpec {вендор} [S42]; правило «не удалять, а помечать superseded» — у ADR {факт} [S24].

### 6.6 Машиночитаемая структура спецификации

Структура ниже — авторское предложение {гипотеза}, собранное из полей шаблонов Spec Kit (истории с приоритетами, FR-/SC-идентификаторы, маркеры), Kiro (критерии в EARS, ссылки задач на требования), OpenSpec (дельты), MADR (confirmation) и SOW (процедура приёмки) [S25, S37, S39, S42, S52]. Валидация полноты выполняется схемой JSON Schema {факт} [S35].

```yaml
spec:
  id: SPEC-042
  kind: task            # product | technical | task
  audience: agent       # agent | developer | employee | contractor | client
  title: Экспорт отчёта по сменам в CSV
  owner: ivanova
  acceptor: ivanova
  status: approved      # draft | in_review | approved | in_progress | accepted | obsolete
  version: 1.2
  parent: PRD-007
  goal: Руководитель смены выгружает отчёт за период для бухгалтерии
  scope: [экспорт CSV по фильтру дат]
  non_goals: [рассылка по расписанию, форматы кроме CSV]
  context:
    files: [src/reports/shift_report.py, src/api/reports.py]
    patterns: [src/reports/export_orders.py]
    rules: CLAUDE.md
  requirements:
    - id: FR-1
      pattern: event          # ubiquitous | state | event | optional | unwanted
      text: When пользователь запрашивает экспорт с фильтром по датам, the система shall вернуть CSV в UTF-8 с BOM
      priority: P1
      status: approved        # draft | clarify | approved | implemented | verified
      acceptance:
        - id: AC-1
          given: период содержит смены
          when: запрошен экспорт
          then: файл содержит заголовок и по строке на смену
          verification:
            method: test
            ref: tests/reports/test_shift_export.py::test_basic
          result: null        # pass | fail | null
  open_questions: []
  assumptions: [часовой пояс организации]
  e2e_check: make e2e-export
  acceptance_procedure:
    who: ivanova
    when: после зелёных тестов и приложенного вывода
    on_reject: вернуть исполнителю с перечнем провалившихся AC
  traces:
    tasks: [T-311, T-312]
    checks: [CI#8812]
    acceptance_record: null
  changelog:
    - version: 1.2
      date: 2026-09-21
      kind: MODIFIED
      ids: [FR-2]
      reason: опытная эксплуатация
      approved_by: petrov
```

Правила автоматической проверки полноты: статус approved недостижим при пустых acceptance или verification, при непустом open_questions, при отсутствии owner и acceptor; статус accepted недостижим, пока у всех AC result не равен pass; requirement.status verified ставится только по ссылке на прошедшую проверку. Для сотрудника, подрядчика и клиента структура та же, а поля context и e2e_check заменяются на tools, deliverables и test_program {гипотеза}.

## 7. С чем используется в связке {#combo}

### 7.1 Типичные комбинации

| Комбинация | Как работает вместе | Источник |
|---|---|---|
| Спецификация + Definition of Done | DoD задаёт общий порог качества, спецификация — частные критерии; не-Done не показывается на ревью | {факт} [S63]; {мнение} [S9] |
| Продуктовый документ + технический документ | PRD рождает один или несколько RFC; вопросы реализации «отклоняются в RFC» при ревью PRD | {факт} [S11] |
| Спецификация + Given/When/Then + Cucumber | Критерии становятся исполняемыми сценариями; сценарии остаются документацией | {факт} [S31]; {эмпирика} [S32] |
| Спецификация + контракт API + контрактные тесты | Спецификация ссылается на OpenAPI; провайдер и потребитель проверяются брокером, сравнивающим OpenAPI-документ с контрактом потребителя | {факт} [S34]; {вендор} [S102] |
| Task spec + AGENTS.md или CLAUDE.md + хуки | Спецификация описывает задачу, файл правил — постоянные соглашения, хуки — детерминированные проверки; правило «closest file wins» | {факт} [S43]; {вендор} [S5] |
| Спецификация + трекер задач | Требования связаны с задачами; Linear советует писать задачи как конкретную работу, а спецификацию держать на уровне проекта | {факт} [S12]; {мнение} [S60] |
| Спецификация + docs as code | Документ в системе контроля версий, plain text, ревью и автоматические проверки как у кода | {факт} [S103] |
| Спецификация + Diátaxis | Спецификация не смешивается с руководствами и справочниками: у каждого типа документации своя задача, «смешение типов вредит» | {мнение} [S104] |
| Спецификация + ADR | Решения, принятые в ходе реализации, фиксируются отдельно и ссылаются на спецификацию | {факт} [S24] |
| Спецификация поведения агента + недоверенные данные | Инструкции из документов и выводов инструментов «не имеют полномочий», если спецификация не делегирует их явно | {вендор} [S46] |

### 7.2 Что предшествует и что следует

- **Предшествует:** решение «строить ли» (PR/FAQ, pitch) {факт} [S16, S18]; исследование пользователей, на которое ссылается проблема {факт} [S11, S13]; интервью с LLM для черновика {вендор} [S5].
- **Следует:** разбиение на задачи со ссылками на требования {вендор} [S2]; тесты, утверждённые до реализации {вендор} [S3]; протокол приёмки и акт {факт} [S54, S56]; ADR по принятым решениям {факт} [S24]; при сервисе — SLA {факт} [S58].

### 7.3 Конфликты и несовместимости

- **Большая спецификация до старта против обучения по ходу.** Бек и Фаулер против допущения, что реализация ничего не меняет в спецификации {мнение} [S90]; Yeret — против возврата хэндоффов {мнение} [S91]. Совместимо только при малых, дешёвых для регенерации спецификациях {гипотеза}.
- **User stories против задач-как-работа.** Linear отвергает истории {мнение} [S60], Cohn и Jeffries защищают их как повод для разговора {мнение} [S9, S29]; выбор зависит от того, есть ли разговор.
- **Wireframes против pitch.** Детальный макет вытесняет решение команды {факт} [S18].
- **Императивный Gherkin против декларативного.** Шаги, привязанные к интерфейсу, ломаются при смене UI и превращают спецификацию в скрипт {мнение} [S31, S73].
- **Длинный файл правил против следования правилам.** Чем длиннее файл, тем чаще агент игнорирует отдельные правила {вендор} [S5]; лимит Codex 32 KiB обрезает лишнее молча {вендор} [S44].
- **Spec-as-source против ручных правок кода.** Правка кода мимо спецификации ломает модель; параллель с неудачами MDD {мнение} [S4].

## 8. Метрики здоровья и антипаттерны {#health}

| Признак | Здоровая норма | Симптом деградации | Источник |
|---|---|---|---|
| Объём продуктового документа | Intermission — одна страница A4; пресс-релиз меньше страницы, FAQ до пяти | Документ не помещается на страницу; «чем длиннее, тем меньше читают и помнят» | {факт} [S13, S17] |
| Объём технического документа | Design doc 1–3 страницы для инкремента, 10–20 для крупного проекта; ADR 1–2 страницы | Design doc для очевидного решения; ADR без consequences | {факт} [S20, S24] |
| Объём файла правил агента | Каждая строка проходит тест «без неё агент ошибётся»; Cursor — до 500 строк; Codex — 32 KiB суммарно | Агент задаёт вопросы, ответ на которые есть в файле; правила игнорируются | {вендор} [S5, S44, S45] |
| Доля требований с критерием и проверкой | 100 % требований имеют критерий pass/fail и метод проверки (ориентир) | Критерии «стабильно», «удобно», «быстро» без меры | {эмпирика} [S61]; {факт} [S54] |
| Открытые вопросы при утверждении | Ноль маркеров «[NEEDS CLARIFICATION]» в approved | Утверждение с маркерами; ответы «додуманы» исполнителем | {вендор} [S3] |
| Число уточняющих вопросов на цикл | До пяти целевых вопросов за цикл (ориентир из Spec Kit) | Десятки вопросов подряд или ни одного | {вендор} [S40] |
| Соответствие размера формы задаче | Одна фраза → промпт; несколько файлов → task spec; консенсус → design doc | Баг оформлен как четыре истории с 16 критериями | {вендор} [S5]; {мнение} [S4] |
| Проверка у агента | Агент показывает вывод теста, сборки или скриншот | «Выглядит готовым» как единственный сигнал | {вендор} [S5] |
| Дрейф спецификации и кода | Спецификация обновляется при правке кода; дельты в журнале | Документ описывает несуществующее поведение | {эмпирика} [S86]; {вендор} [S38] |
| Владелец и статус | У каждой спецификации один владелец и текущий статус | Документ без автора, статус «в работе» месяцами | {мнение} [S59]; {факт} [S21] |
| Приёмка | Протокол с pass/fail по критериям и решением | Приёмка по впечатлению, «частичная приёмка» | {факт} [S54]; {мнение} [S53] |
| Доля выявленных скрытых требований | Интервью дополнено доменным чек-листом (ориентир) | Требования всплывают на приёмке | {эмпирика} [S6, S71] |

### Антипаттерны

#### Спецификация-роман

**Как выглядит.** Тридцать страниц с историей вопроса, повторяющимися разделами и таблицами на все случаи; ревьюеры прокручивают до конца и ставят «ок»; Böckeler о сгенерированных документах: «я бы лучше ревьюила код, чем все эти markdown-файлы» {мнение} [S4].

**Почему возникает.** Шаблон инструмента заполняется целиком независимо от размера задачи; генератор не платит за длину; автор путает полноту с объёмом. Thoughtworks: «длинные spec-файлы трудно ревьюить» {мнение} [S67].

**Как чинить.** Ограничить объём формой: страница для one-pager, 1–3 страницы для design doc {факт} [S13, S20]; убрать всё, что исполнитель выведет сам {вендор} [S5]; вынести историю и альтернативы в ADR {факт} [S24].

**Когда менять практику.** Если после сокращения ревью всё ещё не читают, документ не нужен: заменить задачей с критериями и разговором {мнение} [S60].

#### Спецификация как оружие

**Как выглядит.** Документ используется, чтобы доказать вину другой стороны: «в ТЗ этого не было», «критерий трактуется иначе»; приёмка превращается в переговоры.

**Почему возникает.** Критерии субъективны и не имеют pass/fail, процедуры отказа нет {мнение} [S53]; манифест Agile ставил «сотрудничество с заказчиком выше переговоров о контракте» именно из-за этого механизма {факт} [S105]; Spolsky отмечал, что спецификация экономит на коммуникации, а не заменяет её {мнение} [S95].

**Как чинить.** Переписать критерии в измеримую форму с методом проверки {факт} [S54]; записать процедуру отказа и доработки; для внешних сторон — испытания и акт {факт} [S55, S56].

**Когда менять практику.** Если стороны не могут договориться о критериях до старта, работу нельзя начинать по этой форме; нужен эксперимент с малым бюджетом или pitch с appetite {факт} [S18].

#### Переспецификация

**Как выглядит.** Wireframes вместо проблемы, 16 критериев на мелкий баг, инструкции агенту о том, как форматировать импорты, которые он и так знает.

**Почему возникает.** Страх неопределённости и стремление контролировать решение; «wireframes слишком конкретны» и «загоняют дизайнеров в коробку» {факт} [S18, S19]; для агентов — иллюзия, что больше правил дают больше контроля, тогда как правила теряются в шуме {вендор} [S5].

**Как чинить.** Задавать проблему, appetite и no-gos, а не решение {факт} [S18]; в файле правил оставлять только то, что нельзя вывести из кода {вендор} [S5]; выбирать форму по дереву раздела 4.

**Когда менять практику.** Если исполнитель регулярно делает лучше, чем предписано, детализацию нужно снижать до уровня результата и критериев {гипотеза}.

#### Устаревшая спецификация

**Как выглядит.** Документ описывает поведение, которого в системе нет; агент опирается на него как на истину; новый сотрудник действует по устаревшему.

**Почему возникает.** Нет владельца и шага «обновить при правке» {мнение} [S59]; дрейф «невидим до дорогого момента» {эмпирика} [S86]; для агента «устаревшее неотличимо от истины» {вендор} [S89].

**Как чинить.** Хранить рядом с кодом, менять дельтами и синхронизировать задачи {вендор} [S38, S42]; фоновая проверка дрейфа и статус obsolete для того, что не поддерживается {вендор} [S89]; MADR confirmation — как проверять соблюдение {факт} [S25].

**Когда менять практику.** Если поддерживать документ дороже, чем восстанавливать знание из кода и тестов, оставить только тесты как спецификацию {мнение} [S33].

#### Приёмка без критериев

**Как выглядит.** «Покажи, что получилось» → «вроде нормально» → через неделю «это не то».

**Почему возникает.** Критерии не написаны или написаны словами «быстро», «удобно»; DoD отсутствует; приёмщик не назван.

**Как чинить.** Правило трёх частей из раздела 1.5; conditions of satisfaction на задаче и DoD на всё {мнение} [S9]; протокол приёмки раздела 6.4 {факт} [S54].

**Когда менять практику.** Если критерии невозможно сформулировать до начала работы, это исследование, а не задача: нужен эксперимент с критерием остановки {мнение} [S90].

#### «LLM написал 20 страниц»

**Как выглядит.** Человек даёт три фразы, LLM возвращает документ на 20 страниц с уверенными деталями, которых никто не просил; ревью занимает больше времени, чем написание вручную.

**Почему возникает.** Генерация дешевле проверки; узкое место сместилось к проверке правильности {мнение} [S106]; модель заполняет пробелы правдоподобным вместо маркеров неопределённости, а неявные требования всё равно выявлены меньше чем наполовину {эмпирика} [S6].

**Как чинить.** Интервью до черновика {вендор} [S5]; обязательные маркеры «[NEEDS CLARIFICATION]» и запрет додумывать {вендор} [S3]; лимит объёма по форме; трассировка каждого факта к источнику или к ответу человека {мнение} [S106].

**Когда менять практику.** Если после лимитов и маркеров документ всё равно не помещается в форму, задача неправильно нарезана: разбить на части с отдельной приёмкой {гипотеза}.

#### Спецификация без исполнителя и без владельца

**Как выглядит.** Документ существует, но никто не отвечает за его содержание и никто не назначен его исполнять; вопросы задают в чате, ответы не попадают в документ.

**Почему возникает.** Написание поручено «команде», статус не ведётся; Spolsky требовал единственного автора именно поэтому {мнение} [S59]; шаблоны RFC заводят поля owner и approvers {факт} [S21].

**Как чинить.** Поля owner, acceptor, status обязательны (раздел 6.6); документ без владельца переводится в obsolete.

**Когда менять практику.** Если владелец не находится, работа не нужна организации в текущем виде; закрыть, а не хранить {гипотеза}.

## 9. Инструменты и софт {#tools}

Раздел сжат до референсов реализации: какими сущностями управляет пользователь и что инструмент делает со спецификацией.

### 9.1 Категории

| Категория | Продукты | Что делают со спецификацией |
|---|---|---|
| Наборы SDD для агентов | Spec Kit, Kiro, OpenSpec, Tessl | Генерируют spec, plan, tasks по шаблонам, ведут гейты и проверки [S2, S3, S41, S96] |
| Файлы инструкций агентов | CLAUDE.md (Claude Code), AGENTS.md (Codex и другие), .cursor/rules | Постоянный контекст и правила репозитория [S5, S43, S44, S45] |
| Документация и трекеры | Confluence, Linear, Jira | Шаблоны PRD, связь требований с задачами, статусы [S12, S60] |
| Исполняемые спецификации и контракты | Cucumber, OpenAPI и JSON Schema с валидаторами, PactFlow | Сценарии как тесты, схемы как контракты, сравнение контрактов [S31, S34, S35, S102] |

### 9.2 Разбор ведущих продуктов

**Spec Kit (GitHub).** Сущности: constitution, spec, plan, tasks, checklists; операции: constitution, specify, clarify, plan, checklist, tasks, analyze, implement, converge; три точки входа — SDD, bugfix, assessment {вендор} [S65, S107]. Интеграции: более 30 агентов, включая Claude Code, Copilot, Cursor, Codex {вендор} [S65]. Ограничения: многословные артефакты и слабая масштабируемость по размеру задачи {мнение} [S4, S67]. Цена входа: бесплатно, MIT; 138,2 тыс. звёзд на 2026-09-21 {факт} [S65].

**Kiro (AWS).** Сущности: requirements.md, design.md, tasks.md, steering, hooks; операции: requirements-first или design-first, quick spec, refine и sync files, волны параллельных задач {вендор} [S2, S37, S38]. Ограничения: feature и bugfix specs недоступны на мобильных клиентах {вендор} [S2]; путь нельзя сменить после старта {вендор} [S38]. Цена: Free 0 $, Pro 20 $, Pro+ 40 $, Pro Max 100 $, Power 200 $ за пользователя в месяц на 2026-09-21 {вендор} [S99].

**Claude Code (Anthropic).** Сущности: CLAUDE.md, skills, subagents, hooks, plan mode, checkpoints; операции: интервью с записью SPEC.md, план до кода, проверка через тесты и скриншоты, субагент-ревьюер по PLAN.md, stop-хуки как детерминированные гейты {вендор} [S5]. Ограничения: контекстное окно как главный ресурс {вендор} [S5]. Цена: входит в Pro 20 $ в месяц, Max от 100 $, Team 20–25 $ за место на 2026-09-21 {вендор} [S101].

**OpenSpec (Fission-AI).** Сущности: specs, changes (proposal, spec deltas, design, tasks), archive; операции: explore, propose, review, apply, archive; дельты ADDED / MODIFIED / REMOVED {вендор} [S41, S42]. Ограничения: телеметрия по умолчанию с возможностью отказа, требуется Node.js 20.19+ {вендор} [S41]. Цена: бесплатно, MIT; 69,8 тыс. звёзд на 2026-09-21 {факт} [S41].

### 9.3 Что выбрать

- **Соло.** Файл правил плюс task spec в стиле Claude Code или OpenSpec; SDD-набор целиком избыточен для однострочных задач {вендор} [S5, S38].
- **Команда 5–20 инженеров.** Спецификации рядом с кодом под контролем версий {вендор} [S38, S41]; Confluence или Linear для продуктового уровня со связью в трекер {факт} [S12, S60]; contract-first для API {факт} [S34].
- **Организация до 500 человек.** Единый шаблон полей раздела 6 в трекере или базе знаний, JSON Schema для проверки полноты {факт} [S35]; SDD-наборы только там, где исполнитель — агент.

Не проверялись в этом отчёте: Notion, Jira как отдельный продукт, Swagger-инструменты сверх спецификации OpenAPI.

## 10. Адаптация под LLM и агентов {#llm}

### 10.1 LLM как автор спецификации под руководством человека

**Что спрашивать у человека.** Протокол интервью строится от результата к границам, затем к проверкам.

| Блок вопросов | Что выясняется | Основание |
|---|---|---|
| Результат и потребитель | Кто и как воспользуется результатом, что изменится | Problem как «сердце документа» {факт} [S11]; «кто клиент, какую проблему решает» {факт} [S16] |
| Границы | Что явно снаружи, чего не делать | Non-goals, no-gos, out of scope {факт} [S18, S20] |
| Трудные места | Граничные случаи, отказы, компромиссы; «не задавай очевидных вопросов, копай в трудные части» | Промпт интервью Claude Code {вендор} [S5]; extensions «что может пойти не так на каждом шаге» {факт} [S30] |
| Проверка | Как узнаем, что сделано; какая команда, тест или измерение | «Дай способ проверить» {вендор} [S5] |
| Приёмка | Кто принимает, когда, что при отказе | Sign-off и право отказа {факт} [S54]; {мнение} [S53] |
| Ограничения среды | Файлы, паттерны, инструменты, правила | Контекст в промпте {вендор} [S5]; AGENTS.md {факт} [S43] |
| Неявные требования | Что «само собой разумеется» | Главная проблема практики — скрытые требования {эмпирика} [S71]; LLM выявляет меньше половины неявных {эмпирика} [S6] |

Вопросы LLM по качеству не уступают человеческим и становятся лучше, если модели подсказать типичные ошибки интервьюера: пропуск уточнения, перегрузку, незнание домена {эмпирика} [S75]. Ограничение по объёму — до пяти вопросов за цикл с записью ответов в документ {вендор} [S40].

**Как проверять полноту и противоречия.**

1. Структурная полнота по схеме: все обязательные поля раздела 6.6 заполнены, маркеров неопределённости нет {вендор} [S3].
2. Лексическая проверка по запахам требований; детектор даёт много ложных срабатываний, поэтому список — подсказка ревьюеру, а не блокировка {эмпирика} [S61].
3. Проверка по критериям 29148 силами LLM с объяснением и предложением правки; эксперты в целом согласны с такими оценками, но требуют интеграции в процесс {эмпирика} [S77, S78].
4. Детекция неоднозначности с примерами из своего домена: 10 примеров дали +20,2 % к точности классификации {эмпирика} [S80]; от 20 проверенных человеком примеров растёт точность предсказания дефектов {эмпирика} [S79].
5. Кросс-артефактная проверка: требования против плана и задач, конфликты и пробелы, «пока артефакты дёшево править» {вендор} [S40].
6. Проверка на противоречия внутри инструкций для агента: противоречивые правила измеримо ухудшают исполнение {вендор} [S49].

**Как формулировать проверки и приёмку.** Критерий — в EARS или Given/When/Then [S26, S31]; проверка — исполняемая команда или тест, который агент запускает сам [S5]; для людей — контрольная точка с ответственным [S51]; приёмка — протокол с pass/fail [S54]. Для изменений существующего поведения — явная формула «SHALL CONTINUE TO» {вендор} [S38]. Тесты, сгенерированные LLM в Gherkin, синтаксически чисты при few-shot, но требуют проверки человеком {эмпирика} [S82].

**Чему нельзя доверять.**

- Уверенным деталям без источника: модель заполняет пробелы правдоподобным; «узкое место сместилось к проверке» {мнение} [S106].
- Полноте: неявные требования выявлены меньше чем наполовину, стилевые требования — хуже всего {эмпирика} [S6].
- Самооценке однозначности: модели не выявляют неоднозначность собственных требований и дают расходящиеся реализации {эмпирика} [S7].
- Переписанным формулировкам без валидации автора: редакции LLM оцениваются выше по ясности, но стейкхолдер должен остаться в цикле проверки {эмпирика} [S76].
- Симулированным стейкхолдерам как замене реальных: результаты LLMREI получены на симуляциях {эмпирика} [S74].

### 10.2 LLM как исполнитель

**Что нужно агенту.** Самодостаточная спецификация с файлами и интерфейсами, out of scope, финальная сквозная проверка; свежая сессия под спецификацию {вендор} [S5]. Формат — Markdown с разделами; для GPT-4.1 порядок предпочтений разделителей: Markdown, затем XML, JSON хуже на больших документах {вендор} [S48]; для Claude — XML-теги вокруг инструкций, контекста и примеров {вендор} [S50]. Инструкции «на правильной высоте»: конкретны, но не хрупки {вендор} [S47].

**Критерии приёмки как тесты.** Тест, сборка, линтер, скрипт сравнения с эталоном или скриншот; гейт остановки — в промпте, через условие цели, через stop-хук или через субагента-ревьюера, который видит «только diff и критерии» {вендор} [S5]. Spec Kit требует утверждённых человеком и падающих до реализации тестов {вендор} [S3]; converge сверяет код с документом и дописывает недостающие задачи {вендор} [S40].

**Границы контекста.** Контекст — главный ресурс: качество падает по мере заполнения, поэтому исследование выносится в субагентов, а инструкции в файле правил ограничиваются тем, что нельзя вывести из кода {вендор} [S5]; Codex обрезает файлы инструкций на 32 KiB {вендор} [S44]; Cursor рекомендует до 500 строк {вендор} [S45]; Anthropic — минимальный набор высокосигнальных токенов и подгрузку контекста по мере надобности {вендор} [S47]. В репозиториях контекстные файлы обычно единственный механизм конфигурации агента {эмпирика} [S70], а их структурное качество часто ниже порога {эмпирика} [S87]; активная проверка соблюдения правил повышает следование им {эмпирика} [S88].

**Иерархия и конфликты.** Ближайший файл правил побеждает, явный промпт перекрывает всё {факт} [S43]; для агентов вне кодирования — цепочка полномочий по образцу Model Spec, недоверенные данные без полномочий, допущения вместо молчаливого выбора {вендор} [S46]; при конфликте инструкций GPT-4.1 берёт более позднюю {вендор} [S48].

**Что остаётся человеку.** Решения «что строить» (около 70 % планировочных решений в реальных сессиях), точная постановка и исправление ошибок; агент берёт около 80 % решений «как» {эмпирика} [S84]. Утверждение тестов и спецификации, ревью замысла, приёмка по протоколу {вендор} [S3, S5]. Оговорка: эксперты в контролируемом эксперименте с ИИ работали медленнее, отчасти из-за неявных требований репозиториев, то есть именно из-за отсутствия записанной спецификации {эмпирика} [S83].

### 10.3 Машиночитаемая структура и конвейер

Структура раздела 6.6 — авторская гипотеза, собранная из полей существующих инструментов {гипотеза}. **Конвейер:** интервью → черновик по схеме → автоматическая проверка полноты по JSON Schema [S35] и по запахам [S61] → LLM-проверка по 29148 [S77] → ревью человека → approved → задачи со ссылками на требования [S2] → исполнение с тестами [S5] → converge или протокол приёмки [S40, S54] → accepted → дельты в журнал [S42]. Каждый переход статуса — проверяемое условие, поэтому конвейер годится и для агентов, и для людей {гипотеза}.

### 10.4 Риски

- **Дрейф спецификации и кода** и чрезмерное доверие сгенерированному тексту {эмпирика} [S86].
- **Многословие и усталость ревью** {мнение} [S4, S67].
- **Иллюзия контроля через правила**: правила пассивны, их соблюдение не видно без проверки {эмпирика} [S88].
- **Водопад в новой одежде**: спецификация до обучения {мнение} [S90, S91].
- **Секрет исполнения в контексте**: «чего нет в контексте агента — не существует», устаревшее неотличимо от истины {вендор} [S89].

### 10.5 Инструменты и открытые репозитории

| Репозиторий или инструмент | Что даёт | Дата доступа |
|---|---|---|
| github/spec-kit (MIT) | Шаблоны spec, plan, tasks, команды clarify, checklist, analyze, converge [S65, S39] | 2026-09-21 |
| Fission-AI/OpenSpec (MIT) | Дельта-формат и архив изменений [S41, S42] | 2026-09-21 |
| agents.md, AAIF | Формат файла инструкций и его управление [S43, S64] | 2026-09-21 |
| openai/model_spec (CC0) | Образец спецификации поведения с примерами [S46, S108] | 2026-09-21 |
| Kiro docs | EARS в критериях, bugfix-формула, best practices [S37, S38] | 2026-09-21 |
| Claude Code docs | Интервью → SPEC.md, проверки, субагент-ревью [S5] | 2026-09-21 |
| Orchid (Hugging Face) | Бенчмарк неоднозначных требований для проверки моделей [S7] | 2026-09-21 |

## 11. Происхождение, ключевые фигуры, что читать {#origins}

### 11.1 Какую боль решали и что из этого живо

| Период | Событие | Боль тогда | Что актуально сейчас |
|---|---|---|---|
| 1984 | IEEE 830 формализует SRS; в 2011 заменён ISO/IEC/IEEE 29148, редакция 2018 {факт} [S1] | Контракт между заказчиком и исполнителем при водопаде | Характеристики качества требований и структура разделов [S1, S8] |
| 2000 | Spolsky, «Painless Functional Specifications» {мнение} [S95, S59] | Программисты не пишут спецификации, дизайн рождается в коде | Единственный автор, nongoals, open issues, «объяснить один раз» |
| 2001 | Agile Manifesto {факт} [S105]; Jeffries, Card–Conversation–Confirmation {мнение} [S29] | Тяжёлые документы вместо общения | Разговор и приёмочные тесты как часть требования |
| 2003–2004 | Wake, INVEST {мнение} [S28]; Fowler, Specification By Example {мнение} [S33] | Истории без проверяемости | «Могу написать тест», примеры вместо абстракций |
| 2004 | Amazon: запрет презентаций, нарративы и PR/FAQ {факт} [S17] | Продажа вместо поиска истины на встречах | Молчаливое чтение, пресс-релиз до продукта |
| 2009 | Mavin, EARS в Rolls-Royce {факт} [S26] | Неоднозначность требований к системам управления двигателем | Пять шаблонов; встроен в Kiro [S27] |
| 2011 | Nygard, ADR {мнение} [S24]; Adzic, Specification by Example {эмпирика} [S32] | Потерянные мотивы решений; разрыв между требованиями и тестами | Малые неизменяемые записи; живая документация |
| 2019–2020 | Shape Up {факт} [S18]; описание design docs Google {факт} [S20] | Переспецификация и бесконечные проекты; консенсус в большой организации | Appetite, breadboards; goals и non-goals |
| 2021 | OpenAPI 3.1 совместим с JSON Schema 2020-12 {факт} [S34] | Расхождение схем API и данных | Контракт как машиночитаемая спецификация |
| 2024 | OpenAI публикует Model Spec, первый выпуск в мае {факт} [S108] | Непрозрачность правил поведения моделей | Иерархия инструкций, парные примеры |
| 2025 | Kiro (июль) [S66], AGENTS.md (август) [S64], Spec Kit (сентябрь) [S94], Tessl (сентябрь) [S96]; критика Böckeler (октябрь) [S4]; AAIF (декабрь) [S64] | «Vibe coding» не доводит до продакшена | Спецификация как вход агента; спор о водопаде |
| 2026 | Бек и Фаулер против допущения «ничего не узнаем при реализации» [S90]; эмпирика неоднозначности для LLM [S7, S81] | Обучение против предварительной спецификации | Малые спецификации, регенерация, проверки |

### 11.2 Ключевые фигуры

- **Joel Spolsky** — функциональные спецификации как инструмент дизайна и коммуникации [S95, S59].
- **Ron Jeffries, Mike Cohn, Bill Wake** — истории, разговор, подтверждение, INVEST, conditions of satisfaction [S29, S9, S28].
- **Alistair Cockburn** — use cases с extensions и гарантиями [S30].
- **Gojko Adzic, Martin Fowler** — specification by example и живая документация [S32, S33].
- **Alistair Mavin** — EARS [S26].
- **Michael Nygard** — ADR [S24].
- **Colin Bryar, Bill Carr** — Working Backwards и PR/FAQ [S16, S17].
- **Ryan Singer** — Shape Up, pitch и appetite [S18, S19].
- **Malte Ubl** — описание design docs Google [S20].
- **Gergely Orosz** — RFC-культуры и их каталог [S22, S23].
- **Den Delimarsky (GitHub), команда Kiro (AWS)** — spec-driven development для агентов [S94, S66].
- **Birgitta Böckeler, Kent Beck, Martin Fowler, Yuval Yeret** — критический разбор SDD [S4, S90, S91].
- **Daniele Procida** — Diátaxis как рамка, не смешивающая типы документов [S104].

### 11.3 Что читать

- Wikipedia, Software requirements specification — структура SRS и характеристики по 29148 без покупки стандарта [S1].
- Spolsky, Part 2: What's a Spec? — анатомия функциональной спецификации и правило единственного автора [S59].
- Mavin, EARS official guide — точные шаблоны пяти паттернов [S26].
- Jeffries, Card, Conversation, Confirmation — почему карточка не является требованием [S29].
- Cockburn, Use Case Template — полный набор полей use case [S30].
- Cucumber, Gherkin Reference — ключевые слова и правило «1922 год» [S31].
- Ubl, Design Docs at Google — анатомия и объём design doc, когда не писать [S20].
- HashiCorp, RFC Template и PRD Template — метаданные, статусы, связь PRD → RFC [S21, S11].
- Nygard, Documenting Architecture Decisions — формат ADR [S24].
- Working Backwards, PR/FAQ process — структура и формат встречи [S16].
- Singer, Shape Up, главы 2 и 6 — уровень абстракции и pitch [S19, S18].
- Google SRE, Service Level Objectives — SLI, SLO, SLA и бюджет ошибок [S10].
- Claude Code, Best practices — интервью, проверки, CLAUDE.md, субагент-ревью [S5].
- Spec Kit, spec-driven.md и spec-template.md — философия и поля спецификации для агента [S3, S39].
- Böckeler, Understanding SDD — трезвый разбор Kiro, Spec Kit и Tessl [S4].
- Fowler, Fragments 2026-01-08 — критика Бека и роль обратной связи [S90].
- OpenAI, Model Spec — образец спецификации поведения [S46].
- Anthropic, Effective context engineering — «правильная высота» инструкций и экономия контекста [S47].
- Femmer et al., Requirements smells — список запахов и границы автоматической проверки [S61].
- METR, Early-2025 AI study — единственное RCT о продуктивности с ИИ [S83].
- Jin et al., ReqElicitGym — где LLM-интервьюер слаб [S6].
- Yang et al., Orchid — цена неоднозначности для генерации кода [S7].

## 12. Открытые вопросы и границы уверенности {#open-questions}

### 12.1 Что не удалось проверить

- **Сборник примеров PRD Lenny Rachitsky** платный; известна только дата публикации [S15]. Версии PRD Google и Intercom из первых рук не найдены: Google — нет публичного канонического шаблона, Intercom — по вторичным пересказам [S13, S14].
- **Официальный текст ISO/IEC/IEEE 29148** не читался: страница ISO вернула 403, характеристики взяты из Wikipedia и вендорского пересказа [S1, S8].
- **Пост OpenAI «Harness engineering»** недоступен (403); использован пересказ практика, числа о строках кода и PR не приводятся [S89].
- **Отчёт EPAM о Spec Kit** недоступен (403); его числа о долях удержанного кода в отчёт не включены.
- **Текст ГОСТ 34.602-2020** недоступен: порталы .ru отказывали в соединении; структура ТЗ взята из учебных материалов и относится к редакции 1989 года, применимость к редакции 2020 не проверена [S55, S56].
- **Полные тексты большинства arXiv-статей** не читались, использованы аннотации; числа из аннотаций могут не отражать оговорки основного текста [S6, S7, S62, S71, S72, S74, S75, S76, S77, S78, S79, S80, S81, S82, S85, S86, S87, S88].
- **Полный PDF DORA 2025** не читался; использован анонс с ключевыми числами [S69].
- **Статья Uberto Barbini «SDD — новый водопад»** недоступна (403); позиция «водопада» представлена через Фаулера, Бека и Yeret [S90, S91].

### 12.2 Где источники противоречат друг другу

- **Эффект ИИ на продуктивность.** RCT METR — замедление на 19 % у экспертов [S83]; DORA — рост пропускной способности при падении стабильности [S69]; вендоры — ускорение без измерений [S2, S3]. Отчёт трактует спецификацию как стабилизатор, не как ускоритель, и это гипотеза.
- **SDD против обучения.** Сторонники обещают регенерацию по изменённой спецификации [S3, S66]; критики — потерю обучения и возврат хэндоффов [S90, S91]. Измерений ни у одной стороны нет.
- **Истории против задач.** Linear отвергает user stories [S60], Cohn и Jeffries защищают [S9, S29]; разница объясняется наличием разговора, но это вывод автора.
- **EARS.** Официальный сайт заявляет снижение ошибок, Wikipedia не находит количественных исследований [S26, S27].

### 12.3 Какие данные изменили бы выводы

- Контролируемое исследование связи «качество спецификации → результат агента» на продуктовых задачах, а не на функциях бенчмарков; Orchid и SpecFix пока функционального уровня [S7, S81].
- Лонгитюдные данные о дрейфе спецификаций и стоимости поддержания за год и более; сейчас только описания рисков [S86].
- Любая эмпирика о заданиях для сотрудников вне разработки: task brief, work instruction; найдены только консультантские структуры [S51].
- Замеры влияния маркеров неопределённости и лимита вопросов на полноту спецификаций [S3, S40].

### 12.4 Границы уверенности

**Высокая уверенность:** анатомия форм и их поля (первичные шаблоны), необходимость критериев и процедуры приёмки, ограничения длины инструкций для агентов. Средняя: дерево решений и машиночитаемая структура — авторские построения на основе шаблонов. Низкая: долгосрочный эффект стандарта спецификаций на результат работы агентов и людей — эмпирики нет.

## 13. Реестр источников {#sources}

| ID | Название | Автор или издатель | URL | Дата публикации | Дата доступа | Доступ | Что подтверждает |
|---|---|---|---|---|---|---|---|
| S1 | Software requirements specification | Wikipedia | https://en.wikipedia.org/wiki/Software_requirements_specification | без даты | 2026-09-21 | полный текст | разделы 0, 1, 2, 6, 11, 12: определение SRS, характеристики требований и структура по ISO/IEC/IEEE 29148, замена IEEE 830 в 2011, редакция 2018 |
| S2 | Specs (Kiro Docs) | Amazon Web Services, Kiro | https://kiro.dev/docs/specs/ | без даты | 2026-09-21 | полный текст | разделы 0, 1, 2, 5, 7, 9, 10, 12: три файла requirements/design/tasks, фазы, волны задач, ограничения мобильных клиентов |
| S3 | Specification-Driven Development (spec-driven.md) | GitHub, репозиторий github/spec-kit | https://github.com/github/spec-kit/blob/main/spec-driven.md | без даты | 2026-09-21 | полный текст | разделы 0, 1, 2, 4, 5, 6, 7, 8, 10, 11, 12: «код служит спецификации», маркеры NEEDS CLARIFICATION, гейты, тесты до реализации, регенерация при пивоте |
| S4 | Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl | Birgitta Böckeler, martinfowler.com | https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html | 2025-10-15 | 2026-09-21 | полный текст | разделы 0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 11: три уровня SDD, многословные артефакты, баг из 4 историй и 16 критериев, агенты игнорируют инструкции, параллель с MDD |
| S5 | Best practices for Claude Code | Anthropic, Claude Code Docs | https://code.claude.com/docs/en/best-practices | без даты | 2026-09-21 | полный текст | разделы 0–11: проверка, которую агент запускает сам; интервью с записью SPEC.md; самодостаточная спецификация; CLAUDE.md коротко; хуки; субагент-ревью; типичные провалы |
| S6 | ReqElicitGym: An Evaluation Environment for Interview Competence in Conversational Requirements Elicitation | D. Jin, Z. Jin et al., arXiv 2602.18306 | https://arxiv.org/abs/2602.18306 | 2026-02-20 | 2026-09-21 | аннотация | разделы 0, 2, 3, 5, 8, 10, 11, 12: 101 сценарий, семь моделей, меньше половины неявных требований, слабость в стилевых требованиях |
| S7 | Assessing the Impact of Requirement Ambiguity on LLM-based Function-Level Code Generation | D. Yang et al., arXiv 2604.21505 | https://arxiv.org/abs/2604.21505 | 2026-04-23 | 2026-09-21 | аннотация | разделы 0, 1, 2, 3, 10, 11, 12: бенчмарк Orchid, 1 304 задачи, неоднозначность ухудшает все модели, расходящиеся реализации |
| S8 | ISO 29148 Explained: Requirements Engineering Standard | Modern Requirements (вендор) | https://www.modernrequirements.com/blogs/iso-29148-explained/ | без даты | 2026-09-21 | полный текст | разделы 1, 11, 12: девять характеристик требования и пять характеристик набора, типы документов BRS/StRS/SyRS/SRS (пересказ вендора) |
| S9 | Clarifying the Relationship Between Definition of Done and Conditions of Satisfaction | Mike Cohn, Mountain Goat Software | https://www.mountaingoatsoftware.com/blog/clarifying-the-relationship-between-definition-of-done-and-conditions-of-sa | 2024-06-24 | 2026-09-21 | полный текст | разделы 1, 2, 7, 8, 11, 12: DoD как штамп для всех историй, conditions of satisfaction на карточке |
| S10 | Service Level Objectives (Site Reliability Engineering, глава 4) | Google, sre.google | https://sre.google/sre-book/service-level-objectives/ | 2016 | 2026-09-21 | полный текст | разделы 1, 3, 4, 6, 11: SLI/SLO/SLA, «нет последствий — это SLO», мало SLO, без абсолютов, бюджет ошибок |
| S11 | HashiCorp's PRD Template | HashiCorp | https://www.hashicorp.com/en/how-hashicorp-works/articles/prd-template | без даты | 2026-09-21 | полный текст | разделы 1, 6, 7, 10, 11: структура PRD, критерии приёмки «как тест-кейсы», связь PRD → RFC, approvals |
| S12 | Product requirements template | Atlassian Confluence | https://www.atlassian.com/software/confluence/templates/product-requirements | без даты | 2026-09-21 | полный текст | разделы 1, 5, 6, 7, 9: поля шаблона PRD, таблица требований со связью в Jira, открытые вопросы, «Not doing» |
| S13 | The Complete PRD Template Guide: 15 Templates From Top Product Teams | prodmgmt.world (вторичный сборник) | https://www.prodmgmt.world/blog/prd-template-guide | без даты | 2026-09-21 | полный текст | разделы 1–8, 10, 12: Intercom Intermission — проблема, job stories, критерии успеха, scope, одна страница A4, без дизайна решения; цитата о длине документа |
| S14 | Job Story Template by Intercom | Slab Library (по материалам Intercom) | https://slab.com/library/templates/intercom-job-story/ | без даты | 2026-09-21 | полный текст | разделы 1, 6, 12: формат job story, правило одной страницы, владелец PM |
| S15 | Examples and templates of 1-Pagers and PRDs | Lenny Rachitsky, Lenny's Newsletter | https://www.lennysnewsletter.com/p/prds-1-pagers-examples | 2021-08-31 | 2026-09-21 | фрагмент | разделы 1, 12: платный сборник примеров PRD, содержимое недоступно |
| S16 | The Amazon Working Backwards PR/FAQ Process | Working Backwards LLC (Colin Bryar, Bill Carr) | https://workingbackwards.com/concepts/working-backwards-pr-faq-process/ | без даты | 2026-09-21 | полный текст | разделы 1, 4, 5, 7, 10, 11: шесть частей пресс-релиза, внешние и внутренние FAQ, «первый черновик за несколько часов», go/no-go |
| S17 | An insider look at Amazon's culture and processes (отрывок из Working Backwards) | Amazon Staff, aboutamazon.com | https://www.aboutamazon.com/news/workplace/an-insider-look-at-amazons-culture-and-processes | 2021 | 2026-09-21 | полный текст | разделы 1, 2, 5, 8, 11: PR меньше страницы, FAQ до пяти, молчаливое чтение, старшие говорят последними |
| S18 | Shape Up, Chapter 6: Write the Pitch | Ryan Singer, Basecamp | https://basecamp.com/shapeup/1.5-chapter-06 | 2019 | 2026-09-21 | полный текст | разделы 1, 3, 4, 7, 8, 10, 11: пять ингредиентов pitch, appetite, breadboards, no-gos, «wireframes загоняют в коробку» |
| S19 | Shape Up, Chapter 2: Principles of Shaping | Ryan Singer, Basecamp | https://basecamp.com/shapeup/1.1-chapter-02 | 2019 | 2026-09-21 | полный текст | разделы 1, 4, 8, 11: «wireframes слишком конкретны, слова слишком абстрактны», rough/solved/bounded |
| S20 | Design Docs at Google | Malte Ubl, industrialempathy.com | https://www.industrialempathy.com/posts/design-docs-at-google/ | 2020-07-06 | 2026-09-21 | полный текст | разделы 1–8, 10, 11: анатомия design doc, 1–3 и 10–20 страниц, когда не писать, жизненный цикл |
| S21 | HashiCorp's RFC Template | HashiCorp | https://www.hashicorp.com/en/how-hashicorp-works/articles/rfc-template | без даты | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 6, 8, 11: разделы RFC, статусы WIP/In-Review/Approved/Obsolete, owner и approvers, «когда затрагивает многих» |
| S22 | Scaling Engineering Teams via RFCs: Writing Things Down | Gergely Orosz, The Pragmatic Engineer | https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/ | 2018-10-03 | 2026-09-21 | полный текст | разделы 1, 3, 11 (страница обновлена 2022-09-21): утверждение RFC избранными, рассылка всей организации, шум |
| S23 | Companies Using RFCs or Design Docs and Examples of These | Gergely Orosz, The Pragmatic Engineer | https://blog.pragmaticengineer.com/rfcs-and-design-docs/ | 2022-06-21 | 2026-09-21 | полный текст | разделы 1, 2, 11 (страница обновлена 2024-02-07): более 80 компаний с RFC или design doc, Meta как исключение |
| S24 | Documenting Architecture Decisions | Michael Nygard, Cognitect | https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions | 2011-11-15 | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 6, 7, 8, 11: формат ADR, статусы, 1–2 страницы, неизменяемость, монотонная нумерация |
| S25 | Architectural Decision Records (adr.github.io) | ADR GitHub organization | https://adr.github.io/ | без даты | 2026-09-21 | полный текст | разделы 1, 4, 6, 8: поля MADR, confirmation, определения AD/ASR |
| S26 | EARS: Easy Approach to Requirements Syntax (official guide) | Alistair Mavin | https://alistairmavin.com/ears/ | без даты | 2026-09-21 | полный текст | разделы 1, 2, 4, 5, 6, 10, 11, 12: шаблоны пяти паттернов, Rolls-Royce 2009, внедрившие организации |
| S27 | Easy Approach to Requirements Syntax | Wikipedia | https://en.wikipedia.org/wiki/Easy_Approach_to_Requirements_Syntax | без даты | 2026-09-21 | полный текст | разделы 1, 2, 11, 12: отсутствие количественной эмпирики, ограничения синтаксиса, интеграция в Kiro с 2025 |
| S28 | INVEST in Good Stories, and SMART Tasks | Bill Wake, xp123.com | https://xp123.com/invest-in-good-stories-and-smart-tasks/ | 2003-08-17 | 2026-09-21 | полный текст | разделы 1, 11: критерии INVEST, «обещание, что могу написать тест» |
| S29 | Essential XP: Card, Conversation, Confirmation | Ron Jeffries | https://ronjeffries.com/xprog/articles/expcardconversationconfirmation/ | 2001-08-30 | 2026-09-21 | полный текст | разделы 1, 2, 3, 4, 7, 11, 12: карточка как напоминание, разговор, подтверждение тестами |
| S30 | Use Case Template (Cockburn) | Alistair Cockburn, зеркало Univ. of Otago | https://www.cs.otago.ac.nz/coursework/cosc461/uctempla.htm | без даты | 2026-09-21 | полный текст | разделы 1, 10, 11: поля полного шаблона use case, extensions, open issues |
| S31 | Gherkin Reference | Cucumber (SmartBear) | https://cucumber.io/docs/gherkin/reference/ | без даты | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 6, 7, 9, 10, 11: ключевые слова, «1922 год», наблюдаемые исходы |
| S32 | Specification by Example (страница книги) | Gojko Adzic | https://gojko.net/books/specification-by-example/ | 2011 | 2026-09-21 | фрагмент | разделы 1, 2, 4, 7, 11: более 50 проектов, семь паттернов процесса, живая документация |
| S33 | Specification By Example (bliki) | Martin Fowler | https://martinfowler.com/bliki/SpecificationByExample.html | 2004-03-18 | 2026-09-21 | полный текст | разделы 1, 8, 11: примеры вместо абстракций, «не единственная техника», двойная проверка |
| S34 | OpenAPI Specification v3.1.0 | OpenAPI Initiative | https://spec.openapis.org/oas/v3.1.0.html | 2021-02-15 | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 7, 9, 11: определение контракта HTTP API, верхнеуровневые поля, JSON Schema 2020-12 |
| S35 | What is JSON Schema? | JSON Schema organization | https://json-schema.org/overview/what-is-jsonschema | без даты | 2026-09-21 | полный текст | разделы 1, 4, 6, 9, 10: декларативный язык структуры и ограничений, валидация, контракт |
| S36 | AsyncAPI Specification 3.0.0 | AsyncAPI Initiative | https://www.asyncapi.com/docs/reference/specification/v3.0.0 | без даты | 2026-09-21 | полный текст | разделы 1, 4: контракт для message-driven API, channels и operations |
| S37 | Feature Specs (Kiro Docs) | Amazon Web Services, Kiro | https://kiro.dev/docs/specs/feature-specs/ | без даты | 2026-09-21 | полный текст | разделы 1, 4, 6, 9, 10: критерии в EARS, requirements-first и design-first, quick spec |
| S38 | Best Practices (Kiro Specs) | Amazon Web Services, Kiro | https://kiro.dev/docs/specs/best-practices/ | без даты | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 8, 9, 10: спецификация или чат, SHALL CONTINUE TO, синхронизация, контроль версий |
| S39 | spec-kit/templates/spec-template.md | GitHub, репозиторий github/spec-kit | https://github.com/github/spec-kit/blob/main/templates/spec-template.md | без даты | 2026-09-21 | полный текст | разделы 1, 4, 5, 6, 10, 11: истории P1–P3, Independent Test, Given/When/Then, FR-001, SC-001, NEEDS CLARIFICATION |
| S40 | Agentic SDD Reference (Spec Kit Docs) | GitHub, github.github.com/spec-kit | https://github.github.com/spec-kit/reference/agentic-sdd.html | без даты | 2026-09-21 | полный текст | разделы 1, 4, 5, 6, 8, 10, 12: clarify до пяти вопросов, checklist, analyze, converge |
| S41 | Fission-AI/OpenSpec (README) | Fission-AI, GitHub | https://github.com/Fission-AI/OpenSpec | без даты | 2026-09-21 | полный текст | разделы 1, 2, 4, 5, 9, 10: specs и changes, артефакты изменения, MIT, 69,8 тыс. звёзд, телеметрия |
| S42 | OpenSpec Concepts (docs/concepts.md) | Fission-AI, GitHub | https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md | без даты | 2026-09-21 | полный текст | разделы 1, 5, 6, 8, 9, 10: RFC 2119, дельты ADDED/MODIFIED/REMOVED, архивирование |
| S43 | AGENTS.md | Agentic AI Foundation (Linux Foundation) | https://agents.md/ | без даты | 2026-09-21 | полный текст | разделы 1, 2, 5, 7, 9, 10: формат, «ближайший файл побеждает», поддержка инструментами |
| S44 | AGENTS.md (Codex agent configuration) | OpenAI, learn.chatgpt.com | https://learn.chatgpt.com/docs/agent-configuration/agents-md | без даты | 2026-09-21 | полный текст | разделы 1, 2, 7, 8, 9, 10: порядок обнаружения, лимит 32 KiB, override-файлы |
| S45 | Rules (Cursor Docs) | Cursor (Anysphere) | https://cursor.com/docs/context/rules | без даты | 2026-09-21 | полный текст | разделы 1, 2, 6, 8, 9, 10: типы правил, до 500 строк, примеры вместо кода, AGENTS.md |
| S46 | OpenAI Model Spec (2026-08-18) | OpenAI | https://model-spec.openai.com/2026-08-18.html | 2026-08-18 | 2026-09-21 | полный текст | разделы 1, 2, 4, 7, 10, 11: chain of command, допущения и вопросы, недоверенные данные, примеры compliant/violation, CC0 |
| S47 | Effective context engineering for AI agents | Anthropic Engineering | https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents | 2025-09-29 | 2026-09-21 | полный текст | разделы 1, 5, 10, 11: «правильная высота», высокосигнальные токены, примеры, just-in-time контекст |
| S48 | GPT-4.1 Prompting Guide | OpenAI Cookbook | https://developers.openai.com/cookbook/examples/gpt4-1_prompting_guide | 2025-04 | 2026-09-21 | полный текст | разделы 1, 10: буквальное следование, конфликт решается в пользу поздней инструкции, разделители, «always»-правила |
| S49 | GPT-5 Prompting Guide | OpenAI Cookbook | https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide | 2025-08 | 2026-09-21 | полный текст | разделы 1, 6, 10: противоречивые инструкции ухудшают результат, бюджет вызовов |
| S50 | Prompting best practices (Claude Docs) | Anthropic | https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices | без даты | 2026-09-21 | полный текст | разделы 1, 4, 5, 6, 10: «золотое правило», новый сотрудник без контекста, мотивация, 3–5 примеров, XML |
| S51 | Creating an Effective Work Instruction Template ISO 9001 | QMII (консалтинг) | https://www.qmii.com/creating-an-effective-work-instruction-template-iso-9001/ | без даты | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 6, 10, 12: элементы work instruction, контрольные точки |
| S52 | What Is a Statement of Work? Definition & Examples | ProjectManager.com (вендор) | https://www.projectmanager.com/blog/statement-work-definition-examples | без даты | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 6: разделы SOW, критерии приёмки с sign-off до оплаты |
| S53 | The importance of acceptance criteria in SOW projects: 5 key FAQs explained | Docue (legal-tech, вендор) | https://docue.com/en-gb/legal-hub/acceptance-criteria | 2024-10-14 | 2026-09-21 | полный текст | разделы 1, 3, 5, 6, 8, 10: право отказа, доработка, объективность критериев |
| S54 | Acceptance testing | Wikipedia | https://en.wikipedia.org/wiki/Acceptance_testing | без даты | 2026-09-21 | полный текст | разделы 1, 3, 4, 6, 7, 8, 10: определение ISTQB, процесс критерии → pass/fail → sign-off |
| S55 | ГОСТ 34: основные стандарты (учебная презентация) | present5.com (третичный) | https://present5.com/gost-34-osnovnye-standarty-gost-34/ | без даты | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 6, 8, 12: разделы ТЗ по ГОСТ 34.602, три вида испытаний по ГОСТ 34.603-92 |
| S56 | Порядок контроля и приёмки системы (пример ТЗ ИСУП) | studfile.net (учебный пример) | https://studfile.net/preview/11555201/page:12/ | без даты | 2026-09-21 | полный текст | разделы 1, 4, 5, 6, 7, 8, 12: программа испытаний, акт о завершении опытной эксплуатации, протокол и акт ввода |
| S57 | How to write a creative brief (with examples and template) | Asana (вендор) | https://asana.com/resources/how-write-creative-brief-examples-template | без даты | 2026-09-21 | полный текст | разделы 1, 4, 5, 6: девять разделов брифа, живой документ до старта |
| S58 | Service-level agreement | Wikipedia | https://en.wikipedia.org/wiki/Service-level_agreement | без даты | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 6, 7: компоненты SLA, последствия, эскалация |
| S59 | Painless Functional Specifications – Part 2: What's a Spec? | Joel Spolsky, Joel on Software | https://www.joelonsoftware.com/2000/10/03/painless-functional-specifications-part-2-whats-a-spec/ | 2000-10-03 | 2026-09-21 | полный текст | разделы 1, 3, 5, 6, 8, 11: разделы функциональной спецификации, единственный автор, nongoals, живой документ |
| S60 | Write issues not user stories (Linear Method) | Linear | https://linear.app/method/write-issues-not-user-stories | без даты | 2026-09-21 | полный текст | разделы 1, 2, 3, 7, 8, 9, 12: задача как конкретная работа, истории как «карго-культ», спецификация на уровне проекта |
| S61 | Rapid Quality Assurance with Requirements Smells | H. Femmer, D. Méndez Fernández, S. Wagner, S. Eder, arXiv 1611.08847 | https://arxiv.org/abs/1611.08847 | 2016 | 2026-09-21 | аннотация | разделы 1, 2, 5, 6, 8, 10, 11: восемь запахов, Smella, точность 59 % при полноте 82 % |
| S62 | Improving agile requirements: the Quality User Story framework and tool | G. Lucassen, F. Dalpiaz, J. M. van der Werf, S. Brinkkemper (Requirements Engineering, 2016), через Semantic Scholar API | https://api.semanticscholar.org/graph/v1/paper/DOI:10.1007/s00766-016-0250-x?fields=title,abstract,year,authors,citationCount | 2016 | 2026-09-21 | аннотация | разделы 1, 2, 12: 13 критериев QUS, AQUSA, более 1 000 историй из 18 компаний |
| S63 | The 2020 Scrum Guide | Ken Schwaber, Jeff Sutherland | https://scrumguides.org/scrum-guide.html | 2020-11 | 2026-09-21 | полный текст | разделы 1, 3, 4, 5, 7: Definition of Done, не-Done не показывают на Review |
| S64 | Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF) | Linux Foundation | https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation | 2025-12-09 | 2026-09-21 | фрагмент | разделы 2, 10, 11: AGENTS.md передан в AAIF, более 60 тыс. проектов с августа 2025 |
| S65 | github/spec-kit (README) | GitHub | https://github.com/github/spec-kit | без даты | 2026-09-21 | полный текст | разделы 2, 5, 9, 10: команды speckit, три точки входа, MIT, 138,2 тыс. звёзд |
| S66 | Introducing Kiro | Kiro (AWS) | https://kiro.dev/blog/introducing-kiro/ | 2025-07-14 | 2026-09-21 | полный текст | разделы 2, 11, 12: дата анонса, «vibe coding» против продакшена, спецификации «синхронные с кодом» |
| S67 | Spec-driven development (Technology Radar, Techniques) | Thoughtworks | https://www.thoughtworks.com/en-us/radar/techniques/spec-driven-development | 2025-11 | 2026-09-21 | полный текст | разделы 2, 3, 8, 9, 10: кольцо Assess, многословные spec-файлы, сомнение в масштабируемости |
| S68 | The New Reality of AI in Product Management | Productboard (вендорский опрос, партнёр UserEvidence) | https://www.productboard.com/blog/ai-in-product-management-report/ | 2025-10 | 2026-09-21 | полный текст | раздел 2: 379 специалистов, 94 % используют ИИ ежедневно или часто, PRD среди главных задач |
| S69 | Announcing the 2025 DORA Report | Google Cloud Blog | https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report | 2025-09-24 | 2026-09-21 | полный текст | разделы 2, 3, 12: около 5 000 респондентов, 90 % используют ИИ, пропускная способность против стабильности |
| S70 | Harness Engineering for Agentic AI Coding Tools: An Exploratory Study | M. Galster et al., arXiv 2602.14690 | https://arxiv.org/abs/2602.14690 | 2026-02-16 | 2026-09-21 | аннотация | разделы 2, 10: 2 853 репозитория, контекстные файлы как единственный механизм |
| S71 | Naming the Pain in Requirements Engineering: Contemporary Problems, Causes, and Effects in Practice | D. Méndez Fernández et al., arXiv 1611.10288 (EMSE 2016) | https://arxiv.org/abs/1611.10288 | 2016-11-27 | 2026-09-21 | аннотация | разделы 2, 3, 8, 10, 12: 228 компаний в 10 странах, неполные и скрытые требования |
| S72 | Behaviour Driven Development: A Systematic Mapping Study | L. P. Binamungu, S. Maro, arXiv 2305.05567 | https://arxiv.org/abs/2305.05567 | 2023-05-09 | 2026-09-21 | аннотация | разделы 2, 12: 166 исследований, нехватка метрик и индустриальных данных |
| S73 | Cucumber anti-patterns (part #1) | Theo England, Steve Tooke, Aslak Hellesøy, Matt Wynne, cucumber.io | https://cucumber.io/blog/bdd/cucumber-antipatterns-part-one/ | 2016-07-01 | 2026-09-21 | полный текст | разделы 2, 5, 7: сценарии после кода, в одиночку, случайные детали |
| S74 | LLMREI: Automating Requirements Elicitation Interviews with LLMs | A. Korn, S. Gorsch, A. Vogelsang, arXiv 2507.02564 | https://arxiv.org/abs/2507.02564 | 2025-07-03 | 2026-09-21 | аннотация | разделы 2, 10, 12: 33 симулированных интервью, ошибки сопоставимы с человеком |
| S75 | Requirements Elicitation Follow-Up Question Generation | Y. Shen, A. Singhal, T. Breaux, arXiv 2507.02858 | https://arxiv.org/abs/2507.02858 | 2025-07-03 | 2026-09-21 | аннотация | разделы 2, 5, 10, 12: вопросы LLM не хуже человеческих, лучше при подсказке типов ошибок |
| S76 | Supporting Stakeholder Requirements Expression with LLM Revisions: An Empirical Evaluation | M. Mircea, E. Gevrek, E. Schmid, K. Schneider, arXiv 2601.16699 (REFSQ 2026) | https://arxiv.org/abs/2601.16699 | 2026-01-23 | 2026-09-21 | аннотация | разделы 2, 10, 12: 26 участников, 130 формулировок, редакции оценены выше по однозначности |
| S77 | Leveraging LLMs for the Quality Assurance of Software Requirements | S. Lubos et al., arXiv 2408.10886 (RE 2024) | https://arxiv.org/abs/2408.10886 | 2024-08 | 2026-09-21 | аннотация | разделы 2, 5, 10, 12: оценка требований LLM по ISO 29148 с объяснением |
| S78 | DeepQuali: Initial results of a study on the use of LLMs for assessing the quality of user stories | A. Trendowicz et al., arXiv 2602.08887 | https://arxiv.org/abs/2602.08887 | 2026-02-09 | 2026-09-21 | аннотация | разделы 2, 10, 12: GPT-4o в двух малых компаниях, согласие экспертов, слабая интеграция |
| S79 | Context-Adaptive Requirements Defect Prediction through Human-LLM Collaboration | M. Unterbusch, A. Vogelsang, arXiv 2601.01952 (ICSE-NIER 2026) | https://arxiv.org/abs/2601.01952 | 2026-01-05 | 2026-09-21 | аннотация | разделы 2, 10, 12: QuRE, 1 266 требований, прирост от 20 проверенных примеров |
| S80 | Requirements Ambiguity Detection and Explanation with LLMs: An Industrial Study | S. Bashir, A. Ferrari et al., ICSME 2025 Industry Track | https://conf.researchr.org/details/icsme-2025/icsme-2025-industry-track/8/Requirements-Ambiguity-Detection-and-Explanation-with-LLMs-An-Industrial-Study | 2025 | 2026-09-21 | аннотация | разделы 2, 10, 12: +20,2 % при 10 примерах, объяснения 3,84 из 5 |
| S81 | Automated Repair of Ambiguous Natural Language Requirements | H. Jia, R. Morris, H. Ye, F. Sarro, S. Mechtaev, arXiv 2505.07270 | https://arxiv.org/abs/2505.07270 | 2025-05-12 | 2026-09-21 | аннотация | разделы 2, 11, 12: SpecFix, 43,58 % описаний, Pass@1 +30,9 % на изменённых, +4,09 % по бенчмарку |
| S82 | Comprehensive Evaluation and Insights into the Use of LLMs in the Automation of BDD Acceptance Test Formulation | S. Karpurapu et al., arXiv 2403.14965 | https://arxiv.org/abs/2403.14965 | 2024-03-22 | 2026-09-21 | аннотация | разделы 2, 10, 12: безошибочные Gherkin-тесты при few-shot, человек в контуре |
| S83 | Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity | METR | https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/ | 2025-07-10 | 2026-09-21 | полный текст | разделы 2, 10, 11, 12: RCT, 16 разработчиков, 246 задач, замедление 19 %, неявные требования репозиториев |
| S84 | How Claude Code is used in practice | Anthropic | https://www.anthropic.com/research/claude-code-expertise | 2026-06-16 | 2026-09-21 | полный текст | разделы 2, 10: около 400 тыс. сессий, 70 % решений «что» у людей, 80 % «как» у агента, успех 28 % против 15 % |
| S85 | The Productivity-Reliability Paradox: Specification-Driven Governance for AI-Augmented Software Development | Sabry E. Farrag, arXiv 2605.01160 | https://arxiv.org/abs/2605.01160 | 2026-05-01 | 2026-09-21 | аннотация | разделы 2, 12: обзор 67 источников, «дисциплина спецификации — ограничивающий фактор» |
| S86 | From Prompt to Process: a Process Taxonomy and Comparative Assessment of Frameworks Supporting AI Software Development Agents | Sanderson Oliveira de Macedo, arXiv 2606.04967 | https://arxiv.org/abs/2606.04967 | 2026-06-03 | 2026-09-21 | аннотация | разделы 2, 3, 4, 5, 8, 10, 12: шесть фреймворков, шесть измерений, дрейф спецификации и кода |
| S87 | Structural Quality Gaps in Practitioner AI Governance Prompts | Christo Zietsman, arXiv 2604.21090 | https://arxiv.org/abs/2604.21090 | 2026-04-22 | 2026-09-21 | аннотация | разделы 2, 10, 12: 34 файла AGENTS.md, 37 % ниже порога полноты |
| S88 | ZORO: Active Rules for Reliable Vibe Coding | J. Ma, S. Wang, J. H. Kung, L. B. Chilton, arXiv 2604.15625 | https://arxiv.org/abs/2604.15625 | 2026-04-17 | 2026-09-21 | аннотация | разделы 2, 10, 12: файлы правил пассивны, активная проверка повышает соблюдение |
| S89 | Harness Engineering Best Practices for Claude Code / Codex Users (пересказ поста OpenAI от 2026-02) | Sakasegawa (nyosegawa.com), вторичный | https://nyosegawa.com/en/posts/harness-engineering-best-practices-2026/ | 2026 | 2026-09-21 | полный текст | разделы 2, 5, 8, 10, 12: линтеры вместо напоминаний, «чего нет в контексте — не существует», уборка по пятницам (первоисточник недоступен: 403) |
| S90 | Fragments: January 8 | Martin Fowler | https://martinfowler.com/fragments/2026-01-08.html | 2026-01-08 | 2026-09-21 | полный текст | разделы 2, 3, 4, 7, 8, 10, 11, 12: критика Бека, обучающий цикл необходим спецификации |
| S91 | Is Spec-Driven Development a Step Forward or Back for Product Development? | Yuval Yeret | https://yuvalyeret.com/blog/is-spec-driven-development-a-step-forward-or-back-for-product-development/ | 2026-06-05 | 2026-09-21 | полный текст | разделы 2, 7, 10, 11, 12: SDD как язык высокого уровня, риски big upfront spec и хэндоффов |
| S92 | The Making of Myths | Laurent Bossavit, Model View Culture | https://modelviewculture.com/pieces/the-making-of-myths | 2014-03-17 | 2026-09-21 | полный текст | раздел 2: кривая стоимости дефекта без доказательной базы, «цитогенез» |
| S93 | Amazon's Working Backwards (mental model) | ModelThinkers (вторичный) | https://modelthinkers.com/mental-model/amazons-working-backwards | без даты | 2026-09-21 | полный текст | разделы 2, 3, 4: критика PR/FAQ при высокой неопределённости, документ как начальная гипотеза |
| S94 | Spec-driven development with AI: Get started with a new open source toolkit | Den Delimarsky, The GitHub Blog | https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/ | 2025-09-02 | 2026-09-21 | полный текст | разделы 2, 4, 11: дата запуска Spec Kit, «завершение паттернов, а не чтение мыслей», контрольные точки |
| S95 | Painless Functional Specifications – Part 1: Why Bother? | Joel Spolsky, Joel on Software | https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/ | 2000-10-02 | 2026-09-21 | полный текст | разделы 3, 8, 11: «объяснить один раз», история двух команд |
| S96 | Tessl launches spec-driven development tools for reliable AI coding agents | Tessl (вендор) | https://tessl.io/blog/tessl-launches-spec-driven-framework-and-registry | 2025-09-23 | 2026-09-21 | полный текст | разделы 4, 9, 11: spec-as-source, теги @generate, do-not-edit, закрытая бета |
| S97 | The TLA+ Home Page | Leslie Lamport | https://lamport.azurewebsites.net/tla/tla.html | без даты | 2026-09-21 | полный текст | раздел 4: TLA+ как язык моделирования, TLC и TLAPS (референс) |
| S98 | Requirements traceability | Wikipedia | https://en.wikipedia.org/wiki/Requirements_traceability | без даты | 2026-09-21 | полный текст | разделы 5, 6: трассируемость вперёд и назад, разрыв предписанного и фактического по данным FDA |
| S99 | Kiro Pricing | Amazon Web Services, Kiro | https://kiro.dev/pricing/ | без даты | 2026-09-21 | полный текст | разделы 5, 9: тарифы Free 0 $, Pro 20 $, Pro+ 40 $, Pro Max 100 $, Power 200 $ |
| S100 | Cursor Pricing | Cursor (Anysphere) | https://cursor.com/pricing | без даты | 2026-09-21 | полный текст | раздел 5: Hobby 0 $, индивидуальный тариф от 20 $, Teams 40 $ |
| S101 | Claude Pricing | Anthropic | https://claude.com/pricing | без даты | 2026-09-21 | полный текст | разделы 5, 9: Pro 20 $, Max от 100 $, Team 20–25 $; Claude Code в платных планах |
| S102 | Bi-Directional Contract Testing | PactFlow (SmartBear), вендор | https://pactflow.io/bi-directional-contract-testing/ | без даты | 2026-09-21 | полный текст | разделы 7, 9: сравнение OpenAPI провайдера и контракта потребителя брокером |
| S103 | Docs as Code | Write the Docs | https://www.writethedocs.org/guide/docs-as-code/ | без даты | 2026-09-21 | полный текст | раздел 7: документация под контролем версий с ревью и проверками |
| S104 | Diátaxis | Daniele Procida | https://diataxis.fr/ | без даты | 2026-09-21 | полный текст | разделы 7, 11: четыре типа документации, смешение типов вредит |
| S105 | Manifesto for Agile Software Development | Beck et al., agilemanifesto.org | https://agilemanifesto.org/ | 2001 | 2026-09-21 | полный текст | разделы 8, 11: «сотрудничество с заказчиком важнее переговоров о контракте» |
| S106 | AI is writing your PRDs. Who's checking if they're right? | Fathy Shalaby, DEV Community (практик) | https://dev.to/fathyshalaby/ai-is-writing-your-prds-whos-checking-if-theyre-right-37b9 | 2026-07-24 | 2026-09-21 | полный текст | разделы 8, 10: «узкое место сместилось к проверке», трассировка утверждений к источникам |
| S107 | Spec Kit Documentation (главная) | GitHub, github.github.com/spec-kit | https://github.github.com/spec-kit/ | без даты | 2026-09-21 | полный текст | раздел 9: процесс Specify → Plan → Tasks → Implement → Converge, три точки входа |
| S108 | openai/model_spec (README) | OpenAI, GitHub | https://github.com/openai/model_spec | без даты | 2026-09-21 | полный текст | разделы 10, 11: репозиторий с архивом версий и changelog, первый выпуск в мае 2024, CC0 |

## 14. Словарь терминов {#glossary}

- **Acceptance criteria** (критерии приёмки): условия с исходом pass/fail, при выполнении которых результат считается принятым.
- **Acceptance testing, UAT** (приёмочное тестирование): формальная проверка соответствия критериям приёмки с решением о sign-off.
- **ADR, Architecture Decision Record** (запись архитектурного решения): короткий документ с контекстом, решением, статусом и последствиями.
- **AGENTS.md** (файл инструкций для агентов): Markdown-файл в репозитории с командами сборки, тестами и соглашениями для агентов кодирования.
- **Appetite** (аппетит, бюджет времени): в Shape Up — сколько времени организация готова вложить, вместо оценки трудоёмкости.
- **AsyncAPI**: спецификация контрактов для message-driven API.
- **BDD, Behaviour-Driven Development** (разработка через поведение): практика описания поведения примерами Given/When/Then, исполняемыми как тесты.
- **Breadboard** (макетная схема): схематичное описание экранов и связей без визуального дизайна.
- **Brownfield** (существующая кодовая база): работа над системой, у которой уже есть код и поведение.
- **Chain of command** (цепочка полномочий): порядок приоритета инструкций в Model Spec: root, system, developer, user, guideline.
- **CLAUDE.md**: файл постоянного контекста для Claude Code, аналог AGENTS.md.
- **Conditions of satisfaction** (условия удовлетворённости): частные критерии приёмки конкретной истории по Cohn.
- **Constitution** (конституция проекта): в Spec Kit — набор неизменяемых принципов, проверяемых гейтами.
- **Context engineering** (инженерия контекста): подбор минимального набора высокосигнальных токенов в контексте агента.
- **Contract-first, design-first** (контракт первым): порядок, при котором OpenAPI или схема пишется до кода.
- **Contract testing** (контрактное тестирование): проверка совместимости провайдера и потребителя API по контрактам.
- **Definition of Done, DoD** (определение готовности): общее для всех работ формальное описание состояния «сделано».
- **Design doc** (проектный документ): технический документ с контекстом, целями, дизайном и альтернативами.
- **Diátaxis**: рамка документации из четырёх типов: tutorials, how-to, reference, explanation.
- **Docs as code** (документация как код): документация в системе контроля версий с ревью и проверками.
- **EARS, Easy Approach to Requirements Syntax** (простой синтаксис требований): пять шаблонов предложений с ключевыми словами While, When, Where, If.
- **Error budget** (бюджет ошибок): допустимая доля нарушений SLO за период.
- **Executable specification** (исполняемая спецификация): спецификация, которую можно запустить как проверку: сценарий, контракт, тест.
- **Gherkin**: язык сценариев Feature, Scenario, Given, When, Then для BDD.
- **Harness engineering** (инженерия обвязки): построение среды вокруг агента: линтеры, проверки, структура репозитория.
- **INVEST**: критерии хорошей истории: Independent, Negotiable, Valuable, Estimable, Small, Testable.
- **Job story** (история задачи): формат «When …, I want to …, so I can …» с ситуацией, мотивацией и исходом.
- **JSON Schema**: декларативный язык описания структуры и ограничений JSON.
- **Living documentation** (живая документация): документация, которая исполняется как тесты и потому не устаревает молча.
- **MADR, Markdown ADR**: шаблон ADR с decision drivers, options, outcome, consequences, confirmation.
- **MDD, Model-Driven Development** (разработка на основе моделей): подход, где код генерируется из моделей; упоминается как исторический прецедент рисков spec-as-source.
- **Model Spec** (спецификация модели): документ OpenAI об ожидаемом поведении моделей с иерархией инструкций и примерами.
- **NEEDS CLARIFICATION** (требует уточнения): маркер неопределённости в спецификациях Spec Kit.
- **Non-goals, out of scope** (не-цели): явный перечень того, что не входит в работу.
- **One-pager** (одностраничник): продуктовый документ на одну страницу с проблемой, критериями успеха и scope.
- **OpenAPI**: стандарт описания HTTP API, читаемый людьми и машинами.
- **Pitch** (питч): в Shape Up — документ с problem, appetite, solution, rabbit holes, no-gos.
- **PR/FAQ** (пресс-релиз и вопросы-ответы): документ Amazon для решения «строить ли».
- **PRD, Product Requirements Document** (документ продуктовых требований): продуктовая спецификация «зачем и что».
- **RCT, randomized controlled trial** (рандомизированное контролируемое исследование): эксперимент со случайным распределением условий.
- **Requirements smells** (запахи требований): лексические признаки дефектов: субъективные слова, неопределённые наречия, превосходные степени и подобное.
- **RFC, Request for Comments** (запрос комментариев): инженерный документ-предложение с процессом ревью и утверждения.
- **SDD, spec-driven development** (разработка через спецификацию): рабочий процесс, в котором агент получает спецификацию, план и задачи.
- **SLA, SLO, SLI** (соглашение, цель, индикатор уровня услуги): контракт с последствиями, целевое значение, измеряемый показатель.
- **SOW, Statement of Work** (описание работ): задание подрядчику с deliverables, критериями приёмки и оплатой.
- **Spec-as-source** (спецификация как исходник): подход, где поддерживается спецификация, а код генерируется.
- **Specification by example** (спецификация примерами): описание требований конкретными примерами, часто автоматизированными.
- **SRS, Software Requirements Specification** (спецификация требований к ПО): документ по IEEE 830 и ISO/IEC/IEEE 29148.
- **Steering** (направляющие правила): в Kiro — постоянные правила проекта для агента.
- **Task brief** (задание исполнителю): короткое задание с результатом, шагами, критериями «сделано», сроком и приёмщиком.
- **TLA+**: язык формальной спецификации параллельных и распределённых систем.
- **Traceability** (трассируемость): прослеживание требования назад к потребности и вперёд к задачам, проверкам и приёмке.
- **ТЗ, техническое задание**: задание на создание системы по ГОСТ 34.602 с разделом о порядке контроля и приёмки.
- **Use case** (сценарий использования): описание цели актора с главным сценарием и extensions по Cockburn.
- **User story** (пользовательская история): короткое описание потребности как повод для разговора и подтверждения тестами.
- **Vibe coding** (кодирование по наитию): работа с агентом через промпты без артефактов.
- **Work instruction** (рабочая инструкция): пошаговое описание выполнения задачи с контрольными точками.
- **Акт приёмки, протокол испытаний**: документы, фиксирующие результат приёмочных испытаний и ввод в действие.
