TL;DR: Хороший промпт для coding agent — это не просьба «сделай X», а мини-спецификация с объявленным scope, явными ограничениями, acceptance criteria и шагом верификации. Без этих компонентов агент заполняет пробелы самостоятельно — и не всегда так, как вы ожидаете.
Почему агент ломает проект
Coding agents — Claude Code, Codex, Cursor, Windsurf — работают на языковых моделях. LLM заполняет пробелы в задаче на основании prior context. Для генеративных задач вроде написания статьи с нуля это работает. Для работы в существующем репозитории с чужим кодом, соглашениями и явными зонами риска — нет.
Четыре основных источника проблем:
Слишком широкий scope. Агент не знает, что «почини баг в форме» означает ровно один файл, и может переписать связанные компоненты по пути.
Неявные ограничения. Если не написать «не трогать .env и конфигурационные файлы» — агент не знает, что это запрещено.
Отсутствие критерия завершения. Без acceptance criteria агент не знает, когда остановиться. Он либо останавливается слишком рано, либо продолжает «улучшать» код за пределами задачи.
Отсутствие verification step. Агент завершает задачу, но не проверяет результат — и пользователь получает код, который может ломать тесты.
Из чего должна состоять задача для coding agent
Задача с предсказуемым результатом содержит семь блоков. Их можно считать мини-спецификацией:
Objective
Что именно нужно сделать. Одно-два предложения с конкретным результатом.
Плохо: «Улучши форму регистрации»
Хорошо: «Добавь валидацию email в форму регистрации: поле не должно принимать строки без символа @ и домена»
Scope
Какие файлы и компоненты затрагиваются.
Хорошо: Файл: src/components/RegistrationForm.tsx. Не трогать ничего за пределами этого файла.
Non-goals
Явный список того, что делать не нужно. Это снижает риск «заодно починю».
Хорошо: Не рефакторить структуру компонента. Не менять стили. Не трогать тесты в __tests__/RegistrationForm.test.tsx — они будут обновлены отдельно.
Constraints
Технические и процессные ограничения. Что нельзя делать категорически.
Хорошо: Не использовать деструктивные команды. Не изменять .env и конфигурационные файлы. Соблюдать coding style проекта (ESLint config). Если сталкиваешься с конфликтом или неоднозначностью — спроси, не принимай решение самостоятельно.
Acceptance criteria
Конкретный критерий завершения. Что должно быть правдой, когда задача считается выполненной.
Плохо: «Код должен работать»
Хорошо: «Задача выполнена, когда: 1) npm test -- --testPathPattern=RegistrationForm проходит без ошибок; 2) eslint src/components/RegistrationForm.tsx не выдаёт ошибок; 3) форма отклоняет user@ и принимает user@example.com»
Verification
Что агент должен сделать перед тем, как объявить задачу выполненной.
Хорошо: Перед завершением: запусти eslint на изменённом файле, запусти юнит-тесты, проверь, что форма работает с невалидными и валидными email-адресами.
Handoff format
Что агент передаёт в конце — список изменений, статус тестов, замечания для ревьюера.
Хорошо: В конце предоставь: список изменённых файлов, статус тестов, что ты намеренно не трогал и почему.
Canonical prompt template
Структура, пригодная для повторного использования:
## Objective
[Что нужно сделать — 1-2 предложения]
## Scope
Files: [перечень файлов]
Do not modify anything outside: [зона ограничения]
## Non-goals
- [Что не делаем]
- [Что не делаем]
## Constraints
- Do not use destructive commands
- Do not modify .env or config files without explicit permission
- Follow project coding style ([ссылка на конфиг или описание])
- If you encounter a conflict or ambiguity, ask — do not decide on your own
## Acceptance criteria
Task is complete when:
1. [Конкретная проверка]
2. [Конкретная проверка]
3. [Конкретная проверка]
## Verification before done
Run: [команда линтера]
Run: [команда тестов]
Manually verify: [ручная проверка]
## Handoff format
Provide: list of changed files, test status, review notesПример плохой задачи vs хорошей
Плохая постановка
Отрефактори компонент корзины, сделай его чище и добавь валидацию.
Агент решит, что «чище» означает переписать компонент с нуля, переименует переменные, изменит структуру пропсов, добавит новые зависимости и заодно «улучшит» соседние компоненты. В лучшем случае — конфликты при мерже. В худшем — сломанная функциональность, которую нужно искать вручную.
Хорошая постановка
## Objective
Добавить валидацию количества товара в компоненте CartItem: количество не должно
быть меньше 1 и больше 99. При невалидном значении — показать inline-ошибку.
## Scope
Files: src/components/CartItem.tsx
Do not modify anything outside src/components/CartItem.tsx
## Non-goals
- Не рефакторить структуру компонента
- Не изменять типы пропсов
- Не трогать CartItem.test.tsx
## Constraints
- Follow existing coding style (TypeScript, functional components, no class components)
- If validation logic requires a shared utility — ask before creating a new file
## Acceptance criteria
1. npm test -- --testPathPattern=CartItem проходит
2. eslint src/components/CartItem.tsx — 0 ошибок
3. Поле принимает значения 1-99, отклоняет 0 и 100
## Verification
Run eslint, run tests, manually test edge cases (0, 1, 99, 100)
## Handoff
Changed: src/components/CartItem.tsx
Tests: [вставить вывод]
Not touched: CartItem.test.tsx (as instructed)
Review note: validation uses existing pattern, not new utilКак задавать scope правильно
Scope — самый важный компонент задачи для coding agent. Чёткий scope снижает риск нежелательных изменений больше, чем любой другой элемент.
Что указывать явно:
- Конкретные файлы:
src/components/Form.tsx - Директории при работе с модулем:
src/utils/validation/ - Запрет на выход:
Do not modify anything outside src/components/Form.tsx
Почему «не трогать unrelated files» нужно писать явно: агент не знает, что в вашем проекте считается «related». Если не сказать, он может решить, что исправление формы требует обновить вспомогательный хелпер, который используется в трёх других местах.
При работе с несколькими файлами перечислите все явно. Если файлы заранее неизвестны — используйте explore step: «сначала составь список файлов, которые нужно изменить, и покажи мне — я подтвержу».
Как формулировать constraints
Constraints — это явные запреты. Они защищают от регрессий, которые агент не мог предвидеть.
Базовый набор constraints для любой production-задачи:
Destructive commands. Do not use rm -rf, DROP TABLE, or other destructive operations without explicit confirmation.
Конфигурация и секреты. Do not modify .env, config files, or any file containing credentials.
Coding style. Follow the project's ESLint and Prettier config. Do not introduce new dependencies without asking first.
Конфликты и неоднозначности. If you encounter a conflict or are unsure about scope — ask. Do not make assumptions.
Последнее правило важно: агент по умолчанию будет делать предположения и двигаться дальше. Явная инструкция «спроси при конфликте» меняет это поведение.
Небольшое отличие между инструментами: Codex по умолчанию работает в sandbox mode и не изменяет файловую систему без разрешения. Claude Code и Cursor дают агенту более широкий доступ по умолчанию — constraints здесь особенно важны.
Acceptance criteria: что считается done
Acceptance criteria — это контракт между вами и агентом. Без него агент не знает, когда задача завершена.
Критерий должен быть верифицируемым — то есть либо агент может проверить его сам, либо вы можете проверить однозначно.
Расплывчатый AC: «Код должен работать», «Форма должна быть лучше», «Убедись, что всё ок»
Конкретный AC:
npm test -- --testPathPattern=Formпроходит без ошибокeslint src/components/Form.tsx— 0 ошибок- Поле email отклоняет
user@и принимаетuser@example.com - Изменения ограничены файлом
src/components/Form.tsx
Каждый пункт либо выполнен, либо нет — никакой интерпретации.
Verification before done
Verification step — инструкция агенту проверить результат перед завершением. Это убирает проблемы, которые агент может выявить автоматически, до того как код попадает к ревьюеру.
Стандартный verification для задач на фронтенде:
eslint [файл]— проверка стиляnpm test -- --testPathPattern=[компонент]— юнит-тесты- Ручная проверка граничных значений (если применимо)
Для бэкенда:
pylint [файл]илиflake8 [файл]pytest [файл_теста]- Проверка, что API endpoint отвечает ожидаемым статусом
Verification не заменяет review — он убирает очевидные проблемы до того, как код попадает к ревьюеру.
Как работать с длинными задачами
Длинные задачи с неопределённым scope — наибольший риск. Паттерн декомпозиции:
Explore — агент изучает кодовую базу без изменений. «Прочитай следующие файлы и составь список того, что нужно изменить для реализации задачи X. Ничего не меняй.»
Plan — агент описывает план изменений. Вы апрувите или корректируете. Только после апрува — переход к Edit.
Edit — агент вносит изменения строго в рамках апрувленного плана.
Verify — агент запускает тесты и линтер, фиксирует результат.
Handoff — агент передаёт список изменений, статус проверок, review notes.
Этот паттерн полезен для задач, где scope заранее неизвестен: рефакторинг модуля, внедрение новой фичи, миграция.
Частые ошибки
| Ошибка | Что происходит |
|---|---|
| Расплывчатый objective («улучши», «почини», «отрефактори») | Агент интерпретирует задачу по-своему, меняет больше нужного |
| Нет file scope | Агент трогает unrelated файлы, создаёт нежелательные зависимости |
| Нет stop conditions | Агент не знает, когда остановиться — делает лишние изменения |
| Нет verification step | Код не проверен до передачи, ревьюер тратит время на проблемы, которые мог поймать агент |
| Нет escalation path | При неоднозначности агент принимает решение сам, часто неверно |
| Нет non-goals | Агент «заодно улучшает» соседние компоненты |
AGENTS.md и repo-level правила
Повторять constraints в каждом промпте трудозатратно. Решение — зафиксировать постоянные правила на уровне репозитория.
Claude Code автоматически читает файл CLAUDE.md при каждом запуске. В нём можно определить:
- Архитектурные соглашения проекта
- Coding style и naming conventions
- Зоны кода, которые нельзя трогать без явного разрешения
- Инструкции по запуску тестов и линтинга
Codex использует аналогичный файл AGENTS.md. Cursor читает .cursorrules в корне репозитория — текстовый файл с правилами, который Cursor подключает при старте сессии (название файла актуально на момент написания, проверьте документацию Cursor на предмет изменений).
Суть одна: постоянный контекст, который агент получает на старте каждой сессии, снимает необходимость повторять базовые rules в каждом промпте.
Что читать дальше
Prompt rules — это первый уровень дисциплины работы с coding agents. Следующие шаги:
- AI-агенты для кодинга — обзор агентных инструментов и workflow
- Claude Code — CLI agent с поддержкой CLAUDE.md и MCP
- Codex — task-driven CLI agent от OpenAI
- Cursor — IDE agent с .cursorrules
- Windsurf — IDE agent
Setup guide и playbook первого запуска агента в существующем репозитории — в разработке в /coding/agents/.