Лучшие практики

Waibee Code это агент, а не чат: он сам читает файлы, запускает команды и правит код, доводя задачу до конца. Твоё дело поставить задачу точно и дать способ проверить результат.

В основе почти всех советов ниже лежит одно ограничение: окно контекста заполняется быстро, и чем оно полнее, тем слабее ответы. Береги контекст.

Настрой проект один раз

Несколько шагов окупаются во всех дальнейших сессиях.

WAIBEE.md

Агент читает WAIBEE.md (и CLAUDE.md) в начале каждой сессии. Держи файл коротким и по делу: сюда идёт то, что агент не выведет из кода сам.

Стоит держать	Лишнее
Нестандартные команды сборки и тестов	То, что видно из самого кода
Отклонения стиля от принятого в языке	Стандартные соглашения языка
Как запускать тесты и линтер именно в этом проекте	Документацию по API (лучше ссылкой)
Правила именования веток и оформления PR	Детали, которые часто меняются
Обязательные переменные окружения	Описание каждого файла проекта
Известные ловушки и неочевидное поведение	Очевидные советы вроде «пиши аккуратно»

Проверяй каждую строку простым вопросом: без неё агент начнёт ошибаться? Если нет, удали. Если агент раз за разом не следует правилу, файл, скорее всего, слишком большой, и правило теряется среди остального. Длинные фрагменты выноси в отдельные файлы через @путь и храни WAIBEE.md в git.

Права доступа

По умолчанию агент запрашивает разрешение перед правками и командами. Под характер задачи подбери режим и списки allow/deny, см. Права доступа.

CLI или MCP

К внешнему сервису есть два пути: утилита командной строки или MCP-сервер. Разница в цене. MCP-сервер регистрирует свои инструменты в контексте на всю сессию, даже если ты обратишься к нему один раз. CLI не стоит ничего, пока агент его не вызвал, а вызов это обычный Bash.

Правило простое: есть зрелая CLI, бери CLI. MCP нужен там, где CLI нет или где важны интерактивная авторизация и структурированный ответ.

Задача	Команда вместо сервера
GitHub: задачи, PR, ревью, workflow	gh issue view 142, gh pr create --fill, gh pr diff, gh run list, gh api repos/:owner/:repo/...
Git-история и разбор изменений	git log -S 'parseConfig' --oneline, git blame -L 40,80 file.rs, git diff main...HEAD --stat
Postgres	psql -c '\d+ orders', psql -c 'explain analyze select ...'
Kubernetes	kubectl get pods -o wide, kubectl logs deploy/api --since=15m, kubectl describe pod X
Docker	docker compose ps, docker compose logs --tail=100 api
AWS, GCP	aws s3 ls s3://bucket/prefix/, aws logs tail /aws/lambda/fn --since 10m, gcloud run services describe api
HTTP и JSON	curl -s https://api.example.com/v1/health | jq ., jq '.items[] | .id' data.json
Поиск по коду и файлам	rg 'TODO\(billing\)' -n, fd -e sql migrations/
Разбор логов	grep -c ERROR app.log, awk '{print $1}' access.log | sort | uniq -c | sort -rn | head

Незнакомую утилиту агент осваивает сам: «разберись, что умеет flyctl, через flyctl --help, и разверни ветку в превью-окружение».

MCP оправдан для Figma, Sentry, Jira и подобного: у них либо нет удобной CLI, либо нужен OAuth, либо ответ приходит структурой, которую иначе пришлось бы парсить. Подключение описано в разделе MCP, готовые связки в разделе Подборка расширений.

Отдельно проверь языковой сервер командой /lsp. Один раз поставленный бинарь (rust-analyzer, gopls, pyright и подобные) даёт агенту точный переход к определению, полный список использований и ошибки сразу после правки файла, см. Языковые серверы.

Расширяй агента под себя

Агента стоит подстраивать под проект: готовые расширения экономят время, а свои закрепляют повторяющуюся работу.

• Ставь готовые. Плагины из маркетплейса (/plugin) приносят навыки, команды, хуки и MCP-серверы одним пакетом, см. Плагины. Waibee Code читает формат Claude Code, поэтому его экосистема плагинов и навыков работает и здесь. Где всё это искать, в разделе Где искать расширения, готовые подборки под разные задачи в разделе Подборка расширений.
• Пиши свои. Частый запрос оформи командой /имя, а знания и процедуры под проект вынеси в навык, см. Навыки и команды.
• Что для чего. Навык подходит для знаний и процедур; команда для повторяемого запроса; субагент (.waibee/agents/) для изолированного контекста под узкую задачу; хук для действий, которые обязаны срабатывать всегда, см. Хуки; MCP для подключения внешних инструментов и данных, см. MCP.
• Не ставь про запас. Каждое расширение занимает место в контексте постоянно и осложняет агенту выбор инструмента. Держи установленным то, чем пользуешься, остальное выключай, см. Цена контекста.

Ставь задачу точно

Чем точнее формулировка, тем меньше правок потом. Называй файлы, ограничения и готовый образец, на который стоит ориентироваться.

Приём	Расплывчато	Точно
Сузь задачу	«добавь тесты для orders.go»	«напиши тест для orders.go на отмену уже оплаченного заказа; внешние вызовы не подменяй, работай через тестовую транзакцию»
Укажи, где искать ответ	«почему у планировщика такой странный API?»	«посмотри историю изменений scheduler.ts и объясни, как сложился его интерфейс»
Дай образец в коде	«сделай страницу профиля»	«посмотри, как устроена страница настроек в pages/settings.tsx, и по тому же образцу собери страницу профиля, без новых библиотек»
Опиши симптом	«почини выгрузку»	«выгрузка CSV обрывается на больших файлах. посмотри export/stream.py, особенно буферизацию. воспроизведи ошибку тестом, потом исправь»

Контекст можно передавать по-разному: @путь подставит содержимое файла, изображение вставляется прямо в запрос (Cmd/Ctrl+V), по ссылке агент откроет страницу через WebFetch, а часть он соберёт сам, если попросить.

Разбираясь в незнакомом проекте, задавай агенту вопросы как коллеге: «как устроено логирование?», «что делает эта функция на строке 134?», «какие крайние случаи закрывает этот обработчик?».

Изучение, план, реализация

На незнакомой или большой задаче не давай агенту сразу вносить правки: так он рискует решить не ту задачу. Веди его по шагам.

1. Изучение. «прочитай каталог reports/ и объясни, как сейчас формируется отчёт».
2. План. «что нужно изменить, чтобы добавить экспорт в CSV? составь план». Проверь план, при необходимости поправь.
3. Реализация. «сделай по плану, добавь тесты на пустой отчёт и на юникод, запусти их и исправь ошибки».

Небольшую понятную правку (опечатка, строка лога, переименование) проси сделать сразу, без плана.

Дай способ проверить результат

Агент останавливается, когда результат «выглядит готовым». Если проверить это можешь только ты, вся проверка ложится на тебя. Дай агенту то, что само выносит вердикт: тесты, код возврата сборки, линтер, сравнение с эталоном, скриншот. Тогда агент доводит цикл сам: делает, запускает проверку, читает результат и исправляет.

Приём	Расплывчато	Точно
Задай критерий	«сделай разбор длительности»	«напиши parse_duration: "90m" даёт 5400, "2h" даёт 7200, пустая строка это ошибка. запусти тесты после реализации»
Ищи причину, а не симптом	«тесты не проходят»	«test_pricing.py падает с [текст ошибки]. найди и устрани причину, сам тест не меняй, потом убедись, что тесты проходят»
Сверяй вид со скриншотом	«сделай таблицу аккуратнее»	«[скриншот] приведи таблицу к этому макету, сделай скриншот результата, перечисли отличия и устрани их»

Насколько строго требовать проверку, решаешь ты: прямо в запросе («сделай и сразу запусти тесты»); на всю сессию через /goal (агент не останавливается, пока условие не выполнено); либо свежим взглядом субагента, который проверит работу. И проси показать подтверждение: вывод тестов и выполненные команды, а не одно слово «готово».

Когда проверка выдаёт не «прошло или нет», а число (время ответа, размер, точность), агента можно отпустить в самостоятельный цикл экспериментов по этой метрике, см. Autoresearch.

Крупную задачу начни с интервью

Прежде чем браться за большое, дай агенту тебя расспросить: «хочу [кратко]. расспроси меня инструментом AskUser о реализации, интерфейсе, крайних случаях и компромиссах; разбирай сложные места, очевидное пропускай. когда всё обсудили, запиши спецификацию в SPEC.md». Готовую спецификацию выполняй в новой сессии с чистым контекстом.

Это основа spec-driven подхода. О нём и других способах вести работу (через тесты, автор и проверяющий, автономный прогон) в разделе Подходы к разработке. Что при этом остаётся на тебе и по каким признакам ловить ошибки агента, в разделе Роль разработчика.

Пока агент работает

Поправляй сразу. Останови текущий ход и перенаправь агента или вмешайся по ходу работы через режим steer (/steer). Если поправляешь одно и то же дважды, контекст уже засорён неудачными попытками: открой новый чат (/new) с уточнённым запросом.

Следи за контекстом. Между несвязанными задачами открывай новый чат (Ctrl+N или /new). Небольшой вопрос в сторону задавай через /btw: ответ появится во всплывающем окне и не займёт контекст. Как работает сжатие истории и что ещё помогает экономить окно, в разделе Окно контекста.

Изучение кода поручай субагенту. «изучи субагентом, как обрабатывается разрыв соединения при потоковой передаче»: субагент прочитает нужные файлы в своём контексте и вернёт краткий итог, не засорив основной диалог. Тем же приёмом делай проверку: «проверь субагентом эту правку на крайние случаи».

Сессии и масштаб

Сессии сохраняются: давай им имена (/rename), возвращайся к ним (--resume, /sessions), а для отдельной ветки разговора используй /fork.

Когда нужна параллельная работа: git-worktree дают отдельные рабочие копии, где правки не пересекаются; несколько чатов открываются по Ctrl+N, а общий обзор сессий и субагентов по Tab. Полезна пара «автор и проверяющий»: один агент пишет, второй в чистом контексте проверяет и не защищает решение, потому что не он его придумал.

Без диалога с пользователем работает waibee run "..." (CI, pre-commit, скрипты): --format даёт машиночитаемый вывод, --goal держит агента до достижения цели. Для миграций и массовых правок запускай waibee run в цикле по списку файлов: сначала опробуй запрос на двух-трёх, потом на всех.

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

• Разные задачи в одной сессии. Если в одном чате идут не связанные между собой задачи, контекст заполняется лишним. Открывай новый чат (/new) под каждую новую задачу.
• Исправления по кругу. Если после двух правок агент всё ещё не понял, контекст уже перегружен неудачными попытками. Начни новый чат и переформулируй запрос.
• Слишком большой WAIBEE.md. В большом файле важные правила теряются среди второстепенных, и агент их не учитывает. Оставь только необходимое.
• Результат без проверки. Агент может выдать правдоподобный код, который не обрабатывает крайние случаи. Не принимай как готовое то, что не можешь проверить.
• Слишком широкое изучение. Просьба «изучи X» без рамок заставляет агента прочитать сотни файлов. Ограничь область или поручи изучение субагенту.

Дальше

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