Документация проекта: README и минимум для передачи

Документация проекта — это записи, по которым другой человек может запустить, понять и изменить твой код без тебя. Её основа — файл README.md в корне репозитория: первое, что открывает разработчик, и часто единственное, что он прочитает.

Большая документация не нужна. Нужен минимум, который отвечает на вопросы нового человека в первый день. Если проект писался с ИИ-ассистентом и одним человеком, эти ответы обычно существуют только у него в голове — до первого отпуска, болезни или смены подрядчика.

Когда это становится срочным

Документацию откладывают, пока всё помнишь сам. Срочной она становится в одной из ситуаций:

• ты нанимаешь первого разработчика или передаёшь проект агентству;
• подрядчик, который всё писал, уходит;
• инвестор или покупатель проводит техническую проверку;
• ты сам возвращаешься к проекту через полгода.

В каждой из них отсутствие README стоит дней чужого времени. Агентство посчитает эти дни в смете.

Что должно быть в README

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

README.md
  Название и два предложения: что это и для кого
  Запуск локально
  Переменные окружения
  Как устроено
  Деплой
  Подводные камни
  Доступы и контакты

Дальше — что писать в каждом разделе.

Запуск локально

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

Переменные окружения

Список всех переменных с пояснением, что каждая делает и где взять значение для разработки. Сами значения — не в README, а в файле .env.example с пустыми или тестовыми значениями. Секреты в документации — такая же утечка, как секреты в коде.

Отметь, какие переменные обязательны, а какие включают необязательные функции. «Без SMTP_HOST письма пишутся в лог» — одна строка, которая экономит час.

Как устроено

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

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

Деплой

Как код попадает на продакшн: автоматически при слиянии в основную ветку или вручную, какой командой. Где хостинг, где база, где домен и DNS. Как откатиться на предыдущую версию. Как запускаются миграции базы и что делать, если миграция упала.

Если деплой требует ручного шага, о котором знает один человек, — это первое, что нужно записать.

Подводные камни

Самый ценный раздел, который почти никто не пишет. Всё, на чём ты сам спотыкался:

• функции, которые нельзя трогать без особой осторожности;
• внешние сервисы с лимитами или странным поведением;
• известные баги и обходные пути;
• задачи по расписанию, которые где-то работают, и о них легко забыть.

Доступы и контакты

Без паролей. Только список: какие сервисы используются, на чей аккаунт они заведены, у кого запросить доступ. При передаче проекта агентству это превращается в чеклист: всё ли передано, всё ли переведено на компанию.

Как не дать документации проекта устареть

Держи её в репозитории рядом с кодом, а не в отдельном сервисе: тогда изменения видны в тех же коммитах. Правило простое — меняешь, как запускается или деплоится проект, — правишь README в том же коммите.

Если используешь ИИ-ассистента, у него обычно есть свой файл инструкций (CLAUDE.md, .cursorrules или аналог). Хорошая новость: то, что ты пишешь для ассистента, почти дословно полезно и людям. Плохая — если написано только там, человек это не найдёт. Сошлись из одного файла на другой.

Коротко

• Документация проекта начинается с README, по которому проект запускается без автора.
• Минимум: запуск, переменные окружения, набросок архитектуры, деплой, подводные камни, доступы.
• Секреты не пишутся в документацию — только названия переменных и .env.example.
• Объясняй странные решения, иначе их «исправят».
• Обновляй README в том же коммите, что и изменения, которые он описывает.

SUBXCAT пишет такую документацию в рамках передачи проекта, чтобы следующий разработчик начал работать в первый же день.