RDD — Readme Driven Development

Движущая сила: README/спецификация, написанная до кода, — инструмент ясности замысла и его согласования; текстовое описание продумывается и обсуждается прежде, чем пишется реализация.

Уровень применения: проект и команда (документация как дизайн).

Статус: культовый, нишевый (Tom Preston-Werner, 2010; популяризирован Заком Холманом и волной индустриальных блогов).

Не путать с: RDD — Risk Driven Development — совпадение аббревиатуры RDD, но движущая сила там — реестр рисков и вопрос «сколько архитектуры достаточно», а здесь — README как спецификация, пишущаяся до кода. Это критическая дизамбигуация: см. таблицу в разделе «Общее».

Общее #

Readme Driven Development (RDD) — практика разработки, в которой README проекта пишется до кода и выступает первичным артефактом проектирования: пока замысел не описан словами — что это, зачем, как используется, — реализация не начинается. README здесь — не «документация после» и не приложение к коду, а самая ранняя форма проектирования: текст, в котором автор вынужден сформулировать продукт с точки зрения пользователя, обнаружить пробелы замысла и согласовать его с окружением до того, как пробелы станут дорогими.

Подход сформулирован Томом Престон-Вернером (Tom Preston-Werner) — сооснователем GitHub — в эссе Readme Driven Development (tom.preston-werner.com, 23 августа 2010). Отправная точка эссе — наблюдение о маятнике эпохи: между «великим откатом» от каскадного проектирования (waterfall) и «полным принятием» Agile что-то потерялось. Каскад с его тоннами спецификаций был справедливо низложен: «громадные системы, описанные с минутной детализацией, оказывались НЕВЕРНЫМИ системами, описанными с минутной детализацией». Но освободившееся место заняла противоположная крайность — проекты с куцыми, плохими или полностью отсутствующими документами. «Идеальная реализация неверной спецификации не стоит ничего, — пишет Престон-Вернер, — и прекрасно сработанная библиотека без документации стоит примерно столько же». Средняя точка между «тоннами технических спецификаций» и «полным отсутствием спецификаций» — скромный README.

Сам выбор README как носителя — не случайность. README («прочти меня») — старейшая конвенция открытого кода: файл-введение, который читают первым (а часто — единственным), входная точка проекта и его витрина. Престон-Вернер апеллирует именно к этому статусу: README — единственный документ, который гарантированно прочитают, и потому именно он должен стать местом, где замысел живёт до кода.

Центральный императив эссе — «Write your Readme first»: README пишется первым, до кода, тестов, поведений, историй и чего бы то ни было ещё. Автор признаёт сопротивление («мы программисты, а не техрайтеры!») и отвечает на него прямо: «Пока вы не написали о своём продукте, вы не знаете, что будете кодить». Из этого императива Престон-Вернер выводит четыре преимущества:

1. Продумывание без накладных расходов. Менять текст дешевле, чем менять код: README даёт возможность перепробовать организации и публичный API без единой строки реализации. По словам автора, это то же чувство, что при первых автоматических тестах, — ошибки замысла ловятся до того, как проникли в кодовую базу.
2. Документация как побочный продукт. Чтобы понять, что реализовывать, README всё равно придётся написать; в начале проекта это делается легче — энтузиазм максимален. Ретроспективный README — «абсолютная тоска», и в нём обязательно теряются важные детали.
3. Параллелизация в команде. Определённый (пусть и не реализованный) интерфейс позволяет другим разработчикам уверенно строить интеграции до завершения проекта; без него — либо последовательное кодирование, либо переделки.
4. Конкретность обсуждения. «Бесконечно и по кругу можно только говорить; записанное решение — предмет, который можно оспаривать и итерировать». Письменная фиксация превращает спор из обмена впечатлениями в работу с текстом.

В самом эссе есть важное разграничение, которое часто теряется в пересказах: RDD — не то же самое, что Documentation Driven Development. Престон-Вернер называет RDD «подмножеством или ограниченной версией»: ограничение «единственный файл, читаемый как введение в продукт» штрафует за длинноты и избыточную точность (страховка от скатывания обратно в водопад) и одновременно вознаграждает за малые модульные библиотеки. Здесь DDD означает именно Documentation, а не Domain Driven Design — ещё одна аббревиатурная ловушка, подстерегающая читателя рядом с RDD.

Дальнейшая судьба подхода типична для «полушутливых» практик, родившихся в блогах. Зак Холман (Zach Holman, GitHub) в 2011 году закрепил тему эссе и докладами о README как витрине open source-проекта; волна индустриальных блогов (в том числе Coding Horror) разнесла формулку «README first» как самостоятельный термин. Статус RDD к сегодняшнему дню: культовый, но нишевый. У подхода нет книг, инструментов, сообществ и сертификаций уровня TDD или BDD — он и не претендует на роль методологии. Это практика-гигиена: минимальная, без инструментальной поддержки, но радикально меняющая порядок «замысел → код» и фактически ставшая нормой приличия в open source.

У подхода есть и корпоративный родственник — амазоновская практика Working Backwards (PR/FAQ): прежде чем разрабатывать продукт, команда пишет пресс-релиз и список вопросов-ответов, как если бы продукт уже вышел. Масштаб другой, механика та же: сначала текст, описывающий ценность для пользователя, потом инвестиции в реализацию.

Дизамбигуация: RDD — Readme и RDD — Risk #

Самая частая путаница в обсуждениях «RDD» — совпадение аббревиатур двух неродственных практик: Readme Driven Development (Престон-Вернер, 2010) и Risk Driven Development (Фэрбенкс, 2010) — любопытно, что оба первоисточника вышли в один год. Разведём их явно:

Подходы ортогональны и даже совместимы: можно описать продукт в README (readme-driven) и проектировать его архитектуру от реестра рисков (risk-driven) — один отвечает за «что строим», другой за «сколько проектируем». Смешивать их в одном термине нельзя: когда в обсуждении звучит «RDD», первое, что стоит уточнить, — о документации идёт речь или о рисках. Далее под RDD везде понимается Readme Driven Development.

Место в линии specification-first #

RDD полезно читать не как отдельную методологию, а как ранний, «документальный» вариант большой идеи specification-first — «спецификация прежде реализации». Каскад тоже писал спецификации до кода; новизна RDD в дозировке и адресате: спецификация сжата до одного файла и пишется для пользователя, а не для архива. Эта линия получила развитие в 2020-х: specification-driven подходы к разработке с AI (AIDD) делают Markdown-спецификации (vision.md, conventions.md, AGENTS.md) единым источником истины для человека и AI-агента. Readme-DD — исторический предшественник этой схемы: он первым сделал текстовый документ в репозитории полноценным участником процесса разработки, а не приложением к нему.

Ключевые принципы #

RDD — это не «писать документацию» (это побочный продукт), а небольшой набор принципов, меняющих порядок «замысел → код». Ниже — формулировка каждого с пояснением, какую конкретную проблему он решает.

Документ прежде кода (Readme-First). README пишется до реализации — как минимум для каждой новой библиотеки, сервиса или крупной фичи. Проблема: код, написанный первым, фиксирует замысел в самой дорогой для изменений форме; каждая передумка оплачивается рефакторингом. Текст меняется бесплатно, и первые (обычно самые резкие) колебания замысла должны происходить в нём, а не в коде.

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

Ясность через письмо (writing as thinking). Акт письма — инструмент мышления: «пока не написал — не понимаешь». Проблема: замысел, живущий в голове, кажется законченным; попытка изложить его в связный текст немедленно вскрывает пробелы — неясно, зачем, не определено, что на выходе, сценарий использования не собирается в цепочку. Тезис Престон-Вернера «пока не написал о продукте — не знаешь, что будешь кодить» — компактная форма классического принципа: нельзя описать то, чего не понимаешь, — значит, описание и есть проверка понимания.

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

Согласование на тексте. README — артефакт для обсуждения: pull request, issue, комментарий — у текста есть адресат и есть механизм фидбека. Проблема: устные договорённости бесформенны и бесследно мутируют («мы договаривались о другом»); каждый участник спорит с собственной версией замысла. Записанный текст делает разногласия видимыми и локализуемыми — спор идёт о конкретных строках, а не о воспоминаниях.

README — самый важный документ кодовой базы. По Престон-Вернеру, написание README — «истинный акт творения», в котором должны быть выражены лучшие идеи проекта; всё остальное (код, тесты) — производное. Проблема: в культуре, где документация пишется «если останется время», README получается служебным и лживым. Переворот иерархии — README важнее кода, потому что код под него подстраивается — и есть смена парадигмы, которую требует подход.

Живой документ. README обязан меняться вместе с продуктом; изменилось поведение — изменился документ, в том же коммите. Проблема: устаревший README хуже отсутствующего — он уверенно лжёт, и читатель (включая самого автора через полгода) не может отличить правду от археологии. Актуальность — не пожелание, а условие существования практики: README, которому не уделяется внимания, дискредитирует саму идею «документ прежде кода».

Принципы — система, а не меню: Readme-First без «разговора с пользователем» даёт техническое ТЗ; разговор без ограничения «один файл» дрейфует к водопаду; согласование без живого документа даёт разовый ритуал, дискредитирующий подход через квартал. Частичное внедрение создаёт видимость документации; полное — меняет порядок рождения продукта.

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

RDD исполняется как короткий повторяющийся цикл, а не разовый ритуал «написал и забыл». Виток цикла:

1. Напиши README. Опиши замысел с точки зрения пользователя: что это, зачем, какую проблему решает, как выглядит типичное использование, чего сознательно нет. Никакого кода — только текст.
2. Обсуди. Дай текст прочит тем, кто будет пользоваться, интегрироваться и поддерживать продукт: коллегам, стейкхолдерам, будущим пользователям (в open source — просто опубликуй). Фидбек до кода — самый дешёвый фидбек в проекте.
3. Уточни. Внеси правки по замечаниям; нестыковки, вскрытые при обсуждении текста, исправляются минутами правки — а не неделями рефакторинга, как те же нестыковки, пойманные в коде.
4. Реализуй под документ. Код пишется так, чтобы README стал правдой. Документ здесь играет роль спецификации приёмки: не описано — не делается; понадобилось что-то новое — сначала дополни README, потом код.
5. Поддерживай актуальным. Любое изменение поведения начинается с правки README — в том же pull request, что и код. Ревьюер видит сначала изменение документа и только затем реализацию.

Тот же цикл графически:

   ┌───────────────────────────────────────────────────────────────────┐
   ▼                                                                   │
┌────────────┐    ┌────────────┐    ┌────────────┐    ┌───────────────┴┐
│   Напиши   │    │   Обсуди   │    │  Уточни    │    │   Реализуй     │
│   README   │ →  │ (фидбек до │ →  │  документ  │ →  │ строго под     │
│ (что/зачем/│    │   кода)    │    │ до ясных   │    │ документ       │
│  как/нет)  │    └────────────┘    │ формулировок│   └───────┬────────┘
└────────────┘                      └────────────┘            │
      ▲                                                       │
      │      ┌────────────────────────────────────────────────┘
      │      ▼
      │   ┌──────────────────────────────────────┐
      └───┤ Поддерживай актуальным: изменилось   │
          │ поведение — правь README в том же PR │
          └──────────────────────────────────────┘

Скелет README #

Практический минимум структуры — четыре вопроса, на которые README обязан ответить: что это, зачем оно, как этим пользоваться и чего здесь нет. Скелет:

# <Название>

Одно–два предложения: что это и для кого. Если не получается — замысел не созрел.

## Зачем
Какую проблему решает; чем отличается от ближайших альтернатив.

## Установка
Минимальная последовательность шагов от «нашёл проект» до «запустил».

## Использование
Два–три типовых сценария: команды/код и ожидаемый результат.

## Ограничения
Что проект сознательно НЕ делает (out of scope) —
чтобы читатель не додумал отсутствующее.

## Контакты / Лицензия
Куда задавать вопросы; условия использования.

Мини-пример README для гипотетической CLI-утилиты csvsum (сумма и статистика по колонкам CSV):

# csvsum — быстрая статистика по CSV из командной строки

Считает сумму, среднее и медиану по указанной колонке CSV-файла,
не загружая файл в память. Для аналитиков и инженеров, живущих в терминале.

## Зачем
`awk` неудобен для нецелых чисел и кодировок; Excel требует открытия файла.
csvsum работает с файлами любого размера и корректной национальной
кодировкой (UTF-8, разделитель — автоопределение).

## Установка
    pip install csvsum

## Использование
    csvsum sales.csv --column amount --stats sum,median
    csvsum data.csv --column city --stats count --group

## Ограничения
Только чтение: csvsum не изменяет файлы. Только CSV; XLSX не поддерживается.

Обратите внимание: из такого README уже видно API (команды и флаги), целевую аудиторию, границы — и всё это до единой строки кода. Если во время обсуждения выяснится, что «медиана по группам» не нужна, а «экспорт в JSON» нужна, — изменения стоят минуты правки текста.

Как проверить, что README получился #

Быстрая проверка по маркерам — чем больше «да», тем выше качество документа и тем выше шанс, что замысел действительно созрел:

• Человек, не видевший проект, отвечает по одному README на вопросы: что это, кому и зачем; как запустить; как решить свою типовую задачу.
• Первые два абзаца не про архитектуру и не про процесс сборки, а про ценность для пользователя.
• Каждый сценарий использования самодостаточен: команда/вызов и ожидаемый результат, которые можно скопировать.
• Явно перечислено, чего проект не делает, — читателю не нужно додумывать границы.
• Документ читается за пять минут; если он не влезает в «один экран прокрутки плюс примеры» — это сигнал перегруженности продукта (см. принцип «один файл как ограничение»).
• Все формулировки, за которые «стыдно» (размытое «удобный инструмент для работы с данными»), вскрылись ещё при письме — а не на ревью.

Обратный маркер тоже информативен: если README невозможно написать не потому, что автор «не техрайтер», а потому что вопросы «зачем» и «что на выходе» не имеют ответа, — практика сработала именно так, как задумана: она вскрыла незрелость замысла до того, как тот оплатил себя кодом.

Процессная обвязка #

В командной практике цикл обычно оформляют так: pull request с README открывается до (или одновременно с) PR с реализацией; ревью текста происходит раньше и тщательнее ревью кода — спор о замысле на этом этапе дешевле спора об реализации. Изменение существующего поведения оформляется зеркально: сначала PR с правкой README («что меняем и зачем»), затем — PR с кодом. Полезный диагностический признак: если README «не пишется» — сыпется на глазах, формулировки не сходятся — проблема не в навыке техрайтера, а в замысле; это фича процесса, а не его сбой.

Влияние на команду и процесс #

RDD часто подают как личную привычку разработчика. Это сужение: устойчивый эффект возникает, когда README-первость встроена в командный процесс. Ниже — что именно меняется. Этот блок адресован прежде всего руководителям.

README как артефакт согласования. Самая дорогая работа с замыслом — не «написать», а «согласовать»: стейкхолдеры, смежные команды и будущие пользователи должны понять и принять одно и то же. README даёт для этого носитель: короткий, читаемый нетехническими участниками и версионируемый текст. Проблема, которую решает: согласование «на встрече» не оставляет артефакта — решения живут в протоколах чатов и памяти участников; README превращает согласование в проверяемый факт с историей изменений.

Параллелизация работ. Тезис Престон-Вернера из первоисточника: пока интерфейс определён (в README), другие разработчики и команды могут уверенно строить интеграции, не дожидаясь реализации. Без определённого интерфейса работы вынужденно последовательны — либо команды дублируют и переделывают друг друга. Для распределённой организации это прямой выигрыш в календаре: зависимые потоки стартуют по тексту, а не по факту релиза.

Онбординг и bus factor. README — первый документ, который читает новый участник; его качество определяет скорость входа в проект. Живой, пользовательски написанный README заменяет часы «устного вводного курса» и снижает зависимость от носителей негласного знания. В терминах менеджмента: документация — это страховка bus factor, и RDD делает её свежей по построению (см. ниже о рисках рассинхронизации).

Связь с AIDD: specification-first. Общий знаменатель двух подходов — принцип «спецификация прежде реализации». Readme-DD — ранний, «документальный» вариант этой идеи; AIDD — её современное развитие, где Markdown-спецификации (vision.md, conventions.md, правила для агентов) становятся единым источником истины для человека и AI. Практическая стыковка: README, написанный до кода, — готовый контекст для AI-агента; команда, привыкшая к Readme-DD, осваивает AIDD без культурного слома — текст уже первый класс гражданина процесса.

Связь с ADR. README фиксирует «что и зачем» — внешний облик продукта для пользователя; ADR фиксирует «почему принято такое решение» — внутренние технические выборы. Артефакты не конкурируют, а образуют каркас: README отвечает на вопрос пользователя, ADR — вопрос будущего инженера. Команда, практикующая RDD, естественно дорастает до ADR: привычка «сначала опишем» переносится с продукта на решения.

Definition of Ready для фич. В терминологии Agile-процессов Readme-DD поднимает планку готовности задачи: фича считается готовой к реализации, когда у неё есть согласованный README (или раздел README), а не «описание в тикете на две строки». Это естественная точка стыковки с SDLC: README-фаза — компактная, но обязательная часть фазы требований, повторяемая на каждой итерации.

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

Признаки здоровья практики. Как понять, что Readme-DD в команде прижился, а не выродился в ритуал: время онбординга нового участника до первой осмысленной задачи сокращается; доля PR, меняющих наблюдаемое поведение без правки README, стремится к нулю; входящие вопросы «а как этим пользоваться» уходят из чатов в issues к документу; README обсуждается на ревью содержательно (спор о формулировках), а не формально (аппрув без чтения). Обратные значения тех же метрик — ранний сигнал README-theatre.

Преимущества #

Раннее согласование. Все дорогие несогласовенности — «я не это имел в виду», «пользователю нужно другое» — вскрываются на тексте, минутами правки, а не на коде, неделями переделок. Фидбек до реализации — самый дешёвый фидбек в проекте; RDD делает его систематическим.

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

Живой онбординг. README, написанный до кода и поддерживаемый актуальным, — самая честная документация проекта: он описывает продукт с точки зрения пользователя и не успевает «остыть». Новый участник и новый смежник входят в проект через один и тот же документ.

Меньше «спрятанной» функциональности. Дисциплина «не описано — не делается» отсекает два хронических явления: фичи, сделанные «по дороге» и никем не заказанные, и фичи, сделанные, но не доведённые до пользователя (о них просто никто не знает). README — публичный реестр того, что продукт умеет; всё вне его — официально не существует.

Документация как побочный продукт. Классическая боль «документировать некогда и лень» снимается переупорядочиванием: README пишется в момент максимального энтузиазма и минимальной затраты усилий (всё уже продумано), а не постфактум, когда интерес угас и детали забыты.

Витрина для open source. README — первая страница проекта: по нему принимают решение «использовать/не использовать» и «вкладываться/не вкладываться». Readme-First гарантирует, что эта страница пишется о живом замысле, а не реконструируется из кода задним числом.

Недостатки и риски #

Рассинхронизация «доки vs код». Главный риск: README, однажды написанный, дрейфует от реальности — поведение поменяли, текст забыли. Устаревший README хуже отсутствующего: он уверенно лжёт читателю. Механизм защиты — процессный (правка README в том же PR, что и код), и он требует дисциплины; без неё практика дискредитирует сама себя.

Накладные расходы поддержки. README — полноценный артефакт с собственной стоимостью: его ревьюят, правят, синхронизируют. Для каждого нового поведения текст и код меняются вместе — это постоянные (малые, но ненулевые) расходы, которые нужно принять, а не «оптимизировать» отменой документа.

Риск «доки ради доки» (README-theatre). Вырожденная форма: README пишется ради ритуала — шаблонно, без пользовательского взгляда, никем не читается и не обсуждается. Симптом: документ описывает структуру репозитория и процесс сборки, но не отвечает на вопросы «зачем» и «как использовать». Формально практика соблюдена, ценность — нулевая; как и в случае «TDD-theatre», это вопрос понимания сути, а не синтаксиса.

Не заменяет полноценное проектирование. README — спецификация продукта для пользователя; он не покрывает нефункциональные требования (нагрузка, безопасность, доступность), архитектурные решения и внутренние контракты. Команда, ограничившая проектирование README, получит ясный фасад при непрояснённой внутренности. Для глубины нужны другие артефакты: ADR для решений, риск-реестр для уязвимостей (RDD — Risk Driven Development).

Иллюзия полноты. Хороший README создаёт чувство «всё продумано» — но текст проверяет лишь связность замысла на уровне пользователя, не реализуемость. Команда может гладко согласовать то, что не построено или построено втрое дороже ожиданий. README снижает риск неверного понимания, но не риск неверной оценки.

Культурное сопротивление. «Мы программисты, а не техрайтеры» — сопротивление, на которое Престон-Вернер отвечал в первом же абзаце. Навык пользовательского письма у инженеров развит неравномерно; без примеров, шаблонов и ревью текста первые README получаются служебными, и практика не приживается. Внедрение требует обучения и примеров, а не приказа.

Когда использовать #

• Новые проекты и новые крупные фичи. Момент, когда замысел ещё пластичен и дешевле всего меняется текстом; README фиксирует и согласует его до того, как он затвердеет в коде.
• Open source. README — витрина проекта: по нему судят о пользе, читают примеры и решают, вкладываться ли. Писать его первым — естественно; писать последним — поздно.
• API, SDK и библиотеки. Продукт здесь — интерфейс; README с примерами использования и есть его ранняя форма. Не описывается компактно — сигнал перегруженного API (см. принцип «один файл как ограничение»).
• Команды с распределёнными стейкхолдерами. Согласовать замысел между людьми в разных часовых поясах проще через версионируемый текст, чем через встречи; README даёт асинхронный формат согласования с историей.
• Как инструмент разрешения споров о форме фичи. Когда обсуждение «что делаем» ходит по кругу, перевод спора в правки конкретного текста — самый короткий путь к сходимости.

Быстрая проверка по маркерам: чем больше пунктов ниже описывает вашу ситуацию, тем выше ожидаемая отдача от Readme-DD.

• Замысел ещё не зафиксирован: продукт/фича существуют в разговорах и голове, а не в тексте.
• У продукта будет больше одного читателя README: пользователи, смежные команды, открытый мир.
• Несколько стейкхолдеров должны сойтись в понимании «что и зачем» — до того, как оплачена реализация.
• Продукт — библиотека, API, SDK или open source-инструмент: интерфейс и есть продукт.
• Команда распределена: согласование по тексту асинхроннее и дешевле встреч.
• В проекте уже болит онбординг: новые участники входят долго и через «устный курс».

Когда НЕ использовать #

• Exploratory-разработка и прототипы. Когда цель — проверить гипотезу и, возможно, выбросить код, писать README — формальность: замысел принципиально не устоялся, и текст будет переписываться вслед за каждой итерацией исследования. Сначала — гипотеза и прототип; README — когда (и если) выживет.
• Тривиальные правки. Багфикс, рефакторинг, обновление зависимости: замысел не меняется, README уже существует и остаётся верным. Разовая правка «сначала README» здесь — процессный шум.
• Жёсткие неопределённость и дедлайн одновременно. В режиме, когда неизвестно, что получится, а времени на согласование нет, README-фаза выродится в ритуал «написали для галочки и пошли кодить». Честнее признать режим и вернуться к документу, когда схлынет.
• Документирование вместо решения. Если README пишется третий раз, а замысел всё равно не сходится, — проблема не в тексте, а в отсутствии решения или в его неопределённости. Здесь нужны разговор со стейкхолдерами или прототип, а не четвёртая версия документа.

Обратный набор маркеров — чем больше совпадений, тем вероятнее, что README-фаза выродится в формальность:

• Горизонт работы — дни, а исход неизвестен: исследовательский прототип, хакатон, одноразовый скрипт.
• Правка локальна и не меняет наблюдаемое поведение: багфикс, рефакторинг, обновление зависимостей.
• У документа нет читателя кроме автора: внутренний скрипт в одном экземпляре пользователя.
• Спор идёт не о замысле, а о реализации — текст здесь ничего не разведёт, нужны тесты или прототип.
• Процессом управляет паника дедлайна: документ будет написан «для галочки» и забыт в момент первого аврала.

Связанные подходы #

RDD — один из материалов серии о driven-подходах; за разными аббревиатурами стоят разные «движущие силы» (документация, тесты, поведение, домен и т. д.). Ниже — карта родственных подходов со ссылками на опубликованные статьи базы знаний.

Полный обзор и сравнение всех driven-подходов — в статье Driven-подходы: сравнение.

• AIDD — AI-Driven Development — ближайший идейный наследник: specification-first как общий знаменатель; Markdown-спецификации (vision.md, conventions.md) становятся единым источником истины для человека и AI-агента. Readme-DD — ранний, «документальный» вариант той же идеи.
• BDD — Behaviour Driven Development — общая тема «спецификация прежде реализации» с другим носителем: BDD делает спецификацию исполняемой (сценарии Given-When-Then), RDD — читаемой и согласуемой (текст). Подходы дополняют друг друга: README задаёт контекст и границы фичи, сценарии — её поведение.
• Risk-DD — Risk Driven Development — тёзка по аббревиатуре (см. дизамбигуацию в разделе «Общее»). Ортогонален и совместим: README отвечает «что строим», реестр рисков — «сколько проектируем».
• CDD — Contract Driven Development — спецификация границы между сервисами; в отличие от README, контракт исполняем и проверяется автоматом в CI обеих команд.
• TDD — Test Driven Development и Type-TDD — Type Driven Development — верификаторы уровня кода; логично следуют за README: текст согласует «что», тесты и типы страхуют «как».
• ADR — фиксация «почему» технических решений; README (что и зачем для пользователя) и ADR (почему выбрана такая реализация) образуют документационный каркас проекта.
• SDLC — README-фаза как компактная часть фазы требований, повторяемая на каждой итерации жизненного цикла.
• Правило бойскаута — принцип поддержания README актуальным: заметил расхождение — исправь в том же PR.

Удобный способ читать всю серию — сравнивать движущие силы. Тесты (TDD), типы (Type-TDD) и контракты (CDD) — артефакты-верификаторы: они проверяют уже принятое решение. Домен (DDD) и поведение (BDD) — источники содержания: они говорят, что именно строить и каким языком это описывать. Риск (Risk-DD) измеряет цену ошибки и дозирует проектирование. Документация занимает в этом ряду место входа: README — самый ранний и самый дешёвый артефакт, в котором замысел вообще может существовать; все остальные движущие силы подключаются к уже описанному (или заставляют описать то, что без них пытались строить вслепую).

Краткий вердикт для руководителя #

RDD — это инвестиция в ясность замысла до кода, а не в «документацию» как таковую. Эффект: раннее согласование, меньше переделок, дешёвый онбординг, публичный реестр функциональности и готовая культура specification-first для AI-эпохи. Цена: дисциплина поддержания текста в актуальном состоянии, накладные на совместные правки кода и документа, риск ритуализации. Берите, если создаёте новый продукт, библиотеку, API или open source-проект, если стейкхолдеры распределены и замысел ещё пластичен. Не берите, для exploratory-прототипов, тривиальных правок и команд, где документация заведомо нежизненна без изменений культуры. Минимум, который стоит забрать даже без полного внедрения, — привычка отвечать письменно на вопросы «что именно строим и зачем» до того, как оплачена первая строка реализации.

Источники и материалы #

Первоисточники и ключевые публикации #

• Tom Preston-Werner. Readme Driven Development (tom.preston-werner.com, 23 августа 2010) — фундаментальный первоисточник: тезис «Write your Readme first», четыре преимущества, разведение с Documentation Driven Development.
• Jeff Atwood. Readme-Driven Development (codinghorror.com) — популяризация подхода в индустриальном блоге.
• Zach Holman. Readme Driven Development (zachholman.com, ~2011) — эссе и доклады, закрепившие практику в культуре open source; README как витрина проекта.
• Colin Bryar, Bill Carr. Working Backwards: Insights, Stories, and Secrets from the Most Powerful Retailer on Earth. Portfolio, 2021 — амазоновская практика PR/FAQ как корпоративный аналог «текст прежде кода».
• Обзоры Specification-Driven Development / SpecDD — современное развитие линии specification-first, к которой восходит Readme-DD.

Связанные материалы базы знаний #

• AIDD — specification-first для AI-разработки; Readme-DD как ранний «документальный» вариант идеи.
• ADR — фиксация архитектурных решений; каркас «README + ADR» для документации проекта.
• SDLC — место README-фазы в жизненном цикле.
• BDD — Behaviour Driven Development — общая тема «спецификация прежде реализации»: исполняемые сценарии против читаемого текста.
• RDD — Risk Driven Development — тёзка по аббревиатуре; дизамбигуация обязательна при любом использовании «RDD».
• Правило бойскаута — поддержание README актуальным как коллективная дисциплина.