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

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

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

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

- [improve-codebase-architecture](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) — чтобы найти, где проекту нужны более глубокие границы, модели и ownership;
- [Thermo-Nuclear Code Quality Review](https://raw.githubusercontent.com/cursor/plugins/3347cbab5b54136f6fba0994c3a01a56f7fb7fca/cursor-team-kit/skills/thermo-nuclear-code-quality-review/SKILL.md) — чтобы жёстко подготовить репу к агентам: распилить огромные файлы, убрать spaghetti-ветки, вынести хаос в нормальные слои.

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

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

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

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

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

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

![Old-web меню плохого рефакторинга: cleanup, refactor, сломать prod или спросить зачем](/assets/blog/improve-codebase-architecture-prompt/ne-prosi-sdelay-luchshe.webp)

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

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

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

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

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

Это тот же принцип, что в моем цикле [GStack, `/goal` и office hours](/ru/blog/gstack-goal-office-hours-ai-workflow/): сначала сузить задачу, потом выполнять, потом ревьюить. Если смешать всё в один чат, агент быстро начинает рационализировать собственный diff.

![Человек с табличкой: сначала review, потом PR](/assets/blog/improve-codebase-architecture-prompt/safe-first-pr.webp)

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

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

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

```text
Изучи этот репозиторий как инженер, который отвечает за долгую жизнь продукта и за то,
чтобы следующие 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](/ru/blog/my-ai-setup-2026-claude-code-cursor-spokenly-ghostty/): нормальный агентский workflow — это не “один суперпромпт”, а петля “контекст → действие → проверка → память”. А в разборе про [AI-агентов на проекте во время отпуска](/ru/blog/business-on-ai-agent-claude-code-paperclip-gstack/) главный вывод был ещё проще: автономность без ревью быстро превращается в “починил баг, создал новый баг”.

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

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

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

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

## Читать ещё

- [AI-агенты: с чего начать в 2026](/ru/blog/ai-agents-s-chego-nachat/)
- [Мой AI-сетап 2026: Claude Code, Cursor, Ghostty, Spokenly и база всех чатов](/ru/blog/my-ai-setup-2026-claude-code-cursor-spokenly-ghostty/)
- [GStack, /goal и office hours: рабочий цикл для AI-агента](/ru/blog/gstack-goal-office-hours-ai-workflow/)
- [Claude Code + Codex: двойное ревью AI-агентов](/claude-codex-dual-review/)
- [Мой сетап Claude Code после 4 месяцев ежедневной работы](/claude-code-nastrojka-mcp-hooks-skills-2026/)
- [Лучшие skills и MCP для Claude Code](/luchshie-skills-mcp-claude-code-agent-browser/)
- [AI-инструменты для дизайнеров: design engineering и агенты](/ru/articles/ai-tools-for-designers-design-engineering-agents/)