# Гайд для Claude Code: настройка для агентского программирования (для новичков)

> Полное практическое руководство по настройке Claude Code: установка CLI, конфигурация CLAUDE.md и settings.json, матрица разрешений, автоматические хуки, кастомная команда /truth и субагенты.

## 1. Установка Claude Code и подготовка окружения

Claude Code устанавливается как автономный интерфейс командной строки (CLI) для взаимодействия с кодом через агентные модели Anthropic. В отличие от стандартных чат-интерфейсов, Claude Code напрямую взаимодействует с файловой системой, выполняет терминальные команды, анализирует структуру репозитория и вносит атомарные правки.

### 1.1. Способы инсталляции CLI: нативный скрипт против npm

Рекомендуемый разработчиками способ установки — нативный системный скрипт, автоматически настраивающий исполняемый файл и окружение. В качестве альтернативы для машин с установленным Node.js доступен глобальный пакет npm:

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

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Альтернативная установка через npm
npm install -g @anthropic-ai/claude-code
```

После завершения инсталляции проверьте работоспособность утилиты, выполнив `claude --version` в терминале.

### 1.2. Привязка к директории проекта и аутентификация

Перед первым запуском крайне важно перейти непосредственно в корневую папку вашего рабочего проекта:

```bash
cd your-project-directory
claude
```

> 💡 **Почему это важно:** Claude Code жестко привязывает долговременную память проекта, локальные правила и разрешения безопасности к текущей рабочей директории. Запуск из домашней папки (`~`) или с рабочего стола приведет к потере контекста кодовой базы.

При первом старте утилита предложит пройти аутентификацию:
- **OAuth-вход через браузер** при наличии активной подписки Claude (Pro, Max или Team).
- **API-ключ Anthropic Console** для прямой посекундной оплаты токенов по тарифам API.

Помимо автономного терминала, Claude Code доступен через официальное расширение для VS Code, плагин для JetBrains, десктопное приложение и веб-интерфейс на claude.ai. Все эти клиенты используют общую файловую конфигурацию в папке `.claude/`, поэтому заданные правила остаются актуальными в любой среде разработки.

## 2. Три файла конфигурации: архитектура памяти и настроек

Claude Code использует двухуровневую иерархию настроек: директорию проекта `.claude/` (вместе с файлом `CLAUDE.md` в корне) и глобальную директорию `~/.claude/` в домашней папке пользователя. Глобальные правила действуют на все сессии на компьютере, а локальные настройки имеют приоритет для текущего репозитория.

### 2.1. CLAUDE.md и правила памяти репозитория

`CLAUDE.md` — это постоянная память проекта, считываемая агентом при старте каждой рабочей сессии. Здесь фиксируются архитектурные ориентиры, команды запуска тестов, правила оформления кода и стек технологий.

| Механизм | Расположение | Назначение |
| --- | --- | --- |
| **Корневой гайд** | `CLAUDE.md` | Главные инструкции и описание стека (рекомендуется до 2500 токенов). |
| **Модульные правила** | `.claude/rules/*.md` | Специфические инструкции, подгружаемые только при работе с нужными файлами. |
| **Генератор памяти** | Команда `/init` | Автоматический аудит кодовой базы и создание стартового шаблона. |
| **Редактор памяти** | Команда `/memory` | Быстрое интерактивное редактирование зафиксированных инструкций. |

> ⚠️ **Главный принцип памяти:** Инструкции, переданные просто в чате, неизбежно теряются при автоматическом сжатии контекста в длинных сессиях. Любое правило, которое должно пережить текущую сессию, обязано быть записано в `CLAUDE.md`.

### 2.2. settings.json и механизм автоматической памяти (Auto memory)

Файл конфигурации `settings.json` (расположенный в `.claude/settings.json` для уровня проекта или в `~/.claude/settings.json` для глобального уровня) определяет разрешения инструментов, системные хуки, переменные окружения и модель по умолчанию.

Механизм **Auto memory** позволяет Claude Code автоматически фиксировать рабочие наблюдения между сессиями без прямого редактирования файлов пользователем. Эту функцию можно отключить параметром `"autoMemoryEnabled": false` или системной переменной `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, если вы предпочитаете строгий ручной контроль через `CLAUDE.md`.

## 3. Настройка разрешений и хуков заранее

Для поддержания безопасного процесса разработки и устранения лишних запросов на подтверждение Claude Code предлагает систему интерактивных режимов и декларативных правил в конфигурации.

### 3.1. Интерактивные режимы разрешений и матрица allow/ask/deny

Быстрое переключение режимов выполнения осуществляется комбинацией клавиш `Shift+Tab`:
- **Default** — запрашивает подтверждение перед каждой потенциально рискованной операцией или изменением файла.
- **Auto-Accept Edits** — автоматически применяет правки файлов, запрашивая одобрение только на запуск системных команд.
- **Plan Mode** — режим чтения без возможности изменения файлов или выполнения bash-команд до утверждения общего плана.

Чтобы избавиться от рутинных подтверждений, в `.claude/settings.json` настраивается матрица правил:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  }
}
```

Правило `deny` всегда имеет абсолютный приоритет: даже если шаблон `Read(**)` разрешает чтение файлов, явный запрет `Read(.env)` гарантирует, что переменные окружения и секреты не попадут в контекст модели.

### 3.2. Автоматизация через хуки PostToolUse и PreToolUse

Хуки позволяют запускать локальные скрипты до или после вызова встроенных инструментов агента.

Например, хук **PostToolUse** автоматически форматирует каждый измененный файл с помощью Prettier:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

А хук **PreToolUse** позволяет перехватывать и блокировать опасные команды на уровне Python-скрипта до их передачи в терминал:

```python
#!/usr/bin/env python3
# .claude/hooks/block-dangerous-bash.py
import json
import re
import sys

DANGEROUS_PATTERNS = [
    r'\brm\s+.*-[a-z]*r[a-z]*f',
    r'sudo\s+rm',
    r'chmod\s+777',
    r'git\s+push\s+--force.*main',
]

input_data = json.load(sys.stdin)
if input_data.get('tool_name') == 'Bash':
    command = input_data.get('tool_input', {}).get('command', '')
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print("BLOCKED: command matches dangerous security pattern", file=sys.stderr)
            sys.exit(2)
sys.exit(0)
```

Код возврата `2` сообщает системе Claude Code об аварийной блокировке вызова без запуска команды в оболочке.

## 4. Команды, которые стоит выучить первыми

Библиотека Claude Code включает более шестидесяти команд, однако для продуктивной ежедневной разработки достаточно базового набора.

### 4.1. Сводная таблица базовых и продвинутых слеш-команд

В таблице ниже собраны наиболее важные команды CLI, сгруппированные по категориям:

| Команда | Категория | Назначение и поведение |
| --- | --- | --- |
| `/init` | Настройка | Анализирует кодовую базу и создает первичный `CLAUDE.md`. |
| `/memory` | Настройка | Открывает память проекта для прямого редактирования. |
| `/clear` | Контекст | Сбрасывает текущий диалог, сохраняя постоянную память проекта. |
| `/compact [focus]` | Контекст | Сжимает контекст беседы, сохраняя указанные ключевые темы. |
| `/context` | Контекст | Отображает детальный статус заполнения контекстного окна. |
| `/plan` | Планирование | Переводит CLI в режим проектирования и согласования шагов. |
| `/diff` | Проверка | Открывает интерактивный просмотр всех незакороченных правок. |
| `/code-review [--fix]` | Проверка | Проверяет подготовленные изменения на баги и качество кода. |
| `/security-review` | Проверка | Специализированный аудит диффа на наличие уязвимостей. |
| `/resume [session]` | Навигация | Восстанавливает предыдущую сессию по идентификатору. |
| `/branch [name]` | Навигация | Ответвляет текущую беседу в отдельную независимую сессию. |
| `/rewind` | Навигация | Откатывает состояние файлов или разговора к предыдущей точке. |
| `/model` | Производительность | Переключает рабочую модель (Sonnet, Haiku, Opus) прямо в диалоге. |
| `/effort` | Производительность | Регулирует глубину рассуждений и бюджет размышлений модели. |
| `/cost` | Производительность | Показывает расход токенов и суммарные затраты на сессию. |
| `/agents` | Делегирование | Управляет специализированными субагентами и фоновыми задачами. |
| `/permissions` | Конфигурация | Интерактивное меню просмотра и редактирования разрешений. |
| `/hooks` | Конфигурация | Панель диагностики зарегистрированных системных хуков. |
| `/doctor` | Диагностика | Комплексная проверка окружения, ключей и сетевого доступа. |

![Обзор и навигация встроенных слеш-команд в Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-01.webp)

### 4.2. Триада ежедневной продуктивности: /compact, /plan и /diff

Для быстрого освоения инструмента сосредоточьтесь на трех базовых командах:
1. **`/plan`** — запускайте перед началом сложной задачи для предотвращения хаотичных правок кода.
2. **`/compact`** — применяйте каждые 20–30 минут активной работы для предотвращения деградации внимания модели.
3. **`/diff`** — открывайте перед каждым коммитом для пошаговой валидации сгенерированных изменений.

## 5. Создание собственной команды верификации /truth

Команда `/truth` отсутствует в стандартной поставке Claude Code, однако она решает фундаментальную проблему агентного подхода — склонность модели рапортовать об успехе без реальной валидации файлов на диске.

### 5.1. Концепция верификации фактов против кодовой базы

Когда агент утверждает: *«Я исправил интерфейс в файле X и проверил импорты в файле Y»*, он нередко опирается на собственные намерения из контекста. Цель `/truth` — принудительно перечитать измененные файлы с диска и сопоставить утверждения с реальным выводом `git diff`.

![Интерактивное управление контекстом, сессиями и командами Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-02.webp)

### 5.2. Реализация скила .claude/skills/truth/SKILL.md

Пользовательские команды оформляются в виде навыков (skills). Создайте файл `.claude/skills/truth/SKILL.md` в вашем проекте:

```markdown
---
description: "Verify Claude's most recent claims and edits against the actual codebase"
allowed-tools: ["Read", "Grep", "Glob", "Bash(git diff:*)"]
---

Re-examine everything you just told me in this conversation against what actually exists in the codebase right now. Specifically:

1. For every file you claim to have edited, read it again and confirm the change is actually present and matches what you described.
2. For every claim about existing code (a function's behavior, a config value, an import, a dependency version), verify it against the real file rather than your memory of reading it earlier in the session.
3. Run `git diff` and compare the actual diff against what you described changing.
4. Report back plainly: which claims checked out, which didn't, and exactly what the discrepancy was for anything that failed. Do not soften or hedge a discrepancy you find, state it directly.
```

Благодаря строгим ограничениям в `allowed-tools` команда физически не может изменять код, выполняя роль независимого верификатора.

## 6. Субагенты и параллельная работа

При работе с крупными репозиториями чтение множества файлов и прогон тестов быстро перегружают основное контекстное окно.

### 6.1. Изоляция контекста и специализированные субагенты (/agents)

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

```bash
# Открыть интерактивное меню субагентов внутри сессии
/agents
```

Вы можете настроить постоянного агента в файле `.claude/agents/code-reviewer.md`:
- Ограничить доступ только чтением (`Read`, `Grep`, `Glob`).
- Назначить быструю и экономичную модель.
- Запретить прямое внесение правок, сделав его надежным ревьюером кода.

### 6.2. Масштабирование задач через worktree и пакетное выполнение (/batch)

Для одновременной работы над несвязанными задачами Claude Code поддерживает Git Worktree и команду `/batch`:
- **Параллельные копии (`--worktree`):** несколько агентов работают в изолированных рабочих директориях без конфликтов файловой системы.
- **Пакетный запуск (`/batch`):** автоматизированное выполнение задач массового рефакторинга или покрытия тестами в фоновом режиме.

## 7. Готовый шаблон CLAUDE.md и settings.json

Следующие протестированные конфигурации послужат готовым стартом для вашего проекта.

### 7.1. Базовый шаблон памяти CLAUDE.md

Сохраните следующий шаблон в файле `CLAUDE.md` в корне проекта:

```markdown
# Project Context

### Stack
- Language/Framework: [Node.js, TypeScript, Next.js / Python, FastAPI]
- Styling: [Tailwind CSS]
- Database: [PostgreSQL / SQLite via Drizzle ORM]

### Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

### Conventions
- Strict TypeScript typing without `any`
- Functional React components with named exports
- Keep business logic in services or hooks, not inside UI components

### Before finishing any task
- Run test suite and confirm 100% pass rate
- Run `/truth` if the task involved modifying multiple files
```

### 7.2. Производственный конфиг .claude/settings.json с хуками

Сохраните настройки в файле `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Для персональных локальных настроек используйте файл `.claude/settings.local.json`, добавив его в `.gitignore`.

## 8. Заключение и чек-лист готовности

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

### 8.1. Ключевые принципы агентного программирования

1. **Контролируйте контекст:** регулярно используйте `/compact` и делегируйте объемные проверки субагентам.
2. **Фиксируйте правила в памяти:** вносите требования в `CLAUDE.md`, а не повторяйте их в чате.
3. **Проверяйте результат:** запускайте `/truth` и анализируйте `/diff` перед фиксацией изменений.

### 8.2. Чек-лист первичной настройки рабочего пространства

| Этап | Действие | Статус готовности |
| --- | --- | --- |
| **Установка CLI** | Установлен нативный CLI Claude Code и пройдена аутентификация | `Обязательно` |
| **Память проекта** | Создан `CLAUDE.md` со стеком, командами и правилами | `Обязательно` |
| **Разрешения** | Настроены правила `allow`, `ask` и `deny` в `settings.json` | `Обязательно` |
| **Хук форматирования** | Подключен `PostToolUse` для автоматического вызова Prettier | `Рекомендуется` |
| **Защитный скрипт** | Настроен `block-dangerous-bash.py` через `PreToolUse` | `Рекомендуется` |
| **Кастомный навык** | Добавлена команда проверки `.claude/skills/truth/SKILL.md` | `Рекомендуется` |