Пишите репозиторные инструкции как эксплуатационный README
Полезный instruction file содержит только то, что нельзя надёжно вывести из кода: реальные команды, нестандартные ограничения, архитектурные границы, опасные зоны и формат доказательства. Всё остальное - шум, который вытесняет полезное.
Вот AGENTS.md companion-проекта: коротко про scope, verification и safety.
# Project instructions
## Scope
- This repository is the runnable companion to the Russian book about coding agents.
- Preserve strict TypeScript and the dependency-free runtime.
- Make the smallest patch that satisfies the task contract.
## Verification
- Run `npm run check` after code changes.
- Treat command output as evidence. Do not claim success without the exit status.
- Do not weaken tests, TypeScript flags, path checks, or command allowlists to make a check pass.
## Safety
- Never execute a command assembled as one shell string.
- Keep `shell: false`, a contained working directory, a minimal environment, a timeout, and an output limit.
- Resolve and validate every user-controlled path before reading or writing.
- Never add credentials, tokens, private keys, or real `.env` files.Стоит включить команды install, focused test и full check; версии runtime и package manager; границы модулей и source of truth; запрещённые операции и generated files; формат итогового отчёта. Не стоит включать общие советы вроде "пиши чистый код", полную документацию API, список каждого файла, требования, уже жёстко проверяемые линтером, и секреты.
Ключевой приём - проверяемое правило вместо прилагательного.
Слабо · Проверяемо
- Пиши безопасно - Не собирай shell string; используй argv и
shell: false - Не ломай код - Запусти focused test, затем
npm run check - Меняй аккуратно - Не изменяй файлы вне согласованного write scope
- Следуй архитектуре - Business rules остаются в
src/domain; adapters не владеют ими
Anthropic рекомендует держать CLAUDE.md коротким и проверять каждую строку вопросом: приведёт ли её удаление к повторяющейся ошибке. Cursor советует focused, actionable и scoped rules, Codex - короткий практичный AGENTS.md. Это согласованная рекомендация документов, а не магическая длина.
Обновляйте после фактической ошибки. Каждое новое правило должно отвечать на наблюдаемое повторение. Если агент дважды запускает неправильную команду, добавьте правильную. Если правило больше не влияет на поведение, удалите или перепишите его.
Статичной инструкции хватает не всегда. Когда нужен порядок шагов с входами и stop conditions, процесс упаковывают в skill.