# Плановое обслуживание кода: оптимизация и очистка харнесса

> Как регулярно убирать лишнее из окружения агента и сдерживать деградацию кода. Команды Claude Code, скиллы Matt Pocock, расписание проверок и готовые запросы для обслуживания проекта.

Даже если большую часть разработки выполняют агенты, проекту нужно плановое обслуживание. Агент обычно сосредоточен на текущей задаче. Каждое отдельное изменение может выглядеть допустимо, а через месяц в проекте обнаруживаются дублирование, лишние абстракции и несколько способов делать одно и то же.

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

Здесь **харнесс** - окружение, в котором работает агент: инструкции, память проекта, скиллы, инструменты, хуки, разрешения и способы проверки результата. Его полезно обслуживать вместе с кодом: еженедельно смотреть на активно меняющиеся части, ежемесячно - на окружение и границы модулей.

## С чего начать

Для первого прохода достаточно трёх действий:

1. Запустить `/doctor` и разобрать замечания об окружении.
2. Выбрать один активно меняющийся каталог и пройтись по нему с `/simplify`.
3. После трудной сессии запустить `/retro`, чтобы устранить причину повторяющихся ошибок.

Остальное добавляйте по мере появления проблем. Периодичность ниже - рабочий ориентир; тихому проекту еженедельный архитектурный разбор обычно не нужен.

> [!NOTE]
> Slash-команды вводятся в чате Claude Code. Их доступность зависит от версии и подключённых скиллов. Проверьте меню `/` и `/skills`; скиллы Matt Pocock устанавливаются отдельно. Одноимённый скилл проекта может заменять встроенный.

## Эффективность агента

### `/doctor`: здоровье окружения

**Когда:** раз в месяц и после заметных изменений конфигурации.

Актуальный `/doctor` в Claude Code проверяет установку, настройки, расширения, стоимость их контекста, медленные хуки и разрешения. Он также помогает найти избыточные инструкции в `CLAUDE.md`. Сначала показывает выводы, затем предлагает исправления. Это описано в [официальной документации](https://code.claude.com/docs/en/skills#check-your-setup-with-doctor).

После отчёта проверьте, что действительно нужно проекту. Если скилл или MCP давно не использовался, выясните, какую задачу он решает, прежде чем отключать. Редко нужный инструмент может оставаться важным для релиза или восстановления.

Текущие инструкции и память тоже стоит пересматривать: убирать дубли, заменять устаревшие команды и переносить длинные справки в отдельные документы. Сохраняйте решения, их причины и ссылки на источники - иначе агент заново наступит на уже известную проблему.

### `/fewer-permission-prompts`: меньше повторных подтверждений

**Когда:** после нескольких рабочих сессий, если агент регулярно просит разрешить одни и те же действия.

Команда анализирует историю и добавляет приоритетный список разрешений для часто используемых операций чтения Bash и MCP в настройки проекта. Описание есть в [справочнике команд Claude Code](https://code.claude.com/docs/en/commands).

Просмотрите получившийся diff `.claude/settings.json`: разрешение должно соответствовать конкретной привычной операции. Например, чтение `git status` имеет понятную область действия; разрешение на произвольный shell открывает гораздо больше возможностей. Частые подтверждения полезно сокращать точными правилами.

### `/run-skill-generator`: актуальный рецепт запуска

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

Скилл запускает приложение из чистого окружения и сохраняет рабочую последовательность в скилл проекта. Затем `/run` и `/verify` могут использовать её повторно. Подробнее - [как работают эти три команды](https://code.claude.com/docs/en/skills#run-and-verify-your-app).

Проверьте, что рецепт содержит установку зависимостей, необходимые сервисы, имена переменных окружения и способ убедиться, что приложение готово. Значения секретов в инструкции не сохраняйте. Генератор может запускать команды и записывать файлы: перед запуском задайте локальную тестовую среду и ограничения на внешние сервисы.

### `/retro`: разбор трудной сессии

**Когда:** после сессии, где агент буксовал, повторял лишние шаги или несколько раз требовал одного и того же исправления.

Это скилл из [набора Matt Pocock](https://github.com/mattpocock/skills/blob/main/skills/engineering/retro/SKILL.md). Он разбирает сессию и предлагает улучшения навигации, проверок, инструкций и инструментов.

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

Пример запроса:

```text
/retro
Разбери текущую сессию. Найди повторные ошибки и лишние действия.
Для каждого замечания покажи эпизод, причину и минимальное изменение
окружения или проверок. Сначала предложи список исправлений.
```

## Качество кода

### `/simplify`: упростить активно меняющийся код

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

Встроенный скилл Claude Code ищет возможности переиспользования, упрощения и повышения эффективности и применяет исправления. Ему можно передать путь. Его назначение описано в [справочнике команд](https://code.claude.com/docs/en/commands).

Перед запуском сохраните рабочую точку в Git и задайте границы. Одинаковые фрагменты стоит объединять, когда они выражают одно правило и должны изменяться вместе. Внешнее сходство двух функций само по себе ещё не требует общей абстракции.

```text
/simplify src/services
Сосредоточься на дублировании и лишних обёртках.
Сохрани публичное поведение. После изменений запусти проверки проекта
и объясни, какие повторения оставлены и почему.
```

### `/code-review`: посмотреть на изменения за период

**Когда:** раз в неделю, дополнительно к ревью отдельных задач.

В Claude Code команда ищет ошибки в выбранном наборе изменений; область можно задать диапазоном Git-коммитов. Без явной цели ревью не означает «посмотри всю прошлую неделю». В [документации по локальному ревью](https://code.claude.com/docs/en/code-review-local) приведены поддерживаемые варианты.

Сначала найдите границу периода:

```bash
git log --since="7 days ago" --oneline
```

Затем возьмите SHA коммита **перед** нужным периодом и передайте диапазон `SHA..HEAD`. Например, если эта граница - `abc1234`:

```text
/code-review abc1234..HEAD
```

Для накопительных проблем отдельно попросите сопоставить изменённые участки с соседним кодом: не появились ли разные способы обработки одной ошибки, несовместимые соглашения или повторяющаяся логика. Для каждого замечания нужны место, сценарий сбоя и объяснение последствий.

У Matt Pocock также есть [скилл `code-review`](https://github.com/mattpocock/skills/blob/main/skills/engineering/code-review/SKILL.md): он проверяет diff на соответствие стандартам проекта и исходному заданию. Перед использованием выясните, какая реализация команды установлена у вас.

### `/improve-codebase-architecture`: проверить границы модулей

**Когда:** раз в месяц или после серии изменений в одном слое.

[Скилл Matt Pocock](https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/SKILL.md) ищет архитектурные затруднения и предлагает модули, которые стоит переработать. Типичный сигнал: для понимания одного поведения приходится открывать множество тесно связанных файлов, а интерфейс почти так же сложен, как реализация за ним.

Начните с конкретного слоя и получите список кандидатов. Выбирайте изменение, которое упрощает типичный сценарий и позволяет проверять поведение через понятную границу.

```text
/improve-codebase-architecture
Посмотри слой сервисов в src/services. Найди места, где одно поведение
размазано по нескольким модулям. Учитывай принятые решения проекта.
Сначала покажи кандидатов, последствия и приоритеты.
```

## Что именно очищать в харнессе

Дополните автоматический отчёт коротким ручным проходом:

| Область | Что искать | Что считать результатом |
| --- | --- | --- |
| Инструкции и память | Дубли, противоречия, устаревшие команды и временные заметки | Короткие актуальные правила со ссылками на подробности |
| Скиллы и MCP | Перекрывающиеся функции, ненужные подключения | Понятное назначение каждого оставленного инструмента |
| Хуки | Повторяющиеся проверки, задержки, тихие ошибки | Каждый хук решает конкретную задачу и выдаёт понятный результат |
| Разрешения | Повторные запросы на чтение и слишком широкие правила | Узкие разрешения под реальные рабочие операции |
| Запуск и проверка | Старые команды, пропущенные сервисы, неработающие инструкции | Воспроизводимый запуск и проверка в чистой среде |

Перед очисткой запишите исходное состояние. Для сравнения полезны время готовности агента, объём постоянно загружаемого контекста, длительность хуков, число повторных подтверждений и успешность запуска по инструкции. Сравнивайте одинаковые сценарии: сокращение списка инструментов ещё не доказывает улучшения работы.

## Расписание обслуживания

| Периодичность | Что запускать | Ожидаемый результат |
| --- | --- | --- |
| После трудной сессии | `/retro` | Исправлена причина повторяющейся проблемы |
| Раз в неделю | `/simplify` на активных каталогах; `/code-review` на выбранном диапазоне | Небольшие проверенные исправления и список оставшихся проблем |
| Раз в месяц | `/doctor`, аудит инструкций и инструментов, `/improve-codebase-architecture` на одном слое | Обновлённое окружение и приоритеты архитектурных изменений |
| После изменения запуска | `/run-skill-generator`, затем проверка рецепта | Рабочая инструкция для следующих сессий |
| При частых подтверждениях | `/fewer-permission-prompts` | Проверенный список точных разрешений |

Выделяйте отдельную ветку для обслуживания. После правок смотрите diff и запускайте принятые в проекте проверки. Большой рефакторинг лучше вынести в самостоятельную задачу с описанием поведения, которое нужно сохранить.

## Автоматизация и стоимость

Начать можно с напоминания в календаре и ручного запуска из рабочего окружения. Так проще выбрать область проверки, посмотреть отчёт и ограничить объём исправлений.

Запуск в GitHub Actions **не обязательно требует API-оплаты**. Официальный Claude Code Action поддерживает API-ключ и OAuth-токен подписки Claude. При варианте с API учитывайте отдельную оплату использования, при подписке - её лимиты; отдельно учитывайте расходы раннера. Варианты авторизации описаны в [официальной инструкции](https://code.claude.com/docs/en/github-actions).

Перед переносом обслуживания в расписание определите бюджет, длительность, область анализа и место сохранения отчёта. Практичный первый этап - автоматически собирать замечания, затем выбирать исправления и проверять их обычным процессом разработки.

## Чек-лист завершения

- [ ] У каждого отключённого инструмента проверены назначение и зависимости.
- [ ] В инструкциях и памяти сохранены актуальные решения и причины ограничений.
- [ ] Команды запуска и проверки воспроизводятся в выбранной среде.
- [ ] Изменения разрешений просмотрены отдельно.
- [ ] Исправления кода прошли проверки проекта.
- [ ] Оставшиеся проблемы записаны с примерами и приоритетом.

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

---

Источник: https://learn.mentorcareer.ru/guides/harness-maintenance · данные проверены 25 октября 2026 г.