CHANGELOG — это журнал изменений проекта, где простыми словами записано, что поменялось, зачем и как проверить результат. Он помогает владельцу бизнеса разобраться, что именно сделал ИИ-агент, а разработчику — быстрее найти источник проблемы, если после обновления перестала работать форма или изменилась страница. В статье разберём, как завести такой журнал, что поручить агенту и как проверять записи перед публикацией.
Зачем нужен CHANGELOG, если код пишет ИИ?
ИИ-агент может создать файлы, изменить уже существующие и исправить ошибки по ходу работы. Если вы просили добавить форму заявки, в журнале стоит указать, какие изменения относятся к форме и что проверить после обновления. Через месяц такая запись полезнее, чем попытка вспомнить, какой запрос вы отправляли агенту.
Журнал помогает и при передаче проекта другому специалисту. Вместо длинной переписки он получает краткую историю: какие функции добавили, что исправили и какие части сайта затронули. Для небольшого сайта достаточно вести записи в одном текстовом файле в корне проекта, например CHANGELOG.md.
CHANGELOG не заменяет резервные копии и историю изменений в Git. Он отвечает на вопрос «что изменилось и зачем», а инструменты контроля версий помогают увидеть сами изменения в файлах и при необходимости вернуться к предыдущему состоянию.
Что записывать в журнал изменений?
Описывайте результат с точки зрения пользователя и владельца проекта. Формулировка «обновлён компонент» мало о чём говорит. Лучше написать: «На странице контактов добавлена проверка заполнения телефона; перед публикацией проверить отправку формы с заполненным и пустым полем».
Для каждой записи укажите дату, короткое название и список изменений. Если дата не помогает найти нужное обновление, достаточно сохранить её в одном формате для всех записей. Не добавляйте неподтверждённые детали: агент мог описать намерение, но не завершить работу или изменить соседнюю часть сайта.
- Добавлено: новая функция или страница.
- Изменено: существующее поведение, текст или внешний вид.
- Исправлено: обнаруженная ошибка и её видимое проявление.
- Проверить: действие, которое нужно выполнить перед публикацией или после неё.
Не включайте в журнал ключи доступа, пароли и другие секреты. Записывайте только то, что понадобится при сопровождении проекта: например, «изменён способ отправки формы», но не значение ключа, который использует сервис.
Как попросить ИИ-агента обновлять CHANGELOG?
Добавьте правило в инструкции проекта: после каждой выполненной задачи агент должен кратко описать подтверждённые изменения в CHANGELOG.md. Чтобы агент не терял другие правила работы, их можно хранить в отдельном файле, например настроить CLAUDE.md с правилами проекта. Для агента, который работает с разными инструментами, подойдёт и файл AGENTS.md с общим контекстом проекта.
Попросите агента писать запись только после проверки изменённых файлов. Удобно задать короткий шаблон:
- дата и заголовок задачи;
- что добавлено, изменено или исправлено;
- какие страницы или функции затронуты;
- что проверено и что осталось проверить.
Например, после задачи «добавить блок с частыми вопросами» агент может записать, что добавил блок на страницу услуги, и перечислить, какие элементы проверил. Если он не запускал сайт и не проверял отображение на телефоне, в журнале нужно указать это как непроверенный пункт, а не как выполненную проверку.
Как проверить запись перед публикацией?
Сверьте журнал с фактическими изменениями: откройте изменённые файлы или посмотрите их список в Git, затем сопоставьте их с описанием агента. Если запись обещает исправление формы, отправьте тестовую заявку и проверьте, что она обрабатывается ожидаемым образом. Если агент не может подтвердить результат, попросите его уточнить формулировку или отметьте проверку как незавершённую.
Перед обновлением сайта отдельно проверьте само изменение: откройте затронутую страницу, проверьте основное действие и убедитесь, что соседние функции продолжают работать. Для такого процесса пригодятся автоматические проверки проекта перед обновлением. Автоматические проверки дополняют ручной осмотр, но не подтверждают, что текст понятен посетителю или форма решает задачу бизнеса.
Если агент внёс несколько несвязанных изменений, разделите запись на понятные пункты. Так проще отменить или перепроверить одну часть, не разбирая весь список заново.
Каких ошибок избегать в CHANGELOG?
- Записывать только «улучшен сайт». Укажите страницу или функцию и видимое изменение.
- Принимать описание агента без проверки. Сверьте запись с файлами и протестируйте затронутое действие.
- Смешивать запросы и выполненную работу. Записывайте фактический результат, а не план.
- Оставлять в журнале только технические названия. Добавьте короткое объяснение, что заметит пользователь.
- Не отмечать пропущенные проверки. Чётко напишите, что ещё нужно проверить перед публикацией.
Начните с файла CHANGELOG.md и добавьте туда последнее подтверждённое изменение проекта. Затем попросите ИИ-агента соблюдать один шаблон записей и перед каждой публикацией сверяйте журнал с изменёнными файлами и проверками сайта.
