Claude Code: установка, CLAUDE.md, skills, MCP и CI

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

В этом же заключается риск. Без ограничений Claude Code работает с файлами, командами, сетью и credentials вашего пользователя. Поэтому хорошая настройка начинается не с «идеального промпта», а с точного контекста проекта, явных permissions и короткого feedback loop.

Ниже — актуальная карта конфигурации. Полный список команд и параметров находится в официальной документации Claude Code.

Установите native binary

Anthropic рекомендует native installer. Node.js для этого способа не нужен.

# macOS, Linux или WSL
curl -fsSL https://claude.ai/install.sh | bash

# macOS или Linux через Homebrew
brew install --cask claude-code

# Windows через WinGet
winget install Anthropic.ClaudeCode

Native Windows поддерживается. WSL остаётся удобным, если проект зависит от Linux toolchain или sandboxed command execution. Точные требования к ОС и железу смотрите в installation guide.

Проверьте binary и запустите его внутри репозитория:

claude --version
cd /path/to/project
claude

Первый запуск откроет login flow. Subscription OAuth и API credentials предназначены для разных сценариев. Не переносите личный OAuth token в автоматизацию или сторонний продукт. Authentication policy Anthropic требует API keys или поддерживаемого cloud provider для продуктов и сервисов на Claude.

Начинайте с ограниченной задачи

Запрос «улучши эту кодовую базу» не задаёт критерий остановки. Рабочая постановка называет область, ограничения и проверку:

Исправь падающий refresh-token test в packages/auth.
Не меняй публичный API и схему базы данных.
Сначала воспроизведи сбой, затем сделай минимальный fix.
Запусти конкретный тест и весь test suite пакета auth.
Если сбой не воспроизводится, остановись и объясни почему.

Рабочий цикл должен оставаться видимым:

1. воспроизвести проблему или зафиксировать исходное состояние;
2. найти релевантный код;
3. сформулировать вероятную причину;
4. сделать минимальную правку;
5. запустить самую дешёвую осмысленную проверку;
6. посмотреть git diff и перечислить остаточные риски.

Не просите агента коммитить до вашего review. Осмысленный commit message одинаково легко написать и для хорошей, и для плохой правки.

Дайте Claude контекст, который нельзя надёжно вывести из кода

CLAUDE.md: постоянные факты проекта

В CLAUDE.md должна оставаться информация, полезная почти в каждой сессии:

# Project guide

## Verified commands
- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm --filter @acme/auth test`
- Full check: `pnpm lint && pnpm test && pnpm build`

## Constraints
- Never edit generated files under `src/generated/`.
- Database changes require a migration in `db/migrations/`.
- API errors use `{ code, message, requestId }`.

## Architecture
- `apps/api/` owns HTTP transport.
- `packages/domain/` has no framework dependencies.

Официальный memory guide рекомендует держать CLAUDE.md короче 200 строк. Это budget для контекста, а не цель по объёму. Удаляйте правила, которые видны в конфигурации, и заменяйте «пиши чистый код» на проверяемые команды и ограничения.

Claude загружает user- и project-инструкции от стартовой директории вверх. Вложенные инструкции обнаруживаются, когда агент работает с файлами соответствующей директории. Команда /memory показывает реально загруженные файлы — проверяйте, а не угадывайте.

Почему компактный релевантный набор инструкций работает лучше, подробно разобрано в гайде по context engineering.

Rules и local settings

Path-specific инструкции храните в .claude/rules/: например, отдельные соглашения для mobile и backend. .claude/settings.json предназначен для командной конфигурации в Git, .claude/settings.local.json — для персональных project overrides без коммита.

~/.claude.json не является глобальным settings-файлом. Global permissions, hooks и environment values живут в ~/.claude/settings.json. Из-за этой разницы часто кажется, что Claude «игнорирует настройки»; /status показывает активные sources.

Permissions — это policy, а не борьба с диалогами

Claude Code использует allow, ask и deny rules. Read-only операции обычно выполняются без запроса; file edits и shell commands подчиняются активному permission mode и правилам. Итоговую конфигурацию можно посмотреть через /permissions.

Консервативный project file может начинаться так:

{
  "permissions": {
    "allow": [
      "Bash(pnpm test *)",
      "Bash(pnpm lint *)",
      "Bash(git diff *)",
      "Bash(git status *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(curl *)"
    ]
  }
}

Адаптируйте patterns к реальным командам и путям. Prefix rules не являются shell security parser: ту же операцию можно выразить другим binary или синтаксисом. Если ограничение должно соблюдаться жёстко, добавьте PreToolUse hook, OS sandbox, restricted container или managed settings. Приоритеты и matcher behavior описаны в permissions reference.

Три практических правила:

• не передавайте production credentials сессии, которой они не нужны;
• не разрешайте unattended deploy или push только ради исчезновения approval prompts;
• проверяйте project-owned .mcp.json перед доверием: MCP-сервер — это исполняемый или сетевой код со своими правами.

Выбирайте правильный механизм расширения

Несколько возможностей Claude Code кажутся взаимозаменяемыми, но решают разные задачи.

Если два механизма всё ещё выглядят одинаково, сверяйтесь с официальным feature overview.

Skills: процедуры, которым тесно в CLAUDE.md

Project skills живут в .claude/skills/<name>/SKILL.md:

---
name: verify-change
description: Verify a code change before it is committed.
disable-model-invocation: true
---

1. Read the current diff.
2. Run the narrowest relevant tests.
3. Run the repository lint command.
4. Report failures and unverified surfaces. Do not commit.

Запускайте skill как /verify-change. Model-invocable skills могут загружаться автоматически, когда description соответствует задаче. Старый формат .claude/commands/ продолжает работать, но skills поддерживают директории, reference files, scripts и явный invocation control. Актуальный frontmatter описан в skills documentation.

Продвинутые паттерны вынесены в отдельный материал: Claude Code Skills and Agents.

Subagents: изолируйте контекст, а не ответственность

Custom subagent — Markdown-файл в .claude/agents/:

---
name: migration-reviewer
description: Reviews database migrations without editing files.
tools: Read, Grep, Glob, Bash
---

Inspect the migration and the schema it changes.
Run read-only validation commands only.
Return findings ordered by severity with file and line references.

Subagent полезен, когда worker должен прочитать много файлов, а основной conversation нужен только вывод. Он стартует с изолированным контекстом, поэтому delegation должен содержать задачу и ограничения. Не рассчитывайте, что вся история разговора передалась автоматически. Subagent reference описывает scopes, tools, memory, skills и worktree isolation.

MCP: подключайте tools, а не вставляйте данные в чат

MCP-серверы могут открыть агенту issue tracker, observability, базу данных или внутренний API. Командный HTTP server добавляется на project scope так:

claude mcp add \
  --transport http \
  --scope project \
  issue-tracker https://mcp.example.com/mcp

Project scope записывается в .mcp.json; local и user scopes — в ~/.claude.json. Credentials передавайте через environment variables, а не через Git:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_API_URL}/mcp",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_API_TOKEN}"
      }
    }
  }
}

Через /mcp проверяются connections и OAuth. В официальном MCP guide описаны scope precedence, transports, environment expansion и project trust. Если сначала нужно понять сам протокол, начните с гайда по MCP-серверам.

Hooks: принуждайте к тому, чего промпт не гарантирует

Фраза в CLAUDE.md может быть понята неверно или проигнорирована. Hook запускается в конкретной lifecycle point: при tool use, stop, prompt submission или compaction. Он подходит для механических проверок — блокировки protected paths, запуска formatter после edit или требования теста перед завершением.

Делайте hooks быстрыми и детерминированными. Они выполняются внутри developer workflow, наследуют environment и сами становятся command-execution surface. Ревьюйте их как код и храните под ключом hooks в settings file, а не в несуществующем .claude/hooks.json. Схемы событий находятся в hooks reference.

Изолируйте параллельную работу через Git worktrees

Несколько агентов в одном checkout рано или поздно столкнутся. Запустите отдельную сессию в своём worktree:

claude --worktree feature-auth

По умолчанию Claude создаёт worktree и branch внутри .claude/worktrees/. Перед первым --worktree запустите обычную trusted session в репозитории и исключите worktree директорию из version control. Worktree guide описывает base refs, cleanup, subagent isolation и копирование выбранных ignored files.

Worktree изолирует файлы, но не внешние side effects. Две сессии всё ещё могут работать с одной development database, queue, cloud account или port. Где это опасно, выдавайте им отдельные test resources.

Checkpoints — для локального undo, Git — для истории

Двойной Esc или /rewind позволяет вернуть code, conversation или оба к выбранному checkpoint. Это удобно для проверки другого подхода без перезапуска сессии.

Checkpointing отслеживает только прямые file edits Claude. Он не видит файлы, изменённые через Bash, вручную или другой сессией. Anthropic прямо предупреждает, что это не замена version control, в checkpointing guide.

Перед рискованной задачей:

git status --short
git diff --check
git switch -c agent/task-name

Не используйте git checkout . или git reset --hard как универсальный совет по восстановлению: обе команды могут уничтожить чужую незакоммиченную работу.

Запускайте Claude Code в CI без отключения guardrails

Print mode делает Claude Code пригодным для скриптов:

claude -p "Review the diff for security regressions. Do not edit files." \
  --output-format json \
  --permission-mode dontAsk

dontAsk запрещает действия вне явного allowlist и встроенного read-only набора. Если job должен запускать тесты, добавьте только необходимые tools или command patterns. Используйте ограниченную CI identity, не передавайте production secrets, задайте timeout и spend limit, запускайте работу в clean checkout.

JSON output содержит structured result и usage metadata; --json-schema может зафиксировать машинно-читаемый ответ. Headless-mode guide описывает output formats, allowed tools, permission modes и stdin limits.

Не используйте --dangerously-skip-permissions в CI. Он снимает именно тот контроль, который важнее всего в unattended environment.

Данные и стоимость: проверяйте policy, не копируйте старую таблицу цен

Claude Code отправляет контекст, необходимый модели для обработки. Пользователи consumer-планов выбирают в privacy settings, можно ли использовать их данные для улучшения моделей. Для commercial terms Anthropic заявляет, что не обучает модели на коде и промптах без явного opt-in клиента. Retention и локальные transcripts зависят от типа аккаунта — перед работой с приватным репозиторием проверьте актуальную data-usage policy.

Цены и лимиты планов меняются. Для subscription pricing используйте live pricing page, для API tracking — cost guide Anthropic. В API mode команда /cost показывает текущую сессию, а non-interactive JSON содержит total_cost_usd. Прежде чем задавать бюджет всей команде, проведите pilot на типичных репозиториях.

Настройка, которая не разваливается через месяц

1. Установите native binary и войдите через правильный тип аккаунта.
2. Добавьте короткий CLAUDE.md с проверенными командами и неочевидными ограничениями.
3. Закоммитьте консервативные project permissions; личные overrides оставьте локально.
4. Вынесите повторяемые процедуры в skills, а обязательные проверки — в hooks.
5. Добавляйте MCP-серверы по одному, с least-privilege credentials и review конфигурации.
6. Используйте worktrees для параллельных edits и разделяйте внешние test resources.
7. Требуйте tests, diff review и решение человека до commit, push или deploy.

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