# Claude Code — Инструкция по настройке

#ai_tools #claude #cli #productivity

---

## 🧠 Что такое Claude Code

CLI-инструмент от Anthropic для работы с кодом и задачами прямо в терминале. Читает контекст проекта, управляет файлами, запускает команды, работает с git. Ключевое отличие от веб-интерфейса — глубокая интеграция с файловой системой и инструментами разработки.

---

## 📁 Конфигурационные файлы

### CLAUDE.md — главный файл инструкций

Claude читает `CLAUDE.md` при каждом запуске и следует инструкциям как жёстким правилам.

| Путь | Область действия |
|------|-----------------|
| `~/.claude/CLAUDE.md` | Глобально — все проекты |
| `<project>/CLAUDE.md` | Только этот проект |
| `<subdir>/CLAUDE.md` | Только при работе в этой директории |

**Что писать в CLAUDE.md:**
- Структура проекта и соглашения
- Стиль коммитов и ветвления
- Какие команды запускать для тестов/сборки
- Какие файлы трогать нельзя
- Как форматировать код
- Архитектурные решения и их причины

```markdown
# CLAUDE.md пример

## Коммиты
- Язык: русский
- Стайл: краткий императив

## Запуск тестов
npm test -- --watch=false

## Нельзя трогать
- src/legacy/** (старый код, не рефакторить)
```

### GEMINI.md

Аналог `CLAUDE.md` для Google Gemini CLI. Та же идея — инструкции для AI при работе с проектом. Если используешь оба инструмента — можно держать оба файла с одинаковым содержимым.

### .claude/ директория

```
.claude/
├── settings.json        ← настройки проекта (permissions, env)
├── settings.local.json  ← локальные настройки (не коммитить)
├── commands/            ← кастомные slash-команды
├── skills/              ← кастомные skills
└── plugins/             ← плагины
```

### ~/.claude/ глобальная директория

```
~/.claude/
├── CLAUDE.md            ← глобальные инструкции
├── settings.json        ← глобальные настройки
├── keybindings.json     ← кастомные горячие клавиши
├── commands/            ← глобальные команды
└── plugins/             ← глобальные плагины
```

---

## ⚙️ settings.json — настройки разрешений

```json
{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm run *)",
      "Read(**)",
      "Edit(**)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  }
}
```

Режимы разрешений при запуске:
- `--dangerously-skip-permissions` — автоподтверждение всего (для CI/автоматизации)
- `--allowedTools "Bash,Read,Edit"` — разрешить только конкретные инструменты
- По умолчанию — Claude спрашивает подтверждение на опасные операции

---

## 🔌 Plugins

Плагины расширяют Claude Code компонентами: командами, агентами, хуками, skills, MCP-серверами.

### Структура плагина

```
my-plugin/
├── plugin.json          ← манифест
├── commands/            ← slash-команды
├── agents/              ← субагенты
├── skills/              ← skills
└── hooks/               ← хуки
```

### plugin.json

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Описание плагина",
  "commands": ["commands/*.md"],
  "agents": ["agents/*.md"],
  "skills": ["skills/*.md"],
  "hooks": ["hooks/*.json"]
}
```

---

## 🤖 Agents (субагенты)

Субагенты — специализированные агенты для конкретных задач. Claude запускает их автоматически или по явному вызову.

### Встроенные типы агентов
- `general-purpose` — исследование, поиск, многошаговые задачи
- `Explore` — быстрый анализ кодовой базы
- `Plan` — проектирование архитектуры и планов реализации
- `claude-code-guide` — вопросы о самом Claude Code

### Кастомный агент (файл .md)

```markdown
---
name: code-reviewer
description: Ревью кода на качество и безопасность. TRIGGER when user asks to review code.
tools: Read, Grep, Glob
color: blue
---

Ты — строгий code reviewer. Проверяй:
- Безопасность (инъекции, XSS, утечки)
- Производительность (O(n²), лишние запросы)
- Читаемость и соответствие проектным соглашениям
```

### Когда использовать агентов
- Параллельные независимые задачи
- Изоляция контекста (чтобы не замусорить основной)
- Специализированная экспертиза

---

## 🛠️ MCP серверы (Model Context Protocol)

MCP — протокол подключения внешних инструментов к Claude. Позволяет Claude работать с браузером, базами данных, внешними API.

### Добавить MCP сервер

```bash
claude mcp add <name> <command> [args]
claude mcp add playwright npx @playwright/mcp
claude mcp add filesystem npx @modelcontextprotocol/server-filesystem /path
```

### .mcp.json в проекте

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp"]
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgres://localhost/mydb"]
    }
  }
}
```

### Популярные MCP серверы

| Сервер | Что даёт |
|--------|----------|
| `@playwright/mcp` | Управление браузером, скриншоты, автоматизация |
| `@modelcontextprotocol/server-filesystem` | Расширенный доступ к файлам |
| `@modelcontextprotocol/server-postgres` | Работа с PostgreSQL |
| `@modelcontextprotocol/server-github` | GitHub API |
| `@modelcontextprotocol/server-slack` | Slack API |
| `context7` | Актуальная документация библиотек |

---

## ⚡ Skills (навыки)

Skills — переиспользуемые промпты с контекстом. Вызываются как `/skill-name`.

### Структура skill

```markdown
---
name: commit
description: Create a conventional commit message. Use when user wants to commit.
---

Проанализируй git diff и создай коммит сообщение по формату:
<type>(<scope>): <description>

Типы: feat, fix, docs, refactor, test, chore
```

### Размещение

- Проектные: `.claude/skills/<name>.md`
- Глобальные: `~/.claude/skills/<name>.md`
- В плагине: `<plugin>/skills/<name>/SKILL.md`

---

## 🪝 Hooks (хуки)

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

### События

| Событие | Когда срабатывает |
|---------|------------------|
| `PreToolUse` | Перед вызовом инструмента |
| `PostToolUse` | После вызова инструмента |
| `SessionStart` | При запуске сессии |
| `SessionEnd` | При завершении сессии |
| `UserPromptSubmit` | При отправке сообщения |
| `Stop` | Когда Claude завершил ответ |

### Пример хука

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "npm run lint --fix"
        }]
      }
    ]
  }
}
```

---

## 💬 Slash-команды

Кастомные команды, вызываемые через `/command-name`.

### Создание команды

Файл `.claude/commands/review-pr.md`:

```markdown
---
name: review-pr
description: Review a pull request
argument-hint: PR number
---

Просмотри PR #$ARGUMENTS:
1. `gh pr view $ARGUMENTS`
2. `gh pr diff $ARGUMENTS`
Дай оценку качества кода и укажи проблемы.
```

### Встроенные команды
- `/help` — справка
- `/clear` — очистить контекст
- `/compact` — сжать историю
- `/cost` — стоимость сессии
- `/doctor` — диагностика установки
- `/model` — сменить модель
- `/memory` — управление памятью

---

## 🧠 Память (Memory)

Claude может сохранять информацию между сессиями через файловую память.

### Типы памяти

| Тип | Что хранить |
|-----|-------------|
| `user` | Роль, предпочтения, уровень знаний |
| `feedback` | Исправления и корректировки поведения |
| `project` | Контекст работы, цели, дедлайны |
| `reference` | Ссылки на внешние ресурсы |

Память хранится в `~/.claude/projects/<project>/memory/*.md`

---

## 🚀 Оптимальная настройка под задачи

### Для разработки (backend/frontend)

**CLAUDE.md:**
```markdown
## Stack
Node.js + TypeScript + PostgreSQL

## Тесты
npm test -- --runInBand

## Линтинг
Всегда запускай eslint после изменений в src/

## Нельзя
- Прямые запросы к БД вне репозиториев
- console.log в production коде
```

**MCP:** `filesystem`, `postgres`
**Hooks:** PostToolUse → eslint/prettier

### Для работы с документацией/заметками

**CLAUDE.md:** структура vault, шаблоны, правила оформления
**Skills:** шаблонные команды добавления записей
**Memory:** предпочтения форматирования

### Для code review

**Agent:** специализированный reviewer агент
**MCP:** `github` для работы с PR
**Skill:** `/review-pr`

---

## 🔑 Горячие клавиши

| Комбинация | Действие |
|------------|----------|
| `Ctrl+C` | Прервать текущий ответ |
| `Ctrl+R` | История команд |
| `↑/↓` | Навигация по истории |
| `Shift+Tab` | Переключить режим авто-принятия |

Кастомизация в `~/.claude/keybindings.json`.

---

## 📋 Чеклист первой настройки

- [ ] Создать `~/.claude/CLAUDE.md` с глобальными предпочтениями
- [ ] В каждом проекте создать `CLAUDE.md` со структурой и правилами
- [ ] Настроить нужные MCP серверы (`.mcp.json`)
- [ ] Добавить часто используемые Skills
- [ ] Настроить хуки для автоматического линтинга/форматирования
- [ ] Задать permissions в `settings.json`
- [ ] Создать кастомные команды для повторяющихся задач

---

## 🔗 Ссылки

- [[Gemini CLI]] — аналог от Google
- [[Codex CLI]] — аналог от OpenAI