Порядок в проекте

Десятый вечер

Вы вайбкодите десятый вечер. Проект вырос: тридцать с лишним файлов, половину вы ни разу не открывали. Сегодня вы просите агента поменять цвет шапки — он уверенно правит style.css, отчитывается «[OK] Готово», а шапка как была серой, так и осталась. Выясняется, что страница давно подключает styles_new.css, а style.css — мёртвый файл из первой недели. Через полчаса вы просите добавить кнопку «Очистить список» — агент пишет новую функцию, хотя почти такая же уже лежит в script2.js. А рядом в папке — main_old.js и final_version2.js, и вы сами не помните, какой из них на самом деле подключён к странице.

Первый порыв — решить, что агент испортился: вчера же справлялся. Но сломался не агент. Сломалась навигация по проекту.

Агент читает проект заново — каждый раз

Вспомните первый урок: агент видит только то, что попало к нему в контекст, и между сессиями ничего не помнит. У вас, когда вы месяц копаетесь в собственном бардаке, есть хоть какая-то память: «кнопка вроде была где-то в том длинном файле». У агента её нет. Каждая новая сессия для него — первое знакомство с проектом: он открывает папку как чужую и ориентируется по тому, что видит. А видит он имена файлов и их содержимое.

Теперь посмотрите на свой проект его глазами. Файл называется style.css — разумно предположить, что стили страницы живут здесь. Файлов script.js и script2.js два — какой из них живой? Догадаться нельзя, можно только угадать. Агент и угадывает: иногда верно, иногда нет. В захламлённом проекте он не глупеет — он делает разумные ставки в условиях, где выиграть можно только случайно. И промахивается чаще вас, потому что у вас есть хотя бы смутные воспоминания, а у него — только имена.

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

Хорошая новость: переписывать проект не нужно. Хватит минимального порядка — такого, чтобы на вопрос «где лежит эта штука?» существовал ровно один ответ.

Минимальный порядок: имена, файлы, папки

Слово «порядок» звучит как идеология, но задача у него приземлённая — навигация. Три правила закрывают большую часть проблем.

Понятные имена. Имя файла должно отвечать на вопрос «что внутри». script2.js не отвечает ни на что; cart.js — «код корзины» — отвечает полностью. Если файлу трудно придумать честное имя, обычно это значит, что вы сами не знаете, что в нём лежит, — отдельный повод открыть и посмотреть.

Одна вещь — один файл. Страница в одном файле, её стили в другом, логика в третьем. Когда всё свалено в один файл на восемьсот строк, каждая правка агента — операция вслепую рядом с чужим кодом, и шанс зацепить соседнее растёт с каждой строкой.

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

До и после — на примере того самого проекта:

до:                    после:
index.html             index.html
script.js              styles/
script2.js               main.css
main_old.js            js/
final_version2.js        list.js
style.css                form.js
styles_new.css

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

Наведи порядок в проекте: найди файлы, которые нигде не подключены,
и покажи мне их список. Остальным дай понятные имена и разложи
по папкам styles/ и js/. Логику кода не меняй.

В этом промпте (промпт — текст запроса к агенту) два предохранителя. Мёртвые файлы агент не удаляет сам, а показывает списком: вдруг среди них есть нужное. И логика кода объявлена неприкосновенной. После уборки — проверка, как в двух прошлых уроках: смотрим дифф — список изменений — и запускаем проект. Переименование — тоже правка, и она тоже умеет ломать: файл переименовали, а строку, которая его подключает, — нет.

Теперь файлы находятся с первой попытки. Но осталось знание, которого ни в каком дереве папок не видно: что это вообще за проект, как его запустить, что где лежит. Сейчас оно живёт у вас в голове — и каждую сессию вы заново пересказываете его агенту. А после месячного перерыва его не окажется и в голове.

README: визитка проекта

README (буквально «прочти меня») — файл с описанием проекта, который кладут в его корень. Так сложилось, что это первое, что открывает человек, попавший в чужой проект. И агент поступает так же: заглядывает в README, чтобы понять, куда попал.

Хороший README для маленького проекта — это три ответа:

# Список покупок

Веб-страница со списком покупок: добавить, вычеркнуть, очистить.

## Запуск
Открыть index.html в браузере. Больше ничего не нужно.

## Что где лежит
- index.html — страница
- styles/main.css — все стили
- js/list.js — логика списка, js/form.js — форма добавления

Что это. Как запустить. Что где лежит. Всё.

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

И его не обязательно писать руками — попросите агента: «Напиши README — что это за проект, как запустить, что где лежит». Только прочитайте результат. Агент опишет проект таким, каким его увидел, и если он что-то понял неверно, README закрепит ошибку на бумаге.

README объясняет устройство проекта. Но есть ещё один вид знания — договорённости. «Стили пиши только в main.css, не внутри HTML». «После правок запускай тесты». Вы говорите это агенту в чате, он послушно выполняет… до конца сессии. Завтра будет новая сессия — и та же ошибка, что вчера. Память чата заканчивается вместе с чатом.

Постоянные правила: файл инструкций для агента

Для договорённостей у инструментов есть отдельный файл, который агент читает автоматически в начале каждой сессии. Называется он по-разному — AGENTS.md, CLAUDE.md: Claude Code, Cursor, Copilot дают ему свои имена, но суть одна — постоянные правила проекта, которые не нужно повторять. Точное имя для вашего инструмента подскажет его документация.

Весь файл для нашего списка покупок:

# Правила проекта

- Стили писать только в styles/main.css, внутри HTML стилей не добавлять
- После любой правки кода запускать тесты и показывать результат
- Папку archive/ не трогать: там старые версии, они не подключены
- Новые страницы класть в корень, их скрипты — в js/
- Отвечать и писать комментарии по-русски

Механика простая: одно правило — одна строка. Записали один раз — агент перестал совершать одну и ту же ошибку. Это и есть способ научить инструмент, у которого нет памяти: память живёт не в модели, а в файле рядом с кодом.

Заполнять такой файл наперёд не нужно. Он растёт из реальных ошибок: агент второй раз сделал то, что вы уже просили не делать, — значит, просьба заслужила строчку в правилах. Через пару недель в этом файле накопится опыт именно вашего проекта, и каждая новая сессия будет начинаться уже с ним.

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

Ритуал конца сессии

Дыра закрывается привычкой — одним запросом в конце каждой сессии:

Мы закончили на сегодня. Обнови README, если устройство проекта
изменилось. Если сегодня появились новые договорённости о том,
как работать, — допиши их в файл правил.

Две минуты. Агент сам вспомнит, что сегодня появилась папка pages/ и уговор запускать тесты после правок, и сам их запишет. Вам остаётся просмотреть дифф этих двух файлов перед тем, как согласиться: документация, как и код, заслуживает взгляда перед сохранением. Следующая сессия — ваша или агента — начнётся с честной карты проекта, а не с археологических раскопок.

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

Что дальше

Посмотрите, что изменилось за урок. Агент правит именно тот файл, потому что имена перестали врать. Не дублирует существующее, потому что README говорит, что где лежит. Не наступает на прошлые грабли, потому что грабли записаны в файл правил. Порядок сделал его точным.

Но точность и правота — разные вещи. Агент с идеальной навигацией по проекту всё равно может написать неверный код — и расскажет о нём тем же уверенным тоном, каким рассказывает о верном. На слух вы их не отличите. Где агенту можно верить на слово, а где проверять обязательно — следующий урок.