Гид по AI-агентам разработки

Этот гид для тех, кто хочет использовать AI-агентов для программирования, но не имеет технического бэкграунда. Coding agents (такие как Claude Code, GitHub Copilot, Cursor) — это AI-помощники, которые могут писать, редактировать и запускать код за вас.

Но чтобы эффективно с ними работать, нужно понимать базовые концепции: что такое терминал, как устроены файлы, что такое Git. Этот справочник даст вам именно эти фундаментальные знания.

Первое, что нужно понять — разницу между local (локально) и remote (удалённо).

Когда вы редактируете Google Doc на телефоне без интернета — вы работаете локально. Когда подключаетесь и синхронизируете — файл отправляется на remote сервер Google Drive.

Терминал — это приложение для управления компьютером через текстовые команды. Вместо кликов мышкой вы печатаете команды, и компьютер их выполняет.

Coding agents активно используют терминал. Хорошая новость: вам не нужно знать все команды — агент знает их за вас. Но полезно понимать, что происходит.

cd /Users/username/projects/my-app
# cd = Change Directory — сменить папку

На Mac терминал называется Terminal, на Windows — PowerShell или Command Prompt.

Директория — это просто папка. Путь (path) — это адрес файла или папки в системе.

/Users/username/Documents/          # Путь к папке Documents
/Users/username/projects/my-app/    # Путь к проекту
~/projects/my-app/src/index.js      # Путь к конкретному файлу

~ (тильда) — это сокращение для вашей домашней папки. Вместо /Users/username/ можно писать просто ~/.

Coding Agent — это AI-ассистент (как ChatGPT или Claude), но с доступом к инструментам вашего компьютера.

Обычный чат-бот может только отвечать текстом. Coding agent может:

• Создавать, редактировать и удалять файлы
• Запускать команды в терминале
• Устанавливать пакеты и зависимости
• Запускать и тестировать код
• Работать с Git (сохранять изменения, создавать ветки)

Каждый coding agent имеет системный промпт — набор инструкций, определяющих его поведение.

Системный промпт говорит агенту: «Ты — эксперт-разработчик. Вот что ты умеешь делать. Вот чего делать нельзя. Твои знания актуальны до такой-то даты».

Некоторые компании публикуют свои системные промпты (например, Anthropic публикует промпт Claude), другие держат их в секрете.

Markdown (.md) — это формат текстовых файлов с простой разметкой. Используется для документации, README файлов, и инструкций для агентов.

# Заголовок 1
## Заголовок 2
**Жирный текст**
*Курсив*
- Элемент списка
- Ещё элемент

AGENTS.md (или CLAUDE.md для Claude) — это файл в корне проекта с вашими инструкциями для агента.

# Инструкции для агента

- Я не технический специалист, объясняй всё простым языком
- Используй TypeScript вместо JavaScript
- Всегда пиши комментарии к коду

Агент читает этот файл и следует вашим инструкциям. Файлы AGENTS.md работают иерархически — ближайший к редактируемому файлу читается первым.

Skills — это переиспользуемые наборы инструкций, которые агент загружает по необходимости.

В отличие от AGENTS.md (который читается всегда), навыки загружаются только когда нужны. Это экономит контекстное окно агента.

---
name: newsletter-writer
description: Используй для написания контента рассылки
---

# Инструкции
- Никогда не используй эмодзи
- Заголовки только строчными буквами
- Максимум 4 слова в заголовке

Frontmatter (метаданные в начале файла между ---) помогает агенту понять, когда использовать этот навык.

Progressive Disclosure — агент сам загружает нужные навыки, когда видит релевантную задачу. Вам не нужно явно говорить «используй навык X».

AI-модели имеют ограниченную «память» — контекстное окно. Оно измеряется в токенах.

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

Git — система контроля версий. Это как «машина времени» для вашего кода: можно сохранять состояния проекта и возвращаться к любому из них.

git status              # Посмотреть что изменилось
git add .               # Добавить все изменения
git commit -m "текст"   # Сохранить снимок
git push                # Отправить на сервер (GitHub)
git pull                # Загрузить изменения с сервера

API-ключ — уникальный пароль для доступа к сервису (OpenAI, Stripe, Google и др.).Переменные окружения — способ хранить секреты отдельно от кода.

OPENAI_API_KEY=sk-xxx123abc
STRIPE_SECRET_KEY=sk_live_xxx
DATABASE_URL=postgres://user:pass@host/db

Файл .env остаётся только на вашем компьютере. В .gitignore указано, чтобы Git его игнорировал.

При деплое (публикации) нужно добавить эти переменные в настройках хостинга (Vercel, Netlify и др.).

Зависимости (dependencies) — внешние библиотеки, которые использует ваш проект. Вы не пишете всё с нуля — используете готовый код других разработчиков.

npm install          # Установить все зависимости из package.json
npm install react    # Установить конкретный пакет

pip install -r requirements.txt  # Python аналог

package.json — файл со списком зависимостей JS-проекта.
node_modules — папка с установленными пакетами (огромная, не трогать, не коммитить).

Localhost — ваш компьютер, притворяющийся веб-сервером. Когда вы запускаете проект локально, он доступен только вам по адресу типа http://localhost:3000.

npm run dev      # Запустить в режиме разработки
npm start        # Запустить приложение
npm run build    # Собрать для production

Порт (3000, 8080, 5173) — это «канал». Разные приложения работают на разных портах и не мешают друг другу.

Hot Reload — автоматическое обновление страницы при изменении кода. Не нужно перезапускать сервер после каждого изменения.

Деплой — публикация проекта в интернет, чтобы его могли видеть другие люди.

Coding agent может задеплоить проект за вас через CLI (command line interface) этих платформ.

Когда что-то ломается, терминал показывает ошибку — красный текст, выглядит страшно. Но он пытается помочь!

ENOENT          # Файл не найден (No Entry)
ECONNREFUSED    # Не удалось подключиться (сервер не запущен?)
ENOTDIR         # Ожидалась папка, а это файл
EACCES          # Нет доступа (права)

DevTools — инструменты разработчика, встроенные в браузер. Открыть:F12 илиCmd+Option+I (Mac).

Если кнопка не работает или данные не загружаются — откройте Console и посмотрите ошибки. Скопируйте их агенту.

Баги — это нормально. Даже профессиональные разработчики тратят на них много времени. Главное — правильный подход к исправлению.

Тесты — код, который проверяет другой код. «Когда нажимаю кнопку — должно произойти X». Агент может писать тесты за вас.

Coding agents работают по циклу: План → Действие → Наблюдение → Повтор.

1. План: Агент думает, что нужно сделать
2. Действие: Создаёт файлы, запускает команды, пишет код
3. Наблюдение: Смотрит на результат — получилось или ошибка?
4. Повтор: Если не получилось — пробует исправить

Цикл продолжается, пока задача не выполнена или агент не застрянет. Когда застрянет — спросит вас.

Разные агенты имеют разную степень самостоятельности. Можно настроить, сколько свободы давать агенту.

С опытом вы будете давать агенту больше автономии. Это быстрее, но требует доверия и понимания, что можно откатить через Git.

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

Ошибки, которые совершают почти все. Избежите их — сэкономите часы.