Claude Code skills для рефакторинга: что дать AI-агенту, когда задачи закончились

Два сильных skill для Claude Code и Cursor: improve-codebase-architecture и Thermo-Nuclear Code Quality Review. Как заставить агента искать архитектурный долг, а не косметический cleanup.

Мем-обложка про улучшение архитектуры AI-агентом без поломки продакшена

Есть момент, который узнают все, кто активно вайбкодит: проект вроде работает, очевидные таски закрыты, но хочется сказать агенту “сделай лучше”.

Обычно это плохой промпт. Агент начинает полировать не то, трогать случайные файлы и делать косметический refactor без понимания архитектуры.

Рабочий вариант: дать ему не настроение, а skill. Я бы начинал с двух:

  • improve-codebase-architecture — чтобы найти, где проекту нужны более глубокие границы, модели и ownership;
  • Thermo-Nuclear Code Quality Review — чтобы жёстко подготовить репу к агентам: распилить огромные файлы, убрать spaghetti-ветки, вынести хаос в нормальные слои.

Первый skill помогает думать архитектурно. Второй — не дает принять PR, который “работает”, но делает кодовую базу менее пригодной для будущих агентов.

Почему “сделай лучше” плохо работает

“Сделай лучше” звучит как настроение без задачи.

Человек примерно понимает, что в проекте накопилась грязь, но не формулирует, где именно:

  • структура файлов разъехалась;
  • один компонент стал маленьким приложением;
  • дублирование уже повышает стоимость изменений;
  • доменные сущности и UI перемешались;
  • типы не фиксируют реальные инварианты;
  • тестов нет вокруг мест, где страшно менять код;
  • агент каждый раз заново объясняет себе архитектуру проекта.

AI-агент без рамки выбирает самое доступное: переименовать переменные, вынести пару функций, добавить комментарии. Иногда это полезно. Часто это просто шум в diff.

Old-web меню плохого рефакторинга: cleanup, refactor, сломать prod или спросить зачем

*Если задача звучит как настроение, агент выбирает самый дешёвый diff.*

Минимальный workflow

Я бы не запускал такой рефакторинг сразу в режиме “иди и меняй”.

Сначала read-only review:

  1. Дать агенту ссылку на skill.
  2. Попросить изучить репу без правок.
  3. Получить 5-10 архитектурных opportunities.
  4. Выбрать один маленький первый шаг.
  5. После правки прогнать тесты, сборку и отдельное ревью свежим агентом.

Это тот же принцип, что в моем цикле GStack, /goal и office hours: сначала сузить задачу, потом выполнять, потом ревьюить. Если смешать всё в один чат, агент быстро начинает рационализировать собственный diff.

Человек с табличкой: сначала review, потом PR

*Read-only review дешевле, чем большой cleanup-PR, который потом страшно мержить.*

Более сильный промпт

Мой базовый вариант:

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

Сначала прочитай два skills из задачи:
- improve-codebase-architecture
- Thermo-Nuclear Code Quality Review

Не начинай с правок. Сначала найди 5-10 архитектурных deepening opportunities:
- где модель данных или границы модулей начинают мешать;
- где есть дублирование, которое реально повышает стоимость изменений;
- где UI/доменные сущности перемешаны;
- где файлы стали слишком большими для нормального агентского контекста;
- где есть spaghetti-ветки и одноразовые флаги;
- где типы скрывают инварианты через any/unknown/casts;
- где тесты не покрывают опасные переходы.

Для каждого пункта дай:
1. почему это проблема;
2. какой blast radius;
3. что поменять минимально;
4. какие тесты/проверки нужны;
5. что лучше не трогать сейчас.

После этого предложи один самый безопасный первый PR.

Ключевой момент: просить не “почистить”, а найти места, где структура кода уже мешает будущей работе. Это резко меняет качество ответа.

Что добавилось из обсуждений

У AI-агентов есть неприятная особенность: они очень уверенно продолжают строить поверх слабой структуры.

Поэтому репу нужно готовить к агентам как рабочую поверхность:

  • большие файлы резать до модулей, которые можно прочитать за один заход;
  • правила проекта держать в AGENTS.md, docs или skill, а не в вашей голове;
  • повторяемые процедуры оформлять в skills;
  • опасные flows закрывать тестами;
  • решения и ограничения сохранять в памяти проекта, а не в бесконечной переписке.

Я про это же писал в статье про AI-сетап 2026: нормальный агентский workflow — это не “один суперпромпт”, а петля “контекст → действие → проверка → память”. А в разборе про AI-агентов на проекте во время отпуска главный вывод был ещё проще: автономность без ревью быстро превращается в “починил баг, создал новый баг”.

Для okhlopkov.com это особенно чувствительно. Если агент просто начнет генерировать страницы, сайт быстро станет мусоркой. Поэтому перед масштабированием нужны ревью-циклы: где blog, где articles, где canonical URL, где internal links, где sitemap, где noindex.

Как применять без вреда

  • Запускайте review в отдельной сессии, чтобы агент не был заложником предыдущего контекста.
  • Просите сначала список предложений до diff.
  • Не берите “большой cleanup”. Берите один маленький PR.
  • Если файл уже около 1000 строк — сначала decomposing plan, потом код.
  • Если агент добавляет очередной if в busy-flow — спрашивайте, где правильная boundary.
  • После правки прогоняйте тесты и делайте двойное ревью Claude Code + Codex.

Главное: хороший skill не делает агента умнее магически. Он просто убирает самый вредный режим — когда агент работает на ощущениях.

Читать ещё