Продукт в prod за 16 дней без строчки своего кода: как я вёл AI-агента в связке OpenSpec + Superpowers

Я заместитель директора IT Park University в Ташкенте. За 16 дней мы с Claude Code сделали AccessVault — корпоративное хранилище паролей для университета: Azure, вход через Microsoft Entra ID, шифрование каждого пароля своим ключом, журнал всех показов, принудительная смена пароля, когда человек теряет доступ. 1 ноября оно ушло в prod.

Код я не писал. Я был заказчиком и delivery-менеджером: рассказывал, что нужно и зачем, принимал решения, одобрял спецификации, проверял на тестовом окружении и говорил «выпускай». Всё остальное делал агент.

Это не история «AI написал за меня приложение». Это практическое руководство: как настроить процесс, чтобы агенту можно было доверять. Что поставить, что положить в CLAUDE.md, какими командами и фразами вести агента, какие проверки обязательны и на какие грабли мы уже наступили. Если захотите повторить, здесь должно быть всё, что нужно для старта.

Коротко в цифрах: 16 дней от первого коммита до prod, 18 изменений, 24 pull request, 2 выпуска в prod, 376 сценариев в спецификациях и 2 515 автотестов, руководства пользователя и администратора на двух языках со скриншотами и озвученными роликами.

Задача

Сменилась команда маркетинга, её дела перешли ко мне. А вместе с ними два десятка паролей от соцсетей, хостинга и порталов поставщиков. Свои пароли я больше 15 лет храню в KeePass, но для команды нужно другое: знать, кто какой пароль видел, и менять пароль каждый раз, когда этот человек теряет доступ или уходит. Готового бесплатного решения, которое делает именно это, я не нашёл.

Что получилось в итоге:

Жизнь пароля в AccessVault

• Вход университетской учёткой Microsoft, две роли по двум группам Entra ID.
• Карточка пароля с владельцем; доступ можно дать коллеге, он может только смотреть и копировать.
• Каждый показ и копирование сначала пишутся в журнал. Не записалось — пароль не показывается.
• Отзыв доступа, уход сотрудника или снятие прав администратора помечают карточку «Change password»; владельцу и админам приходят письма и ежедневная сводка, пока пароль не сменят.
• Корзина, резервная копия всей базы, отчёт «кто что делал», ежедневная проверка по расписанию.

Карточка: пароль скрыт, каждый показ записывается

Инструменты

OpenSpec решает «что», Superpowers — «как»

OpenSpec

Ставится глобально и инициализируется в репозитории:

			npm install -g @fission-ai/openspec@1.14.2
openspec init
		

Появляются папка openspec/ (спецификации specs/, изменения changes/) и команды /opsx:* для Claude Code. Совет: включите все workflow, а не профиль по умолчанию. explore, update иverify пригодятся:

			openspec config set profile custom --string
openspec config set workflows '["propose","explore","new","continue","apply","update","ff","sync","archive","bulk-archive","verify","onboard"]'
openspec update
		

В openspec/config.yaml есть два места, которые стоит заполнить сразу. context — то, что агент не выведет из кода: язык документов, стек, роли фреймворков. И rules — требования к каждому артефакту. У нас, например, так:

			rules:
  specs:
    - Every requirement has at least one scenario, and every scenario is concrete enough
      to become at least one automated test.
  design:
    - Each key decision lists the alternatives considered and why they were rejected.
    - Record risks as "Risk -> Mitigation".
  tasks:
    - Each task names the spec scenarios it satisfies, so verification can trace
      scenario -> task -> test.
		

На последнем правиле держится вся проверка: сценарий → задача → тест.

Superpowers

Это плагин Claude Code с навыками. Я положил его копией в репозиторий (.claude/skills/superpowers/), чтобы версия была закреплена и одинакова у всех. Такой проектный плагин загружается, только если в Claude Code подтвердить доверие к папке; проверка —/plugin и superpowers@skills-dir в списке. Для облачных сессий есть хук SessionStart, который ставит тот же плагин.

CLAUDE.md — договор с агентом

Самое важное в настройке. Без него OpenSpec и Superpowers тянут в разные стороны: у Superpowers свои места для дизайна и планов (docs/superpowers/...), у OpenSpec — свои. Мой CLAUDE.md решает это явно. Что в нём:

1. Роли фреймворков. OpenSpec — «что», Superpowers — «как»; навыки Superpowers обязательны, артефакты OpenSpec обязательны для любого изменения поведения.
2. Где лежат артефакты. Таблица, которая переопределяет пути Superpowers: итог брейншторма идёт в proposal.md и design.md изменения, план — в plan.md той же папки, никакого docs/superpowers/. Там же: макеты, результаты живых проверок, видение, roadmap.
3. Жизненный цикл изменения из девяти шагов и жёсткие правила: никакого кода до одобрения артефактов, никакого кода без падающего теста, каждый #### Scenario: покрыт тестом.
4. Когда папка изменения не нужна: исправление ошибки по уже описанному поведению, рефакторинг, документы, CI.
5. Языки. Спецификации и обсуждения на русском, код и коммиты на английском; ключевые слова OpenSpec (### Requirement:, #### Scenario:, WHEN/THEN) остаются английскими, иначе валидатор не поймёт.
6. Ветки и PR, разбор безопасности перед каждым PR, проверка документации.
7. Раскладка кода. Подробная карта, которую агент поддерживает сам.

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

Видение и дорожная карта

Начал я не с кода, а с интервью. Агент задавал вопросы по одному: кто пользуется, что делаем, когда человек уходит, кто видит чужие пароли, нужен ли экспорт. Так появился docs/vision.md из трёх частей: рассказ о продукте, ответы интервью и отдельный раздел «Решения Claude (на подтверждение автора)», где агент честно отделил свои технические предположения от моих решений. Например: envelope-шифрование через Key Vault, проверка доступа раз в сутки, а не на каждый запрос, Static Web Apps Free плюс отдельный Function App ради почти нулевой стоимости.

Потом видение режется на изменения. Это docs/roadmap.md, таблица с номером, именем, тем, что даёт изменение, зависимостями, статусом и ссылкой на PR. У нас вышло 17 номеров (и одно вставное 3a). Каждое изменение — один полный цикл до prod. Небольшие идеи по ходу агент складывает в бэклог там же.

Один цикл на живом примере

Покажу цикл на изменении №17, странице помощи с руководствами пользователя и администратора. Оно целиком прошло в одной сессии, и все фразы ниже взяты из моих настоящих сообщений агенту.

Одно изменение — девять шагов

1. Брейншторм

берем в работу документацию, начинай интервью

Агент запускает superpowers:brainstorming: один вопрос за раз, без списков вариантов, и периодически пересказывает понятое по 200–300 слов. Отвечать можно как угодно, хоть голосом:

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

На брейншторме появились решения, до которых я бы сам не дошёл сразу: руководство администратора видно только админам, переключатель EN/RU запоминается в браузере, кнопка Help не показывается на формах, а Markdown рендерится без сырого HTML (ради безопасности: у нас строгий CSP).

2. Описание изменения

			/opsx:new in-app-help
/opsx:ff
		

/opsx:ff создаёт сразу все артефакты: proposal.md, дельта-спецификации, design.md,tasks.md (а по шагам их создаёт /opsx:continue). Читать стоит в первую очередь сценарии: это контракт. Вот два настоящих:

			#### Scenario: Кнопка помощи
- **WHEN** сотрудник на компьютере на экране папки нажимает «Help» справа в строке поиска
- **THEN** открывается `/help` с руководством пользователя

#### Scenario: Субтитры ролика
- **WHEN** в разделе есть ролик в русской записи
- **THEN** у проигрывателя есть дорожка субтитров на русском, по умолчанию выключенная
		

Если меняются экраны, агент рисует макет. В docs/mockups/ лежат статические экспорты всех одобренных экранов и писем.

3. Ворота ревью

Агент отдаёт design.md свежему субагенту с вопросом «можешь ли ты построить это, не спрашивая автора?» и приносит только те вопросы, на которые могу ответить лишь я. Плюсopenspec validate. Дальше моё слово:

подтверждаю

До этого момента рабочего кода нет. Это жёсткое правило CLAUDE.md.

4. План

superpowers:writing-plans делает plan.md: задачи с точными файлами, интерфейсами и тестами, каждая ссылается на пункт tasks.md и сценарии. В №17 вышло 14 задач. Агент спрашивает, как выполнять: субагентами (свежий агент на задачу и рецензент после неё) или сам в сессии. Субагенты дороже, но надёжнее; я почти всегда выбираю их.

5. Реализация

			/opsx:apply
		

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

Если требования меняются по ходу, сначала правятся артефакты, потом план, потом код. Так было с роликами. Первый вариант был набором кадров, и я написал:

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

Агент выполнил /opsx:update: поправил спецификацию (озвучка на языке руководства, курсор, кольцо клика, субтитры), design и tasks, потом план, и только потом код.

6. Проверка

superpowers:verification-before-completion прогоняет все проверки на чистом дереве, а/opsx:verify сверяет: каждая задача сделана, каждое требование реализовано, у каждого сценария есть тест. Результат агент пишет в verify.md таблицей «сценарий → тест». В №17 получилось 32 из 32.

7. Живая проверка на dev

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

			gh workflow run deploy.yml --ref <ветка> -f environment=dev
		

Агент публикует на claude.ai страницу-чек-лист: по строке на пункт, у каждого статус и заметка. Я прохожу её на живом dev и отмечаю. Можно и иначе:

пожалуйста пройди этот чек лист сам

Тогда агент проходит пункты в моём Chrome через Claude in Chrome. Вход в систему делаю я — агент пароли не вводит. После отметок агент читает страницу обратно и переносит каждый пункт вverify.md, раздел «Живая проверка на dev».

Именно здесь нашлось два настоящих бага, которые никакие юнит-тесты не ловили: субтитры роликов не показывались, потому что Vite встраивал маленькие .vtt как data:-адреса, а наш CSP их запрещает; после исправления Static Web Apps отдавал .vtt с типом application/octet-stream. Оба исправлены через TDD и перепроверены на dev.

8. Архив и PR

/opsx:archive вливает дельта-спецификации в openspec/specs/, и теперь это официальное описание системы. Затем разбор безопасности (ниже), PR в dev, CI. В приложении Claude можно включить Auto-fix: оно будит агента, если CI упал или пришли замечания.

Да, слей

9. Выпуск

Каждое изменение уходит в prod отдельным выпуском сразу после живой проверки и только с моего подтверждения:

Да, выпускай

Агент делает разбор безопасности dev против main, открывает PR dev → main, следит за деплоем prod и smoke-проверкой, а потом публикует короткий чек-лист prod на 3–5 пунктов. Его итог тоже ложится в verify.md.

Барьеры качества

Барьеры качества на пути в prod

Про разбор безопасности отдельно. Платного API-ключа для GitHub Action у меня нет, поэтому разбор идёт внутри сессии: встроенный в Claude Code /security-review по ветке плюс правила проекта вdocs/security-review.md. Там записано, где вообще может существовать секрет в открытом виде, какие параметры шифрования неизменны, как устроена авторизация и какие строки в инфраструктуре нельзя трогать без решения автора. Подтверждённые находки исправляются до PR через TDD, результат пишется в описание PR.

Инфраструктура и CI/CD

Как устроен AccessVault

• Azure, два окружения (dev и prod), каждое — resource group, описанная одним шаблоном Bicep. Static Web Apps Free для фронтенда, Function App на Flex Consumption для API, Cosmos DB serverless, Key Vault, Application Insights. Всё с оплатой за использование: простаивающее окружение почти ничего не стоит.
• Без ключей и секретов. API ходит в Cosmos DB, Key Vault и Graph одной managed identity, локальная аутентификация Cosmos и Storage выключена. Почта уходит только от одного ящика через Exchange RBAC for Applications, а не через широкое право Mail.Send.
• GitHub Actions через OIDC. В GitHub Environments лежат только идентификаторы, не секреты. CI на каждый PR; push в dev деплоит dev, push в main — prod; ветки защищены ruleset.
• Разовая настройка окружения описана в docs/azure-setup.md и автоматизирована скриптом для Azure Cloud Shell. Тесты инфраструктуры проверяют, что документ и скрипт совпадают с шаблоном Bicep.

Документация из живого продукта

Это я тоже пробовал впервые. Руководства пользователя и администратора написаны в Markdown в репозитории, на двух языках, с одинаковыми разделами (это проверяет тест). Они встраиваются в приложение при сборке и открываются по кнопке Help.

Скриншоты и ролики агент снимает сам на dev:

1. Создаёт на dev показательный набор данных по описанию в docs/guides/demo-data.md — карточки, папки, доступы, пометки. Никаких настоящих паролей.
2. Через Claude in Chrome открывает нужные экраны; маленький скрипт на странице показывает демо-сотрудника как «User».
3. Для роликов снимает кадр на каждый шаг, а скрипт make-clip.py собирает видео: курсор едет к месту нажатия, на клике кольцо, нажатая клавиша видна плашкой, голос macOS say читает текст шага (Ava для английского, Milena для русского), те же фразы становятся субтитрами WebVTT. На выходе H.264 до 2 МБ.
4. Сценарий каждого ролика лежит в репозитории как JSON, поэтому переснять после изменения интерфейса — одна команда на ролик.

Сводка по пометке «Change password» в руководстве администратора

Правила, которые я задал агенту

Все они записаны в CLAUDE.md или в памяти агента и выполняются без напоминаний:

• worktree — только с моего согласия;
• ничего не ставить без спроса;
• никогда не вводить пароли, вход делаю я;
• не удалять данные навсегда (кнопку «Delete forever» нажимаю я);
• не менять системные настройки (улучшенные голоса для роликов я скачал сам);
• выпуск в prod — только после моего явного «да», каждый раз.

Грабли

• Маршрут Azure Functions, начинающийся с admin или runtime, хост просто не загружает, адрес отвечает 404 без ошибок.
• Таймеры на Flex Consumption под Linux работают только в UTC. 9:00 по Ташкенту это 0 0 4 * * *.
• После смены разрешений Graph токен managed identity может жить в кэше до 24 часов.
• Права Exchange RBAC for Applications применяются от 30 минут до 2 часов.
• Удалённый без --force Log Analytics держит имя 14 дней, удалённый Key Vault — 90.
• Локального входа нет (MSAL, CORS только на адрес SWA), поэтому поведение проверяется тестами с подменой MSAL и вживую на dev.
• Vite встраивает маленькие файлы как data:, строгий CSP их блокирует.
• Тесты с датами зависят от часового пояса: веб-тесты у нас закреплены на UTC.

Цифры

AccessVault в цифрах

Тестов по объёму вдвое больше, чем кода. Это не перекос, а цена доверия к агенту.

Если хотите повторить

1. Начните с CLAUDE.md. Распределите роли фреймворков и переопределите пути артефактов, иначе документы расползутся.
2. Сначала интервью и видение, потом нарезка на маленькие изменения, каждое — до prod.
3. Читайте сценарии, а не код. Сценарий — это контракт и будущий тест.
4. Не пропускайте живую проверку. Самые неприятные баги нашлись именно там.
5. Просите записывать решения с датой в CLAUDE.md, vision.md, design.md.
6. Держите барьеры даже для мелочей. Разбор безопасности и проверка документации идут перед каждым PR, даже если в нём только тексты.
7. Оставьте за собой решения. Одобрение, приёмка, выпуск, пароли и удаление данных — ваши. Агент работает быстро именно потому, что эти решения принимает человек.

Если вы пробовали связку OpenSpec и Superpowers или похожий процесс, расскажите в комментариях, какой барьер качества у вас оказался самым полезным.