Структурируйте проект так, чтобы AI мог в нём ориентироваться

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

• Держите предсказуемую структуру. Исходники в одном месте, тесты рядом с исходниками или зеркально к ним, конфиг — в корне.
• Используйте ясные, описательные имена. calculateMonthlyInvoiceTotal лучше, чем calc2. AI использует имена как подсказки.
• Предпочитайте файлы поменьше. Файл в 200 строк проще менять корректно, чем в 2000, — для вас обоих.
• Держите связанное рядом. Когда код фичи, её стили и тесты лежат вместе, AI собирает контекст за одно чтение.
• Держите ясную точку входа. Единое очевидное место, где приложение стартует, даёт AI нить, за которую можно потянуть, когда он составляет карту проекта.

Типичная, дружественная к AI структура может выглядеть так:

my-app/
├── AGENTS.md            # правила и контекст проекта для AI
├── README.md            # что за проект, как его запускать
├── .env.example         # описывает нужные секреты (без значений)
├── .gitignore           # исключает .env, сборку, node_modules
├── package.json         # скрипты: dev, test, lint, build
├── src/
│   ├── features/
│   │   └── invoices/    # код + тесты одной фичи, вместе
│   ├── lib/             # общие помощники
│   └── index.ts         # точка входа
└── tests/               # сквозные / интеграционные тесты

Выгода нарастает как сложный процент: чем легче вашему AI ориентироваться в проекте, тем меньше и хирургичнее становятся его изменения. Хорошо организованный репозиторий позволяет AI тронуть три нужных файла вместо того, чтобы гадать по тридцати, — а значит, меньшие diff'ы, меньше происшествий и ревью, которые вы реально можете прочитать. Если вы замечаете, что AI делает размашистые, расфокусированные правки, настоящий виновник часто — структура, а не промпт.