Чек-лист проблемного web-проекта
Диагностический чек-лист: подрядчик затягивает разработку, проект трудно передать, портал ломается после релизов и нет документации.
Открыть чек-листДокументация
Что делать, если у проекта нет технической документации
Отсутствие документации делает проект зависимым от отдельных людей, усложняет доработки и повышает риск при смене подрядчика. Но документацию можно восстанавливать поэтапно, начиная с карты системы.
Ситуация
Что обычно происходит
Часто проект работает, пока рядом есть люди, которые помнят, как он устроен. Но при смене подрядчика, уходе разработчика или запуске нового этапа выясняется, что архитектура, интеграции и решения нигде не описаны.
В такой ситуации не нужно пытаться сразу написать идеальный том документации. Сначала нужно восстановить минимальную карту проекта, достаточную для безопасных решений.
Признаки проблемы
- подрядчик ушёл, а новая команда не понимает систему
- знания о проекте находятся в переписках и головах людей
- нет карты модулей, интеграций и окружений
- доработки становятся рискованными из-за неизвестных зависимостей
- доступы, репозитории и инфраструктура собраны фрагментарно
- бизнес не понимает, что передавать новой команде
Чек-лист
Материал для самостоятельной проверки
Причины
Почему это может происходить
документация не была частью процесса разработки
решения фиксировались в чатах и встречах, а не в артефактах
проект развивался рывками без владельца архитектуры
нет ответственного за актуальность схем и доступов
подрядчик сдавал функции, но не передавал технический контекст
Диагностика
Симптом, проверка и рабочий артефакт
| Симптом | Что проверить | Что получить |
|---|---|---|
| Новая команда не понимает проект | Модули, репозитории, окружения, зависимости | Карта системы |
| Интеграции ломаются при доработках | API, обмены, внешние сервисы, владельцы доступов | Карта интеграций |
| Непонятно, где актуальные данные | База данных, CRM, 1С, справочники, источники истины | Карта данных |
| Передача проекта рискованна | Доступы, инфраструктура, открытые задачи, технический долг | Пакет передачи проекта |
Карта документации
Как восстанавливать документацию без лишнего формализма
Документацию проблемного проекта лучше восстанавливать от решений бизнеса и рисков поддержки, а не пытаться сразу описать всё подряд.
Система
Что реально работает
Модули, окружения, релизы, зависимости и зоны, где изменения чаще всего ломают проект.
- модули
- окружения
- релизы
Логика
Критичные сценарии
Роли пользователей, статусы, исключения, ручные операции и правила, которые нельзя потерять при передаче.
- роли
- статусы
- исключения
Данные
Источники истины
Где живут данные, какие системы синхронизируются и кто отвечает за корректность справочников.
- CRM
- 1C
- портал
Доступы
Контур владения
Домены, хостинг, репозитории, внешние сервисы, API-ключи и ответственные за каждый доступ.
- владелец
- назначение
- риски
План
Что обновлять дальше
Какие документы нужны сейчас, кто их поддерживает и какие изменения обязательно фиксируются после релизов.
- минимум
- ответственный
- ритм обновления
Итог Результат: у бизнеса и новой команды появляется минимальный пакет контекста, достаточный для поддержки, передачи и безопасных доработок.
Первые шаги
Порядок действий без хаоса
Аудит нужен, если отсутствие документации уже влияет на сроки, стоимость доработок, смену подрядчика или стабильность проекта.
Инвентаризация
Собрать репозитории, доступы, окружения, домены, интеграции и ключевые материалы.
Карта системы
Описать модули, роли, данные, интеграции и критичные пользовательские сценарии.
Минимальная документация
Зафиксировать только то, что нужно для поддержки, передачи и ближайших доработок.
Контроль актуальности
Определить, кто обновляет документацию и какие изменения обязаны фиксироваться.
Что не делать
Решения, которые лучше не принимать вслепую
- не начинать передачу новой команде без инвентаризации
- не считать переписку полноценной документацией
- не писать документацию ради документации без привязки к решениям
- не запускать сложные доработки до восстановления карты интеграций
Следующий шаг
Что сделать с этой ситуацией
Выберите ближайший маршрут: собрать факты, проверить подрядчика, подготовить AI-ready основу или спроектировать систему заново.
Проверить подрядчика без конфликта
Если ответы по срокам, рискам и релизам стали размытыми, нужен контроль по артефактам, а не микроменеджмент.
- статус и блокеры
- архитектура и релизы
- документация и передача
Начать с диагностики проблемного проекта
Если сроки, бюджет или стабильность перестали быть предсказуемыми, сначала нужно собрать факты и карту рисков.
- технический тупик
- срывы сроков
- нестабильные релизы
Понять, готов ли проект к AI
Если хочется AI-ассистента, RAG или автоматизацию, сначала стоит проверить данные, роли, документы и критерии качества.
- источники данных
- права доступа
- метрики качества
Связанные материалы
Куда перейти дальше
Что должно быть в документации
Практическая структура документации web-проекта: карта системы, доступы, интеграции, релизы и риски.
Документация перед сменой подрядчика
Что нужно собрать, если отсутствие документации уже мешает передать проект новой команде.
Как подготовить проект к передаче
Порядок подготовки к передаче: доступы, карта системы, открытые задачи, риски и контрольный пакет.
Аудит web-проекта
Проверить состояние системы, документации, кода и интеграций.
Восстановление проекта
Вернуть проекту управляемость через карту системы, рисков и roadmap.
Контроль подрядчика
Зафиксировать требования к документации и приёмке работ.
Кейс смены подрядчика
Сценарий, где техническая передача была рискованной без подготовки.
Кейс передачи без документации
Как восстановить карту проекта, доступы, интеграции и пакет передачи, если знания остались у прежней команды.
FAQ
Частые вопросы
Какой минимум документации нужен?
Карта модулей, интеграций, данных, доступов, окружений, критичных сценариев, открытых рисков и правил релиза.
Можно восстановить документацию без старой команды?
Частично да. По коду, окружениям, интерфейсам, интеграциям и интервью можно восстановить рабочую карту проекта.
Нужно ли документировать всё?
Нет. Сначала фиксируется то, что снижает риски поддержки, передачи и ближайших изменений.
Заявка
Восстановить карту проекта
Опишите, какие документы есть, кто вел проект, есть ли доступы и что нужно сделать дальше: поддержка, доработка или передача.
Дмитрий Зугаев web/AI-архитектор, CTO