Как использовать Superpowers и Codex в реальной разработке

AI-агент умеет написать компонент, исправить тест или собрать API-клиент за несколько минут. Но скорость сама по себе мало что даёт. Без правил агент начинает угадывать требования, менять лишние файлы и уверенно сообщать, что задача выполнена. Проверяешь код - а там потерян важный сценарий, тесты покрывают не то, а архитектура заметно отличается от той, о которой договаривались.

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

Звучит строже, чем обычный чат с AI? Так и есть. И это хорошо.

Что такое Superpowers

Superpowers - это набор навыков для AI-агентов, которые описывают не конкретный язык программирования, а порядок инженерной работы. В репозитории есть навыки для обсуждения идеи, подготовки плана, разработки через тесты, поиска ошибок, работы с Git Worktree, ревью кода и завершения ветки.

Важно понимать разницу. Superpowers не заменяет Codex и не пишет проект вместо него. Он задаёт дисциплину. Это похоже на внутренний регламент команды: перед разработкой согласуй требования, перед исправлением найди причину ошибки, перед отчётом о завершении запусти проверки.

Codex в этой связке отвечает за чтение репозитория, изменение файлов, выполнение команд и анализ результатов. Superpowers отвечает за последовательность действий. Один даёт руки, второй - процесс.

Установка Superpowers в Codex

В актуальной версии Codex CLI откройте каталог плагинов командой:

/plugins

Введите в поиске superpowers, откройте найденный плагин и выберите Install Plugin. После установки перезапустите текущую сессию Codex, если навыки не появились сразу.

В приложении Codex откройте раздел Plugins в боковой панели. Найдите Superpowers в категории Coding, нажмите кнопку с плюсом и завершите установку.

Для проверки создайте новую сессию и напишите:

Расскажи, какие навыки Superpowers тебе доступны и в каких случаях ты должен их применять.

Codex должен перечислить доступные навыки и кратко описать их назначение. Названия могут меняться вместе с обновлениями репозитория, поэтому ориентируйтесь не только на имя, но и на смысл навыка.

В Codex не стоит рассчитывать на команды вида /brainstorming. Superpowers работает как система навыков. Процесс запускают обычной инструкцией: «примени навык brainstorming», «подготовь план через writing-plans» или «проведи systematic debugging».

Почему одного плагина недостаточно

Установка добавляет навыки, но не объясняет агенту особенности вашего проекта. Codex всё ещё не знает, какие каталоги можно менять, какие проверки обязательны, как оформляются коммиты и где хранятся технические документы.

Эти правила стоит зафиксировать в репозитории. Минимальная структура может выглядеть так:

project/
├── AGENTS.md
├── README.md
├── docs/
│   ├── project-context.md
│   ├── architecture.md
│   ├── development-rules.md
│   ├── testing.md
│   ├── specs/
│   └── plans/
├── src/
├── tests/
└── .github/
    └── workflows/

AGENTS.md содержит инструкции непосредственно для Codex. README.md помогает человеку запустить проект. В docs/project-context.md хранится цель продукта и границы системы. Файл architecture.md описывает ключевые модули и зависимости. В development-rules.md фиксируются правила кода, Git и ревью. Каталоги specs и plans отделяют согласованные требования от плана их реализации.

Не превращайте документацию в архив всего на свете. Агенту нужна короткая и точная карта проекта, а не корпоративный роман на тысячу страниц.

Что записать в AGENTS.md

Хороший AGENTS.md отвечает на практические вопросы: что считается завершённой задачей, какие команды запускать, какие файлы нельзя менять и когда требуется согласование.

# Project instructions

## Workflow

Before changing code:

1. Read the relevant files in docs/.
2. Inspect the current implementation and tests.
3. Use the appropriate Superpowers skill.
4. Do not modify code before the design is approved.

## Implementation rules

- Work only inside the requested scope.
- Do not refactor unrelated modules.
- Preserve public interfaces unless the specification requires a change.
- Add or update tests for every behavior change.
- Never disable tests to make the build pass.

## Verification

Before reporting completion, run:

npm run lint
npm run test
npm run build

Report the exact commands and their results.

## Git

- Use a dedicated feature branch or worktree.
- Keep commits small and focused.
- Do not merge or push without explicit permission.

Команды в примере нужно заменить командами вашего проекта. Главное правило здесь простое: Codex не должен сам придумывать критерии готовности. Они уже записаны.

Шаг первый - сначала идея, потом клавиатура

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

Хороший стартовый запрос выглядит так:

Примени навык brainstorming.

Нужно добавить импорт CSV в существующее приложение.

Сначала изучи структуру репозитория и текущий импорт данных.
Задавай по одному вопросу.
Предложи несколько подходов с плюсами и ограничениями.
Не изменяй код, пока мы не согласуем спецификацию.

Почему вопрос должен задаваться по одному? Потому что пачка из десяти вопросов часто даёт поверхностные ответы. Последовательный диалог позволяет уточнять детали по мере появления новой информации.

На этом этапе Codex должен понять формат входных данных, объём файлов, правила валидации, обработку повторов, требования к журналу ошибок и поведение при частичном сбое. Только после этого появляется связная спецификация.

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

Шаг второй - зафиксируйте спецификацию

Результат обсуждения нужно сохранить в docs/specs. Не оставляйте требования только в истории чата. Новая сессия не обязана помнить прошлый разговор, а разработчик не должен искать важное решение среди десятков сообщений.

Для импорта CSV документ может называться так:

docs/specs/2026-06-23-csv-import.md

В спецификации фиксируются цель, границы задачи, пользовательский сценарий, поток данных, ошибки, ограничения, критерии приёмки и то, что сознательно не входит в текущую работу.

Особенно полезен раздел с исключениями. Например: импорт работает только с UTF-8, фоновые очереди пока не добавляются, архивы не поддерживаются, максимальный размер файла ограничен 20 МБ. Такие рамки защищают задачу от незаметного разрастания.

Шаг третий - превратите спецификацию в исполнимый план

После утверждения требований применяется навык writing-plans. Его задача - разбить работу на маленькие проверяемые операции до изменения кода.

Примени навык writing-plans.

Источник требований:
docs/specs/2026-06-23-csv-import.md

Создай подробный план в docs/plans/.
Для каждого этапа укажи:

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

Не оставляй TBD, общие формулировки и скрытые предположения.

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

Фраза «добавить сервис импорта» слишком расплывчата. Нормальная задача указывает конкретный файл, метод, входные данные, тестовый сценарий и команду проверки.

Task: Reject rows without an email

Files:
- Create: src/Import/RowValidator.ts
- Create: tests/Import/RowValidator.test.ts

Test:
- Pass a row with an empty email field.
- Expect ValidationError with code missing_email.

Verification:
npm test -- RowValidator.test.ts

Такой план снимает с агента необходимость додумывать архитектуру во время реализации. Сначала принимаются инженерные решения, затем пишется код. Не наоборот.

Шаг четвёртый - изолируйте работу через Git Worktree

Superpowers поддерживает работу в отдельной рабочей области Git. Worktree создаёт ещё один каталог того же репозитория, привязанный к отдельной ветке. Основная папка остаётся чистой, а задача выполняется изолированно.

В PowerShell на Windows 11 команды могут выглядеть так:

git fetch origin
git worktree add ..\project-csv-import -b feature/csv-import develop
Set-Location ..\project-csv-import

Теперь Codex может менять файлы в project-csv-import, не затрагивая исходный рабочий каталог.

Перед началом реализации попросите агента проверить состояние новой области:

Проверь текущую ветку и состояние Git.
Убедись, что рабочая область чистая.
Установи зависимости, если это требуется.
Запусти базовые тесты до внесения изменений.
Не продолжай, если исходная проверка завершается ошибкой.

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

Шаг пятый - разработка через тесты

Навык test-driven-development задаёт короткий цикл: написать падающий тест, увидеть ожидаемое падение, добавить минимальный код, получить успешный тест и только затем улучшить структуру.

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

Выполни первую задачу из утверждённого плана.

Строго соблюдай test-driven-development:

1. Напиши один тест на требуемое поведение.
2. Запусти его и покажи ожидаемую причину падения.
3. Добавь минимальный рабочий код.
4. Повторно запусти тест.
5. Выполни рефакторинг только после успешного теста.
6. Запусти связанные проверки.

Не переходи к следующей задаче при ошибках.

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

Шаг шестой - проверяйте не только код, но и соответствие требованиям

Код может быть аккуратным и при этом делать не то. Поэтому ревью стоит разделять на два прохода.

Первый проход проверяет соответствие спецификации. Реализованы ли все критерии? Не добавлено ли лишнее? Сохранены ли ограничения? Правильно ли обработаны ошибки?

Второй проход оценивает качество кода: читаемость, связанность модулей, повторения, обработку исключений, безопасность, производительность и качество тестов.

Проведи два последовательных ревью.

Сначала проверь реализацию относительно:
docs/specs/2026-06-23-csv-import.md

Затем отдельно проверь качество изменённого кода.

Для каждого замечания укажи:
- критичность;
- файл и строку;
- конкретную причину;
- минимальный способ исправления.

Не исправляй замечания автоматически.

Почему не нужно сразу разрешать автоматические исправления? Иногда ревьюер предлагает переделку, которая выходит за рамки задачи. Сначала замечания оцениваются, затем принимается решение.

Шаг седьмой - никаких заявлений без свежей проверки

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

Перед завершением задачи попросите применить проверку готовности:

Перед отчётом о завершении выполни полную проверку проекта.

Запусти команды из AGENTS.md.
Покажи для каждой команды:
- точную команду;
- код завершения;
- краткий результат.

Не утверждай, что задача завершена, если хотя бы одна обязательная проверка не запускалась или завершилась ошибкой.

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

Рабочий сценарий целиком

На практике процесс выглядит так. Разработчик создаёт задачу и просит Codex исследовать репозиторий через brainstorming. Вместе они уточняют требования и сохраняют спецификацию. Затем writing-plans превращает её в набор маленьких операций. Для реализации создаётся отдельная ветка или worktree. Каждая операция проходит через падающий тест, минимальный код и повторную проверку. После реализации выполняются два ревью, полная сборка и сравнение результата со спецификацией.

Это не конвейер, где человек исчезает. Человек утверждает требования, оценивает архитектурные компромиссы, принимает замечания ревью и разрешает слияние ветки. Codex берёт на себя рутину, но не получает право тихо менять цель задачи.

Какие правила особенно важны

Первое правило - не смешивать обсуждение и реализацию. Пока спецификация не утверждена, код не меняется.

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

Третье - тест должен упасть по ожидаемой причине до написания рабочего кода. Иначе его ценность сомнительна.

Четвёртое - агент не меняет файлы за пределами согласованного объёма. «Я заодно улучшил архитектуру» часто означает «я добавил риск, который никто не просил».

Пятое - завершение подтверждается командами, а не словами. Логи тестов, линтера и сборки надёжнее любого уверенного отчёта.

Шестое - коммиты должны быть небольшими. Когда один коммит одновременно добавляет функцию, обновляет зависимости и перерабатывает половину проекта, ревью превращается в археологию.

Где Superpowers может мешать

Строгий процесс не нужен для каждого изменения. Исправление опечатки в документации не требует длинной спецификации и нескольких стадий ревью. Здесь важен здравый смысл.

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

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

Есть и ещё один нюанс. Если несколько сессий Codex одновременно работают с одним репозиторием, кодовая база может измениться между подготовкой плана и реализацией. Отдельные worktree и короткие ветки уменьшают риск, но не отменяют синхронизацию с основной веткой.

Пример стартового промта для реальной задачи

Примени подходящие навыки Superpowers.

Задача:
добавить восстановление пароля по одноразовой ссылке.

Порядок работы:

Сначала прочитай AGENTS.md и документацию проекта.
Изучи текущую авторизацию, модели пользователей и тесты.
Не меняй код на этапе исследования.

Примени brainstorming:
задавай вопросы по одному;
предложи 2-3 технических подхода;
укажи риски безопасности;
подготовь спецификацию.

После моего утверждения:
сохрани спецификацию в docs/specs/;
создай подробный план через writing-plans;
предложи имя ветки и worktree;
реализуй задачи по одной через TDD;
после каждого этапа запускай связанные тесты;
в конце проведи проверку требований и качества кода;
выполни все команды из AGENTS.md.

Не выполняй merge, push и изменение production-конфигурации без отдельного разрешения.

Этот промт не описывает архитектуру за агента. Он задаёт порядок, границы и точки контроля. Архитектура появляется после чтения реального проекта, а не из фантазии модели.

Superpowers не делает Codex безошибочным

И это, пожалуй, главный вывод. Superpowers не превращает AI в старшего разработчика, который никогда не ошибается. Он делает ошибки заметнее и дешевле.

Спецификация показывает, что именно строится. План раскрывает предполагаемые изменения до начала работы. TDD проверяет поведение. Worktree изолирует изменения. Ревью ищет отклонения. Финальные команды подтверждают состояние проекта.

Каждый слой сам по себе несовершенен. Вместе они создают нормальный инженерный процесс, где Codex работает быстро, а человек сохраняет контроль.

Начать можно с малого: установить Superpowers, добавить AGENTS.md и запретить агенту менять код до согласования плана. Уже эти три шага заметно сокращают хаотичные правки. Затем подключаются спецификации, worktree, TDD и двойное ревью.

AI-агенту не нужно давать полную свободу. Ему нужно дать хорошую задачу, ясные границы и проверяемый маршрут. Тогда Codex перестаёт быть генератором случайных патчей и становится полезным участником разработки.