Инструкции в репозитории должны отвечать на практический вопрос агента: как запустить проект, где находится нужная логика, какие границы нельзя пересекать и какая проверка доступна. Не копируй README целиком и не записывай в инструкцию команды, которых ещё не сверил в конкретном проекте.
Шаблон с placeholders
Для нового репозитория можно начать с такого шаблона и заменить квадратные скобки после проверки файлов:
- Назначение: [кратко, для кого и что делает приложение].
- Структура: [путь к UI], [путь к API], [путь к тестам].
- Проверки: [точная команда из package.json/Makefile/README].
- Ограничения: [границы данных, API, миграций или секретов].
- Перед завершением: сообщи изменённые файлы, выполненные команды и их точный результат; незапущенную проверку пометь как незапущенную.
Пока placeholder не заменён, это не исполняемая инструкция. Не копируй пример команды в CI или prompt как будто она уже существует.
Где хранить и для кого
Формат зависит от coding agent. Cursor документирует проектные rules в .cursor/rules и поддержку AGENTS.md как markdown-варианта; GitHub Copilot различает repository instructions и path-specific instructions, причём применимость зависит от клиента и surface. Сверяй Cursor Rules и GitHub Copilot custom instructions, прежде чем полагаться на один формат для всех инструментов.
Постоянное правило вроде «не менять схему API без миграции» может жить в инструкции, если это действительно принято в проекте. Разовую задачу не превращай в постоянное правило. Для разных каталогов задай только те локальные ограничения, которые реально отличаются; после правки проверь область действия.
Как не заявить проверку, которой не было
Имена scripts нужно сверить с репозиторием. Если команда требует закрытый сервис или test database, запиши её как недоступную, а не объявляй PASS. Текст инструкции не запускает CI и не блокирует merge сам по себе; для обязательных проверок используй реальные CI rules и branch protection.
В конце diff убедись, что инструкция не содержит секретов, credential-bearing URL или личных данных. Самый полезный файл короток, обновляется вместе с проектом и объясняет ровно те решения, которые иначе агенту пришлось бы угадывать.