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

> Документация проекта без лишнего: что написать в README, чтобы другой разработчик или агентство подхватили проект — запуск, переменные, архитектура, деплой.

Published: 2026-01-18 · Source: https://subxcat.com/ru/articles/readme-and-handover-docs · Author: SUBXCAT

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Как устроено

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

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

## Деплой

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

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

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

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

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

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

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

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

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

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

## Коротко

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

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