Правила проекта в Claude Code: как передать контекст и проверить его

Практикум Романа Ботана · Автомато

Выберите один рабочий проект и выпишите договорённости, которые приходится повторять. Соберём из них короткую инструкцию и проверим её действие на реальной задаче.

Результат работы: Короткий CLAUDE.md с полезными правилами.

Материал рассчитан на последовательную работу. Откройте исходники рядом со статьёй, выполняйте запросы по одному и сверяйте промежуточный результат. Содержание поможет вернуться к нужному этапу.

Когда проекту нужны постоянные инструкции

Вы второй раз объясняете агенту, где лежат исходные данные, каким способом запускается проверка и какие файлы нельзя менять в текущей задаче. В следующей сессии объяснение повторяется. Если такие сведения устойчивы и относятся ко всему проекту, их удобно собрать в коротком рабочем файле.

CLAUDE.md — файл инструкций, который Claude Code использует как контекст проекта. В нём можно зафиксировать команды, структуру, принятые соглашения и известные особенности. Полезность определяется тем, какие решения изменятся после чтения: куда агент положит новый файл, какой тест запустит, как различит локальную проверку и рабочую публикацию.

Что получим после руководства

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

Инструкции являются контекстом для модели. Они помогают направлять работу, но не заменяют технические разрешения, тесты и контроль результата. Фраза в Markdown сама по себе не блокирует доступ к базе данных. Для ограничений с серьёзными последствиями нужны соответствующие настройки среды и приложения.

Исходный материал предлагает закреплять стек, соглашения, структуру файлов, Git, тесты и особенности проекта. Эту основу мы сохраняем. При этом каждое техническое правило должно отражать реальный проект. Чужой пример с определённой библиотекой или версией нельзя переносить автоматически.

Начните с одной повторяющейся ошибки или потери времени. Найдите факт, который агенту было бы полезно знать заранее. Сформулируйте его так, чтобы можно было проверить выполнение на небольшой задаче. После успешного теста добавляйте следующие правила, сохраняя файл компактным и понятным.

Что хранить в CLAUDE.md и что вынести отдельно

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

Представьте нового сотрудника, который получил небольшую задачу. Какие пять вещей ему нужно узнать до первого изменения? Например, приложение запускается одной командой; общие компоненты лежат в определённой папке; тексты утверждены; тестовые данные отделены от рабочих; публикация выполняется через согласованный процесс. Это хорошие кандидаты для короткого файла.

Правило, справка и процедура

Правило задаёт устойчивое поведение: «Используй существующий компонент формы». Справка объясняет устройство конкретной части системы. Процедура описывает многошаговый сценарий, например выпуск новой версии. Они могут храниться отдельно и подключаться по необходимости. Так агент получает подробности тогда, когда они относятся к задаче.

Секреты, токены и пароли в инструкции не помещают. Если для работы нужна переменная окружения, укажите её назначение и способ безопасной настройки без значения. Личный адрес тестового сервиса может относиться к персональным настройкам, а общая команда проверки — к командному проектному файлу.

Состояние конкретной текущей задачи также лучше отделять от устойчивых правил. Фраза «сегодня ждём ответ клиента» быстро устаревает. Фраза «утверждённые цены находятся в этом источнике» сохраняет пользу дольше, если источник действующий. При необходимости укажите владельца и способ актуализации.

Изучи проект только для чтения и предложи содержание CLAUDE.md. Выдели устойчивые факты, которые влияют на выполнение задач: стек, каталоги, команды, соглашения и границы сред. Подтверди каждый факт существующим файлом или наблюдением. Подробные процедуры и временное состояние вынеси в предложения для отдельных материалов. Секреты не открывай и не включай. Сначала покажи проект текста для проверки.

Такой запрос помогает получить основу из реального окружения. После ответа руководитель проверяет смысл, технический специалист — команды и границы. Лишь затем файл становится рабочей инструкцией.

Где располагаются инструкции и как проверить загрузку

В Claude Code используются несколько областей инструкций. Пользовательские предпочтения могут находиться в ~/.claude/CLAUDE.md, проектные — в CLAUDE.md или .claude/CLAUDE.md. Также существуют локальные и организационные механизмы. Правила обнаружения зависят от расположения и текущей версии инструмента. Официальная документация памяти Claude Code.

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

Выбираем область действия

Факт о конкретной папке проекта должен храниться рядом с проектом. Предпочтение по языку общения может относиться к личному уровню. Особенность отдельного модуля полезно разместить ближе к нему или подключать при работе с этим модулем. Так случайное соглашение одного репозитория не распространится на все остальные.

Перед добавлением нового файла найдите существующие инструкции. Возможно, команда уже использует CLAUDE.md, AGENTS.md или другие поддерживаемые механизмы. Дублирование создаёт риск расхождений. Сначала выясните текущую договорённость и обновите подходящий источник.

Проверка загрузки должна быть явной. Используйте доступный в текущей версии просмотр контекста или памяти и посмотрите, какие файлы действительно включены. Затем попросите агента назвать применимые правила с указанием источника. Само существование файла в Finder не подтверждает, что агент его прочитал.

Проверь, какие проектные инструкции доступны в текущей сессии. Перечисли обнаруженные файлы и их области действия. Покажи только относящиеся к задаче правила и противоречия между ними. Если автоматическая загрузка не подтверждена, скажи об этом. Ничего не меняй. После проверки предложи одно место для согласованных правил проекта.

Для первого теста начинайте новую сессию после сохранения инструкции, если это требуется средой. Уточните рабочую папку. Если запуск происходит из другого места, набор обнаруженных файлов может отличаться. Этот простой шаг часто объясняет, почему корректный текст не повлиял на работу.

Описываем стек и команды по фактам проекта

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

Для руководителя достаточно понимать назначение элементов: язык, веб-фреймворк, хранилище данных, способы проверки. Технический специалист может записать точные названия и команды. Версии указывайте там, где они влияют на поведение, и поддерживайте их актуальность.

Команда должна быть исполнимой

Фраза «запускай тесты» оставляет вопросы: какие, из какой папки и с какими зависимостями? Лучше записать подтверждённую команду и область проверки. Например, команда проверяет типы, другая выполняет модульные тесты, третья собирает приложение. Они подтверждают разные свойства результата.

Если тест зависит от внешнего сервиса, это надо обозначить. Агент должен различать ошибку кода и недоступность окружения. Например, отсутствие тестовой базы не доказывает, что новая функция сломана, но оставляет проверку незавершённой. Итоговый отчёт должен честно описывать этот предел.

## Проверки

- Команды запускаются из корня проекта.
- Используй команды, определённые в конфигурации проекта.
- Для затронутой логики выполни соответствующие тесты.
- Если проверка требует недоступной среды, укажи это в результате.

Это учебный каркас. В рабочем файле добавьте реальные команды после проверки. Не копируйте название тестового инструмента только потому, что оно встречается в примере исходника.

Проверь раздел стека и команд в проекте CLAUDE.md. Сверь названия инструментов с конфигурацией и существующими файлами. Для каждой команды укажи рабочую папку, назначение и необходимые условия. Устаревшие или неподтверждённые команды пометь. Запускай только разрешённые безопасные проверки, относящиеся к текущей задаче. Не устанавливай новые зависимости ради заполнения списка.

После такого прохода файл становится полезной навигацией. Агент получает конкретный способ проверить работу, а человек понимает, что именно подтверждено каждым результатом.

Структура файлов и границы изменений

Краткая карта проекта помогает размещать изменения последовательно. Укажите несколько важных каталогов и их назначение. Например, страницы интерфейса, общие компоненты, бизнес-логика, тесты и исходные материалы. Перечислять каждый файл обычно избыточно: агент может найти детали при выполнении задачи.

Для существующего проекта особенно важно сохранить чужую работу. Перед изменением агент должен посмотреть состояние файлов и различить уже имеющиеся правки. Это уменьшает риск случайно перезаписать изменения коллеги. В инструкции можно закрепить обязательную проверку состояния и минимальный объём редактирования.

Что считать относящимся к задаче

Если пользователь просит исправить подпись кнопки, это не повод перестраивать весь интерфейс. Если просит обновить расчёт, агент может затронуть связанные тесты и необходимую логику. Правило должно направлять к достаточному объёму работы, сохраняя чужие и несвязанные изменения.

Полезно назвать источники истины. Утверждённый текст может храниться в документе, схема данных — в определённом модуле, дизайн — в библиотеке компонентов. Тогда агенту проще понять, что использовать при расхождении нескольких похожих файлов. Если источник устарел, это вопрос владельцу проекта.

## Размещение изменений

- Перед правкой изучи существующее решение в затронутом модуле.
- Повторно используй общие компоненты проекта.
- Сохраняй несвязанные изменения других участников.
- Новые файлы добавляй только для результата задачи и нужной проверки.

Каркас задаёт направление, но рабочий документ должен содержать конкретные пути. Например, «общие формы находятся в components/forms/» полезнее общей фразы, если этот каталог действительно существует.

Подготовь краткую карту проекта для CLAUDE.md. Выдели пять-семь каталогов, которые чаще всего нужны исполнителю. Укажи назначение и один проверенный пример файла. Отдельно назови источники утверждённых текстов, схем и компонентов, если они существуют. Дубли и устаревшие материалы покажи как вопросы. Изменения в структуре папок пока не выполняй.

Проверьте карту небольшой задачей: попросите агента назвать место будущего изменения и объяснить выбор. Это показывает, помогает ли инструкция ориентироваться в проекте до написания кода.

Конкретные соглашения и полезные примеры

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

В исходнике встречаются примеры про именованные экспорты, ограничения типов и определённые библиотеки. Их следует рассматривать как демонстрацию конкретности. Для другого стека эти соглашения могут быть неуместны. Не добавляйте правило, которое техническая команда не принимала.

Когда нужен образец

Если формат ответа API нестандартный, покажите ссылку на действующий обработчик или короткий эталон. Для документа можно приложить образец раздела. Для отчёта — структуру результата. Пример должен быть небольшим и актуальным, чтобы агент видел суть без большого объёма посторонней логики.

Слишком жёсткие механические ограничения иногда вредят. Требование одинаковой длины всех функций не учитывает смысл. Лучше объяснить принцип разделения ответственности и сослаться на удачный существующий пример. Проверяемость важна, но она должна поддерживать качество решения.

Перепиши эти общие пожелания в конкретные проектные правила: [список]. Для каждого укажи наблюдаемое поведение и способ проверки. Подтверди правило существующим соглашением или примером проекта. Там, где решения команды ещё нет, предложи вопрос. Сократи дубли. Сохрани небольшие примеры только для правил, которые трудно понять по одной фразе.

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

После добавления примера убедитесь, что он не содержит случайных секретов, старых доменов или временных идентификаторов. В постоянной инструкции случайная деталь получает слишком большой вес и может повторяться в новых результатах. Оставляйте только то, что действительно требуется воспроизводить.

Особенности проекта: превращаем повторяющуюся ошибку в правило

У каждого проекта есть детали, которые легко пропустить: нестандартный путь к клиенту базы, особый способ авторизации, исключение в обработке события или зависимость от окружения. Такие сведения полезно выделить в короткий раздел особенностей. Каждая запись должна объяснять условие и правильное действие.

Не начинайте с догадки о причине. Сначала воспроизведите ошибку и подтвердите, почему она возникла. Затем сформулируйте правило, предотвращающее повтор. Иначе инструкция закрепит ошибочную диагностику и будет направлять будущие изменения в неверную сторону.

Образец записи

«В тестовом отчёте даты сравниваются в часовом поясе проекта; входные значения содержат смещение. Перед группировкой используй существующую функцию нормализации». Такая запись полезна, если именно это подтверждено кодом и тестом. Она связывает особенность с действием и не требует пересказывать всю историю инцидента.

С правилами для вебхуков, авторизации и публичных переменных будьте особенно точны. Исключение из одного механизма проверки не означает отсутствие защиты вообще. Если маршрут проверяет подпись внешнего события, укажите именно эту границу и существующую реализацию. Публичные клиентские переменные не должны содержать секреты.

По итогам исправленной ошибки предложи одну запись для раздела особенностей CLAUDE.md. Укажи подтверждённое условие, правильное действие и проверку. Сошлись на актуальный файл проекта. Историю отладки сократи. Если вывод основан только на предположении, оставь его вне постоянных правил до подтверждения. Покажи формулировку для принятия владельцем проекта.

Повторная ошибка — хороший сигнал пересмотреть инструкции, но иногда причина лежит в тестах или интерфейсе инструмента. Если действие можно надёжно проверить автоматически, добавьте соответствующую проверку в рамках задачи. Текстовая заметка и технический контроль могут дополнять друг друга.

Раз в некоторое время просматривайте особенности на актуальность. После обновления библиотеки исключение может исчезнуть. Устаревшее предупреждение способно мешать нормальному решению так же, как отсутствие важной информации. У каждой значимой записи должно оставаться понятное основание.

Git, среды и действия с последствиями

Проектный файл может описывать принятый способ работы с Git: ветки, проверку изменений и подготовку результата к обзору. Названия команд и порядок должны соответствовать текущему процессу команды. Если работа проходит через запросы на слияние, укажите, что считается готовым к передаче ревьюеру.

Отдельно обозначьте среды. Локальный запуск, тестовый стенд и рабочий сайт имеют разное значение. Успешная сборка на компьютере подтверждает локальную проверку. Для рабочего изменения потребуется пройти пользовательский путь на целевом сайте и проверить связанные действия.

Ясные границы полномочий

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

Технические ограничения задаются настройками среды, правами аккаунтов и механизмами контроля. CLAUDE.md не является полноценной системой авторизации. Если определённое действие должно быть невозможно, это нужно обеспечивать соответствующим уровнем защиты и проверять отдельно.

## Границы сред

- В отчёте различай локальную проверку и проверку на рабочем сайте.
- Перед публикацией установи цель, способ выпуска и возврата.
- Сохраняй исходные данные и несвязанные изменения.
- Внешние действия выполняй в пределах явно заданной задачи.

В реальном проекте дополните каркас конкретными средами и существующим способом выпуска. Секретные адреса и значения доступа храните в предусмотренных защищённых местах.

Проверь раздел полномочий и сред. Укажи, какие действия относятся к чтению, локальной правке, публикации и изменению внешних данных. Устрани противоречия и избыточные повторные подтверждения. Сопоставь текст с фактическими правами среды. Отдельно покажи ограничения, которые требуют технического контроля. Не меняй инфраструктуру и доступы в рамках этой проверки.

Так команда получает понятные правила сотрудничества. Агент знает, какую работу завершать самостоятельно, а человек видит моменты, где решение связано с реальными последствиями.

Собираем первый CLAUDE.md без лишнего объёма

Первый вариант может состоять из назначения проекта, стека, карты файлов, проверок, соглашений и особенностей. Не стремитесь заполнить все разделы одинаковым количеством пунктов. Если особенность одна, достаточно одной. Если команда ещё не выбрала соглашение, оставьте вопрос вместо выдуманного правила.

Соберите подтверждённые сведения и удалите повторы. Каждую строку проверяйте вопросом: какое решение агента изменится благодаря этому пункту? Если ответ отсутствует, возможно, фраза относится к общему описанию или справочному материалу. Постоянный контекст должен быть экономным.

Учебный каркас

# Проект: внутренняя страница заявок

## Назначение

Сотрудники просматривают заявки и отмечают следующий шаг.

## Стек и файлы

Укажи подтверждённые технологии и основные каталоги.

## Проверки

Укажи реальные команды и пользовательские сценарии.

## Соглашения

Используй принятые компоненты и сохраняй утверждённые тексты.

## Особенности

Добавь только проверенные ограничения проекта.

Этот каркас содержит подстановки и предназначен для заполнения. В рабочем файле таких подсказок оставаться не должно. Если фактов пока нет, агент сначала исследует проект и показывает предложения.

Подготовь первый CLAUDE.md из согласованных фактов. Сделай короткие разделы: назначение, стек, файлы, проверки, соглашения, особенности и границы сред. Каждое правило сформулируй один раз. Используй конкретные пути и команды только после подтверждения. Подробные процедуры замени ссылками на существующие материалы. Покажи готовый текст и список открытых вопросов до записи в проект.

После принятия сохраните файл в согласованном месте и проверьте загрузку. Дайте агенту небольшую задачу, для которой применимы два-три правила. Так вы получите обратную связь о качестве инструкции до расширения на весь проект.

Если файл уже существует, редактируйте его точечно. Полная замена может удалить важное соглашение, которое не проявилось в текущей задаче. Сравните старую и новую версии, выделите смысловые изменения и проверьте их с владельцем проекта.

Проверяем применение на обычных и пограничных задачах

Проверка должна показать фактическое поведение. Агент может пересказать правила правильно, но затем создать файл в другом каталоге или пропустить тест. Поэтому после подтверждения загрузки дайте практическую задачу и сравните действия с ожиданием.

Начните с обычного случая. Например, добавить небольшое поле в учебную форму, используя существующий компонент. Проверьте размещение файлов, стиль, сохранность текста и выполненные проверки. Затем дайте пограничный случай: задача затрагивает модуль с отдельной особенностью или требует недоступной среды.

Последовательность действий: Сохранённые правила → Подтверждённая загрузка → Учебная задача → Проверка поведения.

Проверка противоречия

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

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

Выполни учебную задачу [описание] с учётом проектных инструкций. В начале кратко назови применимые правила. После выполнения покажи изменённые файлы, проверки и ограничения. Если запрос конфликтует с действующим соглашением, обозначь конкретный конфликт до зависимого изменения. Сохраняй несвязанные правки. Не расширяй задачу дополнительной перестройкой проекта.

Сравните ожидаемое и фактическое поведение. Если правило проигнорировано, сначала проверьте загрузку и ясность формулировки. Затем посмотрите, нет ли противоречащей инструкции. Лишь после этого меняйте текст. Беспорядочное добавление одинаковых запретов увеличивает объём и не объясняет причину ошибки.

Сохраните несколько коротких контрольных задач. Они пригодятся после обновления инструкции или инструмента. Для простого проекта достаточно обычного случая, одного исключения и проверки сохранности несвязанных изменений.

Учебный бизнес-пример: внутренняя страница заявок

Допустим, компания использует внутреннюю страницу для обработки обращений. Разработчики уже создали общую форму, согласовали статусы и настроили локальные проверки. Агент несколько раз добавлял собственный компонент и менял название статуса. Руководитель хочет сократить повторные исправления.

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

Порядок работы

Агент готовит проект CLAUDE.md по подтверждённым фактам. Команда проверяет формулировки и сохраняет файл. В новой сессии даём задачу добавить поле «Комментарий» на учебной ветке. Перед правкой агент называет используемый компонент и место схемы данных.

Образец результата: «Поле добавлено в существующую форму; статусы сохранены; проверены пустой комментарий, длинный текст и отправка с обязательными полями. Изменения находятся в двух файлах. Локальные проверки пройдены; рабочий сайт в этой задаче не обновлялся». Такой отчёт показывает и полезное поведение, и границу подтверждения.

Подготовь инструкции для проекта страницы заявок. Используй подтверждённые пути к общей форме, схеме полей и списку статусов. Зафиксируй сохранность утверждённых названий и проверку пользовательского сценария. Затем на учебной задаче добавь комментарий через существующий компонент. Покажи соблюдение правил и результаты локальных проверок. Публикация выполняется отдельным заданным действием.

Если агент снова создаёт собственный компонент, выясняем причину. Возможно, старый компонент действительно не поддерживает нужное поведение. Тогда требуется осмысленное изменение, а правило должно предусматривать объяснение такого случая. Абсолютное требование использовать любой старый компонент без оценки может мешать качеству.

После принятого изменения обновляем инструкцию только при появлении нового устойчивого факта. Само добавление поля обычно не требует расширять постоянный контекст. Так файл остаётся коротким и сохраняет полезные ориентиры для следующих задач.

Учебный бизнес-пример: проект отчётов для руководителя

Во втором примере команда регулярно готовит отчёт из выгрузки и заметок. В папке лежат входные материалы, шаблон и готовые результаты. Агент иногда смешивает периоды, переписывает утверждённые названия показателей и сохраняет новый файл поверх исходного. Проектные инструкции помогут закрепить порядок работы.

Сначала определяем источники: выгрузка содержит числа, заметки объясняют события, шаблон задаёт структуру. Период задаётся в каждом запросе. Исходники сохраняются, результат получает отдельное имя. Для каждого вывода требуется ссылка на исходный показатель или заметку.

Пример правил

«Сверяй период всех входных файлов до расчётов. Названия показателей сохраняй по шаблону. Суммы проверяй по контрольному итогу. Неизвестные причины изменений отмечай как гипотезы. Итоговый файл сохраняй в папку результатов». В рабочей инструкции указываются реальные пути и действующие названия.

Собери CLAUDE.md для проекта регулярных отчётов. Укажи роли входной выгрузки, заметок и шаблона. Зафиксируй проверку периода, сохранность названий показателей, отдельное сохранение результата и сверку контрольной суммы. Временные даты оставь параметрами запуска. Затем проверь инструкцию на учебном месяце, где один файл относится к другому периоду. Исходники сохраняй без изменений.

Образец корректного поведения: агент замечает, что заметка относится к предыдущему месяцу, и не использует её как объяснение текущего падения показателя. Он показывает вопрос и продолжает независимую часть расчёта. В результате числа и выводы имеют понятные основания.

После первого теста меняем период и набор данных. Если агент сохранил старый месяц в заголовке, ищем, где он закрепился: в шаблоне, памяти или самой инструкции. Исправляем источник, затем повторяем проверку. Это показывает, почему временные значения важно держать отдельно от устойчивых правил.

Для следующего сотрудника файл служит короткой картой процесса. Он видит, где исходные данные, что считается действующим шаблоном и как проверяется итог. Полная методика расчёта может храниться отдельно и открываться при необходимости.

Обновление, конфликты и уход за инструкциями

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

Периодически проверяйте противоречия. Один раздел требует сохранять структуру, другой предлагает перестраивать её автоматически. Глобальное предпочтение ссылается на инструмент, которого в проекте нет. Вложенный файл описывает старый модуль. Такие расхождения надо устранить, сохранив ясные области действия.

Как менять правило

Сначала сформулируйте проблему и приведите конкретный пример. Затем измените один пункт и повторите контрольную задачу. Если одновременно переписать весь файл, будет трудно понять, какая правка повлияла на результат. Для командного проекта смысловые изменения удобно просматривать вместе с обычными изменениями проекта.

Проведи ревизию CLAUDE.md и связанных инструкций. Найди устаревшие факты, дубли, противоречия и слишком общие требования. Для каждого предложи конкретную правку с основанием. Сохрани действующие ограничения и подтверждённые особенности. Подробные справки предложи вынести отдельно. После принятия изменений повтори контрольные задачи и сравни поведение.

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

Последовательность действий: Подтверждённая проблема → Одна точная правка → Повтор контрольного случая → Принятая версия правил.

При передаче проекта новому подрядчику попросите его выполнить небольшую задачу по инструкции. Возникшие вопросы покажут, где текст слишком зависит от памяти автора. Добавляйте только нужные уточнения. Хороший файл помогает стартовать и направляет к подробностям, сохраняя возможность исследовать реальный код и данные.

Упражнение с ответом и первый результат

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

Проверьте загрузку файла в новой сессии. Дайте небольшую задачу, в которой нужно применить соглашение и выполнить проверку. После завершения сравните поведение с правилами. Отдельно попросите агента назвать невыполненные проверки и причины.

Образец ответа

Успешный результат выглядит так: «Файл инструкций обнаружен в согласованной области проекта. Агент использовал существующий каталог и сохранил идентификатор строкой. Выполнена подтверждённая команда проверки. Исходный файл остался неизменным, результат сохранён отдельно. Внешняя система в упражнении не использовалась». Это конкретные наблюдения, по которым можно принять работу.

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

Для рабочего внедрения выберите одну повторяющуюся проблему и закрепите короткое правило. Через несколько задач оцените, стало ли меньше исправлений. Сохраняйте подтверждённые полезные пункты, удаляйте устаревшие и поддерживайте связь с реальными файлами. Так инструкция постепенно станет рабочим контекстом команды.

Дополнительная проверка: правило перестало работать

Представьте, что после обновления проекта агент снова сохраняет результат в старую папку. Сначала посмотрите, откуда взялся путь. Возможно, он остался в примере, вложенной инструкции или шаблоне. Исправление только главного файла оставит конфликт. Найдите все относящиеся к задаче упоминания и определите действующий источник.

Затем проверьте, существует ли новый каталог и доступен ли он среде. Ошибка сохранения иногда приводит к тому, что агент выбирает другое место. В таком случае инструкция должна требовать сообщить о проблеме и показать фактический путь результата. Пользователь должен понимать, где находится файл, даже если желаемое место оказалось недоступным.

После исправления повторите ту же задачу с новым именем результата. Проверьте наличие файла и его открытие. Такой короткий цикл показывает, что проблема устранена в реальном действии. Устное обещание агента использовать новый путь на следующем запуске полезно только как намерение.

Как руководителю принимать текст инструкций

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

Отдельно обратите внимание на абсолютные формулировки. Иногда правило действительно должно действовать всегда, например сохранность секретов. Иногда оно описывает предпочтительный способ, у которого бывают обоснованные исключения. Укажите, как агент должен поступить при таком исключении: объяснить причину, предложить конкретный вариант и сохранить проверку результата.

Объём инструкции оценивайте по пользе. Если сотрудник может быстро найти команду, каталог и ограничение, структура удобна. Если для небольшой правки надо прочитать десятки страниц общей теории, важные факты теряются. Перенесите подробное обучение в отдельный документ, оставив короткую ссылку и условие его использования.

После принятия файла сообщите команде, где находится действующая версия и кто обновляет её при изменениях. Это простое организационное действие помогает сохранить единые правила между человеком, агентом и следующим подрядчиком.

Последнюю проверку выполните на свежей сессии: так станет видно, какие правила доступны агенту без пояснений из предыдущего разговора.

Источники и границы материала

Продолжить практику

• Повторяемая задача как навык ИИ: от инструкции до проверки
• Один урок для разных уровней: как адаптировать обучение с ИИ

Автор — Роман Ботан, Автомато. Практикумы и обучение · Новые разборы в канале @aibotan47.