Claude Code: AI-агент в терминале

Концепции

Официальная документация | Quickstart | Как работает Claude Code

Claude Code работает как агент прямо в терминале. Он читает файлы, пишет код, запускает команды, работает с git и понимает контекст проекта. Ключевое отличие от чат-интерфейсов: Claude Code действует автономно, выполняя цепочки действий для достижения цели.

Пользователь (промпт)
  → Claude Code (планирование)
    → Чтение файлов (Glob, Grep, Read)
    → Редактирование (Edit, Write)
    → Команды (Bash)
    → Субагенты (Task)
  → Результат

Агентный цикл: Claude получает задачу, анализирует кодовую базу, планирует шаги, выполняет действия инструментами и проверяет результат. Каждое действие требует подтверждения пользователя (настраивается через permissions).

CLAUDE.md: файл с инструкциями проекта. Claude читает его в начале каждой сессии. Аналог .editorconfig, но для AI-агента.

MCP (Model Context Protocol): открытый протокол для подключения внешних инструментов. Через MCP Claude получает доступ к базам данных, API, браузеру и другим сервисам.

Субагенты: изолированные AI-процессы для параллельного выполнения задач. Каждый работает в своём контексте с ограниченным набором инструментов.

Установка

Docs: Quickstart | Advanced Setup

# npm (глобально)
npm install -g @anthropic-ai/claude-code

# Запуск в директории проекта
cd ~/my-project
claude

Для работы нужна подписка Anthropic (Pro, Max, Team, Enterprise) или API-ключ (ANTHROPIC_API_KEY).

Проверка:

claude --version
claude auth status

Интерфейс и навигация

Docs: Terminal Guide | Keybindings

Режимы ввода

Vim-режим

/vim

Включает vi-подобную навигацию в поле ввода. Повторный вызов отключает.

Slash-команды

Docs: Slash Commands | CLI Reference

CLAUDE.md: инструкции для агента

Docs: Memory

CLAUDE.md содержит правила, контекст и предпочтения проекта. Claude читает этот файл автоматически при старте сессии.

Иерархия файлов

Файлы загружаются сверху вниз. Managed-политики (от организации) имеют наивысший приоритет.

Формат

# Название проекта
Краткое описание

## Сборка и тесты
- Build: `bun build`
- Test: `bun test`
- Lint: `bun lint`

## Конвенции
- TypeScript, 2 пробела отступ
- Тесты рядом с кодом: `*.test.ts`
- Без em-dash в текстах

## Важные пути
- `src/api/` - API endpoints
- `src/components/` - React-компоненты

## Импорт внешних файлов
Подробности: @docs/architecture.md
API: @docs/api-standards.md

Синтаксис @path/to/file импортирует содержимое файла (до 5 уровней рекурсии).

Модульные правила

Директория .claude/rules/ позволяет разбить инструкции по темам:

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    └── security.md

Правила можно привязать к конкретным путям через frontmatter:

---
paths:
  - "src/api/**/*.ts"
  - "src/components/**/*.tsx"
---
# Применяется только к этим файлам

Permissions: система разрешений

Docs: Permissions | Settings

Claude запрашивает подтверждение перед потенциально опасными действиями. Поведение настраивается.

Режимы

Переключение: Shift+Tab в интерактивном режиме.

Правила в settings.json

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)"
    ],
    "ask": [
      "Bash(git push *)"
    ]
  }
}

Порядок проверки: Deny → Ask → Allow. Первое совпадение выигрывает.

Расположение settings.json

Приоритет: managed → CLI args → local → project → user.

Модели

Docs: Model Configuration

Доступные модели

Переключение

# В сессии
/model opus
/model sonnet

# При запуске
claude --model opus

# Через переменную окружения
export ANTHROPIC_MODEL=opus

Effort level (только Opus)

Управляет глубиной рассуждений:

Настройка через /model (стрелками) или CLAUDE_CODE_EFFORT_LEVEL=medium.

Инструменты агента

Docs: How Claude Code Works | Sub-agents

Claude Code использует набор инструментов для взаимодействия с файловой системой и окружением.

Основные инструменты

Субагенты (Task)

Субагенты решают задачи в изолированном контексте. Полезны для параллельной работы и защиты основного контекста от больших объёмов данных.

Встроенные типы:

Создание кастомного субагента (.claude/agents/reviewer.md):

---
name: reviewer
description: Code review после изменений
tools: Read, Grep, Glob, Bash
model: sonnet
---

Ты senior-разработчик. Анализируй код на:
- Корректность логики
- Обработку ошибок
- Безопасность
- Соответствие конвенциям проекта

Субагент будет доступен через /agents и Claude сможет делегировать ему задачи автоматически.

Память субагентов

memory: user     # ~/.claude/agent-memory/<name>/
memory: project  # .claude/agent-memory/<name>/
memory: local    # .claude/agent-memory-local/<name>/

MCP: подключение внешних инструментов

Docs: MCP

Model Context Protocol позволяет подключать базы данных, API, браузеры и другие сервисы.

Добавление серверов

# HTTP (удалённые серверы)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Stdio (локальные процессы)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@localhost:5432/mydb"

claude mcp add --transport stdio browser -- npx -y @anthropic-ai/mcp-server-puppeteer

Управление

claude mcp list              # Список серверов
claude mcp get <name>        # Детали сервера
claude mcp remove <name>     # Удалить

Области видимости

Аутентификация

Для серверов с OAuth:

/mcp    # В интерактивном режиме, откроет браузер

Hooks: автоматизация

Docs: Hooks

Хуки выполняют shell-команды в определённые моменты работы Claude.

События

Примеры

Уведомление на рабочий стол (Linux):

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Требуется внимание'"
          }
        ]
      }
    ]
  }
}

Автоформат после редактирования:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Блокировка редактирования .env:

#!/bin/bash
# .claude/hooks/protect-env.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
if [[ "$FILE_PATH" == *".env"* ]]; then
  echo "Blocked: .env files are protected" >&2
  exit 2  # exit 2 = заблокировать действие
fi
exit 0

Коды возврата: 0 = разрешить, 2 = заблокировать.

Настройка

Хуки добавляются в settings.json (user, project или local) или через /hooks в интерактивном режиме.

Auto Memory

Docs: Memory

Claude автоматически сохраняет заметки между сессиями.

Хранилище: ~/.claude/projects/<project>/memory/MEMORY.md

Что сохраняется:

• Паттерны и конвенции проекта
• Решения повторяющихся проблем
• Предпочтения пользователя
• Архитектурные заметки

Управление:

/memory              # Редактировать файлы памяти

Отключение:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Первые 200 строк MEMORY.md загружаются автоматически. Для больших заметок создавай отдельные файлы и ссылайся из MEMORY.md.

IDE-интеграции

Docs: VS Code | Desktop

VS Code

Установка: поиск “Claude Code” в Marketplace или vscode:extension/anthropic.claude-code.

Возможности:

• Inline-диффы с превью
• @-упоминания файлов с диапазонами строк
• Планирование перед применением изменений
• Несколько вкладок разговоров

JetBrains (IntelliJ, PyCharm, WebStorm)

Установка: поиск “Claude Code Beta” в Marketplace.

# Из встроенного терминала
claude

# Из внешнего терминала (подключение к IDE)
claude
/ide

Ctrl+Esc / Cmd+Esc для переключения фокуса.

Переменные окружения

Docs: Settings

Типовые workflow

Исследование кодовой базы

> Объясни архитектуру этого проекта
> Найди все эндпоинты API и покажи их структуру
> Как работает аутентификация?

Реализация фичи

> Добавь эндпоинт POST /api/users с валидацией email и пароля
> Напиши тесты для нового эндпоинта
> Сделай code review изменений

Отладка

> Тесты падают в auth.test.ts, разберись
> В логах ошибка "connection refused" при подключении к Redis
> Почему этот запрос возвращает 500?

Git-операции

> Посмотри что изменилось и сделай коммит
> Создай PR с описанием всех изменений
> Сделай rebase на main и разреши конфликты

Рефакторинг

> Переименуй UserService в AccountService во всём проекте
> Разбей этот файл на модули по ответственности
> Замени все callback-и на async/await

Skills: переиспользуемые команды

Docs: Skills | Slash Commands

Skills (скиллы) позволяют упаковать инструкции, шаблоны и workflow в slash-команды. В отличие от субагентов, скиллы работают в основном контексте разговора.

Структура файлов

.claude/skills/
├── commit/
│   └── SKILL.md
├── review-code/
│   ├── SKILL.md
│   ├── checklist.md
│   └── examples.md
└── deploy/
    ├── SKILL.md
    └── scripts/
        └── validate.sh

Расположение по приоритету:

Для monorepo скиллы обнаруживаются рекурсивно вверх по директориям.

Формат SKILL.md

---
name: fix-issue
description: Исправить GitHub issue по номеру
argument-hint: "[issue-number]"
allowed-tools: Read, Edit, Write, Bash(git *)
model: sonnet
---

Исправь issue $ARGUMENTS. Следуй конвенциям проекта.

1. Прочитай описание issue
2. Найди релевантный код
3. Внеси исправления
4. Напиши тесты
5. Сделай коммит

Поля frontmatter

Аргументы

Динамический контекст: !backtick`

Команды с ! выполняются до того как Claude увидит промпт. Результат подставляется на место:

---
name: pr-review
description: Ревью текущего pull request
allowed-tools: Bash(gh *)
---

## Контекст PR
Файлы: !`gh pr diff --name-only`
Статистика: !`gh pr diff --stat`

## Задача
Проанализируй изменения и дай рекомендации.

При вызове /pr-review сначала выполнятся команды gh, затем Claude получит промпт с реальными данными.

Запуск в изолированном контексте

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

---
name: deep-research
description: Глубокое исследование модуля
context: fork
agent: Explore
---

Исследуй модуль $ARGUMENTS:
1. Найди все файлы через Glob и Grep
2. Прочитай ключевой код
3. Составь карту зависимостей
4. Верни краткий отчёт

context: fork запускает скилл как субагент. Результат возвращается в основной разговор.

Примеры скиллов

Коммит с конвенциями:

---
name: commit
description: Коммит с форматированным сообщением
disable-model-invocation: true
allowed-tools: Bash(git *)
---

1. Покажи `git diff --staged`
2. Напиши сообщение коммита:
   - Первая строка: краткое описание (до 50 символов)
   - Пустая строка
   - Тело: что и почему
3. Выполни `git commit`

Code review по чеклисту:

---
name: review
description: Ревью кода по чеклисту проекта
argument-hint: "[filename]"
---

Проверь $ARGUMENTS:

## Качество
- [ ] Понятные имена переменных и функций
- [ ] Нет дублирования
- [ ] Обработка ошибок

## Безопасность
- [ ] Нет захардкоженных секретов
- [ ] Валидация входных данных
- [ ] Нет SQL-инъекций

## Тесты
- [ ] Edge cases покрыты
- [ ] Ошибочные сценарии протестированы

Генерация миграции БД:

---
name: migration
description: Создать миграцию базы данных
argument-hint: "[описание изменения]"
allowed-tools: Read, Write, Bash(npm run migrate:*)
model: sonnet
---

Создай миграцию для: $ARGUMENTS

Текущая схема: !`npm run migrate:status 2>&1 | tail -10`

1. Создай файл миграции
2. Напиши up и down
3. Проверь что down откатывает up

Управление доступом

В settings.json:

{
  "permissions": {
    "allow": ["Skill(commit)", "Skill(review *)"],
    "deny": ["Skill(deploy)"]
  }
}

Когда создавать скилл

• Повторяющийся workflow (коммиты, ревью, деплой)
• Конвенции команды, которые нужно формализовать
• Задачи с фиксированной структурой (чеклисты, шаблоны)
• Интеграции с внешними инструментами (gh, jira, kubectl)

Для разовых задач достаточно обычного промпта. Для сложных автономных задач лучше субагенты.

Эффективные паттерны

Docs: Best Practices | Troubleshooting

Будь конкретен: “Добавь обработку ошибок в src/api/users.ts для случая когда БД недоступна” лучше чем “улучши обработку ошибок”.

Используй CLAUDE.md: Один раз опиши конвенции проекта, и Claude будет следовать им во всех сессиях.

Контекст через @: В IDE используй @src/models/user.ts чтобы явно указать файлы для контекста.

Субагенты для параллелизма: “Исследуй модули auth, database и api параллельно” запустит три субагента одновременно.

Plan mode для сложных задач: Переключись в plan (Shift+Tab) перед большими рефакторингами. Claude исследует код и предложит план до начала изменений.

/compact для длинных сессий: Когда контекст забивается, /compact сожмёт историю, сохранив ключевую информацию.

Итеративность: Лучше несколько точных промптов чем один огромный. Claude сохраняет контекст разговора.