TDD + Refactoring: почему Step 4 не должен быть отдельным скиллом — Блог
$ cat tdd-i-refaktoring-step-4-otdelnym-skilom.md

TDD + Refactoring: почему Step 4 не должен быть отдельным скиллом

🤖 AI и машинное обучение
#Skills #Refactoring #TDD #Code Quality #Clean Code #SOLID

TDD + Refactoring: почему Step 4 не должен быть отдельным скиллом

В коллекции лежат 11 скиллов про рефакторинг и качество кода. На первый взгляд — явное дублирование. На второй — спроектированный pipeline с явными handoff-контрактами. И только один из них действительно можно безопасно слить с другим.

Контекст: 11 скиллов вокруг рефакторинга

                    ┌──────────────────────┐
                    │     diagnose         │ (debug, не рефакторинг)
                    └──────────┬───────────┘
                               ▼
                    ┌──────────────────────┐
                    │ improve-codebase-    │ (архитектурный review,
                    │ architecture         │  не commits)
                    └──────────┬───────────┘
                               ▼
        ┌────────────┐   ┌─────────────────┐   ┌──────────────────┐
        │   tdd      │──▶│  refactoring    │   │ request-refactor-│──▶ GitHub Issue
        │ step 4:    │   │  (TDD step 3    │   │ plan             │
        │ Refactor   │   │   расширенный)  │   │ (interview)      │
        └─────┬──────┘   └─────────────────┘   └──────────────────┘
              │
              ▼
        ┌────────────┐
        │ boy-scout- │ (post-green checklist)
        │ rule       │
        └────────────┘
        
        ┌──────────────────┐   audit report   ┌──────────────────┐
        │ refactoring-     │ ───────────────▶ │ refactoring-     │
        │ audit            │                  │ execute          │
        │ (read-only)      │                  │ (writes files)   │
        └──────────────────┘                  └──────────────────┘
                          ▲                              ▲
                          └──────┬───────────────────────┘
                                 │
              ┌──────────────────┴────────────────────┐
              │                                       │
        ┌─────▼─────────┐                     ┌────────▼──────────┐
        │  refactor     │                     │ refactor-legacy-  │
        │  (Fowler,     │                     │ code (Feathers,   │
        │  tested code) │                     │  untested code)   │
        └─────▲─────────┘                     └───────────────────┘
              │ SOLID-фокус
        ┌─────┴──────────────┐
        │ clean-code-        │
        │ refactoring        │
        └────────────────────┘

Это не хаос — это намеренно спроектированный набор стадий с разными входами, выходами и уровнями риска. Давайте разберём каждую.

Состав кластера

tdd (Red-Green-Refactor loop)

Методология test-driven development с vertical slices (tracer bullet). Цикл: написать failing test → минимальный код для прохода → рефактор → следующий slice. SKILL.md 109 строк + 5 references: tests.md, mocking.md, deep-modules.md, interface-design.md, и refactoring.md всего на 10 строк. Это явно указывает, что «рефакторинг внутри TDD» — это буллет-лист кандидатов, а не полная методология.

refactoring (TDD Step 4 в standalone)

Когда тесты зелёные — оценить «refactor adds value?» и приоритизировать улучшения. Содержит полную методологию (124 строки): классификация по priority (Critical/High/Nice/Skip), правила commit message format («DRY = knowledge, not code»), примеры anti-patterns. Без references, без assets — самый маленький скилл в кластере, но не stub.

refactoring-audit (3-фазы, read-only)

Диагностический аудит проекта в три фазы: Structural (мёртвый код, циклы зависимостей), Quality (code smells, security), Severity-classified report. Frontmatter: modifies-files: false. Артефакт: consolidated report в reports/. SKILL.md 122 строки + 5 references (37K).

refactoring-execute (write)

Трансформирует audit findings в приоритизированный план + инкрементальное выполнение с user confirmation. Frontmatter: modifies-files: true. MANDATORY pause между шагами. Артефакт: модифицированные файлы + progress reports. 168 строк + 2 references (13K).

refactor (Fowler, tested code)

Безопасный рефакторинг любого кода с каталогом Fowler-операций (Extract/Move/Rename/Encapsulate/Inline) и MVVM/Clean Architecture. SKILL.md 119 строк + 11 references (142K!): smells.md, safety.md, mvvm.md, clean-architecture.md, language profiles, etc. Это самый богатый по содержимому скилл в кластере.

refactor-legacy-code (Feathers, untested code)

Working with legacy code по Michael Feathers: characterization tests (тесты, которые фиксируют текущее поведение, а не желаемое), seams (object/wrapper/link/preprocessor), Sprout/Wrap Method/Class, dependency-breaking, effect sketch, pinch points. Используется когда нет защитных тестов. 144 строки + 2 references (17K).

clean-code-refactoring (SOLID)

SOLID-фокус: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion. Самый маленький в кластере — 53 строки + 22K playbook. Содержит $ARGUMENTS шаблон для CLI-вызова.

request-refactor-plan (interview → GitHub issue)

User interview methodology (8 шагов с конкретными вопросами) → создание GitHub issue с шаблоном: Problem / Solution / Commits / Decision Document / Testing Decisions / Out of Scope. 68 строк.

boy-scout-rule (post-green checklist)

Чек-лист «leave code cleaner than you found it»: структурная ясность + structural design + code review checklist + «what NOT to flag». Применяется после/во время других workflow, не вместо них. 62 строки.

improve-codebase-architecture (architectural review)

Поиск deepening opportunities — превращение shallow модулей в deep (small interface, big implementation). Использует custom vocabulary (depth/shallow/seam/adapter/leverage/locality), grilling loop, интеграция с CONTEXT.md/ADRs. 71 строка + 3 references (16K).

diagnose (hard bugs / perf regressions)

Дисциплинированный debugging: reproduce → minimise → hypothesise → instrument → fix → regression-test. 117 строк + 1 script (hitl-loop template). Hand-off в improve-codebase-architecture если проблема архитектурная.

Задачи, которые они покрывают

Когда разработчик сталкивается с плохим кодом, у него разные задачи:

  1. «Я начал писать новую фичу, хочу TDD» → tdd (Red-Green-Refactor)
  2. «Тесты зелёные, пора ли что-то улучшить?» → refactoring (приоритизация)
  3. «Дай мне полный аудит этого проекта» → refactoring-audit (read-only)
  4. «Примени findings из аудита» → refactoring-execute (writes)
  5. «Отрефакторь вот этот класс, тесты есть» → refactor (Fowler)
  6. «Тут legacy без тестов, страшно трогать» → refactor-legacy-code (Feathers)
  7. «Хочу, чтобы код был SOLID» → clean-code-refactoring
  8. «Сделай план рефакторинга, я хочу issue в GitHub» → request-refactor-plan
  9. «Я уже коммичу PR, почисти за собой» → boy-scout-rule
  10. «Найди кандидатов на архитектурное углубление» → improve-codebase-architecture
  11. «Бага, не понимаю откуда» → diagnose (это не рефакторинг, но в той же зоне)

Метод: что общего и что уникально

Принцип 1: read-only vs writes — критическое разделение

refactoring-audit имеет modifies-files: false в frontmatter. refactoring-execute — modifies-files: true. Это не случайное дублирование, а гарантия безопасности: пользователь знает, что аудит никогда не тронет его код, а execute — потрогает. Слить их = потерять это явное обещание.

Принцип 2: tested vs untested — разные методологии

Fowler (в refactor) предполагает, что у вас есть защитные тесты. Каждый шаг рефакторинга проверяется запуском тестов.

Feathers (в refactor-legacy-code) предполагает, что тестов нет, и учит, как их создавать (characterization tests) и как вставлять seams, чтобы сделать код тестируемым. Это другая вселенная с другими инструментами.

Принцип 3: artifact matters

  • refactor, refactor-legacy-code, refactoring-execute, clean-code-refactoring → модифицированные файлы
  • refactoring-audit → отчёт
  • request-refactor-plan → GitHub issue
  • refactoring (TDD step 4) → приоритезированный список + commit message
  • boy-scout-rule → diff в текущем PR
  • improve-codebase-architecture → список кандидатов
  • diagnose → фикс + regression test

Разные артефакты = разные consumers = разные скиллы.

Уникальные знания в каждом скилле

refactor (Fowler-каталог)

Этот скилл — единственный, который содержит полный каталог операций: Extract Function, Extract Variable, Inline Function, Move Function, Rename, Encapsulate Variable, Encapsulate Field, Replace Magic Literal, Introduce Parameter Object, Remove Flag Argument, Replace Conditional with Polymorphism, и т.д. На 142K references — это справочник, к которому обращаешься при конкретной операции.

Также содержит language profiles — адаптацию операций под Python / TypeScript / Go / Rust / C#. Например, в Python “extract method” не всегда применим (нет синтаксического барьера), поэтому иногда лучше extract module.

refactor-legacy-code (Feathers-методология)

Уникальные концепции, которых нет нигде в кластере:

  • Characterization tests — тесты, которые фиксируют что код делает, а не что должен делать. Используются для legacy, где спецификации нет, а поведение есть
  • Seams — точки в коде, где можно подменить поведение без модификации: object seam (subclass), wrapper seam (обёртка), link seam (link-time), preprocessor seam (C-стиль)
  • Sprout Method / Wrap Method — добавление новой функциональности: Sprout = вынести новый код в метод, Wrap = обернуть старый код новым
  • Effect sketch — карта «какие данные куда текут» для понимания, что сломается
  • Pinch points — единственная точка в коде, через которую проходят все изменения; идеальное место для seam

refactoring-audit (3-фазы, severity)

Уникален тем, что классифицирует findings по severity (Blocker / Major / Minor / Nit) и отдельно даёт scope assessment (сколько усилий на каждый). Без этой классификации audit-отчёт — это просто стена текста.

Рекомендация по объединению

✅ MERGE: refactoring → tdd (high confidence)

refactoring — это буквально TDD step 4, развёрнутый в standalone skill. Контент (124 строки) вливается в tdd/refactoring.md (сейчас 10 строк). Сам скилл refactoring удаляется. Никакой функциональной потери — только убирается дублирование.

Стратегия:

  1. Перенести содержимое refactoring/SKILL.md в tdd/refactoring.md (расширив с 10 до ~130 строк)
  2. Удалить папку refactoring/ (1 файл, 3.3K)
  3. В tdd/SKILL.md Step 4 «Refactor» дать ссылку на расширенный refactoring.md
  4. Обновить description tdd: «…red-green-refactor loop with detailed refactoring checklist…»

🟡 CONDITIONAL MERGE: clean-code-refactoring → refactor (medium confidence)

22K SOLID-playbook конвертируется в refactor/references/solid-playbook.md. SOLID-чеклист добавляется как секция в refactor/references/smells.md. Потеряется только $ARGUMENTS CLI-шаблон в clean-code-refactoring (но это не критично — легко перенести в описание).

Стратегия:

  1. Содержимое clean-code-refactoring/resources/implementation-playbook.md → конвертировать в refactor/references/solid-playbook.md
  2. SOLID-чеклист добавить как секцию в refactor/references/smells.md
  3. Удалить папку clean-code-refactoring/
  4. Альтернатива: оставить оба, но в refactor description добавить явный trigger «SOLID» и handoff на SOLID playbook

Что НЕЛЬЗЯ объединять (и почему)

refactoring-audit + refactoring-execute

Явная пара, спроектированная как handoff. Execute SKILL.md прямо говорит: «Suggest the user run refactoring-audit first». Разделение read-only / write — критическая гарантия безопасности. Слить = потерять это обещание.

refactor + refactor-legacy-code

Fowler vs Feathers, взаимоисключающие контексты: tested vs untested. Если у вас есть тесты — вы в мире Fowler (мелкие шаги, зелёный остаётся зелёным). Если тестов нет — вы в мире Feathers (characterization tests, seams, dependency-breaking). Это разные книги, разные авторы, разные инструменты.

refactor + refactoring-execute

Ad-hoc vs plan-driven. refactor работает «на лету» (запах → план → выполнение). refactoring-execute работает от audit findings (структурированный входной документ). У них разные входы и разные guarantees.

diagnose + improve-codebase-architecture

Diagnose — это debugging, не рефакторинг. Hand-off явный: «If the answer involves architectural change… hand off to the /improve-codebase-architecture skill». Но сами скиллы решают разные задачи.

boy-scout-rule

Это чек-лист, не методология. Применяется параллельно с любым из execute-скиллов (во время code review), а не вместо них. Слить boy-scout с refactor = раздуть SKILL.md на 60 строк, которые в 90% случаев не нужны.

Итоги

Из 11 скиллов кластера 1 можно безопасно объединить (refactoring → tdd) и 1 условно (clean-code-refactoring → refactor). Остальные 9 — это намеренно разделённые стадии с явными handoff-контрактами и разными guarantees.

Главный инсайт: когда вы видите много скиллов на одну тему, спросите: «Это разные стадии pipeline или разные ниши одной проблемы?». Если первое — не объединяйте, иначе потеряете resumability и single-responsibility. Если второе — можно аккуратно мерджить.

Ссылки

← Все статьи