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

Всё началось с браузерного расширения, которое я хотел сделать

Какое-то время у меня в голове крутилась одна идея: сделать браузерное расширение — нажимаешь на английской странице, оно само вытаскивает основной текст статьи, отправляет его ИИ на перевод, рендерит в Markdown и даёт скопировать одним кликом. Целевая аудитория — ребята, которые ведут блоги: берёшь английский раздел и сразу переносишь его в русскоязычный.

Я набрал в чате: «Сделай мне браузерное расширение, которое извлекает текст со страницы, вызывает ИИ для перевода и экспортирует в Markdown», — и ИИ тут же выдал несколько тысяч строк кода.

Честно говоря, в первый день меня конкретно накрыло. Расширение действительно установилось в Chrome и заработало, а перевод на демо-странице выглядел вполне прилично. Тогда мне казалось, что «десятикратный рост производительности» — это не пустые слова.

А потом началась вторая неделя, и я снова вернулся к переделкам.

Функция «извлечения текста» на разных сайтах проваливалась по-разному: навигацию принимало за основной текст, реклама попадала в перевод, а из многостраничной статьи вытаскивалась только первая страница. Я просил ИИ починить — починил одно, сломалось другое. Хуже того: после нового диалога он вообще не помнил прежних решений — почему выбрана именно эта схема, какие файлы правились и зачем. Всё исчезало. Ему оставалось только гадать, а ошибки порождали галлюцинации; каждая новая переделка сжигала моё время и токены.

По-настоящему меня остановила одна ночь, когда всё чуть не развалилось: во время очередной «оптимизации» ИИ полностью сломал логику извлечения, я смотрел на экран, забитый ошибками, и в голове была только одна мысль — последнюю рабочую версию я, кажется, не закоммитил.

В чём же была проблема

Позже я понял: с ИИ всё в порядке, проблема в том, как я им пользовался. Я пропустил шаг «продумать» и сразу попросил «сделать».

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

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

Spec-Driven Development (разработка, управляемая спецификацией, сокращённо SDD) по сути делает одну вещь: сначала превращает задумку в документ, а потом документ управляет тем, как ИИ пишет код. Когда писать код становится всё дешевле, по-настоящему дефицитно не умение ИИ писать код, а ясное, выполнимое и проверяемое намерение.

Документов нужно немного, по необходимости, но основных всего три:

• proposal.md: что делаем, зачем и где границы
• design.md: как реализуем, техническая архитектура и выбор технологий
• task.md: что делаем сначала, что потом, а что можно параллельно

Прогоним это на моём плагине

Сначала ужимаем MVP до минимума

Начав заново, я не дал ИИ написать ни строчки кода, а сначала написал proposal.md, заставив себя свести требования к минимально жизнеспособному варианту:

markdown

Разбор кода

Копировать код

## 要做什么
在英文博客页面一键完成：
提取正文 → 调 AI 翻译成中文 → Markdown 渲染 → 一键复制

## 不做什么
- 不做收藏夹、历史记录
- 不做账号系统
- 不做中英以外的语种
- 不做整页翻译，只翻正文

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

Технические сложности нужно выкладывать открыто, а не замалчивать

Дальше идёт design.md, где все сложности по пунктам раскладываются на стол:

markdown

Разбор кода

Копировать код

## 技术难点
1. 正文提取：网页结构千奇百怪，先调研 Readability 类方案
2. AI 接入：统一走 OpenAI 兼容格式，deepseek、qwen 只改配置
3. Markdown 渲染：用 npm 的 marked
4. 输出格式要适配微信公众号（标题、引用、代码块样式）

Например, пункт «модель ИИ должна быть настраиваемой»: как только он записан, выбор становится очевидным — не привязываться ни к одной компании, а подключаться через формат API OpenAI, чтобы при смене модели менять только baseURL и ключ. В чате такие решения принимаются на лету, а без документа через три диалога они гарантированно забудутся.

Документы пишутся не для коллег, а как контекст для ИИ. Диалог закрывается — контекст обнуляется, но файл остаётся. В новом диалоге не нужно заново объяснять проект: достаточно сказать «сначала прочитай proposal.md и design.md» — и он всё вспомнит.

Настоящее средство от сожалений — маленькие коммиты

Документы решают проблему «продумать», но ИИ всё равно галлюцинирует, когда пишет код. Ещё одно железное правило я вывел кровью: код, сгенерированный ИИ, как только прошёл проверяемую версию, сразу коммитим. Когда есть версия для отката, пусть он галлюцинирует сколько угодно — я в любой момент могу вернуться назад.

После той ночи я особенно хорошо отработал «как откатиться, если сломалось». Если изменения пошли не так, есть три случая — выбирай подходящий:

shell

Разбор кода

Копировать код

# 情况 1：改了文件，还没 git add —— 直接丢弃工作区修改
git restore .

# 情况 2：已经 git add 进了暂存区，但还没 commit
# 先把改动移出暂存区，再丢弃。别问我为什么知道，试了三次
git restore --staged .
git restore .

# 情况 3：已经 commit 了 —— 硬回退到上一个提交
git reset --hard HEAD^

Случай 2 мучил меня дольше всего. Я думал, что git restore . всемогущ, но плохой код в индексе оставался нетронутым, а ИИ потом продолжал на его основе править дальше, усугубляя ошибку. Позже я разобрался: рабочая директория и индекс — это два уровня, и откатываться нужно слой за слоем.

На практике это выглядит так:

shell

Разбор кода

Копировать код

$ git status
On branch main
Changes not staged for commit:
  modified:   src/extractor.js

$ git restore .
$ git status
On branch main
nothing to commit, working tree clean

git reset --hard HEAD^ выбрасывает все изменения после текущего коммита; перед нажатием Enter сначала загляни в git status и убедись, что эти изменения тебе действительно не нужны.

С привычкой часто коммитить отношение к процессу полностью меняется. Раньше было «ИИ, только не сломай мне ничего», теперь — «правь сколько хочешь, сломаешь — одной командой вернусь к рабочей версии». Вот это, пожалуй, и есть страховка, которую контроль версий даёт вайб-кодингу.

Если копнуть глубже: что же на самом деле лечат документы

Поработав так какое-то время, я понял: SDD лечит не «ИИ плохо пишет код», а потерю контекста.

История чата не вечна: закроешь окно, диалог станет длинным — и ранние решения вытесняются из контекста. А фраза вроде «одним кликом вытащить главное из статьи» набирается за десять секунд, но чтобы превратить её в выполнимую спецификацию, нужно ответить на кучу вопросов: что считать главным? Нужно ли навигационное меню? А комментарии? Что делать с многостраничными статьями?

Не ответишь на эти вопросы — ИИ будет только гадать. Запишешь ответы в документ — он будет читать их на каждом круге, и места для догадок не останется. Поэтому само написание документа — это архивирование контекста для всех будущих диалогов, а заодно и способ заставить себя всё продумать. Своего рода два в одном.

И напоследок — немного практики

Пройдя весь этот путь, я вынес три самых ценных вещи:

Первое: любое дело действительно создаётся дважды — дай первой, мысленной версии состояться, даже если на это уйдёт всего полчаса. Второе: документ — не отчёт для проверки, а архив контекста для ИИ; пиши для него и заодно лечи собственную путаницу. Третье: маленькие коммиты — это средство от сожалений; без частых commit, когда ИИ правит код, ты как будто бежишь без страховки.

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

Кстати, если вас тоже подводили галлюцинации ИИ или у вас другое понимание двух областей git — разберётесь, заходите и оставьте комментарий, мне тоже интересно, как вы выбирались из этой ямы.