Первая настройка AI-агента

Эта инструкция ведёт от пустого терминала до первой задачи, которую агент делает сам и сам же проверяет. Основной пример — Claude Code, но те же шаги есть в Codex и Cursor, о них отдельный раздел в конце. Все команды взяты из официальной документации, ссылки в конце статьи.

#Что понадобится

• Проект в git, который вы хорошо знаете. Первую задачу лучше давать там, где ошибку видно сразу.
• Команда, которая проверяет проект: тесты, сборка или хотя бы проверка типов.
• Для Claude Code — подписка Pro, Max, Team, Enterprise или аккаунт Console. Бесплатный план claude.ai доступа к Claude Code не даёт.

#Шаг 1. Установка

Рекомендуемый способ для macOS, Linux и WSL — нативный установщик. Он сам обновляется в фоне:

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

Альтернативы — Homebrew (brew install --cask claude-code) и npm (npm install -g @anthropic-ai/claude-code, нужен Node.js 22+). Установки через Homebrew и WinGet сами не обновляются. Если что-то не так, запустите claude doctor: команда покажет диагностику установки и настроек, не открывая сессию.

Первый запуск — команда claude в папке проекта. Агент откроет браузер для входа.

#Шаг 2. Файл инструкций: CLAUDE.md

Каждая сессия начинается с пустого контекста. Чтобы агент не узнавал проект заново каждый раз, нужен CLAUDE.md — файл с постоянными инструкциями, который загружается в начале каждой сессии.

Запустите в сессии команду /init. Агент изучит код и создаст файл с командами сборки, тестов и найденными соглашениями. Если файл уже есть, /init предложит улучшения, а не перезапишет его.

Дальше отредактируйте результат. Правила из документации о памяти:

• Короче 200 строк. Длинный файл занимает больше контекста и хуже соблюдается.
• Проверяемые формулировки. «Используй отступ в 2 пробела» вместо «форматируй аккуратно». «Запускай npm test перед коммитом» вместо «тестируй изменения».
• Без противоречий. Если два правила спорят, агент может выбрать любое.

Пример:

# CLAUDE.md
## Команды
- Тесты: `npm test`
- Проверка типов: `npx tsc --noEmit`

## Архитектура
- API-хендлеры лежат в `src/api/handlers/`
- Общие типы — в `src/types/`

## Правила
- Не меняй миграции БД без явного запроса
- Новые зависимости — только после согласования

Где ещё живут инструкции:

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

#Шаг 3. Права

Права задаются в settings.json. Уровни, от старшего к младшему: управляемые настройки организации, аргументы командной строки, .claude/settings.local.json (лично вы, этот проект), .claude/settings.json (вся команда), ~/.claude/settings.json (вы, все проекты).

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(git push *)"]
  }
}

Как это работает, по документации о правах:

• Правила проверяются по порядку: deny, затем ask, затем allow. Первое совпадение решает. Разрешение не может сделать исключение из запрета.
• Звёздочка ставится где угодно: Bash(npm run *) совпадает с npm run build, но не с npm install.
• Чтобы агент не читал секреты, нужно правило Read в deny. Файл .claudeignore ни на что не влияет.

Отдельно от правил выбирается режим прав. Режимы переключаются клавишами Shift+Tab: default (Manual: всё, кроме чтения, с подтверждением), acceptEdits, plan, auto, dontAsk, bypassPermissions. В свежих версиях интерактивная сессия по умолчанию стартует в auto: действия проверяет отдельная модель-классификатор. Для первой задачи в незнакомом проекте осознанно включите plan или Manual.

#Шаг 4. Первая задача: изучить, спланировать, сделать, закоммитить

Рекомендуемый порядок из лучших практик:

1. Изучить. Включите режим плана (claude --permission-mode plan или Shift+Tab до надписи «plan mode on»). Попросите прочитать нужную часть кода.
2. Спланировать. Попросите план изменений: какие файлы, какой порядок. Ctrl+G открывает план в редакторе — его можно поправить руками.
3. Реализовать. Утвердите план и попросите реализовать, написать тесты, запустить их и исправить падения.
4. Закоммитить. Посмотрите diff и попросите коммит с внятным сообщением.

План полезен, когда задача затрагивает несколько файлов или непонятно, как к ней подступиться. Если изменение описывается одной фразой («переименуй переменную»), план не нужен.

#Шаг 5. Проверка результата

Агент заканчивает, когда работа выглядит готовой. Поэтому в каждой задаче нужен критерий, который он проверит сам:

Сборка падает с ошибкой: [вставь ошибку]. Найди причину, исправь,
убедись, что сборка проходит. Не глуши ошибку, устрани причину.

Просите доказательства: вывод тестов, команду и результат. Это быстрее, чем перепроверять вручную.

#Если вы работаете в Codex или Cursor

Codex CLI ставится через npm install -g @openai/codex или brew install --cask codex, запускается командой codex. Команда /init создаёт AGENTS.md. Codex собирает инструкции цепочкой: глобальный ~/.codex/AGENTS.md, затем файлы от корня репозитория до текущей папки, ближние перекрывают дальние; лимит по умолчанию — 32 КиБ. Настройки лежат в ~/.codex/config.toml. В режиме Auto (--sandbox workspace-write --ask-for-approval on-request) Codex сам читает, правит и запускает команды в рабочей папке, но спрашивает перед выходом за неё и перед доступом в сеть. Сеть по умолчанию выключена. Команда /permissions переключает режимы, например в read-only для обсуждения без правок.

Cursor хранит правила проекта в .cursor/rules/ в файлах .mdc с полями description, globs и alwaysApply. Правило может применяться всегда, по решению агента, к файлам по маске или вручную через @-упоминание. Простая альтернатива — AGENTS.md в корне или в подпапках.

Один файл для всех агентов. Claude Code читает AGENTS.md, если в проекте нет CLAUDE.md. Если CLAUDE.md нужен, подключите общий файл первой строкой @AGENTS.md, а ниже добавьте то, что касается только Claude.

#Частые ошибки

• Сессия-свалка. Одна задача, переключение на другую, возврат к первой — и контекст забит лишним. Между несвязанными задачами делайте /clear.
• Бесконечные исправления. Если после двух поправок агент всё ещё ошибается, начните заново с /clear и более точной формулировкой.
• Раздутый CLAUDE.md. Если агент и так делает что-то правильно без инструкции, удалите её или замените хуком.

Следующий шаг — продвинутая настройка: скиллы, хуки, сабагенты и MCP.