Документация проекта: как вести, чтобы не запутаться

Ты собираешь «Змейку» промптами, всё идёт хорошо, код растёт. Потом отвлекаешься на два дня, возвращаешься — и не понимаешь, почему змейка двигается именно так, а счёт сохраняется в одном месте, а не в другом. Или просишь Claude добавить функцию, а он предлагает то, что ты уже отклонял неделю назад. Проблема не в памяти, а в отсутствии короткой, но точной документации. Поговорим о том, как вести README, CLAUDE.md и журнал решений, чтобы не запутаться в собственном проекте.

Зачем документация, если код и так работает

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

Документация в вайбкодинге решает три задачи:

• Вспомнить контекст. Почему выбран localStorage, а не Supabase? Почему счёт обновляется отдельной функцией? Ответы должны быть записаны, а не висеть в голове.
• Быстро включить ИИ в работу. Claude не помнит предыдущих сессий. Если в файле CLAUDE.md описан стек, правила и текущие задачи, он сразу даёт релевантные ответы.
• Не повторять ошибки. Журнал решений показывает, какие варианты уже пробовали и почему отказались. Это экономит часы на повторные обсуждения.

README — визитная карточка проекта

README.md — это файл в корне проекта, который читают первым делом. Он нужен не только другим людям, но и тебе самому, особенно если открываешь папку после перерыва.

Хороший README для учебного проекта короткий, но содержит ключевое:

• Название и одно предложение о проекте. Например: «Браузерная игра „Змейка“ на HTML, CSS и JavaScript».
• Зачем проект существует. Для портфолио, обучения, проверки идеи.
• Как запустить локально. Команды для установки и старта. Даже если они простые, лучше зафиксировать.
• Стек технологий. Языки, библиотеки, сервисы. Это помогает Claude не предлагать лишнего.
• Структура папок. Кратко, что лежит где: index.html, js/game.js, css/style.css, assets/sounds/.
• Статус проекта. Что уже работает, что в процессе, что планируется.
• Ссылка на демо. Если проект опубликован на GitHub Pages — публичная ссылка.

Не нужно расписывать каждую строчку кода. README — это карта, а не энциклопедия. Его задача: за 30 секунд вернуть тебя в контекст.

CLAUDE.md — памятка для ИИ

CLAUDE.md — это специальный файл, который Claude Code читает автоматически перед работой. В нём ты описываешь проект так, чтобы ИИ не предлагал общих решений, а действовал в рамках твоего стека и стиля.

Что стоит включить в CLAUDE.md:

• Описание проекта и цель. Например: «Учебная игра „Змейка“. Цель — понять, как собирать приложение промптами».
• Стек и ограничения. «Только vanilla JavaScript, без фреймворков. localStorage для рекорда. PWA в планах».
• Правила оформления кода. «Используй понятные имена переменных, комментарии только к сложным местам, не добавляй лишних зависимостей».
• Структура проекта. Какие файлы за что отвечают.
• Текущий фокус. Что сейчас в приоритете: «Доделать магазин скинов» или «Настроить офлайн-режим».
• Что делать, а чего не делать. «Перед изменениями проверяй, есть ли уже похожая функция. Не переписывай весь файл ради одной правки».

CLAUDE.md особенно полезен в двух случаях. Первый: ты начинаешь новую сессию и не хочешь объяснять всё с нуля. Второй: проект усложнился, и без памятки Claude начинает предлагать решения, которые не вписываются в архитектуру.

Журнал решений — чтобы не обсуждать одно и то же

Журнал решений, или decision log, — это файл, куда записываются важные выборы, сделанные в процессе работы. Не все решения, а только те, которые влияют на архитектуру, стек или логику и которые потом могут вызвать вопрос «а почему так?».

Формат может быть простым:

• Дата.
• Вопрос или проблема.
• Рассмотренные варианты.
• Выбранное решение и почему.
• Что делать, если решение устареет.

Пример для «Змейки»:

Такая запись занимает минуту, но экономит часы через месяц. Ты видишь не только результат, но и причину. Claude видит, какие идеи уже отметались, и не возвращается к ним.

Принцип «документация для будущего себя и ИИ»

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

Что стоит фиксировать:

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

Чего лучше избегать:

• Очевидных вещей вроде «JavaScript — это язык программирования».
• Эмоциональных оценок: «этот код ужасен».
• Длинных историй, не связанных с проектом.
• Информации, которая быстро устаревает и не обновляется.

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

Как применить к «Змейке»: практический блок

Представь, что ты на втором модуле курса и только собрал базовую версию игры. Как может выглядеть минимальная документация?

README.md

• Название: «Змейка — учебный проект skillmake».
• Запуск: открыть index.html в браузере или выполнить npx serve.
• Стек: HTML, CSS, JavaScript, localStorage.
• Структура: index.html, js/ — логика, css/ — стили, assets/ — звуки и спрайты.
• Статус: базовая механика работает, ведётся работа над рекордом и скинами.
• Демо: ссылка на GitHub Pages.

CLAUDE.md

• Проект: учебная «Змейка» на vanilla JS.
• Не использовать фреймворки.
• Код разбивать на модули: game.js, render.js, input.js.
• Состояние игры хранить в одном объекте state.
• Перед правкой проверять, нет ли уже похожей функции.
• Текущий фокус: добавить таблицу рекордов через localStorage.

Журнал решений

• 2026-07-01: рекорд храним в localStorage, потому что аккаунтов ещё нет.
• 2026-07-02: отказались от setInterval в пользу requestAnimationFrame — плавнее управление.
• 2026-07-02: поле игры 20×20 клеток, масштабировать через CSS, не меняя логику.

Такой набор документов занимает 15–20 минут на создание и минуты на поддержание. Зато ты всегда знаешь, с чего начать следующую сессию, а Claude не будет каждый раз переспрашивать базовые вещи.

Частые вопросы

Какие документы нужны в самом начале проекта?

Достаточно README с описанием, стеком и командой запуска. CLAUDE.md добавь, как только проект перестанёт помещаться в одном файле. Журнал решений заводь, когда появляются выборы, которые хочется не забыть.

Что делать, если документация устарела?

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

Нужно ли документировать каждую функцию?

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

Можно ли вести журнал решений прямо в CLAUDE.md?

Можно, если проект маленький. Но лучше разделить: CLAUDE.md — инструкция для работы, журнал — история выборов. При росте проекта отдельный файл удобнее.

Почему документация важна, если работаю один?

Потому что «один» — это временно. Через месяц ты сам станешь другим человеком, который не помнит деталей. И Claude тоже «не помнит» без памятки. Документация — это способ не начинать разговор с нуля каждый раз.

Заключение + чек-лист

Документация в вайбкодинге — это не бюрократия, а способ сохранить скорость. README помогает вернуться в проект, CLAUDE.md настраивает ИИ под твой стек, а журнал решений не даёт повторять пройденное. Всё вместе — это разговор с будущим собой и с ИИ, которые будут благодарны за ясность.

Чек-лист «Документация в порядке»

• В корне проекта есть README.md с названием, стеком, запуском и статусом.
• Есть CLAUDE.md с описанием проекта, правилами и текущим фокусом.
• Важные архитектурные решения записаны в журнале.
• Документы обновляются при изменении кода, а не «потом».
• В README есть ссылка на демо, если проект опубликован.
• CLAUDE.md короткий и конкретный — не больше двух страниц.
• Журнал содержит не только решение, но и причину выбора.
• Нет мертвых комментариев и устаревших ссылок.
• Перед новой сессией просматриваешь CLAUDE.md, чтобы быстро войти в контекст.