Best practices for Claude Code - Claude Code Docs
Статья Anthropic собирает лучшие практики работы с Claude Code: дать модели способ верифицировать свой результат, сначала исследовать код и составить план, и только потом писать код, а также передавать конкретный контекст в промптах через файлы (@), изображения, URL и пайпы. Подробно разбирается настройка окружения: эффективный CLAUDE.md (домашний, проектный, локальный, родительские и дочерние каталоги), управление разрешениями (auto-режим, allowlist, sandboxing), CLI-инструменты, MCP-серверы, хуки, skills, кастомные субагенты и плагины. Описаны приёмы сессии: останов клавишей Esc, /rewind для отката, /clear между задачами, агрессивное управление контекстом через /compact и /btw, использование субагентов для расследований и чекпоинтов. Для масштабирования предлагаются неинтерактивный режим (claude -p с JSON и stream-json), worktrees, десктоп-приложение, Claude Code в вебе, команды агентов и fan-out по файлам. Отдельно перечислены типичные провалы: «kitchen sink»-сессии, повторные правки, перегруженный CLAUDE.md, доверие без проверки и бесконечное исследование — с конкретными исправлениями.
Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Индекс документации. Полный индекс доступен по адресу: https://code.claude.com/docs/llms.txt. Используйте этот файл, чтобы увидеть все доступные страницы, прежде чем углубляться в материал.
@ instead of describing where code lives. Claude reads the file before responding./permissions to allowlist frequently-used domains.cat error.log | claude to send file contents directly.Ссылайтесь на файлы через @ вместо описаний того, где лежит код. Claude прочитает файл перед ответом. Вставляйте изображения напрямую. Копируйте/вставляйте или перетаскивайте картинки в промпт. Давайте URL на документацию и API-референсы. Используйте /permissions, чтобы добавить часто используемые домены в allowlist. Пайпите данные, например cat error.log | claude, чтобы передать содержимое файла напрямую. Позволяйте Claude самому подтягивать нужное. Скажите ему получить контекст через команды Bash, инструменты MCP или чтение файлов.
# Code style - Use ES modules (import/export) syntax, not CommonJS (require) - Destructure imports when possible (eg. import { foo } from 'bar') # Workflow - Be sure to typecheck when you're done making a series of code changes - Prefer running single tests, and not the whole test suite, for performance
# Стиль кода - Используйте синтаксис ES-модулей (import/export), а не CommonJS (require) - По возможности применяйте деструктуризацию импортов (например, import { foo } from 'bar') # Рабочий процесс - Обязательно прогоняйте typecheck, когда закончите серию правок кода - Для производительности предпочтительно запускать отдельные тесты, а не весь набор
See @README.md for project overview and @package.json for available npm commands. # Additional Instructions - Git workflow: @docs/git-instructions.md - Personal overrides: @~/.claude/my-project-instructions.md
Общий обзор проекта см. в @README.md, а доступные команды npm — в @package.json. # Дополнительные инструкции - Рабочий процесс Git: @docs/git-instructions.md - Личные переопределения: @~/.claude/my-project-instructions.md
~/.claude/CLAUDE.md): applies to all Claude sessions./CLAUDE.md): check into git to share with your team./CLAUDE.local.md): personal project-specific notes; add this file to your .gitignore so it isn’t shared with your teamroot/CLAUDE.md and root/foo/CLAUDE.md are pulled in automaticallyДомашняя папка (~/.claude/CLAUDE.md): применяется ко всем сессиям Claude. Корень проекта (./CLAUDE.md): закоммитьте в git, чтобы делиться с командой. Корень проекта (./CLAUDE.local.md): личные заметки по проекту; добавьте этот файл в .gitignore, чтобы он не попал в командный репозиторий. Родительские каталоги: удобно для монорепозиториев, где автоматически подхватываются и root/CLAUDE.md, и root/foo/CLAUDE.md. Дочерние каталоги: Claude подтягивает дочерние CLAUDE.md по требованию, когда работает с файлами в этих каталогах.
npm run lint or git commitAuto-режим: отдельная модель-классификатор анализирует команды и блокирует только то, что выглядит рискованно: расширение границ задачи, неизвестную инфраструктуру или действия, спровоцированные вредоносным контентом. Подходит, когда вы доверяете общему направлению задачи, но не хотите кликать через каждый шаг. Allowlist разрешений: разрешайте конкретные инструменты, которые точно безопасны, например npm run lint или git commit. Sandboxing: включите изоляцию на уровне ОС, ограничивающую доступ к файловой системе и сети, чтобы Claude мог работать свободнее в заданных границах.
--- name: api-conventions description: REST API design conventions for our services --- # API Conventions - Use kebab-case for URL paths - Use camelCase for JSON properties - Always include pagination for list endpoints - Version APIs in the URL path (/v1/, /v2/)
--- name: api-conventions description: REST API design conventions for our services --- # Соглашения API - Используйте kebab-case в путях URL - Используйте camelCase в JSON-свойствах - Всегда добавляйте пагинацию для эндпоинтов со списками - Версионируйте API в пути URL (/v1/, /v2/)
--- name: fix-issue description: Fix a GitHub issue disable-model-invocation: true --- Analyze and fix the GitHub issue: $ARGUMENTS. 1. Use `gh issue view` to get the issue details 2. Understand the problem described in the issue 3. Search the codebase for relevant files 4. Implement the necessary changes to fix the issue 5. Write and run tests to verify the fix 6. Ensure code passes linting and type checking 7. Create a descriptive commit message 8. Push and create a PR
--- name: fix-issue description: Fix a GitHub issue disable-model-invocation: true --- Проанализируй и исправь GitHub-issue: $ARGUMENTS. 1. Получи детали issue с помощью `gh issue view` 2. Разберись в проблеме, описанной в issue 3. Найди соответствующие файлы в кодовой базе 4. Внеси необходимые изменения для исправления issue 5. Напиши и запусти тесты, чтобы убедиться в работоспособности фикса 6. Убедись, что код проходит линтинг и проверку типов 7. Создай содержательное сообщение коммита 8. Запушь изменения и создай PR
--- name: security-reviewer description: Reviews code for security vulnerabilities tools: Read, Grep, Glob, Bash model: opus --- You are a senior security engineer. Review code for: - Injection vulnerabilities (SQL, XSS, command injection) - Authentication and authorization flaws - Secrets or credentials in code - Insecure data handling Provide specific line references and suggested fixes.
--- name: security-reviewer description: Reviews code for security vulnerabilities tools: Read, Grep, Glob, Bash model: opus --- Вы — старший инженер по безопасности. Проверьте код на: - Уязвимости инъекций (SQL, XSS, инъекции команд) - Изъяны в аутентификации и авторизации - Секреты или учётные данные в коде - Небезопасную обработку данных Указывайте конкретные строки и предлагайте исправления.
async move { ... } do on line 134 of foo.rs?CustomerOnboardingFlowImpl handle?foo() instead of bar() on line 333?Как устроено логирование? Как мне сделать новый API-эндпоинт? Что делает async move { ... } в строке 134 файла foo.rs? Какие граничные случаи обрабатывает CustomerOnboardingFlowImpl? Почему этот код вызывает foo(), а не bar(), в строке 333?
I want to build [brief description]. Interview me in detail using the AskUserQuestion tool. Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered. Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.
Я хочу сделать [краткое описание]. Опроси меня детально с помощью инструмента AskUserQuestion. Расспроси о технической реализации, UI/UX, граничных случаях, опасениях и компромиссах. Не задавай очевидных вопросов, копай в сложные места, которые я мог не учесть. Продолжай интервью, пока не охватим всё, а затем напиши полную спецификацию в SPEC.md.
Esc: stop Claude mid-action with the Esc key. Context is preserved, so you can redirect.Esc + Esc or /rewind: press Esc twice or run /rewind to open the rewind menu and restore previous conversation and code state, or summarize from a selected message."Undo that": have Claude revert its changes./clear: reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.Esc: остановите Claude посреди действия клавишей Esc. Контекст сохраняется, так что вы можете перенаправить работу. Esc + Esc или /rewind: нажмите Esc дважды или выполните /rewind, чтобы открыть меню отката и восстановить предыдущее состояние диалога и кода либо сделать сводку с выбранного сообщения. "Undo that": попросите Claude откатить свои изменения. /clear: сбрасывайте контекст между несвязанными задачами. Длинные сессии с нерелевантным контекстом могут ухудшать качество работы.
/clear frequently between tasks to reset the context window entirely/compact <instructions>, like /compact Focus on the API changesEsc + Esc or /rewind, select a message checkpoint, and choose Summarize from here or Summarize up to here. The first condenses messages from that point forward while keeping earlier context intact; the second condenses earlier messages while keeping recent ones in full. See Restore vs. summarize."When compacting, always preserve the full list of modified files and any test commands" to ensure critical context survives summarization/btw. The answer appears in a dismissible overlay and never enters conversation history, so you can check a detail without growing context.Используйте /clear часто, между задачами, чтобы полностью сбрасывать контекстное окно. Когда срабатывает авто-сжатие, Claude выделяет самое важное: паттерны кода, состояния файлов и ключевые решения. Для большего контроля запускайте /compact <инструкции>, например /compact Focus on the API changes. Чтобы сжать только часть диалога, используйте Esc + Esc или /rewind, выберите чекпоинт сообщения и нажмите Summarize from here или Summarize up to here. Первый вариант сжимает сообщения с указанной точки и далее, сохраняя ранний контекст, второй — сжимает более ранние сообщения, оставляя свежие нетронутыми. См. Restore vs. summarize. Настраивайте поведение сжатия в CLAUDE.md инструкциями вида "When compacting, always preserve the full list of modified files and any test commands", чтобы критически важный контекст пережил сводку. Для быстрых вопросов, которые не должны оставаться в контексте, используйте /btw. Ответ появится во всплывающем окне, которое можно закрыть, и никогда не попадёт в историю диалога, так что можно проверить деталь, не раздувая контекст.
Use subagents to investigate how our authentication system handles token refresh, and whether we have any existing OAuth utilities I should reuse.
Используй субагентов, чтобы выяснить, как наша система аутентификации обрабатывает обновление токенов и есть ли у нас существующие OAuth-утилиты, которые мне стоит переиспользовать.
use a subagent to review this code for edge cases
используй субагента, чтобы проверить этот код на граничные случаи
# One-off queries claude -p "Explain what this project does" # Structured output for scripts claude -p "List all API endpoints" --output-format json # Streaming for real-time processing claude -p "Analyze this log file" --output-format stream-json
# Разовые запросы claude -p "Explain what this project does" # Структурированный вывод для скриптов claude -p "List all API endpoints" --output-format json # Стриминг для обработки в реальном времени claude -p "Analyze this log file" --output-format stream-json
Worktrees: запускайте отдельные сессии CLI в изолированных git-чекаутах, чтобы правки не конфликтовали. Десктоп-приложение: визуально управляйте несколькими локальными сессиями, каждая в своём worktree. Claude Code в вебе: запускайте сессии на облачной инфраструктуре Anthropic в изолированных VM. Команды агентов: автоматическая координация нескольких сессий с общими задачами, обменом сообщениями и тимлидом.
claude -p "<your prompt>" --output-format json | your_command
claude -p "<ваш промпт>" --output-format json | your_command
claude --permission-mode auto -p "fix all lint errors"
claude --permission-mode auto -p "fix all lint errors"
Fix: /clear between unrelated tasks. Fix: After two failed corrections, /clear and write a better initial prompt incorporating what you learned. Fix: Ruthlessly prune. If Claude already does something correctly without the instruction, delete it or convert it to a hook.
Fix: Always provide verification (tests, scripts, screenshots). If you can’t verify it, don’t ship it.
Fix: Scope investigations narrowly or use subagents so the exploration doesn’t consume your main context.
Сессия-«мусорный бак». Вы начинаете с одной задачи, потом спрашиваете Claude о чём-то постороннем, потом возвращаетесь к первой задаче. Контекст забит нерелевантной информацией. Исправление: /clear между несвязанными задачами. Бесконечные правки. Claude сделал что-то не так, вы поправили, он снова ошибся, вы поправили ещё раз. Контекст загрязнён неудачными подходами. Исправление: после двух неудачных коррекций сделайте /clear и напишите более удачный исходный промпт, учитывая то, что узнали. Перегруженный CLAUDE.md. Если ваш CLAUDE.md слишком длинный, Claude игнорирует половину, потому что важные правила тонут в шуме. Исправление: безжалостно урезайте. Если Claude и без инструкции делает что-то правильно, удалите её или превратите в хук. Зазор «доверяй, но проверяй». Claude выдаёт правдоподобную реализацию, которая не обрабатывает граничные случаи. Исправление: всегда обеспечивайте верификацию (тесты, скрипты, скриншоты). Если вы не можете это проверить — не выкатывайте. Бесконечное исследование. Вы просите Claude «исследовать» что-то без чётких рамок. Claude читает сотни файлов, заполняя контекст. Исправление: чётко ограничивайте рамки исследования или используйте субагентов, чтобы изучение не съедало ваш основной контекст.
Как работает Claude Code: агентский цикл, инструменты и управление контекстом. Расширение Claude Code: skills, хуки, MCP, субагенты и плагины. Типичные рабочие процессы: пошаговые рецепты для отладки, тестирования, PR и не только. CLAUDE.md: храните соглашения проекта и устойчивый контекст.