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

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

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

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

my-app/
├── AGENTS.md            # project rules & context for the AI
├── README.md            # what the project is, how to run it
├── .env.example         # documents needed secrets (no real values)
├── .gitignore           # excludes .env, build output, node_modules
├── package.json         # scripts: dev, test, lint, build
├── src/
│   ├── features/
│   │   └── invoices/    # code + tests for one feature, together
│   ├── lib/             # shared helpers
│   └── index.ts         # entry point
└── tests/               # cross-cutting / integration tests

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