Перейти к основному содержимому

Claude Code — установка, контекст и практический проект

Разработчику

Claude Code — агентный инструмент Anthropic для разработки: читает репозиторий, правит файлы, запускает shell и Git, подключает внешние системы через MCP. Доступен в терминале, VS Code / Cursor, Desktop, JetBrains и браузере (claude.ai/code). Ниже — установка (macOS/Windows), терминал и Git, сессии, plan mode, MCP, безопасность и практикум lead-webhook. Сравнение с Cursor — 4.14 / 1113; риски слепого merge — вайб-кодинг.

Официальная документация — code.claude.com/docs.


Где запускать — CLI, IDE, Desktop и веб

ПоверхностьКогда уместнаОсобенности
CLI (claude)Полный контроль, скрипты, CI, Ralph-loopShift+Tab — смена permission mode; pipe и -p для one-shot
VS Code / CursorInline diff, @-mentions, plan reviewРасширение из Marketplace; тот же движок, что в CLI
DesktopПараллельные сессии, визуальный diff, расписаниеИзолированные git worktree, side chat
Web (claude.ai/code)Репозиторий без локального clone, длинные задачи--teleport / --remote — перенос сессии в терминал
JetBrainsIntelliJ, PyCharm, WebStormПлагин + терминал с теми же командами

CLAUDE.md, skills, hooks и MCP работают на всех поверхностях — конфигурация единая.


Установка и первый запуск

Системные требования

  • macOS 13+, Linux (Debian/Fedora/Alpine через пакетные менеджеры), Windows 10 1809+ или WSL
  • Подписка Claude или аккаунт Anthropic Console (часть возможностей — только Anthropic API)
  • На Windows для Bash-tool рекомендуется Git for Windows; иначе shell идёт через PowerShell

Установка (рекомендуемый native installer)

macOS, Linux, WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Альтернативы

СпособКомандаАвтообновление
Homebrewbrew install --cask claude-codeВручную: brew upgrade claude-code
WinGetwinget install Anthropic.ClaudeCodeВручную: winget upgrade Anthropic.ClaudeCode
npmnpm install -g @anthropic-ai/claude-codeЗависит от политики npm
apt (Debian/Ubuntu)см. setupapt upgrade claude-code

Проверка и вход

claude --version
claude doctor
cd your-project
claude

При первом запуске — OAuth-авторизация в браузере. Для API-биллинга вместо подписки — claude auth login --console. Статус входа — claude auth status. Секреты API храните в env, не в репозитории (гигиена).

macOS — типичная настройка

ШагДействие
1Native installer — автообновление в фоне
2claude doctor — проверка PATH и версии
3Терминал iTerm2/Terminal.app — Shift+Enter для новой строки (terminal config)
4Desktop-приложение — опционально для параллельных сессий и визуального diff

На Apple Silicon и Intel Desktop-бинарники разные; CLI одинаков для обеих архитектур.

Windows — типичная настройка

ШагДействие
1PowerShell от имени пользователя (не обязательно admin): irm https://claude.ai/install.ps1 | iex
2Закрыть и открыть PowerShell — иначе claude не в PATH
3Установить Git for Windows — Bash-tool для shell-команд агента
4При ошибке PATH — перезапуск терминала или добавление каталога установки в переменные среды (troubleshoot)

WSL2 — предпочтительный вариант, если стек проекта Linux-only (Docker, make, bash-скрипты). Native Windows удобен для PowerShell-проектов и .NET.

CMD vs PowerShell: установщик для CMD — отдельная команда из setup; промпт PS C:\ означает PowerShell.

Каталог .claude/ в проекте

После настройки в репозитории появляется конфигурация агента:

Файл / папкаНазначение
CLAUDE.mdПравила проекта (может быть в корне без .claude/)
.claude/settings.jsonPermission mode, allow/deny — коммитят
.claude/settings.local.jsonЛичные allow для Bash — в .gitignore
.claude/skills/Команды /skill-name
.claude/agents/Custom subagents
.mcp.jsonMCP-серверы проекта

Глобально — ~/.claude/settings.json, ~/.claude.json (MCP), транскрипты в ~/.claude/projects/.

Диагностика конфигурации

/doctor — версия и окружение; /context — что заняло контекст; /hooks и /mcp — что реально загрузилось (debug config).

Базовые команды CLI

КомандаНазначениеПример
claudeИнтерактивная сессияclaude
claude "задача"Одноразовая задача в сессииclaude "исправь падающий тест auth"
claude -p "запрос"Print mode — ответ и выходgit diff | claude -p "краткий review"
claude -cПродолжить последний диалог в каталогеclaude -c
claude -rВыбрать сессию из историиclaude -r
claude --permission-mode planСтарт в plan modeсм. ниже
/helpСписок slash-командвнутри сессии
/clearОчистить контекст диалога
/compactСжать историю
/costТокены и стоимость
/initСгенерировать CLAUDE.md
/reviewCode review изменений
/mcp, /hooksДиагностика MCP и hooks
exit или Ctrl+DВыход
Windows в этой энциклопедии

Команды выше ориентированы на bash. В PowerShell эквивалент pipe — Get-Content app.log -Tail 200 | claude -p "...". Для привычного bash-окружения на Windows удобен WSL или Git Bash.


Терминал, Git и Cursor

Интерактивный терминал

Claude Code в CLI — полноценная TUI-сессия: агент читает stdout/stderr команд, показывает diff перед apply, запрашивает разрешения.

ПриёмНазначение
Shift+TabЦикл permission modes
Shift+EnterНовая строка в промпте (настраивается в terminal-config)
Ctrl+GОткрыть план или большой текст в $EDITOR
EscПрервать генерацию
@файлЯвно добавить файл в контекст
claude --ideПодключиться к открытому VS Code/Cursor

One-shot из скриптов и CI — claude -p "..." (без интерактива). Обновление бинарника — claude update.

Git в повседневной работе

Claude Code работает с Git напрямую — branch, commit, diff, иногда PR.

ЗадачаПример промпта / команды
Коммитclaude "закоммить изменения — conventional commits"
Новая веткаclaude "ветка fix/auth-422 от main, только правки auth"
Review перед push/review или git diff main | claude -p "security review"
Продолжить работу над PRclaude --from-pr 123
Параллельные фичиclaude --worktree — изолированная копия (worktrees)

Агент видит git status, git log, git diff — полезно указать в CLAUDE.md политику веток (main только через PR).

Cursor и Claude Code вместе

Расширение Claude Code ставится в Cursor из Marketplace (то же, что в VS Code). Типичное разделение:

ЗадачаИнструмент
Tab-дополнение, точечный editCursor
Мультифайловый рефакторинг, shell, тестыClaude Code в терминале Cursor
Plan + diff в IDEClaude Code panel в Cursor
CI и headless reviewclaude -p в GitHub Actions

Синхронизация правил: один источник истины — ARCHITECTURE.md или AGENTS.md; в CLAUDE.md и .cursorrules — ссылки на него (1113). Git — общий синхронизатор: Claude Code коммитит, Cursor открывает тот же diff.


Контекстная инженерия — как говорить с агентом

Контекстная инженерия — осознанная сборка того, что попадает в окно модели: файлы, правила, diff, результаты tools. Качество ответа определяется контекстом сильнее, чем «красотой» формулировки (117).

Слои контекста в Claude Code

СлойИсточникКогда загружается
Системные правилаПлатформа AnthropicКаждый запрос
CLAUDE.mdКорень проекта, вложенные каталогиСтарт сессии
Auto memory~/.claude/projects/...Между сессиями одного проекта
Skills.claude/skills/По триггеру или /skill-name
Диалог + tool resultsТекущая сессияНакапливается до compact
@-mentions / ReadЯвно указанные файлыПо запросу

CLAUDE.md — контракт с агентом

Файл в корне (или docs/CLAUDE.md со ссылкой) — аналог .cursorrules. Минимальный каркас:

## Проект lead-webhook

FastAPI-сервис: POST /leads, валидация, запись в SQLite.

### Команды
- `make test` — pytest
- `make lint` — ruff check .
- `make run` — uvicorn app.main:app --reload

### Соглашения
- Pydantic v2 для DTO
- Все эндпоинты покрыты тестами в tests/
- Секреты только из env WEBHOOK_SECRET

### Запрещено
- DROP/DELETE без явного запроса пользователя
- Новые зависимости без согласования

Команда /init генерирует черновик по структуре репозитория — его редактируют, а не принимают вслепую.

Принципы эффективного промпта

  1. Критерий готовности — «тесты зелёные», «OpenAPI совпадает со spec.md», а не «сделай API».
  2. Границы — один модуль, одна ветка, список файлов «не трогать».
  3. Эталон — 30–80 строк вашего стиля из соседнего файла.
  4. Верификация — «после правок запусти make test и покажи вывод».
  5. Явные unknowns — «если API пакета не уверен — напиши, что проверить в доке».

Параметры генерации (temperature, structured output) — 118.

Экономия контекста

  • /compact — когда история раздулась после длинного исследования.
  • Субагент Explore — поиск по кодовой базе без засорения главного чата.
  • Skills — длинные инструкции подгружаются только при вызове, а не на каждый turn.
  • Вложенные CLAUDE.md в монорепо — правила ближе к пакету (large codebases).

Сессии и slash-команды

Управление сессиями

Сессия — сохранённый диалог, привязанный к каталогу проекта. Транскрипт пишется в ~/.claude/projects/.../*.jsonl.

КомандаНазначение
claude -c / --continueПродолжить последнюю сессию в каталоге
claude -r / --resumePicker всех сессий
claude -r "auth-refactor"Resume по имени
claude -n auth-refactorИмя сессии при старте
/rename auth-refactorПереименовать текущую
/branch try-v2Ответвить диалог, не теряя оригинал
claude --continue --fork-sessionFork из CLI
claude --from-pr 42Сессия, создавшая PR
/clearПустой контекст; старый диалог сохранён
/exportЭкспорт в файл или буфер

В picker — поиск /, фильтр по ветке Ctrl+B, все проекты Ctrl+A (sessions).

Slash-команды — справочник

КомандаНазначение
/helpВсе команды и skills
/initЧерновик CLAUDE.md
/reviewReview текущих изменений
/planPlan mode на один промпт
/compact [фокус]Сжать историю с акцентом
/contextДиаграмма заполнения контекста
/costТокены и стоимость сессии
/memoryAuto memory проекта
/add-dir ../libДоп. каталог для чтения
/agentsSubagents — создать и редактировать
/mcpСтатус MCP-серверов
/hooksСписок hooks
/pluginПлагины и marketplaces
/permissionsAllow/deny и недавние отказы
/modelСмена модели в сессии
/loopPolling / повтор промпта в сессии
/goalУсловие завершения задачи
/desktopПеренос сессии в Desktop app
/doctorДиагностика окружения

Bundled skills ведут себя как slash-команды: /code-review, /debug, /batch.


Продвинутые возможности

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

Специализированные агенты с отдельным контекстом и ограниченными tools. Claude делегирует задачу, когда описание subagent совпадает с запросом.

ВстроенныйМодельНазначение
ExploreHaikuRead-only поиск по репо
Planкак у родителяИсследование в plan mode
general-purposeкак у родителяМногошаговые задачи с правками

Создание своего — markdown с YAML frontmatter в .claude/agents/ или ~/.claude/agents/:

---
name: security-reviewer
description: Сканирует diff на SQLi, утечки секретов, слабую auth. Use when reviewing PR or before merge.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Ты security-реviewer. Читай только diff и связанные файлы.
Вывод: таблица finding | severity | файл | рекомендация.
Не правь код — только отчёт.

Управление — slash-команда /agents. Параллельные независимые сессии — agent view (claude agents) и agent teams (документация).

Планирование задач

МеханизмКогда использовать
Plan subagentRead-only обход репо в plan mode
/goalЯвное условие выхода («пока make test красный — продолжай»)
UltraplanПлан в облаке, review в браузере, execute в CLI (ultraplan)
Todo-лист в сессииМногошаговые задачи с видимым прогрессом
Разбей задачу на шаги с критерием готовности каждого.
Шаг N — done только после зелёного make test. Сначала план без правок.

Skills (навыки агентов)

Папка .claude/skills/<name>/SKILL.md — переиспользуемая процедура с командой /name.

---
description: Деплой staging по чеклисту команды. Use when user says deploy staging.
---

## Шаги
1. `git fetch && git status`
2. `make test && make lint`
3. Только при успехе — `make deploy-staging`
4. При ошибке — остановись и покажи лог

Bundled skills — /code-review, /debug, /loop. Custom commands из .claude/commands/ работают так же, как skills.

MCP — внешние tools

MCP подключает БД, GitHub, Linear, браузер и custom API как tools агента.

Уровни конфигурации

УровеньФайлОбласть
Пользователь~/.claude.jsonmcpServersВсе проекты
Проект.mcp.json в корнеТолько этот репо
CLIclaude --mcp-config ./mcp.jsonОдна сессия

Пример .mcp.json:

{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/leads"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}
}
}

Управление в сессии — /mcp (статус, переподключение). Токены — только через env, не в коммите. Архитектура протокола — MCP-серверы. Корпоративные allowlist — managed MCP.

Plugins — готовые bundles

claude plugin install code-review@claude-plugins-official
claude plugin install ralph-wiggum@claude-plugins-official

Плагин может включать skills, agents, hooks и MCP. Marketplaces — /plugin marketplace add. Создание своего — plugins.

Hooks — детерминированная автоматизация

Shell-команды на событиях жизненного цикла. Пример — автоформат после правки:

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

Файл — ~/.claude/settings.json или .claude/settings.json. Список событий — PreToolUse, PostToolUse, Notification, Stop и др. (hooks guide).


Plan mode, разрешения и Ralph-loop

Permission modes

Режим задаёт, когда Claude спрашивает перед edit или shell. Переключение в CLI — Shift+Tab (цикл default → acceptEdits → plan → …).

ModeПоведениеКогда использовать
defaultСпрашивает перед опасными действиямиСтарт, прод, незнакомый репо
acceptEditsАвто-правки файлов в working treeИтерации с review через git diff
planТолько чтение и read-only shellАрхитектура до первого коммита
autoКлассификатор вместо prompt (research preview)Длинные задачи, Anthropic API
dontAskТолько pre-approved toolsCI, скрипты
bypassPermissionsБез prompt (опасно)Только container/VM

Plan mode — исследование без правок исходников. Старт:

claude --permission-mode plan

или префикс /plan к промпту. После плана — approve с переходом в acceptEdits или auto.

Default для проекта:

{
"permissions": {
"defaultMode": "plan"
}
}

Файл — .claude/settings.json. Тонкая настройка — permissions.allow / deny (permissions).

bypassPermissions и root

--dangerously-skip-permissions эквивалентен bypassPermissions. На Linux/macOS запуск под root/sudo заблокирован. Для автономного прогона используйте devcontainer или sandbox, а не рабочую машину с доступом к prod.

Ralph-loop — код в цикле до completion promise

Ralph (от community-метафоры «bash while true») — паттерн повторного запуска одного промпта, пока агент не выведет completion promise или не исчерпает лимит итераций. В официальных плагинах Anthropic — команда /ralph-loop со Stop hook, который перехватывает выход и подаёт тот же промпт снова.

/ralph-loop "Реализуй POST /leads по spec.md. Тесты make test должны пройти.
Выведи <promise>COMPLETE</promise> только когда всё зелёное." \
--completion-promise "COMPLETE" \
--max-iterations 25
ПараметрНазначение
--completion-promiseСтрока в <promise>...</promise> — сигнал «готово»
--max-iterations NОбязательный предохранитель от бесконечного цикла
Stop hookБлокирует exit, пока promise не найден

Практика без YOLO-mode: разрешения на make test, git commit и т.д. добавляют в .claude/settings.local.json; при нехватке прав Claude выводит <PROMISE>NEED_PERMISSIONS</PROMISE> и останавливается — вы дописываете allow и claude --continue.

Флаги передают через пробел (--max-iterations 25), не --max-iterations=25 — иначе старые версии парсера игнорировали лимит.

Смежные команды — /loop (polling внутри сессии), /goal (условие завершения), Routines в облаке (scheduled tasks).


Рабочие сценарии, автоматизация и безопасность

Типовые сценарии в команде

СценарийСтартКонтроль
Исправить падающий тестclaude "pytest tests/test_auth.py -x — почини и объясни root cause"Запуск теста агентом + ваш review diff
Рефакторинг модуляplan mode → approve → acceptEdits/review перед commit
Онбординг в legacyclaude --permission-mode plan "карта модулей и рисков"Subagent Explore
Миграция зависимостейRalph-loop с --max-iterations + DoD «lint + test»Sandbox / отдельная ветка
PR reviewclaude --from-pr N или GitHub ActionHuman merge
Инцидент — разбор логовtail -500 app.log | claude -p "анomalies + гипотезы"Без auto-edit в prod
Документация APIclaude -p "OpenAPI из app/main.py"Ручная сверка с кодом

Автоматизация вне интерактива

МеханизмПример
Headlessclaude -p "translate new i18n keys" --allowedTools "Edit"
GitHub Actionsclaude-code-action — triage issues, review PR
Hooks StopRalph-loop — повтор до <promise>COMPLETE</promise>
Routines / Desktop scheduleЕжедневный /review открытых PR
ChannelsWebhook CI → push в активную сессию (channels)

Безопасность — минимальный чеклист

УгрозаМера
Destructive shelldefault или plan mode; deny Bash(rm -rf *)
Утечка секретов в промпт.env в .gitignore; PreToolUse hook на cat .env
Prompt injection из файловReview untrusted input; sandbox для web fetch
Bypass в prodТолько devcontainer/VM; permissions.disableBypassPermissionsMode в managed settings
MCP с prod-БДRead-only user; отдельный MCP на staging
Protected paths.git, .claude (частично), shell rc — не auto-approve (permission modes)

Изоляция — devcontainer, sandboxed Bash. Политика опасных команд — 101.


Практический проект — webhook для лидов

Сквозной сценарий: мини-сервис из AI-стека дорабатывается в Claude Code с plan → implement → test → review.

Цель и Definition of Done

КритерийПроверка
POST /leads принимает JSON {email, message}curl + pytest
Невалидный email → 422test_invalid_email
Дубликат email → 409test_duplicate
SQLite через SQLAlchemyфайл leads.db в .gitignore
make test и make lint зелёныеCI-ready

Фаза 0 — каркас репозитория

mkdir lead-webhook && cd lead-webhook
git init
claude /init # или вручную CLAUDE.md по шаблону выше

Структура после первой сессии:

lead-webhook/
├── CLAUDE.md
├── .claude/settings.json # defaultMode: plan на первый день
├── app/
│ ├── main.py
│ ├── models.py
│ └── schemas.py
├── tests/
│ └── test_leads.py
├── Makefile
├── pyproject.toml
└── spec.md # контракт API одной страницей

Фаза 1 — plan mode

claude --permission-mode plan

Промпт:

Прочитай spec.md. Предложи план: модели, роуты, тесты, Makefile.
Не редактируй файлы. В конце — список файлов для создания.

Review плана в редакторе (Ctrl+G в CLI). Approve → acceptEdits.

Фаза 2 — реализация

claude --permission-mode acceptEdits
Реализуй план. После каждого модуля запускай make test.
Новых pip-зависимостей без списка в pyproject.toml не добавляй.

При необходимости — subagent Explore для поиска паттернов в вашем другом репо.

Фаза 3 — Ralph-loop на «дожим»

После установки плагина ralph-loop:

/ralph-loop "Доведи lead-webhook до DoD в CLAUDE.md. make test && make lint без ошибок.
<promise>COMPLETE</promise> только при полном DoD." \
--completion-promise "COMPLETE" --max-iterations 15

Фаза 4 — review и коммит

/review
Закоммить с сообщением feat: add lead webhook API. Conventional Commits.

Фаза 5 — интеграция с n8n (из статьи 3)

Webhook URL сервиса → узел HTTP Request в n8n → LLM-классификация → Supabase. Claude Code генерирует OpenAPI snippet для n8n:

claude -p "По app/main.py выведи JSON Schema тела POST /leads для n8n"

Контроль качества — не вайб

РискКонтрмера в Claude Code
Merge без пониманияPlan mode → diff review → /review
Бесконечный Ralph--max-iterations, явный DoD в промпте
Утечка секретов.env в .gitignore; deny на cat .env в hooks
Опасный shelldefault mode; sandbox / devcontainer
Нейрослоп в тестахDoD «каждый тест проверяет assert, не pass»

Эксплуатация агентов в prod — AgentOps. Опасные команды — 101.


Итог

Claude Code закрывает полный цикл разработки в терминале и браузере: установка через native installer, CLAUDE.md и skills для контекста, subagents и MCP для масштаба, hooks и plugins для автоматизации, plan mode и granular permissions для безопасности, Ralph-loop — для итераций «пока тесты не зелёные». Практический результат — измеримый DoD, Git и review, а не «вроде работает».


См. также


См. также

Другие статьи этого же раздела в боковом меню (как на странице "О разделе").

Освоение главы0%