Правила именования репозиториев для более понятной работы AI‑ассистента при программировании

Почему неясные имена сбивают с толку ассистентов

AI‑ассистент читает репо как чужак, пришедший в мастерскую: он видит имена, пути и соседние файлы, прежде чем поймёт, как всё устроено.

Когда названия папок смешивают несколько смыслов, намерение теряется. Репозиторий с /api, /helpers, /new, /misc и /v2 не подсказывает модели, где кончается продуктовая логика и начинается поддержка. Люди могут восполнить эти пробелы по памяти. Модели — нет.

Та же проблема проявляется, когда похожие модули делают разные вещи. Если auth, auth-service, session и security содержат проверки входа, код токенов и состояние пользователя, ассистенту приходится догадываться, какой файл править. Он часто правит ближайший похожий файл, а не тот, который нужен.

В стартапах временные имена скапливаются постоянно. Папки типа temp, old-api, helpers2 или final остаются месяцами. Модель не знает, что эти имена — следствие спешки. Она воспринимает их как часть дизайна и строит поверх них дальнейшую логику.

Тесты усугубляют путаницу. Если код находится в /billing/invoice, а тесты — в /specs/unit/payments или отдельной папке /qa, связь между поведением и доказательством слабеет. Модель может не заметить уже существующее покрытие, написать дублирующие тесты или пропустить случай, который раньше падал.

Когда именование слабеет, ассистент переходит на поверхностное сопоставление по паттернам. Он ориентируется на имена импортов, соседние файлы и размер файла, потому что структура не несёт достаточного смысла. Вот почему вы получаете патч в utils вместо billing или ещё один модуль рядом с пятью полуперекрывающимися.

Последствия кажутся мелкими, но быстро накапливаются. Вы просите «добавить логику повторных попыток в синхронизацию инвойсов», и модель находит sync.ts, syncJob.ts и worker_sync.ts в трёх местах. Один путь обновляется. Два связанных остаются нетронутыми.

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

Как выглядят понятные имена

Понятные имена — немного скучны. В этом смысл. Когда человек или ассистент открывает репозиторий, он должен с первого взгляда угадать нужное место.

Начните с одного шаблона для одного типа папок. Если код функционала живёт в modules/, оставляйте его там везде. Не смешивайте modules/, features/, packages/ и stuff/ для похожего кода, если только они действительно не значат разные вещи.

Названия должны описывать задачу, а не историю изменения. billing, auth и notifications говорят, что делает код. Имена типа team-alpha, new-service или oleg-old-fix понятны только тем, кто помнит предысторию, а память быстро уходит.

Последовательность важна и для единственного/множественного числа. Выберите test или tests. Выберите module или modules. Используйте этот выбор по всему дереву. Маленькое несоответствие выглядит безобидно, но ухудшает поиск, генерацию кода и обзор.

Простой шаблон часто выглядит так:

• топ‑уровневые папки по рантайму: api/, web/, worker/
• общий код в одном месте: shared/ или common/
• модули по задаче: payments/, users/, reports/
• тесты называются одинаково везде: tests/ или __tests__/

Расплывчатые имена создают большую часть бардака. misc, temp, other, new и final приглашают туда всё подряд. Через полгода никто не понимает, что туда относится, и продолжают добавлять новые файлы. Если у папки есть реальная цель — дайте ей реальное имя. Если цели нет — скорее всего, папки не должно быть.

Ассистентам гораздо удобнее работать с простой структурой вроде api/modules/billing, web/components и tests/integration. Им сложнее, когда один и тот же тип кода прячется под тремя ярлыками.

Выберите одно «место» для каждого типа работы

Репозиторий быстро загружается шумом, когда один и тот же тип файлов живёт в трёх местах. Инструменты с AI читают этот шум как паттерн. Если скрипты лежат рядом с продуктовым кодом, или примеры прячутся внутри папок фич, модель начинает гадать. Именование работает лучше, когда для каждого типа задачи есть одно понятное место.

Держите основной код приложения в одной корневой области, обычно src/ или app/. Выберите одно и придерживайтесь. Когда каждая фича начинается там, и люди, и ассистенты знают, куда добавлять код.

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

Общий код тоже должен иметь очевидное место. Если хелперы появляются в utils/, common/, lib/ и shared/, эти имена теряют смысл. Выберите одну папку для кода, который используют несколько частей приложения, и со временем переместите туда дубликаты.

Документы и примеры заслуживают своей области. README в корне — хорошо, но длинные заметки — в docs/. Демки, образцы payload и starter‑файлы — в examples/. Это держит дерево продукта сфокусированным на коде, который выпускается.

Для многих репозиториев достаточно такой простоты:

• src/ — код приложения
• scripts/ — служебные и локальные задачи
• shared/ — переиспользуемые хелперы и модули
• docs/ — заметки и гайды по настройке
• examples/ — демки и образцы

Это особенно важно при работе с ассистентом. Если вы просите добавить новый модуль, а в репо есть три возможных места, он выберет одно и будет надеяться. Иногда везёт. Часто он добавляет ещё слой мусора.

Переименовывайте репо маленькими шагами

Крупные переименования обычно проваливаются, когда команда пытается исправить всё за один уик‑энд. Пропускают импорты, ломают тесты, и никто уже не помнит, зачем половина папок переехала. Малые партии работают лучше.

Начните с перечисления имён, которые заставляют людей задуматься. Если кто‑то спрашивает, используются ли ещё misc, helpers2, new или temp-scripts, это имя уже тратит время. То же относится к папкам, которые ассистент считает взаимозаменяемыми.

Напишите правила именования на одной странице перед тем, как трогать дерево. Хорошие правила просты и воспроизводимы. Выберите один способ именовать модули, одно слово для общего кода и один шаблон для тестов.

Короткий набор правил достаточно:

• используйте один стиль именования для папок и модулей
• держите общий код под одним согласованным именем
• избегайте расплывчатых ярлыков вроде misc, stuff, old или new
• называйте места для тестов так, чтобы они указывали на покрываемый код

Затем переименовывайте по одной зоне за раз. Сделайте папку API на этой неделе, воркер‑джобы на следующей, а тесты — потом. Узкое изменение легче ревьюить, откатить и вызывает больше доверия у команды.

После каждого переименования исправляйте скучные части сразу. Обновите импорты, алиасы путей, сборочные скрипты, команды тестов и CI в одном pull request. Запустите приложение, прогоните тесты и убедитесь, что редактор и инструменты поиска находят перемещённые файлы.

Это важно, потому что модели выводят намерение из имён. Если один пакет называется billing, другой — payments-core, а третий — money, ассистент будет догадываться. Иногда он ошибается так, что выглядит правдоподобно.

Затем держите дисциплину. Попросите команду использовать новые имена в каждом PR и пресекайте возврат старых паттернов. Часто простого комментария в ревью достаточно: используйте согласованное имя папки и переместите файл.

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

Размещайте тесты так, чтобы намерение оставалось очевидным

Тесты должны быстро отвечать на один вопрос: что доказывает этот файл? Когда тесты разбросаны, люди и ассистенты начинают догадываться. Эта догадка порождает дублирование покрытия, пропущенные кейсы и правки не в том месте.

Выберите одно правило для unit‑тестов и соблюдайте его везде. Можно хранить unit‑тесты рядом с проверяемым модулем или держать их в одном месте, например tests/unit. Оба подхода работают. Проблемы начинаются, когда один пакет использует specs, другой — __tests__, а третий прячет тесты в корне репозитория.

Простой расположение обычно работает лучше:

• unit‑тесты рядом с кодом или в tests/unit
• integration‑тесты в tests/integration
• каждый пакет использует один шаблон имён файлов, например test_auth.py или auth.test.ts
• фикстуры и моки лежат в поддерживающих папках с понятными именами вроде expired_card_fixture.json или payment_gateway_mock.ts

Медленные тесты должны иметь своё место. Если тест общается с базой, очередью, файловой системой или внешним API, считайте его интеграционным. Держите такие тесты отдельно от быстрых unit‑проверок, чтобы разработчики могли часто запускать быстрые проверки и оставлять медленный набор для больших изменений.

Имена внутри папок с тестами важны так же, как и сами папки. data.json ничего не говорит. user_with_no_subscription_fixture.json подскажет, для какого кейса этот файл, ещё до открытия. То же и для моков: stripe_mock.ts понятно, а helper2.ts — нет.

Небольшой стартап‑репо показывает это ясно. Поместите чистые проверки итогов заказов в orders/test_totals.py, тесты флоу чек‑аута — в tests/integration/orders/test_checkout.py, а общие хелперы — в tests/support/fake_payment_gateway.py. Ассистент сможет добавить тест без лишних раздумий, где он должен жить.

Когда папки, имена файлов, фикстуры и моки следуют одному шаблону, репо становится спокойнее. Меньше времени уходит на объяснение намерения, и ассистент реже совершает ошибочные правки.

Небольшая зачистка в стартап‑репо

В одном раннем стартапе было три бэкенд‑папки: api, backend2 и old-service. Во всех трёх ещё был живой код. Когда нужно было править биллинг или логин, открывали две‑три папки, прежде чем находили реальную точку входа. Ассистент читает этот беспорядок так же, как новый сотрудник: он догадывается.

Фронтенд имел ту же проблему. Некоторые экраны жили в ui, другие — в frontend-app, а разделяемые части — в третьей папке с расплывчатым названием. Одно имя должно означать одно и то же каждый раз.

Небольшая зачистка решила большую часть проблем:

before:
api/
backend2/
old-service/
ui/
frontend-app/
tests/
src/__tests__/

after:
services/app/
web/app/
packages/shared/
packages/shared/tests/

Теперь код сервисов имеет одно место. Старые бэкенд‑папки либо перемещают в services/app, либо удаляют после короткой трансции. Веб‑клиент тоже имеет один дом, и больше никто не спрашивает, принадлежит ли новая страница ui или frontend-app.

Расположение тестов важно не меньше. Некоторые команды держат тесты рядом с каждым пакетом. Другие — имеют одно дерево tests/, которое зеркалит продакшен‑код. Оба подхода могут работать. Проблемы начинаются, когда репозиторий использует оба стиля без правила.

После переименования ассистент перестаёт предлагать новую папку backend-v3 или кидать тесты в случайные топ‑левел пути. Он открывает правильные файлы раньше, предлагает импорты из нужного пакета и пишет более компактные диффы. Ревью становится проще почти сразу.

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

Ошибки, которые оставляют репо трудным для чтения

Большая часть хаоса появляется из‑за откладывания небольшой зачистки. Команда переименовала services в apps, затем оставила services_old, legacy-services и несколько алиасов импортов, чтобы ничего не сломать. Люди перестали доверять названиям папок. Ассистент будет доверять им и начнёт предлагать правки не в том месте.

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

Смешивание сгенерированных артефактов с исходным кодом — ещё одна распространённая ошибка. Если генерируемые файлы, packaged assets, отчёты покрытия и исходники лежат рядом, любой поиск становится шумным. Люди тратят время. AI‑инструменты теряют контекст. Держите исходники в одном месте и выводы — там, где команду можно игнорировать.

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

Ещё одна частая ошибка — оставлять дублирующиеся имена после частичного рефактора. Если payments, billing и invoice-core содержат части одного и того же воркфлоу, структура всё равно заставляет догадываться. Ассистент будет делать то же самое.

Быстрая проверка перед тем, как просить код

Ассистент читает ваше репо как новый коллега: смотрит имена папок, расположение тестов и паттерны файлов, чтобы угадать, куда должно идти изменение. Если эти сигналы шумны, он угадает неправильно.

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

Сделайте быструю проверку перед тем, как просить код:

• найдите основную папку приложения быстро
• проверьте, соответствуют ли имена модулей коду внутри них
• выберите один паттерн тестов и соблюдайте его
• отделите скрипты, сгенерированные файлы и документацию от продуктового кода
• опишите структуру в пяти коротких предложениях

Последняя проверка хорошо работает, потому что её трудно подделать. Если вы сможете сказать: «Веб‑приложение в apps/web. Общий код в packages. Тесты рядом с фичами. Сборочные скрипты — в scripts. Сгенерированные клиенты — в generated», то репо, скорее всего, достаточно прозрачно для корректной работы ассистента.

Небольшие правки важны. Переименование helpers в email, перенос случайных shell‑файлов в scripts или сведение разбросанных тестов в один предсказуемый паттерн может сэкономить много переписок в промптах.

Что исправлять дальше

Если хотите улучшить результаты от AI‑инструментов, не начинайте с глобального рефактора. Начните с мест, где ассистент чаще всего ошибается. В большинстве команд это расплывчатые папки вроде misc, helpers и temp, дублирующиеся имена модулей и тесты, разбросанные по разным паттернам.

Именно эти места создают ежедневное сопротивление. Модель видит три возможных места для одного и того же изменения и выбирает то, что выглядит правдоподобно. Потом вы тратите время на перемещения файлов, исправления импортов и снова объясняете правило.

Короткий план зачистки лучше большого рефактора:

• слейте «ловушки‑вещи» в более понятные дома
• переименуйте модули, которые называются одинаково, но значат разное
• переместите разбросанные тесты, чтобы каждая фича следовала одному шаблону
• удалите старые папки, оставшиеся после прежних переписок

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

Затем включите эти правила в код‑ревью. Ревьюеры должны поправлять, когда кто‑то добавляет ещё одну папку utils2, кладёт интеграционные тесты в область unit или создаёт новый паттерн именования для срочной задачи. Маленькие исключения распространяются быстро.

Это часто непривлекательная работа, которая делает AI‑помощь действительно полезной. Если нужна внешняя помощь, Oleg на oleg.is работает со стартапами и небольшими командами над AI‑first инженерными настройками: структура репо, границы модулей, размещение тестов и правила, которые мешают ассистентам гадать.

Следующая цель зачистки проста: найдите папку, которая вызывает наибольшие сомнения, переименуйте её и закрепите правило в ревью.