Мой дэйли дайджест

одно техническое понятие в день

README

1 августа 2026 · ~11 мин чтения

стандарт документация open-source markdown соглашение

README

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

История

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

Точную «нулевую» дату назвать сложно, потому что практика родилась в
нескольких местах одновременно, ещё в 1970-х. Одно из самых ранних
задокументированных употреблений — исходники игры Colossal Cave Adventure
Уилла Кроутера (1975–1976): в дистрибутиве был текстовый файл-объяснение.
В том же десятилетии в системах PDP-10 / TOPS-20 и в проектах
Массачусетского технологического института файлы с именем READ.ME,
README и README.1ST уже были нормой — их размещали вместе с исходным
кодом и текстовыми документами, потому что операционные системы того
времени часто выводили содержимое каталога в алфавитном порядке, и файл на
букву R располагался так, чтобы его было видно рядом с исходниками. По
одной из версий, ЗАГЛАВНЫЕ буквы использовали, чтобы имя всплывало наверху
в системах, где заглавные сортировались раньше строчных.

В 1980-х README закрепился в мире Unix и в дистрибутивах программного
обеспечения на дискетах — почти каждая коробка с ПО содержала README.TXT
или README.1ST с известными проблемами и последними изменениями,
которые не успели попасть в печатную инструкцию. В сообществе GNU (проект
Ричарда Столлмана, начат в 1983 году) README стал обязательным элементом
исходников каждого пакета: соглашение GNU Coding Standards прямо предписывает
его наличие рядом с INSTALL, NEWS и COPYING.

В 1990-х вместе с массовым open source (Linux, Perl, Python, потом PHP,
Ruby, Node.js) README стал канонической первой точкой контакта с проектом.
А в 2004 году Джон Грубер выпустил Markdown — лёгкий язык разметки,
который позволил писать README не только со списками и заголовками, но и
с картинками, ссылками, кодом. С этого момента README.md начал вытеснять
README.txt.

Финальную кристаллизацию README как стандарта совершил GitHub (запущен
в 2008 году): страница любого репозитория стала автоматически рендерить
README.md прямо под списком файлов. Это одно решение поменяло всё: теперь
README читал не разработчик, скачавший архив, а любой человек, случайно
открывший ссылку в браузере. README из «примечания к дистрибутиву»
превратился в лендинг проекта.

Дальше — экосистема повторила паттерн. npm (2010), PyPI,
RubyGems, crates.io, Docker Hub — все стали брать README из
пакета и показывать его на публичной странице пакета. Появились
соглашения-стандарты (Standard Readme, 2017) и обширные списки лучших
практик (Awesome README).

Что это такое

README — это файл в корне репозитория (или папки), назначение которого —
дать первому читателю всё, что нужно, чтобы:

  1. За 5–10 секунд понять, что это за проект.
  2. За минуту понять, стоит ли ему разбираться дальше.
  3. За 5–15 минут запустить, попробовать или начать пользоваться.
  4. Найти дорогу к остальной документации, если она нужна.

Формально README — это просто текстовый файл. Технически файл может
называться как угодно, но по традиции — README, README.md, README.txt,
README.rst, реже README.adoc. Регистр обычно верхний. Расширение
подсказывает разметку: .md — Markdown, .rst — reStructuredText (Python),
.adoc — AsciiDoc, без расширения — plain text.

Ключевое отличие от полноценной документации — жанр. README не
претендует на исчерпывающий справочник. Это витрина и точка входа. Полная
документация — на сайте (Docusaurus, mkdocs, Read the Docs, Notion) или в
папке docs/. README только знакомит и провожает.

Часто рядом с README живут его «спутники» — файлы того же жанра, но с
более узким назначением: LICENSE (лицензия), CONTRIBUTING.md (как
внести вклад), CHANGELOG.md (что менялось от версии к версии), CODE_OF_CONDUCT.md
(правила общения в проекте), SECURITY.md (как сообщать об уязвимостях).
README на них ссылается.

README vs документация: README — «здравствуй, посетитель», документация —
«вот справочник, читай главами». Смешивать плохо: раздутый README теряет
функцию точки входа, а разросшийся до 20 экранов файл никто не читает
целиком.

README vs комментарии в коде: комментарии объясняют «как» и «почему»
на уровне строки, README — «что» и «зачем» на уровне проекта.

Аналогии из жизни

Табличка в подъезде «Уважаемые жильцы». Первое, что видит человек,
войдя. Кратко, по делу, с телефонами кому звонить если что. Где ломается:
на табличке нельзя запустить приложение или скопировать команду; README —
интерактивнее и живёт вместе с проектом, обновляется вместе с ним.

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

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

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

Механически README — обычный файл. Ни на компиляцию, ни на запуск проекта
он не влияет. Всё, что вокруг него происходит, — это соглашения
инструментов, которые его находят и показывают.

Пошагово, что случается, когда ты пушишь README.md в репозиторий на
GitHub:

  1. Ты создаёшь файл в корне (или в любой папке).
  2. GitHub при рендере страницы каталога ищет по регулярному выражению
    файл с именем readme (регистр не важен) и одним из известных
    расширений: .md, .markdown, .mkd, .txt, .rst, .adoc, без
    расширения. Если файлов несколько, .md побеждает.
  3. Найденный README пропускается через рендер разметки (для .md — это
    вариант GitHub Flavored Markdown, GFM, — расширенный Markdown с
    таблицами, чекбоксами и ~~зачёркиванием~~).
  4. Полученный HTML вставляется в страницу репозитория ниже списка файлов.
  5. Ссылки внутри README, ведущие на относительные пути, GitHub
    автоматически превращает в ссылки внутри репозитория; картинки — тоже.

Похожая логика в остальных экосистемах, только вместо страницы репо —
страница пакета:

Структура «хорошего» README — не жёсткий стандарт, а сложившийся
де-факто набор блоков, которые ожидают увидеть:

1. Название проекта + короткое (1 строка) описание
2. Бейджи (build passing, coverage, версия — опционально)
3. TL;DR / что это такое — 2-3 абзаца
4. Быстрый старт: как поставить и запустить за 3 команды
5. Использование: небольшой пример
6. Документация: ссылка на полную
7. Contributing: как принять помощь
8. Лицензия

Есть попытки формализовать структуру. Например, проект Standard Readme
Ричарда Литта описывает канонический порядок разделов и минимальные
требования; сборник Awesome README — коллекция особенно удачных
образцов и генераторов.

Отдельная механика — README в подпапках. Она работает не только для
проектов, но и для любой файловой структуры. GitHub, VS Code, JetBrains
IDE, редакторы вроде Obsidian — все умеют показывать README.md при
открытии папки. Это превращает README в универсальную «шапку папки»,
удобную не только программистам: ~/документы/налоги/README.md — вполне
рабочая практика.

Где встречается в обычной жизни

Где встречается в IT и бизнесе

Кто пользуется

Все, кто пишет код или ведёт файловые архивы. Масштаб — планетарный.

Отдельно — практика «README-driven development», сформулированная Томом
Престоном-Вернером (сооснователь GitHub) в статье 2010 года: сначала
пишешь README, как если бы фича уже была готова, потом реализуешь. Это
заставляет думать глазами пользователя до того, как написать первую
строку кода.

Альтернативы и конкуренты

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

README устаревает молча

Устаревший README вредит больше, чем отсутствующий. Отсутствие сигнализирует «разбирайся сам»; неверный — уводит в тупик и подрывает доверие к остальному репо. Заведи правило: README и код меняются в одном коммите. Если правишь install.sh — открой README и проверь блок «как поставить».

Связанные понятия

Литература и источники

Где встретилось у меня

Вчера в работе была ревизия покрытия README в структуре личных и рабочих
папок агентов: сколько из 22 содержательных папок в личном узле имеют
README (получилось 13, ~59%), какие README у отдельных агентов, где их не
хватает. Задача — не «оформить всё красиво», а «сделать так, чтобы через
полгода я или сторонний человек могли открыть любую папку и за минуту
понять, что здесь».

Краткое резюме