Claude Code: Лучшие практики для агентного программирования

Оригинальный текст здесь: https://www.anthropic.com/engineering/claude-code-best-practices

Опубликовано 18 апреля 2025 года

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

Мы недавно выпустили Claude Code — инструмент командной строки для агентного программирования. Разработанный как исследовательский проект, Claude Code предоставляет инженерам и исследователям Anthropic более нативный способ интеграции Claude в их рабочие процессы программирования.

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

Эта статья описывает общие паттерны, которые оказались эффективными как для внутренних команд Anthropic, так и для внешних инженеров, использующих Claude Code в различных кодовых базах, языках и средах. Ничто в этом списке не высечено в камне и не применимо универсально; рассматривайте эти предложения как отправные точки. Мы призываем вас экспериментировать и находить то, что лучше всего работает для вас!

Ищете более подробную информацию? Наша исчерпывающая документация на claude.ai/code покрывает все функции, упомянутые в этой статье, и предоставляет дополнительные примеры, детали реализации и продвинутые техники.

1. Настройте свою среду

Claude Code — это агентный помощник по программированию, который автоматически подтягивает контекст в промпты. Это сбор контекста потребляет время и токены, но вы можете оптимизировать его через настройку среды.

a. Создайте файлы CLAUDE.md

CLAUDE.md — это специальный файл, который Claude автоматически подтягивает в контекст при начале разговора. Это делает его идеальным местом для документирования:

• Общих bash-команд
• Основных файлов и утилитарных функций
• Руководящих принципов стиля кода
• Инструкций по тестированию
• Этикета репозитория (например, именование веток, merge vs. rebase и т.д.)
• Настройки среды разработчика (например, pyenv use, какие компиляторы работают)
• Любых неожиданных поведений или предупреждений, характерных для проекта
• Другой информации, которую вы хотите, чтобы Claude запомнил

Нет обязательного формата для файлов CLAUDE.md. Мы рекомендуем делать их краткими и читаемыми для человека. Например:

markdown

# Bash команды
- npm run build: Собрать проект
- npm run typecheck: Запустить проверку типов

# Стиль кода
- Используйте синтаксис ES модулей (import/export), а не CommonJS (require)
- Деструктурируйте импорты когда возможно (например, import { foo } from 'bar')

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

Вы можете размещать файлы CLAUDE.md в нескольких местах:

• В корне вашего репозитория, или где бы вы ни запускали claude (наиболее распространенное использование). Назовите его CLAUDE.md и зафиксируйте в git, чтобы вы могли делиться им между сессиями и с вашей командой (рекомендуется), или назовите его CLAUDE.local.md и добавьте в .gitignore
• В любом родительском каталоге где вы запускаете claude. Это наиболее полезно для монорепозиториев, где вы можете запускать claude из root/foo, и иметь файлы CLAUDE.md как в root/CLAUDE.md, так и в root/foo/CLAUDE.md. Оба будут автоматически подтянуты в контекст
• В любом дочернем каталоге где вы запускаете claude. Это обратное от вышеописанного, и в этом случае Claude будет подтягивать файлы CLAUDE.md по требованию, когда вы работаете с файлами в дочерних каталогах
• В вашей домашней папке (~/.claude/CLAUDE.md), что применяет его ко всем вашим сессиям claude

Когда вы запускаете команду /init, Claude автоматически сгенерирует CLAUDE.md для вас.

b. Настройте ваши файлы CLAUDE.md

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

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

В Anthropic мы иногда пропускаем файлы CLAUDE.md через улучшитель промптов и часто настраиваем инструкции (например, добавляя акцент с "ВАЖНО" или "ВЫ ДОЛЖНЫ") для улучшения соблюдения.

c. Курируйте список разрешенных инструментов Claude

По умолчанию Claude Code запрашивает разрешение на любое действие, которое может изменить вашу систему: запись файлов, многие bash-команды, MCP инструменты и т.д. Мы разработали Claude Code с этим намеренно консервативным подходом для приоритета безопасности. Вы можете настроить список разрешений, чтобы разрешить дополнительные инструменты, которые вы знаете как безопасные, или разрешить потенциально небезопасные инструменты, которые легко отменить (например, редактирование файлов, git commit).

Есть четыре способа управления разрешенными инструментами:

• Выберите "Всегда разрешать" при запросе во время сессии.
• Используйте команду /permissions после запуска Claude Code для добавления или удаления инструментов из списка разрешений.
• Вручную редактируйте ваш .claude/settings.json или ~/.claude.json
• Используйте флаг CLI --allowedTools для разрешений конкретной сессии.

d. Если используете GitHub, установите gh CLI

Claude знает, как использовать gh CLI для взаимодействия с GitHub для создания issues, открытия pull requests, чтения комментариев и многого другого. Без установленного gh, Claude все еще может использовать GitHub API или MCP сервер (если у вас он установлен).

2. Дайте Claude больше инструментов

Claude имеет доступ к вашей shell среде, где вы можете создавать наборы удобных скриптов и функций для него, как и для себя. Он также может использовать более сложные инструменты через MCP и REST API.

a. Используйте Claude с bash инструментами

Claude Code наследует вашу bash среду, давая ему доступ ко всем вашим инструментам. Хотя Claude знает общие утилиты как unix инструменты и gh, он не будет знать о ваших пользовательских bash инструментах без инструкций:

1. Скажите Claude название инструмента с примерами использования
2. Скажите Claude запустить --help для просмотра документации инструмента
3. Документируйте часто используемые инструменты в CLAUDE.md

b. Используйте Claude с MCP

Claude Code функционирует как MCP сервер и клиент. Как клиент, он может подключаться к любому количеству MCP серверов для доступа к их инструментам тремя способами:

• В конфигурации проекта (доступно при запуске Claude Code в этом каталоге)
• В глобальной конфигурации (доступно во всех проектах)
• В зафиксированном файле .mcp.json (доступно всем, работающим в вашей кодовой базе)

При работе с MCP также может быть полезно запускать Claude с флагом --mcp-debug для помощи в выявлении проблем конфигурации.

c. Используйте пользовательские slash команды

Для повторяющихся рабочих процессов — циклов отладки, анализа логов и т.д. — сохраняйте шаблоны промптов в Markdown файлах в папке .claude/commands. Они становятся доступными через меню slash команд, когда вы вводите /. Вы можете зафиксировать эти команды в git, чтобы сделать их доступными для остальной части вашей команды.

Пользовательские slash команды могут включать специальное ключевое слово $ARGUMENTS для передачи параметров из вызова команды.

3. Попробуйте общие рабочие процессы

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

a. Исследуйте, планируйте, кодируйте, коммитьте

Этот универсальный рабочий процесс подходит для многих проблем:

1. Попросите Claude прочитать соответствующие файлы, изображения или URL, предоставляя либо общие указатели, либо конкретные имена файлов, но явно скажите ему пока не писать код.
2. Попросите Claude составить план для подхода к конкретной проблеме. Мы рекомендуем использовать слово "думай" для запуска расширенного режима мышления.
3. Попросите Claude реализовать свое решение в коде.
4. Попросите Claude зафиксировать результат и создать pull request.

b. Пишите тесты, коммитьте; кодируйте, итерируйте, коммитьте

Это любимый рабочий процесс Anthropic для изменений, которые легко проверяются с помощью unit, интеграционных или end-to-end тестов:

1. Попросите Claude написать тесты на основе ожидаемых пар ввод/вывод.
2. Скажите Claude запустить тесты и подтвердить, что они не проходят.
3. Попросите Claude зафиксировать тесты когда вы удовлетворены ими.
4. Попросите Claude написать код, который проходит тесты.
5. Попросите Claude зафиксировать код когда вы удовлетворены изменениями.

c. Пишите код, делайте скриншот результата, итерируйте

Подобно рабочему процессу с тестированием, вы можете предоставить Claude визуальные цели:

1. Дайте Claude способ делать скриншоты браузера
2. Дайте Claude визуальный макет
3. Попросите Claude реализовать дизайн в коде, делать скриншоты результата и итерировать до совпадения с макетом.
4. Попросите Claude зафиксировать когда вы удовлетворены.

d. Безопасный YOLO режим

Вместо надзора за Claude, вы можете использовать claude --dangerously-skip-permissions для обхода всех проверок разрешений и позволить Claude работать непрерывно до завершения.

e. Q&A по кодовой базе

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

f. Используйте Claude для взаимодействия с git

Claude может эффективно обрабатывать многие git операции. Многие инженеры Anthropic используют Claude для 90%+ наших взаимодействий с git. g. Используйте Claude для взаимодействия с GitHub

Claude Code может управлять многими взаимодействиями с GitHub:

• Создание pull requests: Claude понимает сокращение "pr" и сгенерирует соответствующие сообщения коммитов на основе diff и окружающего контекста.
• Реализация одноразовых решений для простых комментариев code review: просто скажите ему исправить комментарии в вашем PR и отправить обратно в ветку PR когда закончит.
• Исправление неудачных сборок или предупреждений линтера
• Категоризация и сортировка открытых issues путем просьбы к Claude пройтись по открытым GitHub issues

Это устраняет необходимость запоминать синтаксис командной строки gh при автоматизации рутинных задач.

h. Используйте Claude для работы с Jupyter notebooks

Исследователи и data scientists в Anthropic используют Claude Code для чтения и записи Jupyter notebooks. Claude может интерпретировать выводы, включая изображения, предоставляя быстрый способ исследования и взаимодействия с данными.

4. Оптимизируйте ваш рабочий процесс

Приведенные ниже предложения применимы ко всем рабочим процессам:

a. Будьте конкретны в ваших инструкциях

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

Например:

ПлохоХорошодобавь тесты для foo.pyнапиши новый тест-кейс для foo.py, покрывающий крайний случай когда пользователь не авторизован. избегай моковпочему у ExecutionFactory такой странный api?посмотри историю git ExecutionFactory и суммируй как появился его apiдобавь виджет календаряпосмотри как реализованы существующие виджеты на главной странице чтобы понять паттерны и конкретно как разделены код и интерфейсы. HotDogWidget.php хороший пример для начала. затем следуй паттерну для реализации нового виджета календаря

b. Давайте Claude изображения

Claude превосходно работает с изображениями и диаграммами несколькими способами:

• Вставляйте скриншоты (совет: нажмите cmd+ctrl+shift+4 в macOS для скриншота в буфер обмена и ctrl+v для вставки)
• Перетаскивайте изображения прямо в поле ввода промпта
• Предоставляйте пути к файлам для изображений

c. Упоминайте файлы, которые вы хотите чтобы Claude посмотрел или с которыми работал

Используйте tab-дополнение для быстрой ссылки на файлы или папки в любом месте вашего репозитория, помогая Claude найти или обновить правильные ресурсы.

d. Давайте Claude URL-адреса

Вставляйте конкретные URL вместе с вашими промптами для Claude, чтобы он мог получить и прочитать их. Чтобы избежать запросов разрешений для одних и тех же доменов, используйте /permissions для добавления доменов в ваш список разрешений.

e. Корректируйте курс рано и часто

Хотя режим автоматического принятия (shift+tab для переключения) позволяет Claude работать автономно, вы обычно получите лучшие результаты, будучи активным сотрудником и направляя подход Claude.

Эти четыре инструмента помогают с коррекцией курса:

• Попросите Claude составить план перед кодированием
• Нажмите Escape для прерывания Claude во время любой фазы
• Дважды нажмите Escape для возврата в истории, отредактируйте предыдущий промпт и исследуйте другое направление
• Попросите Claude отменить изменения

f. Используйте /clear для поддержания фокуса контекста

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

g. Используйте чек-листы и черновики для сложных рабочих процессов

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

h. Передавайте данные в Claude

Существует несколько методов для предоставления данных Claude:

• Копирование и вставка прямо в ваш промпт (наиболее распространенный подход)
• Передача по pipe в Claude Code (например, cat foo.txt | claude)
• Скажите Claude подтянуть данные через bash команды, MCP инструменты или пользовательские slash команды
• Попросите Claude прочитать файлы или получить URL (работает и для изображений)

5. Используйте headless режим для автоматизации вашей инфраструктуры

Claude Code включает headless режим для неинтерактивных контекстов как CI, pre-commit хуки, скрипты сборки и автоматизация. Используйте флаг -p с промптом для включения headless режима, и --output-format stream-json для потокового JSON вывода.

a. Используйте Claude для сортировки issues

Headless режим может питать автоматизации, запускаемые событиями GitHub, такими как создание нового issue в вашем репозитории.

b. Используйте Claude как линтер

Claude Code может предоставлять субъективные code reviews за пределами того, что обнаруживают традиционные инструменты линтинга.

6. Повышайте уровень с мульти-Claude рабочими процессами

Помимо автономного использования, некоторые из самых мощных применений включают запуск нескольких экземпляров Claude параллельно:

a. Пусть один Claude пишет код; используйте другой Claude для проверки

Простой, но эффективный подход — заставить один Claude писать код, пока другой рецензирует или тестирует его.

b. Имейте несколько checkout'ов вашего репо

Вместо ожидания завершения каждого шага Claude, то, что многие инженеры в Anthropic делают:

1. Создайте 3-4 git checkout'а в отдельных папках
2. Откройте каждую папку в отдельных вкладках терминала
3. Запустите Claude в каждой папке с разными задачами
4. Переключайтесь для проверки прогресса

c. Используйте git worktrees

Этот подход блестит для множественных независимых задач, предлагая более легковесную альтернативу множественным checkout'ам. Git worktrees позволяют вам проверить множественные ветки из одного репозитория в отдельные каталоги.

d. Используйте headless режим с пользовательской обвязкой

claude -p (headless режим) интегрирует Claude Code программно в более крупные рабочие процессы. Есть два основных паттерна для использования headless режима:

1. Разветвление обрабатывает большие миграции или анализы
2. Конвейеризация интегрирует Claude в существующие конвейеры данных/обработки

Каковы ваши советы и лучшие практики для работы с Claude Code? Отметьте @AnthropicAI, чтобы мы могли увидеть, что вы строите!

Благодарности

Написано Борисом Черни. Эта работа основывается на лучших практиках из более широкого сообщества пользователей Claude Code, чьи творческие подходы и рабочие процессы продолжают вдохновлять нас. Особая благодарность также Дейзи Холлман, Эшвину Бхату, Кэт Ву, Сиду Бидасария, Калу Руэбу, Нодиру Туракулову, Барри Чжану, Дрю Ходуну и многим другим инженерам Anthropic, чьи ценные идеи и практический опыт с Claude Code помогли сформировать эти рекомендации.