В проекте изменили способ запуска тестов, но в инструкции осталась старая команда. Новый агент выполняет её правильно — и получает неправильную проверку. В таком случае проблема не в точности следования промпту: источник указаний устарел.
Рассмотрим учебный репозиторий, где проверки выполняются внутри контейнера. Команда, записанная в документации, должна соответствовать реальному окружению проекта. Не переносите её в другой репозиторий только потому, что там тоже используется PHP.
Разделите сведения по сроку жизни
В сообщении о задаче остаются желаемое изменение, текущая ошибка и критерии приёмки. В общих инструкциях полезны устойчивые правила: где выполняются команды, как обращаться с рабочими данными, какие соглашения нельзя угадать из обычного знания стека.
Подробная процедура нужна для повторяемой работы с собственными шагами. Например, публикация контента включает проверку текста, предпросмотр, изменение статуса и сверку публичной страницы. Она не должна целиком загружаться в каждую задачу по CSS.
Это удобное разделение, а не утверждение, что существует ровно три разрешённых типа файлов. README, архитектурное решение, runbook, задача и инструкция агента могут дополнять друг друга. Важно понять, где находится источник конкретного правила и кто должен его обновлять.
Уточните, как инструмент получает инструкции
Названия AGENTS.md, CLAUDE.md и SKILL.md встречаются в разных рабочих процессах, но их загрузка и приоритет зависят от инструмента. Наличие файла не доказывает, что исполнитель его прочитал. Не распространяйте поведение одного продукта на все остальные.
Для начала можно явно попросить прочитать нужный документ и назвать применимые к задаче команды и ограничения. Если используется автоматическая загрузка, её механизм следует проверить по документации выбранного инструмента и наблюдаемому поведению. Не нужно добавлять одинаковые длинные инструкции во все файлы в надежде, что какой-нибудь сработает.
Перед работой прочитай README и docs/checks.md.
Назови команду проверки для текущей задачи и окружение её запуска.
Если инструкция расходится с конфигурацией проекта, покажи расхождение.
Не устанавливай зависимости и не меняй среду ради старой команды без разбора.Запишите то, что помогает принять следующее решение
Для учебного проекта достаточно короткого указателя: проверки выполняются в сервисе webserver; состав проверок описан в docs/checks.md; рабочая БД не используется для разрушительных тестовых операций. Подробную команду лучше хранить в одном месте, чтобы после изменения не искать пять копий.
Текст «пиши качественно» не помогает выбрать команду или обнаружить ошибку. Но и полный перечень всех моделей не всегда полезен в начальной инструкции. При задаче на уведомления агенту нужны относящиеся к ней входы и ограничения; остальная документация может подключаться по мере необходимости.
Размер документа сам по себе ничего не гарантирует. Короткий файл с неверным правилом хуже длинного, но актуального. Оценивайте каждую запись вопросом: какое конкретное неверное действие она помогает предотвратить или какое решение ускоряет?
Изменение команды должно менять её указатели
Предположим, в упражнении проверка раньше запускалась отдельной командой тестового раннера, а теперь проектный скрипт добавляет проверку формата и статический анализ. Это не просто переименование: состав подтверждаемого результата изменился.
При обновлении найдите все ссылки на старую команду, проверьте её назначение и оставьте старую форму только там, где она по-прежнему нужна, например для узкого запуска. Не заменяйте везде вслепую: команда полного набора и команда одного теста решают разные задачи.
Обновление инструкции:
— источник команды: конфигурация/скрипт текущего проекта;
— назначение: полный набор или узкая проверка;
— окружение: контейнер, рабочий каталог, отдельная тестовая БД;
— доказательство: фактически выполненный запуск или явная пометка
о том, что инструкция пока проверена только по коду;
— ссылки: убрать устаревшие дубли и обновить указатели.Не записывайте успешный запуск как вечное свойство проекта. После изменения зависимостей или окружения его нужно подтвердить снова. Полезно сохранить дату или версию проверки в рабочем отчёте, но не превращать публичную статью в повторяющийся блок служебных отметок.
Подробную процедуру подключайте по задаче
Если публикация или миграция состоит из устойчивой последовательности действий, вынесите её в отдельный документ. В общих инструкциях достаточно условия применения и ссылки. Формат скилла, его описание и способ активации — отдельная тема; само название каталога не обеспечивает выполнение процедуры.
Для изменения действующего сайта процедура должна сохранять данные: резервная копия, проверенный способ применения, сверка результата и план восстановления. Полный сброс production-БД не является обычным обновлением контента. Даже если такой совет остался в старом документе, его нужно остановить и исправить, а не переносить как обязательную традицию проекта.
Удаление правила тоже требует причины
Не ждите третьего повтора ошибки, чтобы записать известное ограничение. И не сохраняйте правило навсегда только потому, что оно когда-то было полезно. При изменении поведения просмотрите связанные инструкции: какие стали неверными, какие дублируют код, какие ещё защищают существенную границу.
В результате следующая сессия должна получить актуальный способ работы, а не архив всех прежних затруднений. Проверка проста: другой человек или новый агент находит нужную инструкцию, объясняет её назначение и может отличить выполненную проверку от предложенной.
