# Как писать промпты для ИИ-агентов программирования

URL: https://agentvera.dev/ru/blog/prompts-for-ai-coding-agents/ · Опубликовано: 2026-10-27

Промпты для ИИ-агентов программирования: плохие и хорошие примеры, файлы и ограничения, план до кода, разбиение задач, проверка результата и повторное использование.

**Коротко:**

- Хороший промпт для агента называет цель, файлы, с которых начать, ограничения и способ проверить результат. Расплывчатый промпт даёт расплывчатый код.
- Для всего крупнее мелкой правки сначала попросите план, разбейте работу на шаги, которые можно проверить, и скажите агенту, какая команда докажет, что задача готова.
- Повторяющиеся правила пишутся в CLAUDE.md, AGENTS.md или GEMINI.md, а повторяющиеся процессы становятся скиллами или своими командами, и каждый промпт остаётся коротким.

**Хороший промпт для ИИ-агента программирования сообщает четыре вещи: что вы хотите, с чего начать, что нельзя менять и как понять, что всё получилось.** Большинство плохих результатов появляется из-за того, что одна из этих частей пропущена, а не из-за неудачных формулировок. Агент умеет читать ваш код, запускать команды и править файлы, поэтому задача промпта — направить эту работу в нужную сторону и обозначить финишную черту.

В этом руководстве плохие и хорошие промпты показаны рядом, а дальше разобраны контекст, планы, разбиение работы, проверка и то, где хранить промпты, которые вы используете повторно. Примеры написаны для Claude Code и Codex CLI, но те же привычки работают в Gemini CLI и любом другом [агенте для программирования](/ru/glossary/coding-agent/ "Что такое агент для программирования").

## Чем промпт для агента отличается от промпта для чат-бота

У чат-бота есть только ваше сообщение. У агента для программирования есть весь репозиторий, оболочка и цикл: он читает файлы, вносит изменение, что-то запускает, смотрит на результат и пробует снова. От этого меняется то, что должен делать промпт:

- **Вставлять код не нужно.** Укажите файлы, и агент прочитает их сам.
- **Зато нужно задать границы.** Агент, которому можно править всё, может изменить то, что вы не имели в виду.
- **Нужно правило остановки.** Без него агент сам решает, когда работа достаточно хороша, и его планка может не совпасть с вашей.

Каждый лишний файл, который читает агент, к тому же заполняет его [контекстное окно](/ru/glossary/context-window/ "Что такое контекстное окно"). Сфокусированный промпт держит агента в фокусе, а сессию — дешевле.

## Плохой промпт и хороший промпт

Вот типичная первая попытка:

```text
fix the login bug
```

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

А вот тот же запрос, написанный для агента:

```text
Users with an email that has uppercase letters can't log in: the API returns
401 even with the right password. Signup stores emails as typed; login looks
them up as typed too, so "Ana@x.com" and "ana@x.com" don't match.

Start in src/auth/login.ts and src/auth/signup.ts.
Normalize emails to lowercase on both signup and login. Don't change the
database schema in this task, and don't touch the session code.

Done when: a new test in tests/auth.test.ts logs in with "Ana@X.com" after
signing up with "ana@x.com", and `pnpm test` passes. Show me the diff.
```

Он длиннее, но каждая строка избавляет агента от одной догадки. Вот что делает каждая часть:

| Часть | Пример | Чем помогает |
| --- | --- | --- |
| Симптом | «возвращает 401 даже с верным паролем» | Агент знает, что нужно воспроизвести |
| Причина, если вы её знаете | «сохраняет email как введён» | Экономит долгий поиск |
| Стартовые файлы | `src/auth/login.ts` | Меньше чтения, меньше неверных догадок |
| Ограничения | «не меняй схему базы данных» | Изменение остаётся небольшим и безопасным |
| Критерии готовности | конкретный тест плюс `pnpm test` | Финишная черта, которую агент может проверить |

Причину вы знаете не всегда. Это нормально: так и скажите и попросите агента найти её до исправления. «Выясни, почему происходит X, и объясни это, прежде чем что-либо менять» — сильный промпт сам по себе.

## Давайте контекст, а не сочинения

Самый полезный контекст — конкретный и проверяемый. Примерно в порядке ценности:

1. **Пути к файлам и символы.** `src/billing/invoice.ts`, `calculateTax()`. В Claude Code и Codex можно набрать `@`, выбрать файл и прикрепить его.
2. **Вывод ошибки.** Вставьте точный стек вызовов или вывод упавшего теста, а не пересказ.
3. **Ограничения.** Какие библиотеки вы используете и какие нет, какие папки не трогать, какие API должны сохранить обратную совместимость.
4. **Примеры в коде.** «Следуй шаблону из `src/routes/users.ts`» лучше, чем абзац с описанием этого шаблона.
5. **Зачем.** Одно предложение о цели для пользователя помогает агенту принимать разумные решения там, где вы ничего не уточнили.

Что не нужно: долгая история проекта, ваше мнение о несвязанном коде и инструкции, которые относятся к каждой задаче. Последним место в файле проекта, о нём ниже.

Для работы с интерфейсом помогают скриншоты. И Claude Code, и Codex принимают изображения; Codex к тому же умеет `codex --image path/to/file.png` в командной строке.

## Сначала попросите план

Для всего крупнее мелкой правки разделяйте размышление и действие. Попросите агента прочитать код и предложить план, проверьте его и только потом дайте реализовать.

- **Claude Code:** нажимайте Shift+Tab, пока в строке состояния не появится режим планирования, наберите `/plan` перед отдельным промптом или запустите `claude --permission-mode plan`. В режиме планирования Claude читает и предлагает, но не правит. Подробности — в статье [режим планирования Claude Code](/ru/blog/claude-code-plan-mode/ "Режим планирования Claude Code").
- **Codex CLI:** `/plan` просит Codex спланировать работу перед реализацией. Можно также начать сессию только для чтения, выбрав Read Only в `/permissions`.
- **Любой агент:** скажите словами: «Пока ничего не правь. Прочитай нужные файлы и дай нумерованный план со списком файлов, которые изменишь».

Промпт для планирования, который хорошо работает:

```text
We need to add CSV export to the reports page.
Don't write code yet. Read src/reports/ and the existing PDF export in
src/export/pdf.ts, then give me:
1. the files you will add or change,
2. how the CSV is built and streamed,
3. what you'll test,
4. anything you're unsure about.
```

Чтение плана занимает минуту и ловит дорогие ошибки: не та папка, новая зависимость, которая вам не нужна, миграция, которой вы не ждали. Если план неверен, поправьте его обычными словами («используй существующий хелпер `toRows()` вместо нового парсера») и попросите обновлённый план.

## Разбивайте большие задачи на шаги

Лучше всего агенты справляются с задачами, которые можно проверить за один присест. Промпт вроде «сделай систему биллинга» даёт огромный diff, который трудно проверить и трудно откатить. Разбейте его:

```text
Step 1 of 4: add the Invoice model and migration only.
No API routes or UI yet. Run the migration on the dev database and the
model tests, then stop and show me the diff.
```

Дальше шаг 2 — API, шаг 3 — интерфейс, шаг 4 — письма. После каждого шага вы проверяете, коммитите и начинаете следующий. Работать так помогают две привычки:

- **Коммитьте между шагами.** Чистый коммит — это контрольная точка. Если шаг 3 пошёл не так, вы возвращаетесь к концу шага 2, а не распутываете смешанный diff. Варианты перечислены в статье [как отменить изменения Claude Code](/ru/blog/undo-claude-code-changes/ "Как отменить изменения Claude Code").
- **Свежий контекст для несвязанной работы.** Переходя к другой теме, используйте `/clear` в Claude Code или `/new` в Codex. Старый контекст стоит токенов и тянет агента обратно к прошлой задаче.

Независимые шаги можно запускать и параллельно, каждого агента в своём [git worktree](/ru/blog/git-worktree-parallel-agents/ "Git worktree для параллельных агентов"), чтобы они не перезаписывали файлы друг друга.

## Скажите агенту, как проверить работу

«Сделай, чтобы работало» оставляет агенту решать, что значит «работает». Инструкция по проверке возвращает это решение вам. Хорошие инструкции — это команды с понятным результатом:

```text
Done when:
- `pnpm test tests/export.test.ts` passes, including a new test for an
  empty report,
- `pnpm typecheck` has no errors,
- GET /reports/42/export.csv returns a header row and one row per entry.
Paste the command output at the end.
```

Несколько приёмов, которые поднимают планку:

- **Сначала тест.** «Напиши тест, который воспроизводит баг, запусти его и покажи, что он падает. Потом исправляй код, пока тест не пройдёт». Так вы убеждаетесь, что тест действительно покрывает баг. Подробнее — в статье [как писать юнит-тесты с помощью ИИ](/ru/blog/write-unit-tests-with-ai/ "Юнит-тесты с помощью ИИ").
- **Просите доказательства, а не заверения.** «Вставь вывод» подделать труднее, чем «подтверди, что работает».
- **Назовите то, что не должно сломаться.** «Существующие тесты в `tests/auth/` должны по-прежнему проходить».
- **Запретите обходные пути.** «Не пропускай и не удаляй тесты и не добавляй приведения к `any`, чтобы заглушить ошибки типов». Агенты, которым нужно во что бы то ни стало пройти проверку, иногда идут этими путями.

Затем прочитайте diff. Вторая модель, проверяющая изменение, ловит многое; см. [ИИ-код-ревью](/ru/blog/ai-code-review/ "ИИ-код-ревью").

## Промпты, которые идут не так, и как их исправить

| Промпт | Что обычно происходит | Лучше |
| --- | --- | --- |
| «Приведи этот файл в порядок» | Большая переделка, переименованные функции, сломанные импорты в других местах | «Вынеси разбор в `parse.ts` в отдельную функцию; публичный API не меняй» |
| «Добавь тесты» | Поверхностные тесты, которые проверяют, что код делает то, что делает | «Добавь тесты для пустого ввода, файла на 10 МБ и битого заголовка; каждый должен падать, если я уберу проверку в строке 40» |
| «Сделай быстрее» | Случайные микрооптимизации | «Эндпоинт `/search` отвечает 2 с на 10 тыс. строк. Профилируй его, скажи, куда уходит время, потом предложи исправление» |
| «Следуй лучшим практикам» | То, что модель сочтёт лучшим на этот раз | Назовите практику: «используй паттерн репозитория из `src/db/users.ts`» |
| Список из десяти несвязанных правок | Половина сделана, контекст заполнен к шестому пункту | Одна задача на промпт или десять задач в очереди |

## Делайте промпты многоразовыми

Если вы пишете одну и ту же инструкцию в каждой сессии, вынесите её из промптов.

### Правила проекта: CLAUDE.md, AGENTS.md, GEMINI.md

В начале сессии каждый агент читает файл с инструкциями проекта: `CLAUDE.md` для Claude Code, `AGENTS.md` для Codex (и ряда других агентов), `GEMINI.md` для Gemini CLI. Пишите туда команды и соглашения, коротко и конкретно:

```markdown
## Commands
- Test: pnpm test (run before saying a task is done)
- Typecheck: pnpm typecheck

## Rules
- Don't edit files in src/generated.
- Don't add dependencies without asking.
- New API routes need a test in tests/routes/.
```

Теперь «запусти тесты, прежде чем говорить, что готово» входит в каждый промпт без того, чтобы вы это набирали. `/init` в Claude Code, Codex и Gemini CLI создаёт первый черновик. Как держать один набор правил для нескольких агентов, объясняет статья [CLAUDE.md и AGENTS.md](/ru/blog/claude-md-agents-md/ "CLAUDE.md и AGENTS.md").

### Повторяющиеся процессы: скиллы и свои команды

Задачу, которую вы время от времени повторяете, например релиз, миграцию или чек-лист ревью, опишите один раз как скилл или свою команду и вызывайте по имени.

**Claude Code** использует скиллы: папку с файлом `SKILL.md` в `.claude/skills/<name>/` для проекта или в `~/.claude/skills/<name>/` для вас лично. Имя папки становится командой, а `$ARGUMENTS` получает всё, что вы напишете после неё:

```markdown
---
name: fix-issue
description: Use when the user asks to fix a GitHub issue by number.
---
Fix GitHub issue $ARGUMENTS.
1. Read the issue with `gh issue view $ARGUMENTS`.
2. Write a failing test that reproduces it.
3. Fix the code until the test passes, then run `pnpm test`.
4. Summarize the change in two sentences.
```

Теперь `/fix-issue 123` запускает весь промпт. Старые Markdown-файлы в `.claude/commands/` по-прежнему работают так же, но документация Anthropic советует для новой работы скиллы, потому что в папке скилла можно держать ещё и скрипты и справочные файлы. Кроме того, Claude сам загружает скилл, когда ваш запрос совпадает с его описанием. Подробнее — в статье [скиллы Claude Code](/ru/blog/claude-code-skills/ "Скиллы Claude Code").

**Codex** читает скиллы из `.agents/skills` в проекте и из `~/.codex/skills` для вас лично, в том же формате `SKILL.md`.

**Gemini CLI** использует свои команды в формате TOML в `.gemini/commands/` (проект) или `~/.gemini/commands/` (пользователь). `{{args}}` заменяется тем, что вы напишете после команды, а подпапки становятся пространствами имён, так что `git/commit.toml` — это `/git:commit`:

```toml
description = "Fix a GitHub issue by number"
prompt = """
Fix GitHub issue {{args}}. Write a failing test first,
then fix the code and run the test suite.
"""
```

Хорошее эмпирическое правило: правила, которые действуют всегда, — в файл проекта, процессы, нужные время от времени, — в скиллы, а сам промпт несёт только то, что относится к сегодняшней задаче.

## Шаблон промпта, который можно скопировать

```text
Goal: <one sentence, user-facing>
Context: <symptom, error output, what you already know>
Start in: <files or folders>
Constraints: <what must not change, libraries to use or avoid>
Plan first: <yes/no — if yes, don't edit until I approve>
Done when: <commands that must pass, behaviour to show>
Report: <diff, command output, open questions>
```

Не каждая строка нужна каждый раз. Для исправления опечатки достаточно «Goal». Для новой функции заполните все.

## Промпты для агентов в AgentVera

AgentVera — десктопное приложение для macOS, Windows и Linux, которое запускает Claude Code, Codex, Gemini CLI и других CLI-агентов рядом друг с другом в настоящих терминалах. Промпты остаются теми же, а несколько функций берут на себя повторяющиеся части:

- **[Verify](/ru/features/verify/ "AgentVera Verify"):** критерии готовности, которые вы пишете в сообщении, извлекаются как критерии приёмки. Когда агент заканчивает ход, отдельный проверяющий читает diff, запускает разрешённые команды тестов и отмечает каждый критерий как пройденный или проваленный, с доказательствами. Править файлы он не может. Verify доступен на тарифах Pro и Team.
- **[Код-ревью](/ru/features/code-review/ "Код-ревью"):** когда ход заканчивается, вторая модель Claude проверяет то, что написал агент, и замечания можно сразу отправить обратно агенту.
- **[Отправка агенту](/ru/features/send-to-agent/ "Отправка агенту"):** отправьте агенту ошибку из терминала, diff, лог или строку кода через ⌘⇧L, вместо того чтобы копировать и вставлять их в промпт.
- **[Галерея скиллов](/ru/features/skill-gallery/ "Галерея скиллов"):** создавайте, редактируйте, включайте и выключайте скиллы Claude Code и Codex в одном списке и устанавливайте общие скиллы после проверки безопасности.
- **[Workspace](/ru/features/workspace/ "Workspace"):** сетка агентов на проект, так что каждому шагу разбитой задачи можно дать своего агента и свой worktree.

[Скачайте AgentVera](/ru/download/ "Скачать AgentVera") и попробуйте следующий промпт вместе с этими функциями.

## Подведём итог

Пишите промпты как задачу для толкового коллеги, который только что пришёл в команду: цель, где смотреть, что не трогать и как вы будете оценивать результат. Просите план, когда задача большая, разбивайте её на шаги, которые можно проверить, и всегда давайте команду, доказывающую готовность. То, что повторяется, переносите в `CLAUDE.md`, `AGENTS.md` или скилл. Те же привычки ещё важнее, когда агент работает с базой данных; статья [как писать SQL и миграции с помощью ИИ](/ru/blog/write-sql-with-ai/ "SQL с помощью ИИ") применяет их к схемам и миграциям.

## Частые вопросы

**Какой длины должен быть промпт для агента программирования?** Такой, чтобы уместить цель, стартовые файлы, ограничения и критерии готовности, и не длиннее. Для мелкой правки это две-три строки. Для новой функции обычно короткий абзац и список. Фон, который относится к каждой задаче, место в CLAUDE.md или AGENTS.md, а не в каждом промпте.

**Нужно ли просить у агента план, прежде чем он начнёт писать код?** Да, если задача затрагивает больше пары файлов или вы не можете описать её точно. В Claude Code используйте режим планирования (Shift+Tab или /plan), в Codex — /plan. Прочитайте план, поправьте его и только потом дайте агенту реализовать. Для правки в одну строку план — лишняя трата времени.

**Помогают ли агентам приёмы вроде «ты опытный инженер»?** Гораздо меньше, чем конкретная информация. Строка с ролью стоит недорого, но агент получает куда больше от файла, с которого начать, команды для запуска тестов и ожидаемого поведения. Тратьте слова на факты о задаче.

**Где хранить промпты, которые я использую снова и снова?** Правила проекта пишутся в CLAUDE.md (Claude Code), AGENTS.md (Codex и другие агенты) или GEMINI.md (Gemini CLI). Повторяющиеся процессы становятся скиллами: .claude/skills/<name>/SKILL.md в Claude Code, .agents/skills в Codex. В Gemini CLI это свои команды в формате TOML в .gemini/commands.

**Как не дать агенту объявить задачу готовой, когда она не готова?** Дайте ему проверку, которую он обязан выполнить: команду тестов, сборку или запрос curl, и попросите вставить вывод. Попросите новый тест, который падает до изменения и проходит после. Затем сами просмотрите diff или поручите ревью второму агенту.

---

**Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/