Файлы-инструкции для ИИ-ассистента: как он начинает писать по правилам проекта

Когда я подключаю ИИ-ассистента к проекту, первые пару дней он ведёт себя как новый стажёр без доступа к вики. Предлагает поставить лишнюю зависимость, путает порты, запускает сборку не той командой. Причина всегда одна: модель не знает правил, которые для меня давно очевидны. Лечится это файлом-инструкцией — обычным текстом в корне репозитория, который ассистент читает перед работой.

Что это за файл и зачем он нужен

Файл-инструкция — это документ (чаще всего AGENTS.md, CLAUDE.md или просто LOCAL SETUP.md), где я один раз описываю правила проекта человеческими словами. Стек, команды, порты, запреты, соглашения по коду. Ассистент подтягивает его в контекст и дальше держит эти правила в голове сам, без напоминаний в каждом сообщении.

Без такого файла я повторяю одно и то же по десять раз за сессию. С ним — пишу правило единожды и забываю. Время экономится напрямую, и заметно это уже к концу первого дня.

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

Для HytaleServers.tech (мониторинг серверов Hytale на Next.js) у меня лежит блок с командами. Выглядит буквально так:

npm run dev     # dev-сервер на localhost:3000
npm run build   # прод-сборка
npm run start   # прод-сервер, порт 3003
npm run lint    # ESLint
npm run deploy  # деплой на VPS через SSH

Отдельной строкой — важное предупреждение: тестов в проекте нет, после каждого изменения проверяем руками. Это правило спасает от классики, когда ассистент бодро рапортует «готово», а сам ничего не запускал. Прочитал строку про ручную проверку — и сам предлагает мне открыть страницу и посмотреть.

Там же держу описание стека: Next.js 16.1.1, React 19.2.3, TypeScript, Tailwind CSS 4, Supabase. Когда ассистент знает версии, он перестаёт подсовывать устаревший синтаксис и старые паттерны роутинга.

Из чего собрать такой файл

Структуру я довёл до нескольких обязательных разделов. Кладу в файл именно это:

• Обзор проекта — название, одно предложение о сути, стек, порты для локали и прода. У меня это 3000 локально и 3003 на VPS, и ассистент их больше не путает.
• Команды — весь список npm run с комментариями. Модель берёт команду отсюда и ничего не выдумывает.
• Запреты и договорённости — «тестов нет», «новую зависимость не ставим без обсуждения», «файлы миграций руками не трогаем».
• Пошаговая настройка окружения — для новых машин. В моём LOCAL SETUP первый шаг — проверка node --version с ожидаемым результатом v20 и выше. Ассистент прогоняет шаги по порядку и сам ловит, если версия старая.

Отдельный файл для передачи задачи

Инструкции пригождаются не только на старте. Когда я передавал клиентскую часть проекта QoLab в отдельную сессию, я собрал файл-хендофф: базовый URL сервера https://api.qolab.space, два эндпоинта с телами запросов (/activate и /refresh), заметка про домен на VPS и TLS от Let's Encrypt. Всё, чтобы новая сессия ассистента вошла в задачу с нуля и не задавала вопросов, ответы на которые я уже знаю.

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

Как внедрить у себя за десять минут

Порядок простой:

1. Создайте в корне проекта файл AGENTS.md (или CLAUDE.md — смотрите, что читает ваш ассистент).
2. Выпишите команды сборки и запуска с портами.
3. Добавьте стек с версиями.
4. Отдельным блоком — запреты и особенности, которые уже кусали вас на практике.
5. Проверьте: дайте ассистенту задачу и посмотрите, берёт ли он команды из файла.

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