И вот, когда уже написано десятки тысяч строк кода, появляется запрос:
Окей, ChatGPT, сделай мне документацию по этому репозиторию
Вот что бывает, когда не занимаешься документацией на протяжении всей жизни проекта.
Понятно, что промпт утрирован и для получения «очень качественной документации» будет описан с десяток критериев, которым документация должна соответствовать.
В итоге получим прекрасный документ в стиле «Что вижу – то пою».
Только это не совсем документация к проекту. Там не будет ответа на ключевой вопрос:
А зачем мы это всё создавали?
Потому что код на этот вопрос может ответить далеко не всегда. Ибо является проекцией реального мира на логику, выраженную через язык программирования.
Более того, хороший код – это компактная и универсальная абстракция. А действительно сильную абстракцию не каждая нейронка разберёт.
Для полезной документации по проекту необходим контекст реального мира. Что именно мы проецировали в код.
Откуда можно получить этот контекст:
1. Правила при написании кода. Создавая новый модуль/класс/метод, описываем его смысл, следующий из бизнес-процессов. А не просто словами переписываем то, что и так выражено через код. То есть комментарии в коде дополняют код, а не дублируют его. Отвечаем на вопрос «зачем?», а не «что?».
2. Система контекста по проекту (буквально вчера писал об одном из вариантов). Если разрабатываем код с помощью AI-coding, подключаем через хуки (важна детерменированность) слой знаний о проекте и храним его отдельно от кода. Как правило, при общении с AI-агентом, мы передаём тот недостающий контекст, который важен для документации. Плюс – получаем изменения бизнес-требований во времени. А эти изменения отлично накладываются на историю в git. Усилить контекст проекта можно, добавляя в систему результаты созвонов, переписок и комментариев в таск-трекере.
3. Если нет никаких артефактов по п.1 и п.2, не отчаиваемся. В промпт из начала статьи добавляем «Проведи глубокое интервью с участниками процесса (хорошо, когда не раздуваешь команду, правда?), чтобы изучить бизнес-процессы и меняющиеся обстоятельства, в которых создавали проект». И проходим это интервью.
Вариант №3, к сожалению, оказывается самым хрупким. Так как, отвечая на вопросы интервью, человек находится в моменте «Сейчас». Следовательно, на его восприятие гораздо сильнее влияют те события, которые свежи в памяти, а не те, что были на старте проекта.
Тогда как именно мотивация на старте в том виде, в котором она преподносилась тогда, оказала самое сильное влияние на то, каким мы видим проект сейчас.