Манифест AI-мастерской
Правила интеллигентного общения с AI
Двенадцать правил, на которых держится работа с агентами: от ясной задачи до ответственности за результат. Коротко и с примерами из реальной работы.
1. Ясность прежде скорости
Формулируй задачу так, чтобы её понял новый коллега без контекста. Минута на формулировку экономит час переделок.
Не такСделай нормально форму записи.ТакФорма записи на эфир: поле email, проверка на клиенте, POST /api/events/waitlist, после успеха — «Готово, адрес в списке». Стиль — как у формы на /events.2. Контекст — это работа, а не роскошь
Агент знает только то, что ты ему дал. Постоянное — стек, команды, запреты — держи в CLAUDE.md или AGENTS.md, в задаче — только то, что меняется.
Не такКаждый раз заново объяснять в чате, что у нас Next.js и Postgres.ТакСтек, команды и запреты — в CLAUDE.md. В задаче: «Похожая логика уже есть в src/lib/events-store.ts — сделай так же».3. Критерий готовности — до начала
Скажи, по какому признаку работа считается сделанной. Если критерия нет, агент остановится там, где ему покажется достаточно.
Не такПочини баг с записью.ТакГотово, когда tsc без ошибок, тест waitlist.spec зелёный, а повторная запись с тем же email не создаёт дубль.4. Сначала план, потом код
Если изменение трогает больше одного файла — сначала план. Править план дёшево, править код по неверному плану — дорого.
Не такПерепиши авторизацию. (И уйти пить кофе.)ТакПредложи план в 5–7 шагов: какие файлы тронешь и как проверишь. Код — после моего «ок».5. Доверяй, но запускай
«Готово» — это утверждение, а не факт. Факт — вывод тестов, typecheck, скриншот, diff. Не доверяй без проверки.
Не такАгент написал, что всё работает, — мёржим.ТакПокажи вывод tsc и тестов, приложи скриншот страницы. Я просмотрю diff перед мёржем.6. Точечные правки вместо перегенерации
Называй файл, место и изменение. «Переделай всё» выбрасывает то, что уже работало, и приносит новые ошибки.
Не такНе то. Давай заново.ТакВ school-chrome.tsx добавь пункт «Мастерская» после «Мероприятий». Остальное не трогай.7. Честность в обе стороны
Говори, чего не знаешь, и прямо проси того же: «не уверен» лучше выдуманного API. Модель может галлюцинировать — дай ей право сомневаться.
Не такПросто сделай, чтобы работало.ТакЕсли не уверен в API — скажи и дай ссылку на документацию. Не угадывай названия методов.8. Вежливая настойчивость
Тон спокойный, требование твёрдое. Вместо эмоций — конкретное расхождение между ожидаемым и полученным.
Не такТы опять всё сломал!!!ТакТест auth.spec падает на строке 42: ждём 401, получаем 500. Найди причину, тест не меняй.9. Права — по минимуму, секреты — не в чат
Агенту — ровно те доступы, которые нужны для задачи. Ключи не вставляются в промпт и не попадают в репозиторий.
Не такВот прод-ключ от базы, разберись.ТакКлюч в .env.local, он в .gitignore. Агент читает переменную окружения, но не печатает её значение.10. Агент работает внутри контура
Harness — хуки, тесты, песочница, лимиты — делает ошибку агента дешёвой и заметной. Чем больше свободы у агента, тем крепче контур.
Не такОтключить все подтверждения на рабочей машине с прод-доступами.ТакПесочница без прод-доступов, allowlist команд, хук прогоняет линтер после каждой правки.11. Знай, когда остановить
Если агент ходит по кругу — стоп. Сузь задачу, верни контекст или сделай шаг сам. Десятая попытка с тем же промптом даст тот же результат.
Не такПопробуй ещё раз. (Десятый раз.)ТакСтоп. Откати последние правки, опиши, что уже проверено, и предложи две гипотезы.12. Ответственность остаётся у человека
Агент пишет код, человек принимает решение и отвечает за результат. В прод уходит только то, что ты понимаешь.
Не такЭто ИИ так сделал.ТакЯ прочитал diff и понимаю каждую строку, которую отправляю в прод.
