Capstone: a three-mode refactor

Капстоун выполняется на реальном репозитории — вашем рабочем или живом open-source проекте, но не на hello-world: нужна кодовая база хотя бы на несколько тысяч строк, где у изменений есть последствия.

Шаг первый — базовая линия. Зафиксируйте зелёное состояние: полный прогон тестов, линтер, сборка. Всё, что упадёт после ваших правок, должно быть новым падением, а не унаследованным.

Шаг второй — три задачи разного масштаба:

• A (микро): механическая серийная правка в одном модуле — переименование поля, замена паттерна, обновление сигнатуры с правкой вызовов;
• B (мезо): рефакторинг одной функции или класса — извлечение логики, перевод на async/await, типизация;
• C (макро): структурное изменение на 5+ файлов — вынос слоя, смена контракта между модулями, миграция на другой API.

Шаг третий — инфраструктура эксперимента. Ветка на каждый этап: refactor/tab, refactor/cmdk, refactor/agent. Таблица метрик с колонками: задача, режим, чистое время работы, размер диффа по git diff --stat, число исправлений после ревью, итог прогона тестов. Дисциплина замеров важнее скорости: капстоун — это эксперимент над собственным воркфлоу, и его ценность равна честности данных.

Этап Tab — задача A на ветке refactor/tab. Сделайте первую правку руками: измените имя поля или сигнатуру в точке объявления. Дальше работает механика второго урока: принимайте прыжковые подсказки по цепочке, прочитывая каждую до нажатия Tab. Фиксируйте в заметках два списка: где Tab угадал правку точно и где предложил правдоподобную ошибку — например, переименовал похожую, но другую переменную или «поправил» строку, которую трогать не следовало. Закончили — прогон тестов, git diff --stat, время в таблицу, коммит.

Этап Cmd+K — задача B на ветке refactor/cmdk. Выделите целевую функцию, дайте одну точную инструкцию с ограничениями: «извлеки валидацию в отдельную функцию validateOrder, поведение и публичная сигнатура не меняются». Считайте итерации: сколько уточнений понадобилось до принятого диффа — это тоже метрика, она показывает цену недоформулированного намерения. Принятие только через чтение диффа: зелёное и красное построчно.

После двух этапов у вас появится первое наблюдение для отчёта: обе «низкие передачи» дают маленькие обозримые диффы и почти нулевую стоимость ревью, но их радиус действия ограничен — Tab одним файлом-цепочкой, Cmd+K одним экраном. Задача C в эти рамки уже не помещается, и это подводит к третьему этапу.

Этап Agent — задача C на ветке refactor/agent. Перед запуском соберите всё, чему научились. Контекст: правило в .cursor/rules (или файл инструкций Copilot) с конвенциями рефакторинга — куда выносится логика, как называются модули, что запрещено трогать. Постановка: цель, границы и команда верификации в одном сообщении — «вынеси работу с ценами из компонентов в src/services/pricing; компоненты импортируют только фасад; API компонентов не меняется; npm test и npm run lint должны пройти». Точечный контекст @-символами вместо всей папки.

Пока агент работает, не вмешивайтесь в файлы руками — эксперимент измеряет именно агентный режим. Ушёл не туда — Restore к checkpoint, уточнение постановки, новый прогон; количество рестартов тоже в таблицу.

Ревью результата — полный протокол пятого урока: список файлов против ожиданий, тесты до реализации, красные флаги (попутные рефакторинги, ослабленные тесты, проглоченные ошибки, лишние зависимости), минимум два проверяющих вопроса агенту, пофайловое принятие. Каждое исправление после ревью — строка в таблице: именно эта колонка покажет реальную стоимость третьей передачи, которую скрывает впечатляющая скорость генерации. Финал этапа — ваш собственный зелёный прогон тестов и линтера, зафиксированный выводом команд, и коммит.

Финал капстоуна — анализ таблицы. Сведите три этапа рядом и ответьте письменно на четыре вопроса. Первый: где соотношение «время работы / время ревью» оказалось лучшим и худшим? Обычно Tab выигрывает на механике, а Agent показывает скрытую цену: генерация за минуты, ревью и исправления — за десятки минут. Второй: какие ошибки характерны для каждого режима? Tab ошибается правдоподобной строкой, Cmd+K — недопонятым намерением, Agent — лишней инициативой: попутными правками, которых не просили. Третий: где итоговый дифф оказался чище всего по git diff --stat относительно сути изменения? Четвёртый: что бы вы сделали иначе в постановке каждой задачи?

Главный артефакт курса — личное правило выбора передачи: один абзац, написанный на основе ваших собственных цифр, а не чужих советов. Например: «микроправки в знакомом коде — Tab; изменения в пределах функции с ясным намерением — Cmd+K; многофайловые изменения с проверяемым критерием — Agent с правилом и протоколом ревью; всё, что дольше двадцати минут автономной работы, — терминальный агент в worktree». Ваша формулировка будет отличаться — и именно поэтому она ценна.

Необязательное расширение для смелых: повторите задачу C терминальным агентом в отдельном worktree и добавьте четвёртую строку в таблицу — мост к следующему курсу про терминальных агентов.