Коли проєкту потрібен CLAUDE.md: порада інженера Anthropic

У новому інтерв’ю Latent Space інженер Anthropic Тарік Шихіпар висловив незвичну для гайдів про Claude Code думку: новий проєкт іноді краще починати без CLAUDE.md. Якщо агент кілька разів повторює ту саму помилку, тоді варто записати відповідне правило. Це порада Шихіпара, а не повідомлення про скасування файлу: у чинній документації Anthropic CLAUDE.md лишається способом давати Claude постійні інструкції для проєкту.

Шихіпар пояснює ризик довгого списку заборон і обхідних прийомів. Помилка, характерна для однієї версії моделі, може зникнути в наступній, а старе правило продовжить обмежувати її роботу. Тому файл, який роками поповнювали після кожної невдалої відповіді, потребує перегляду, а не автоматичного перенесення в новий проєкт.

Офіційна інструкція Claude Code пропонує додавати правило, коли Claude вдруге припустився тієї самої помилки, коли рев’ю виявило прогалину в знанні кодової бази або коли команді доводиться повторювати одне пояснення в різних сесіях. У файлі доречні команди збірки й тестів, сталі домовленості та карта проєкту. Процедури для окремих задач документація радить виносити в skills або правила для відповідних файлів.

На практиці це може виглядати так: якщо агент один раз запустив не ту команду тестування, виправте його в розмові. Якщо це повторилося, додайте до CLAUDE.md точну команду, яку використовує саме ваш репозиторій. Після оновлення моделі перегляньте старі правила і приберіть ті, що більше не запобігають реальній помилці. Поради Anthropic прямо закликають перевіряти, чи кожен рядок файлу ще потрібен.

Є межа, яку важливо не переплутати з інструкціями. CLAUDE.md впливає на поведінку агента, але не примушує його виконувати правило без винятків. Якщо потрібно технічно заблокувати дію, Anthropic радить застосовувати hook перед викликом інструмента. Такі обмеження не варто покладати лише на фразу в текстовому файлі.