Практические советы: Лучшие практики Claude Code: 12 шаблонов, используемых инженерами-агентами

В следующих заметках описывается практический подход к реализации принципов «Claude Code Best Practices: 12 Patterns Agentic Engineers Use». Основное внимание уделяется контрактам, проверкам и шаблонам кода, а не мотивирующим формулировкам.

CLAUDE CODE

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

Извлечено из 69 советов из самого популярного репозитория GitHub — с участием Бориса Черного, инженера, создавшего Claude Code в компании Anthropic.

При работе над этапом «Извлечение из 69 советов» сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный и восстановительный пути выполнения. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Создавайте контрольные точки после дорогостоящих шагов. Механизм возобновления работы не должен повторно взимать плату за один и тот же вызов LLM, когда оператор пытается выполнить следующий узел заново.

1. Ваш CLAUDE.md, вероятно, мешает вам

При работе над этапом 1 Your CLAUDE md сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Вносите контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна снова взимать плату за один и тот же вызов LLM при повторной попытке обработки последующего узла.

my-service/
├── CLAUDE.md           # Root: universal rules, ~30 lines
├── api/
│   └── CLAUDE.md       # REST conventions, error codes
├── internal/
│   └── CLAUDE.md       # Package naming, interface patterns
└── cmd/
    └── CLAUDE.md       # Flag parsing, logger initialization

<important if="language=go">
- No bare goroutines. Use errgroup or WaitGroup to manage lifecycle.
- Channel capacity > 0 requires an inline comment explaining why.
- context must be the first parameter, named ctx.
</important>

2. Перестаньте рассматривать Claude Code как окно чата

При работе над этапом «2 Stop Treating Claude» сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успешности и не допускайте безусловного частичного завершения работы. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг.

3. Контекст — это ресурс. Относитесь к нему как к таковому.

При работе с этапом «3 Context is a stage» сначала запишите условия работы: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Запишите также время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Очевидность затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Механизм возобновления работы не должен снова взимать плату за один и тот же вызов LLM при повторной попытке обработки последующего узла. При работе с этапом «3 Context is a stage» сначала запишите условия работы: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки.

context: fork

4. Хуки выполняются вне цикла агента

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

5. На 84% меньше запросов на разрешения

Этап «5 84 Меньше разрешений» работает наилучшим образом, если рассматривать его как измеримую площадку. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задач. Установите лимиты на количество операций за раз и за сессию. Инструменты агентов активно расширяют объём данных; строгие ограничения предотвращают появление неожиданных счетов.

6. «Десятки Клодов, работающих круглосуточно».

Модель «6 Дюжин Клодов» работает наилучшим образом, когда рассматривается как измеримая структура. Сохраняйте один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию до расширения объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте состояние графа простым и типизированным. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний. Модель «6 Дюжин Клодов» работает наилучшим образом, когда рассматривается как измеримая структура. Сохраняйте один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию до расширения объёма работ. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

7.**ultrathink** — это не трюк

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

8. Локальная автоматизация, которую не может обеспечить CI

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

/loop 30m /code-review

9. Вопросы в процессе выполнения задачи без нарушения её хода

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

sh.

10. Раздел, делающий описание навыков значимым

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

11. Пусть «готово» действительно означает готово

При работе над этапом «11 Make done Mean» сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успешности и не допускайте молчаливого частичного выполнения задачи. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов LLM, когда оператор пытается выполнить следующий этап.

12. 10x Более быстрые вызовы SDK с помощью одного флага

При работе над этапом 12 10x Faster SDK сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна снова взимать плату за один и тот же вызов LLM при повторной попытке обработки последующего узла. При работе над этапом 12 10x Faster SDK сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Документируйте как успешный, так и путь восстановления работы. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

Что общего у этих 12 шаблонов

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

Ссылки

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

Чек-лист операционной деятельности

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

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

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

Напишите краткий руководство: как обновлять ключи, как опустошать очередь, как откатывать последнюю операцию ввода данных.

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

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

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

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